.. -*- coding: utf-8 -*-


Data as objects
===============

In this chapter, we will introduce the objects that are used to handle
the data stored in the database.

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 `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` 
(`cubciweb.common.entity`). We define a sub-class to add methods or to
specialize the handling of a given entity type

Descriptors are added when classes are registered in order to initialize the class
according to its schema:

* we can access the defined attributes in the schema thanks to the attributes of
  the same name on instances (typed value)

* we can access the defined relations in the schema thanks to the relations of
  the same name on instances (entities instances list)

The methods defined for `AnyEntity` or `Entity` are the following ones:

* `has_eid()`, returns true is the entity has an definitive eid (e.g. not in the
  creation process)
        
* `check_perm(action)`, checks if the user has the permission to execute the
  requested action on the entity

:Formatting and output generation:

  * `view(vid, **kwargs)`, applies the given view to the entity

  * `absolute_url(**kwargs)`, returns an absolute URL to access the primary view
    of an entity
    
  * `rest_path()`, returns a relative REST URL to get the entity

  * `format(attr)`, returns the format (MIME type) of the field given un parameter

  * `printable_value(attr, value=_marker, attrtype=None, format='text/html')`, 
    returns a string enabling the display of an attribute value in a given format
    (the value is automatically recovered if necessary)

  * `display_name(form='')`, returns a string to display the entity type by 
    specifying the preferred form (`plural` for a plural form)

:Data handling:

  * `as_rset()`, converts the entity into an equivalent result set simulating the 
     request `Any X WHERE X eid _eid_`

  * `complete(skip_bytes=True)`, executes a request that recovers in one time
    all the missing attributes of an entity

  * `get_value(name)`, returns the value associated to the attribute name given
    in parameter

  * `related(rtype, x='subject', limit=None, entities=False)`, returns a list
    of entities related to the current entity by the relation given in parameter

  * `unrelated(rtype, targettype, x='subject', limit=None)`, returns a result set
    corresponding to the entities not related to the current entity by the
    relation given in parameter and satisfying its constraints

  * `set_attributes(**kwargs)`, updates the attributes list with the corresponding
    values given named parameters

  * `copy_relations(ceid)`, copies the relations of the entities having the eid
    given in the parameters on the current entity

  * `last_modified(view)`, returns the date the object has been modified
    (used by HTTP cache handling)

  * `delete()` allows to delete the entity
  
:Standard meta-data (Dublin Core):

  * `dc_title()`, returns a unicode string corresponding to the meta-data
    `Title` (used by default the first attribute non-meta of the entity
    schema)

  * `dc_long_title()`, same as dc_title but can return a more
    detailled title

  * `dc_description(format='text/plain')`, returns a unicode string 
    corresponding to the meta-data `Description` (look for a description
    attribute by default)

  * `dc_authors()`, returns a unicode string corresponding to the meta-data 
    `Authors` (owners by default)

  * `dc_date(date_format=None)`, returns a unicode string corresponding to 
    the meta-data `Date` (update date by default)
            
:Vocabulary control on relations:

  * `vocabulary(rtype, x='subject', limit=None)`, called by the
    editing views, it returns a list of couples (label, eid) of entities
    that could be related to the entity by the relation `rtype`
  * `subject_relation_vocabulary(rtype, limit=None)`, called internally 
    by  `vocabulary` in the case of a subject relation
  * `object_relation_vocabulary(rtype, limit=None)`, called internally 
    by  `vocabulary` in the case of an object relation
  * `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*
-------

*rtags* allow to specify certain behaviors of relations relative to a given
entity type (see later). They are defined on the entity class by the attribute
`rtags` which is a dictionary with as keys the triplets ::

  <relation type>, <target entity type>, <context position ("subject" ou "object")>

and as values a `set` or a tuple of markers defining the properties that
apply to this relation.

It is possible to simplify this dictionary:

* if we want to specifiy a single marker, it is not necessary to
  use a tuple as value, the marker by itself (character string)
  is enough
* if we only care about a single type of relation and not about the target
  and the context position (or when this one is not ambigous), we can simply
  use the name of the relation type as key
* if we want a marker to apply independently from the target entity type,
  we have to use the string `*` as target entity type


Please note that this dictionary is *treated at the time the class is created*.
It is automatically merged with the parent class(es) (no need to copy the
dictionary from the parent class to modify it). Also, modifying it after the 
class is created will not have any effect...

.. include:: B0031-define-entities.en.txt