merge
authorKatia Saurfelt <katia.saurfelt@logilab.fr>
Wed, 15 Apr 2009 17:25:46 +0200
changeset 1376 eb89386b2f52
parent 1375 5f412bed692c (current diff)
parent 1355 8a3102fb4760 (diff)
child 1377 6c079ce26fa3
merge
--- a/doc/book/en/B0012-schema-definition.en.txt	Wed Apr 15 10:03:48 2009 +0200
+++ b/doc/book/en/B0012-schema-definition.en.txt	Wed Apr 15 17:25:46 2009 +0200
@@ -6,7 +6,9 @@
 An entity type is defined by a Python class which inherits from `EntityType`.
 The class definition contains the description of attributes and relations
 for the defined entity type.
-The class name corresponds to the entity type name.
+The class name corresponds to the entity type name. It is exepected to be
+defined in the module ``mycube.schema``.
+
 
 For example ::
 
--- a/doc/book/en/B0030-data-as-objects.en.txt	Wed Apr 15 10:03:48 2009 +0200
+++ b/doc/book/en/B0030-data-as-objects.en.txt	Wed Apr 15 17:25:46 2009 +0200
@@ -7,12 +7,12 @@
 In this chapter, we will introduce the objects that are used to handle
 the data stored in the database.
 
-Classes `Entity` and `AnyEntity`
---------------------------------
+Class `Entity` and `AnyEntity`
+------------------------------
 
 To provide a specific behavior for each entity, we have to define
 a class inheriting from `cubicweb.entities.AnyEntity`. In general, we
-define this class in a module of `entities` package of an application
+define this class in a module of `mycube.entities` package of an application
 so that it will be available on both server and client side.
 
 The class `AnyEntity` is loaded dynamically from the class `Entity` 
@@ -114,6 +114,105 @@
   * `relation_vocabulary(rtype, targettype, x, limit=None)`, called
     internally by `subject_relation_vocabulary` and `object_relation_vocabulary`
 
