doc/book/en/development/entityclasses/load-sort.rst
author sylvain.thenault@logilab.fr
Thu, 07 May 2009 16:33:22 +0200
branchtls-sprint
changeset 1714 a721966779be
child 2172 cf8f9180e63e
permissions -rw-r--r--
new book layout, do not compile yet


Loaded attributes and default sorting management
````````````````````````````````````````````````

* The class attribute `fetch_attrs` allows to defined in an entity class
  a list of names of attributes or relations that should be automatically
  loaded when we recover the entities of this type. In the case of relations,
  we are limited to *subject of cardinality `?` or `1`* relations.

* The class method `fetch_order(attr, var)` expects an attribute (or relation)
  name as a parameter and a variable name, and it should return a string
  to use in the requirement `ORDER BY` of an RQL query to automatically
  sort the list of entities of such type according to this attribute, or
  `None` if we do not want to sort on the attribute given in the parameter.
  By default, the entities are sorted according to their creation date.

* The class method `fetch_unrelated_order(attr, var)` is similar to the 
  method `fetch_order` except that it is essentially used to control
  the sorting of drop-down lists enabling relations creation in 
  the editing view of an entity.

The function `fetch_config(fetchattrs, mainattr=None)` simplifies the
definition of the attributes to load and the sorting by returning a 
list of attributes to pre-load (considering automatically the attributes
of `AnyEntity`) and a sorting function based on the main attribute
(the second parameter if specified otherwisethe first attribute from
the list `fetchattrs`).
This function is defined in `cubicweb.entities`.

For example: ::

  class Transition(AnyEntity):
    """..."""
    id = 'Transition'
    fetch_attrs, fetch_order = fetch_config(['name'])

Indicates that for the entity type "Transition", you have to pre-load
the attribute `name` and sort by default on this attribute.