117 Class `TreeMixIn`

   118 -----------------

   119 

   120 This class provides a tree interface. This mixin has to be inherited 

   121 explicitly and configured using the tree_attribute, parent_target and 

   122 children_target class attribute to benefit from this default implementation.

   123 

   124 This class provides the following methods:

   125 

   126   * `different_type_children(entities=True)`, returns children entities

   127     of different type as this entity. According to the `entities` parameter, 

   128     returns entity objects (if entity=True) or the equivalent result set.

   129 

   130   * `same_type_children(entities=True)`, returns children entities of 

   131     the same type as this entity. According to the `entities` parameter, 

   132     return entity objects (if entity=True) or the equivalent result set.

   133   

   134   * `iterchildren( _done=None)`, iters on the children of the entity.

   135   

   136   * `prefixiter( _done=None)`

   137   

   138   * `path()`, returns the list of eids from the root object to this object.

   139   

   140   * `iterparents()`, iters on the parents of the entity.

   141   

   142   * `notification_references(view)`, used to control References field 

   143     of email send on notification for this entity. `view` is the notification view.

   144     Should return a list of eids which can be used to generate message ids

   145     of previously sent email.

   146 

   147 `TreeMixIn` implements also the ITree interface (``cubicweb.interfaces``):

   148 

   149   * `parent()`, returns the parent entity if any, else None (e.g. if we are on the

   150     root)

   151 

   152   * `children(entities=True, sametype=False)`, returns children entities

   153     according to the `entities` parameter, return entity objects or the

   154     equivalent result set.

   155 

   156   * `children_rql()`, returns the RQL query corresponding to the children

   157     of the entity.

   158 

   159   * `is_leaf()`, returns True if the entity does not have any children.

   160 

   161   * `is_root()`, returns True if the entity does not have any parent.

   162 

   163   * `root()`, returns the root object of the tree representation of

   164     the entity and its related entities.

   165 

   166 Example of use

   167 ``````````````

   168 

   169 Imagine you defined three types of entities in your schema, and they

   170 relates to each others as follows in ``schema.py``::

   171 

   172   class Entity1(EntityType):

   173       title = String()

   174       is_related_to = SubjectRelation('Entity2', 'subject')

   175 

   176   class Entity2(EntityType):

   177       title = String()

   178       belongs_to = SubjectRelation('Entity3', 'subject')

   179 

   180   class Entity3(EntityType):

   181       name = String()

   182 

   183 You would like to create a view that applies to both entity types

   184 `Entity1` and `Entity2` and which lists the entities they are related to.

   185 That means when you view `Entity1` you want to list all `Entity2`, and

   186 when you view `Entity2` you want to list all `Entity3`.

   187 

   188 In ``entities.py``::

   189 

   190   class Entity1(TreeMixIn, AnyEntity):

   191       id = 'Entity1'

   192       __implements__ = AnyEntity.__implements__ + (ITree,)

   193       __rtags__ = {('is_related_to', 'Entity2', 'object'): 'link'}

   194       tree_attribute = 'is_related_to'

   195 

   196       def children(self, entities=True):

   197           return self.different_type_children(entities)

   198 

   199   class Entity2(TreeMixIn, AnyEntity):

   200       id = 'Entity2'

   201       __implements__ = AnyEntity.__implements__ + (ITree,)

   202       __rtags__ = {('belongs_to', 'Entity3', 'object'): 'link'}

   203       tree_attribute = 'belongs_to'

   204 

   205       def children(self, entities=True):

   206           return self.different_type_children(entities)

   207 

   208 Once this is done, you can define your common view as follows::

   209 

   210   class E1E2CommonView(baseviews.PrimaryView):

   211       accepts = ('Entity11, 'Entity2')

   212       

   213       def render_entity_relations(self, entity, siderelations):

   214           self.wview('list', entity.children(entities=False))

   215