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

Data as objects

===============

the data stored in the database.

Classes `Entity` and `AnyEntity`

--------------------------------

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:

  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)

  requested action on the entity

:Formatting and output generation:

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

-------

entity type (see later). They are defined on the entity class by the attribute

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

apply to this relation.

It is possible to simplify this dictionnary:

* if we want to specifiy a single marker, it is not necessary to

  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

* if we want a marker to apply independently from 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

class is created will not have any effect...

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