.. -*- 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.

Classes `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 `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`


*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