1 Access to persistent data

     2 --------------------------

     3 

     4 XXX is provided by the :class:`Entity <cubicweb.entity.entity>` class

     5 

     6 An entity class is bound to a schema entity type.  Descriptors are added when

     7 classes are registered in order to initialize the class according to its schema:

     8 

     9 * we can access the defined attributes in the schema thanks to the attributes of

    10   the same name on instances (typed value)

    11 

    12 * we can access the defined relations in the schema thanks to the relations of

    13   the same name on instances (entities instances list)

    14 

    15 

    16 :Formatting and output generation:

    17 

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

    19 

    20   * `absolute_url(**kwargs)`, returns an absolute URL to access the primary view

    21     of an entity

    22     

    23   * `rest_path()`, returns a relative REST URL to get the entity

    24 

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

    26 

    27   * `printable_value(attr, value=_marker, attrtype=None, format='text/html')`, 

    28     returns a string enabling the display of an attribute value in a given format

    29     (the value is automatically recovered if necessary)

    30 

    31 :Data handling:

    32 

    33   * `as_rset()`, converts the entity into an equivalent result set simulating the 

    34      request `Any X WHERE X eid _eid_`

    35 

    36   * `complete(skip_bytes=True)`, executes a request that recovers in one time

    37     all the missing attributes of an entity

    38 

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

    40     in parameter

    41 

    42   * `related(rtype, x='subject', limit=None, entities=False)`, returns a list

    43     of entities related to the current entity by the relation given in parameter

    44 

    45   * `unrelated(rtype, targettype, x='subject', limit=None)`, returns a result set

    46     corresponding to the entities not related to the current entity by the

    47     relation given in parameter and satisfying its constraints

    48 

    49   * `set_attributes(**kwargs)`, updates the attributes list with the corresponding

    50     values given named parameters

    51 

    52   * `copy_relations(ceid)`, copies the relations of the entities having the eid

    53     given in the parameters on the current entity

    54 

    55   * `last_modified(view)`, returns the date the object has been modified

    56     (used by HTTP cache handling)

    57 

    58   * `delete()` allows to delete the entity

    59 

    60   

    61 Tne :class:`AnyEntity` class

    62 ----------------------------

    63   

    64 To provide a specific behavior for each entity, we have to define

    65 a class inheriting from `cubicweb.entities.AnyEntity`. In general, we

    66 define this class in a module of `mycube.entities` package of an application

    67 so that it will be available on both server and client side.

    68 

    69 The class `AnyEntity` is loaded dynamically from the class `Entity` 

    70 (`cubciweb.entity`). We define a sub-class to add methods or to

    71 specialize the handling of a given entity type

    72 

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

    74   

    75 :Standard meta-data (Dublin Core):

    76 

    77   * `dc_title()`, returns a unicode string corresponding to the meta-data

    78     `Title` (used by default the first attribute non-meta of the entity

    79     schema)

    80 

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

    82     detailled title

    83 

    84   * `dc_description(format='text/plain')`, returns a unicode string 

    85     corresponding to the meta-data `Description` (look for a description

    86     attribute by default)

    87 

    88   * `dc_authors()`, returns a unicode string corresponding to the meta-data 

    89     `Authors` (owners by default)

    90 

    91   * `dc_date(date_format=None)`, returns a unicode string corresponding to 

    92     the meta-data `Date` (update date by default)

    93 

    94   * `dc_type(form='')`, returns a string to display the entity type by 

    95     specifying the preferred form (`plural` for a plural form)