--- a/doc/book/en/B050-data-as-objects.en.txt Tue Dec 23 13:04:24 2008 -0800
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,144 +0,0 @@
-.. -*- 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