2 .. _FetchAttrs: |
2 .. _FetchAttrs: |
3 |
3 |
4 Loaded attributes and default sorting management |
4 Loaded attributes and default sorting management |
5 ```````````````````````````````````````````````` |
5 ```````````````````````````````````````````````` |
6 |
6 |
7 * The class attribute `fetch_attrs` allows to define in an entity class a list |
7 * The class attribute `fetch_attrs` allows to define in an entity class a list of |
8 of names of attributes or relations that should be automatically loaded when |
8 names of attributes that should be automatically loaded when entities of this |
9 entities of this type are fetched from the database. In the case of relations, |
9 type are fetched from the database using ORM methods retrieving entity of this |
10 we are limited to *subject of cardinality `?` or `1`* relations. |
10 type (such as :meth:`related` and :meth:`unrelated`). You can also put relation |
|
11 names in there, but we are limited to *subject relations of cardinality `?` or |
|
12 `1`*. |
11 |
13 |
12 * The class method `fetch_order(attr, var)` expects an attribute (or relation) |
14 * The :meth:`cw_fetch_order` and :meth:`cw_fetch_unrelated_order` class methods |
13 name as a parameter and a variable name, and it should return a string |
15 are respectively responsible to control how entities will be sorted when: |
14 to use in the requirement `ORDERBY` of an RQL query to automatically |
|
15 sort the list of entities of such type according to this attribute, or |
|
16 `None` if we do not want to sort on the attribute given in the parameter. |
|
17 By default, the entities are sorted according to their creation date. |
|
18 |
16 |
19 * The class method `fetch_unrelated_order(attr, var)` is similar to |
17 - retrieving all entities of a given type, or entities related to another |
20 the method `fetch_order` except that it is essentially used to |
|
21 control the sorting of drop-down lists enabling relations creation |
|
22 in the editing view of an entity. The default implementation uses |
|
23 the modification date. Here's how to adapt it for one entity (sort |
|
24 on the name attribute): :: |
|
25 |
18 |
26 class MyEntity(AnyEntity): |
19 - retrieving a list of entities for use in drop-down lists enabling relations |
27 __regid__ = 'MyEntity' |
20 creation in the editing view of an entity |
28 fetch_attrs = ('modification_date', 'name') |
|
29 |
21 |
30 @classmethod |
22 By default entities will be listed on their modification date descending, |
31 def fetch_unrelated_order(cls, attr, var): |
23 i.e. you'll get entities recently modified first. While this is usually a good |
32 if attr == 'name': |
24 default in drop-down list, you'll probably want to change `cw_fetch_order`. |
33 return '%s ASC' % var |
|
34 return None |
|
35 |
25 |
|
26 This may easily be done using the :func:`~cubicweb.entities.fetch_config` |
|
27 function, which simplifies the definition of attributes to load and sorting by |
|
28 returning a list of attributes to pre-load (considering automatically the |
|
29 attributes of `AnyEntity`) and a sorting function as described below: |
36 |
30 |
37 The function `fetch_config(fetchattrs, mainattr=None)` simplifies the |
31 .. autofunction:: cubicweb.entities.fetch_config |
38 definition of the attributes to load and the sorting by returning a |
|
39 list of attributes to pre-load (considering automatically the |
|
40 attributes of `AnyEntity`) and a sorting function based on the main |
|
41 attribute (the second parameter if specified, otherwise the first |
|
42 attribute from the list `fetchattrs`). This function is defined in |
|
43 `cubicweb.entities`. |
|
44 |
32 |
45 For example: :: |
33 In you want something else (such as sorting on the result of a registered |
|
34 procedure), here is the prototype of those methods: |
46 |
35 |
47 class Transition(AnyEntity): |
36 .. autofunction:: cubicweb.entity.Entity.cw_fetch_order |
48 """...""" |
|
49 __regid__ = 'Transition' |
|
50 fetch_attrs, fetch_order = fetch_config(['name']) |
|
51 |
37 |
52 Indicates that for the entity type "Transition", you have to pre-load |
38 .. autofunction:: cubicweb.entity.Entity.cw_fetch_unrelated_order |
53 the attribute `name` and sort by default on this attribute. |
39 |