+Class `TreeMixIn`
+-----------------
+
+This class provides a tree interface. This mixin has to be inherited 
+explicitly and configured using the tree_attribute, parent_target and 
+children_target class attribute to benefit from this default implementation.
+
+This class provides the following methods:
+
+  * `different_type_children(entities=True)`, returns children entities
+    of different type as this entity. According to the `entities` parameter, 
+    returns entity objects (if entity=True) or the equivalent result set.
+
+  * `same_type_children(entities=True)`, returns children entities of 
+    the same type as this entity. According to the `entities` parameter, 
+    return entity objects (if entity=True) or the equivalent result set.
+  
+  * `iterchildren( _done=None)`, iters on the children of the entity.
+  
+  * `prefixiter( _done=None)`
+  
+  * `path()`, returns the list of eids from the root object to this object.
+  
+  * `iterparents()`, iters on the parents of the entity.
+  
+  * `notification_references(view)`, used to control References field 
+    of email send on notification for this entity. `view` is the notification view.
+    Should return a list of eids which can be used to generate message ids
+    of previously sent email.
+
+`TreeMixIn` implements also the ITree interface (``cubicweb.interfaces``):
+
+  * `parent()`, returns the parent entity if any, else None (e.g. if we are on the
+    root)
+
+  * `children(entities=True, sametype=False)`, returns children entities
+    according to the `entities` parameter, return entity objects or the
+    equivalent result set.
+
+  * `children_rql()`, returns the RQL query corresponding to the children
+    of the entity.
+
+  * `is_leaf()`, returns True if the entity does not have any children.
+
+  * `is_root()`, returns True if the entity does not have any parent.
+
+  * `root()`, returns the root object of the tree representation of
+    the entity and its related entities.
+
+Example of use
+``````````````
+
+Imagine you defined three types of entities in your schema, and they
+relates to each others as follows in ``schema.py``::
+
+  class Entity1(EntityType):
+      title = String()
+      is_related_to = SubjectRelation('Entity2', 'subject')
+
+  class Entity2(EntityType):
+      title = String()
+      belongs_to = SubjectRelation('Entity3', 'subject')
+
+  class Entity3(EntityType):
+      name = String()
+
+You would like to create a view that applies to both entity types
+`Entity1` and `Entity2` and which lists the entities they are related to.
+That means when you view `Entity1` you want to list all `Entity2`, and
+when you view `Entity2` you want to list all `Entity3`.
+
+In ``entities.py``::
+
+  class Entity1(TreeMixIn, AnyEntity):
+      id = 'Entity1'
+      __implements__ = AnyEntity.__implements__ + (ITree,)
+      __rtags__ = {('is_related_to', 'Entity2', 'object'): 'link'}
+      tree_attribute = 'is_related_to'
+
+      def children(self, entities=True):
+          return self.different_type_children(entities)
+
+  class Entity2(TreeMixIn, AnyEntity):
+      id = 'Entity2'
+      __implements__ = AnyEntity.__implements__ + (ITree,)
+      __rtags__ = {('belongs_to', 'Entity3', 'object'): 'link'}
+      tree_attribute = 'belongs_to'
+
+      def children(self, entities=True):
+          return self.different_type_children(entities)
+
+Once this is done, you can define your common view as follows::
+
+  class E1E2CommonView(baseviews.PrimaryView):
+      accepts = ('Entity11, 'Entity2')
+      
+      def render_entity_relations(self, entity, siderelations):
+          self.wview('list', entity.children(entities=False))
+
 
 *rtags*
 -------
--- a/doc/book/en/B0031-define-entities.en.txt	Wed Apr 15 10:03:48 2009 +0200
+++ b/doc/book/en/B0031-define-entities.en.txt	Wed Apr 15 17:25:46 2009 +0200
@@ -133,7 +133,7 @@
 The method ``filterform_vocabulary(rtype, x, var, rqlst, args, cachekey)`` takes 
 the name of a relation and the target as parameters,
 [XXX what does it mean ?]
- which indicates of the
+which indicates of the
 entity on which we apply the method is subject or object of the relation. It
 has to return:
 
--- a/doc/book/en/B1020-define-views.en.txt	Wed Apr 15 10:03:48 2009 +0200
+++ b/doc/book/en/B1020-define-views.en.txt	Wed Apr 15 17:25:46 2009 +0200
@@ -13,6 +13,8 @@
 understanding of the classes and methods available, then detail the view
 selection principle which makes `CubicWeb` web interface very flexible.
 
+A `View` is an object applied to another object such as an entity.
+
 Basic class for views
 ---------------------
 
--- a/doc/book/en/D010-faq.en.txt	Wed Apr 15 10:03:48 2009 +0200
+++ b/doc/book/en/D010-faq.en.txt	Wed Apr 15 17:25:46 2009 +0200
@@ -145,9 +145,15 @@
 
   It depends on what has been modified in the schema.
 
-  * Update of a non final relation.
+  * Update of an attribute permissions and properties: 
+    ``synchronize_eschema('MyEntity')``.
 
-  * Update of a final relation.
+  * Update of a relation permissions and properties: 
+    ``synchronize_rschema('MyRelation')``.
+
+  * Add an attribute: ``add_attribute('MyEntityType', 'myattr')``.
+
+  * Add a relation: ``add_relation_definition('SubjRelation', 'MyRelation', 'ObjRelation')``.
 
 
 * How to create an anonymous user?
@@ -164,9 +170,16 @@
     anonymous-password=anon
 
   You also must ensure that this `anon` user is a registered user of
-  the DB backend. This could be the admin account (for development
+  the DB backend. If not, you can create through the administation
+  interface of your instance by adding a user with the role `guests`.
+  This could be the admin account (for development
   purposes, of course).
 
+.. note::
+    While creating a new instance, you can decide to allow access
+    to anonymous user, which will automatically executes what is
+    decribed above.
+
 
 * How to change the application logo?
 
@@ -225,3 +238,13 @@
   This will yield additional WARNINGs, like this: ::
 
     2009-01-09 16:43:52 - (cubicweb.selectors) WARNING: selector one_line_rset returned 0 for <class 'cubicweb.web.views.basecomponents.WFHistoryVComponent'>
+
+* How to format an entity date attribute?
+
+  If your schema has an attribute of type Date or Datetime, you might
+  want to format it. First, you should define your preferred format using
+  the site configuration panel ``http://appurl/view?vid=systemepropertiesform``
+  and then set ``ui.date`` and/or ``ui.datetime``.
+  Then in the view code, use::
+    
+    self.format_date(entity.date_attribute)