diff -r ce29a9498c83 -r 451a74c5652c doc/book/en/B030-data-as-objects.en.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/B030-data-as-objects.en.txt Tue Dec 23 13:15:23 2008 -0800 @@ -0,0 +1,144 @@ +.. -*- 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 :: + + , , + +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