# HG changeset patch
# User Sylvain Thénault <sylvain.thenault@logilab.fr>
# Date 1282812745 -7200
# Node ID 2f0dd9494b33e364ddb6c5bb7650e39ffd1d9e90
# Parent  16fad8d00787975179b0617378a1c2b2a70a2863
[doc] interesting stuff backported

diff -r 16fad8d00787 -r 2f0dd9494b33 doc/book/_maybe_to_integrate/treemixin.rst
--- a/doc/book/_maybe_to_integrate/treemixin.rst	Thu Aug 26 10:51:55 2010 +0200
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,100 +0,0 @@
-
-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))
-