1 .. -*- coding: utf-8 -*- |
|
2 |
|
3 Parametrization and specific extensions |
|
4 --------------------------------------- |
|
5 |
|
6 Dynamic default values |
|
7 `````````````````````` |
|
8 It is possible to define in the schema *static* default values. |
|
9 It is also possible to define in the schema *dynamic* default values |
|
10 by defining in the entity class a method `default_<attribut name>` for |
|
11 a given attribute. |
|
12 |
|
13 |
|
14 Loaded attributes and default sorting management |
|
15 ```````````````````````````````````````````````` |
|
16 |
|
17 * The class attribute `fetch_attrs` allows to defined in an entity class |
|
18 a list of names of attributes or relations that should be automatically |
|
19 loaded when we recover the entities of this type. In the case of relations, |
|
20 we are limited to *subject of cardinality `?` or `1`* relations. |
|
21 |
|
22 * The class method `fetch_order(attr, var)` expects an attribute (or relation) |
|
23 name as a parameter and a variable name, and it should return a string |
|
24 to use in the requirement `ORDER BY` of an RQL query to automatically |
|
25 sort the list of entities of such type according to this attribute, or |
|
26 `None` if we do not want to sort on the attribute given in the parameter. |
|
27 By default, the entities are sorted according to their creation date. |
|
28 |
|
29 * The class method `fetch_unrelated_order(attr, var)` is similar to the |
|
30 method `fetch_order` except that it is essentially used to control |
|
31 the sorting of drop-down lists enabling relations creation in |
|
32 the editing view of an entity. |
|
33 |
|
34 The function `fetch_config(fetchattrs, mainattr=None)` simplifies the |
|
35 definition of the attributes to load and the sorting by returning a |
|
36 list of attributes to pre-load (considering automatically the attributes |
|
37 of `AnyEntity`) and a sorting function based on the main attribute |
|
38 (the second parameter if specified otherwisethe first attribute from |
|
39 the list `fetchattrs`). |
|
40 This function is defined in `cubicweb.entities`. |
|
41 |
|
42 For example: :: |
|
43 |
|
44 class Transition(AnyEntity): |
|
45 """...""" |
|
46 id = 'Transition' |
|
47 fetch_attrs, fetch_order = fetch_config(['name']) |
|
48 |
|
49 Indicates that for the entity type "Transition", you have to pre-load |
|
50 the attribute `name` and sort by default on this attribute. |
|
51 |
|
52 |
|
53 Editing forms management |
|
54 ```````````````````````` |
|
55 It is possible to manage attributes/relations in the simple or multiple |
|
56 editing form thanks to the following *rtags*: |
|
57 |
|
58 * `primary`, indicates that an attribute or a relation has to be inserted |
|
59 in the simple or multiple editing forms. In the case of a relation, |
|
60 the related entity editing form will be included in the editing form. |
|
61 |
|
62 * `secondary`, indicates that an attribute or a relation has to be inserted |
|
63 in the simple editing form only. In the case of a relation, the related |
|
64 entity editing form sill be included in the editing form. |
|
65 |
|
66 * `generic`, indicates that a relation has to be inserted in the simple |
|
67 editing form, in the generic box of relation creation. |
|
68 |
|
69 * `generated`, indicates that an attribute is dynamically computed |
|
70 or other, and that it should not be displayed in the editing form. |
|
71 |
|
72 If necessarry, it is possible to overwrite the method |
|
73 `relation_category(rtype, x='subject')` to dynamically compute |
|
74 a relation editing category. |
|
75 |
|
76 ``add_related`` box management |
|
77 `````````````````````````````` |
|
78 |
|
79 The box ``add_related`` is an automatic box that allows to create |
|
80 an entity automatically related to the initial entity (context in |
|
81 which the box is displayed). By default, the links generated in this |
|
82 box are computed from the schema properties of the displayed entity, |
|
83 but it is possible to explicitely specify them thanks to the |
|
84 following *rtags*: |
|
85 |
|
86 * `link`, indicates that a relation is in general created pointing |
|
87 to an existing entity and that we should not to display a link |
|
88 for this relation |
|
89 |
|
90 * `create`, indicates that a relation is in general created pointing |
|
91 to new entities and that we should display a link to create a new |
|
92 entity and link to it automatically |
|
93 |
|
94 |
|
95 If necessarry, it is possible to overwrite the method |
|
96 `relation_mode(rtype, targettype, x='subject')` to dynamically |
|
97 compute a relation creation category. |
|
98 |
|
99 Please note that if at least one action belongs to the `addrelated` category, |
|
100 the automatic behavior is desactivated in favor of an explicit behavior |
|
101 (e.g. display of `addrelated` category actions only). |
|
102 |
|
103 |
|
104 Filtering table forms management |
|
105 ```````````````````````````````` |
|
106 |
|
107 By default, the view ``table`` manages automatically a filtering |
|
108 form of its content. The algorithm is as follows: |
|
109 |
|
110 1. we consider that the first column contains the entities to constraint |
|
111 2. we collect the first entity of the table (row 0) to represent all the |
|
112 others |
|
113 3. for all the others variables defined in the original request: |
|
114 |
|
115 1. if the varaible is related to the main variable by at least one relation |
|
116 2. we call the method ``filterform_vocabulary(rtype, x)`` on the entity, |
|
117 if nothing is returned (meaning a tuple `Non`, see below), we go to the |
|
118 next variable, otherwise a form filtering element is created based on |
|
119 the vocabulary values returned |
|
120 |
|
121 4. there is no others limitations to the `RQL`, it can include sorting, grouping |
|
122 conditions... Javascripts functions are used to regenerate a request based on the |
|
123 initial request and on the selected values from the filtering form. |
|
124 |
|
125 The method ``filterform_vocabulary(rtype, x, var, rqlst, args, cachekey)`` takes |
|
126 the name of a relation and the target as parameters, which indicates of the |
|
127 entity on which we apply the method is subject or object of the relation. It |
|
128 has to return: |
|
129 |
|
130 * a 2-uple of None if it does not know how to handle the relation |
|
131 |
|
132 * a type and a list containing the vocabulary |
|
133 |
|
134 * the list has to contain couples (value, label) |
|
135 * the type indicates if the value designate an integer (`type == 'int'`), |
|
136 a string (`type =='string'` or a non-final relation (`type == 'eid'`) |
|
137 |
|
138 For example in our application managing tickets, we want to be able to filter |
|
139 them by : |
|
140 |
|
141 * type |
|
142 * priority |
|
143 * state (in_state) |
|
144 * tag (tags) |
|
145 * version (done_in) |
|
146 |
|
147 For that we define the following method: :: |
|
148 |
|
149 |
|
150 class Ticket(AnyEntity): |
|
151 |
|
152 ... |
|
153 |
|
154 def filterform_vocabulary(self, rtype, x, var, rqlst, args, cachekey): |
|
155 _ = self.req._ |
|
156 if rtype == 'type': |
|
157 return 'string', [(x, _(x)) for x in ('bug', 'story')] |
|
158 if rtype == 'priority': |
|
159 return 'string', [(x, _(x)) for x in ('minor', 'normal', 'important')] |
|
160 if rtype == 'done_in': |
|
161 rql = insert_attr_select_relation(rqlst, var, rtype, 'num') |
|
162 return 'eid', self.req.execute(rql, args, cachekey) |
|
163 return super(Ticket, self).filterform_vocabulary(rtype, x, var, rqlst, |
|
164 args, cachekey) |
|
165 |
|
166 .. note:: |
|
167 Filtering on state and tags is automatically installed, no need to handle it. |
|
168 |
|