.. _FetchAttrs:

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

* The class attribute `fetch_attrs` allows to define in an entity class a list
  of names of attributes or relations that should be automatically loaded when
  entities of this type are fetched from the database. 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 `ORDERBY` 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 default implementation uses
  the modification date. Here's how to adapt it for one entity (sort
  on the name attribute): ::

   class MyEntity(AnyEntity):
       __regid__ = 'MyEntity'
       fetch_attrs = ('modification_date', 'name')

       @classmethod
       def fetch_unrelated_order(cls, attr, var):
           if attr == 'name':
              return '%s ASC' % var
           return None


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, otherwise the first
attribute from the list `fetchattrs`). This function is defined in
`cubicweb.entities`.

For example: ::

  class Transition(AnyEntity):
    """..."""
    __regid__ = '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.