1 .. -*- coding: utf-8 -*- |
|
2 |
|
3 Parametrization and specific extensions |
|
4 --------------------------------------- |
|
5 |
|
6 Dynamic default values |
|
7 `````````````````````` |
|
8 It is possible to define *static* default values in the schema. |
|
9 It is also possible to define *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 |
|
59 inserted **in the simple or multiple editing forms**. In the case of |
|
60 a relation, the related entity editing form will be included in the |
|
61 editing form and represented as a combobox. Each item of the |
|
62 combobox is a link to an existing entity. |
|
63 |
|
64 * `secondary`, indicates that an attribute or a relation has to be |
|
65 inserted **in the simple editing form only**. In the case of a |
|
66 relation, the related entity editing form will be included in the |
|
67 editing form and represented as a combobox. Each item of the combobox |
|
68 is a link to an existing entity. |
|
69 |
|
70 * `inlineview`, includes the target entity's form in the editing form |
|
71 of the current entity. It allows to create the target entity in the |
|
72 same time as the current entity. |
|
73 |
|
74 * `generic`, indicates that a relation has to be inserted in the simple |
|
75 editing form, in the generic box of relation creation. |
|
76 |
|
77 * `generated`, indicates that an attribute is dynamically computed |
|
78 or other, and that it should not be displayed in the editing form. |
|
79 |
|
80 If necessary, it is possible to overwrite the method |
|
81 `relation_category(rtype, x='subject')` to dynamically compute |
|
82 a relation editing category. |
|
83 |
|
84 ``add_related`` box management |
|
85 `````````````````````````````` |
|
86 |
|
87 The box ``add_related`` is an automatic box that allows to create |
|
88 an entity automatically related to the initial entity (context in |
|
89 which the box is displayed). By default, the links generated in this |
|
90 box are computed from the schema properties of the displayed entity, |
|
91 but it is possible to explicitely specify them thanks to the |
|
92 following *rtags*: |
|
93 |
|
94 * `link`, indicates that a relation is in general created pointing |
|
95 to an existing entity and that we should not to display a link |
|
96 for this relation |
|
97 |
|
98 * `create`, indicates that a relation is in general created pointing |
|
99 to new entities and that we should display a link to create a new |
|
100 entity and link to it automatically |
|
101 |
|
102 |
|
103 If necessary, it is possible to overwrite the method |
|
104 `relation_mode(rtype, targettype, x='subject')` to dynamically |
|
105 compute a relation creation category. |
|
106 |
|
107 Please note that if at least one action belongs to the `addrelated` category, |
|
108 the automatic behavior is desactivated in favor of an explicit behavior |
|
109 (e.g. display of `addrelated` category actions only). |
|
110 |
|
111 |
|
112 Filtering table forms management |
|
113 ```````````````````````````````` |
|
114 |
|
115 By default, the view ``table`` manages automatically a filtering |
|
116 form of its content. The algorithm is as follows: |
|
117 |
|
118 1. we consider that the first column contains the entities to constraint |
|
119 2. we collect the first entity of the table (row 0) to represent all the |
|
120 others |
|
121 3. for all the other variables defined in the original request: |
|
122 |
|
123 1. if the variable is related to the main variable by at least one relation |
|
124 2. we call the method ``filterform_vocabulary(rtype, x)`` on the entity, |
|
125 if nothing is returned (meaning a tuple `Non`, see below), we go to the |
|
126 next variable, otherwise a form filtering element is created based on |
|
127 the vocabulary values returned |
|
128 |
|
129 4. there are no other limitations to the `RQL`, it can include sorting, grouping |
|
130 conditions... JavaScript functions are used to regenerate a request based on the |
|
131 initial request and on the selected values from the filtering form. |
|
132 |
|
133 The method ``filterform_vocabulary(rtype, x, var, rqlst, args, cachekey)`` takes |
|
134 the name of a relation and the target as parameters, |
|
135 [XXX what does it mean ?] |
|
136 which indicates of the |
|
137 entity on which we apply the method is subject or object of the relation. It |
|
138 has to return: |
|
139 |
|
140 * a 2-uple of None if it does not know how to handle the relation |
|
141 |
|
142 * a type and a list containing the vocabulary |
|
143 |
|
144 * the list has to contain couples (value, label) |
|
145 * the type indicates if the value designate an integer (`type == 'int'`), |
|
146 a string (`type =='string'` or a non-final relation (`type == 'eid'`) |
|
147 |
|
148 For example in our application managing tickets, we want to be able to filter |
|
149 them by : |
|
150 |
|
151 * type |
|
152 * priority |
|
153 * state (in_state) |
|
154 * tag (tags) |
|
155 * version (done_in) |
|
156 |
|
157 For that we define the following method: :: |
|
158 |
|
159 |
|
160 class Ticket(AnyEntity): |
|
161 |
|
162 ... |
|
163 |
|
164 def filterform_vocabulary(self, rtype, x, var, rqlst, args, cachekey): |
|
165 _ = self.req._ |
|
166 if rtype == 'type': |
|
167 return 'string', [(x, _(x)) for x in ('bug', 'story')] |
|
168 if rtype == 'priority': |
|
169 return 'string', [(x, _(x)) for x in ('minor', 'normal', 'important')] |
|
170 if rtype == 'done_in': |
|
171 rql = insert_attr_select_relation(rqlst, var, rtype, 'num') |
|
172 return 'eid', self.req.execute(rql, args, cachekey) |
|
173 return super(Ticket, self).filterform_vocabulary(rtype, x, var, rqlst, |
|
174 args, cachekey) |
|
175 |
|
176 .. note:: |
|
177 Filtering on state and tags is automatically installed, no need to handle it. |
|
178 |
|