diff -r 875bdc0fe8ce -r 105011657405 doc/book/en/development/entityclasses/data-as-objects.rst --- a/doc/book/en/development/entityclasses/data-as-objects.rst Fri Apr 23 17:07:55 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,136 +0,0 @@ -Access to persistent data --------------------------- - -Python-level access to persistent data is provided by the -:class:`Entity ` class. - -An entity class is bound to a schema 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) - - -:Formatting and output generation: - - * `view(__vid, __registry='views', **kwargs)`, applies the given view to the entity - (and returns an unicode string) - - * `absolute_url(*args, **kwargs)`, returns an absolute URL to access the primary view - of an entity - - * `rest_path()`, returns a relative REST URL to get the entity - - * `printable_value(attr, value=_marker, attrtype=None, format='text/html', displaytime=True)`, - returns a string enabling the display of an attribute value in a given format - (the value is automatically recovered if necessary) - -: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 at - once all the missing attributes of an entity - - * `get_value(name)`, returns the value associated to the attribute name given - in parameter - - * `related(rtype, role='subject', limit=None, entities=False)`, - returns a list of entities related to the current entity by the - relation given in parameter - - * `unrelated(rtype, targettype, role='subject', limit=None)`, - returns a result set corresponding to the entities not (yet) - 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 - - * `set_relations(**kwargs)`, add relations to the given object. To - set a relation where this entity is the object of the relation, - use `reverse_` as argument name. Values may be an - entity, a list of entities, or None (meaning that all relations of - the given type from or to this object should be deleted). - - * `copy_relations(ceid)`, copies the relations of the entities having the eid - given in the parameters on the current entity - - * `delete()` allows to delete the entity - - -The :class:`AnyEntity` class ----------------------------- - -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 `mycube.entities` module (or in a submodule if we want to split code among -multiple files) so that it will be available on both server and client side. - -The class `AnyEntity` is a sub-class of Entity that add methods to it, -and helps specializing (by further subclassing) the handling of a -given entity type. - -Most methods defined for `AnyEntity`, in addition to `Entity`, add -support for the `Dublin Core`_ metadata. - -.. _`Dublin Core`: http://dublincore.org/ - -:Standard meta-data (Dublin Core): - - * `dc_title()`, returns a unicode string corresponding to the - meta-data `Title` (used by default is the first non-meta attribute - of the entity schema) - - * `dc_long_title()`, same as dc_title but can return a more - detailed title - - * `dc_description(format='text/plain')`, returns a unicode string - corresponding to the meta-data `Description` (looks for a - description attribute by default) - - * `dc_authors()`, returns a unicode string corresponding to the meta-data - `Authors` (owners by default) - - * `dc_creator()`, returns a unicode string corresponding to the - creator of the entity - - * `dc_date(date_format=None)`, returns a unicode string corresponding to - the meta-data `Date` (update date by default) - - * `dc_type(form='')`, returns a string to display the entity type by - specifying the preferred form (`plural` for a plural form) - - * `dc_language()`, returns the language used by the entity - - -:Misc methods: - - * `after_deletion_path`, return (path, parameters) which should be - used as redirect information when this entity is being deleted - - * `pre_web_edit`, callback called by the web editcontroller when an - entity will be created/modified, to let a chance to do some entity - specific stuff (does nothing by default) - -Inheritance ------------ - -When describing a data model, entities can inherit from other entities as is -common in object-oriented programming. - -You have the possibility to adapt some entity attributes, as follow: - -.. sourcecode:: python - - from cubes.OTHER_CUBE import entities - class EntityExample(entities.EntityExample): - def dc_long_title(self): - return '%s (%s)' % (self.name, self.description) - -Notice this is different than yams schema inheritance. -