1 

     2 Class `TreeMixIn`

     3 -----------------

     4 

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

     6 explicitly and configured using the tree_attribute, parent_target and 

     7 children_target class attribute to benefit from this default implementation.

     8 

     9 This class provides the following methods:

    10 

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

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

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

    14 

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

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

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

    18   

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

    20   

    21   * `prefixiter( _done=None)`

    22   

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

    24   

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

    26   

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

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

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

    30     of previously sent email.

    31 

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

    33 

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

    35     root)

    36 

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

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

    39     equivalent result set.

    40 

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

    42     of the entity.

    43 

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

    45 

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

    47 

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

    49     the entity and its related entities.

    50 

    51 Example of use

    52 ``````````````

    53 

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

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

    56 

    57   class Entity1(EntityType):

    58       title = String()

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

    60 

    61   class Entity2(EntityType):

    62       title = String()

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

    64 

    65   class Entity3(EntityType):

    66       name = String()

    67 

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

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

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

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

    72 

    73 In ``entities.py``::

    74 

    75   class Entity1(TreeMixIn, AnyEntity):

    76       id = 'Entity1'

    77       __implements__ = AnyEntity.__implements__ + (ITree,)

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

    79       tree_attribute = 'is_related_to'

    80 

    81       def children(self, entities=True):

    82           return self.different_type_children(entities)

    83 

    84   class Entity2(TreeMixIn, AnyEntity):

    85       id = 'Entity2'

    86       __implements__ = AnyEntity.__implements__ + (ITree,)

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

    88       tree_attribute = 'belongs_to'

    89 

    90       def children(self, entities=True):

    91           return self.different_type_children(entities)

    92 

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

    94 

    95   class E1E2CommonView(baseviews.PrimaryView):

    96       accepts = ('Entity11, 'Entity2')

    97       

    98       def render_entity_relations(self, entity, siderelations):

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

   100