+
−.. -*- coding: utf-8 -*-
+
−
+
−
+
−Stored data handling
+
−====================
+
−
+
−Classes `Entity` and `AnyEntity`
+
−--------------------------------
+
−
+
−To provide a specific behavior for each entity, we just need to define
+
−a class inheriting from `cubicweb.entities.EnyEntity`. In genera, we have
+
−to defined those classes in a module of `entites` 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 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 execcute the
+
−  requested action on the entity
+
−
+
−:Formatting and output generation:
+
−
+
−  * `view(vid, **kwargs)`, apply 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 necessarry)
+
−
+
−  * `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`
+
−
+
−
+
−*rtags*
+
−-------
+
−
+
−*rtags* allows 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 dictionnary with as its keys the triplet ::
+
−
+
−  <relation type>, <target entity type>, <context position ("subject" ou "object")>
+
−
+
−and as the values a `set` or a tuple of markers defining the properties that
+
−apply to this relation.
+
−
+
−It is possible to simplify this dictionnary:
+
−
+
−* if we want to specifiy a single marker, it is not necessarry to
+
−  use a tuple as the value, the marker by itself (characters 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 the key
+
−* if we want a marker to apply independently from the target entity type,
+
−  we have to use the string `*` as the target entity type
+
−
+
−
+
−Please note that this dictionnary is *treated at the time the class is created*.
+
−It is automatically merged with the parent class(es) (no need to copy the
+
−dictionnary from the parent class to modify it). Also, modify it after the 
+
−class is created will not have any effect...
+
−
+
−.. include:: B051-define-entities.en.txt