|
1 .. _reledit: |
|
2 |
|
3 The "Click and Edit" (also `reledit`) View |
|
4 ------------------------------------------ |
|
5 |
|
6 The principal way to update data through the Web UI is through the |
|
7 `modify` action on entities, which brings a full form. This is |
|
8 described in the :ref:`webform` chapter. |
|
9 |
|
10 There is however another way to perform piecewise edition of entities |
|
11 and relations, using a specific `reledit` (for *relation edition*) |
|
12 view from the :mod:`cubicweb.web.views.reledit` module. |
|
13 |
|
14 This is typically applied from the default Primary View (see |
|
15 :ref:`primary_view`) on the attributes and relation section. It makes |
|
16 small editions more convenient. |
|
17 |
|
18 Of course, this can be used customely in any other view. Here come |
|
19 some explanation about its capabilities and instructions on the way to |
|
20 use it. |
|
21 |
|
22 Using `reledit` |
|
23 *************** |
|
24 |
|
25 Let's start again with a simple example: |
|
26 |
|
27 .. sourcecode:: python |
|
28 |
|
29 class Company(EntityType): |
|
30 name = String(required=True, unique=True) |
|
31 boss = SubjectRelation('Person', cardinality='1*') |
|
32 status = SubjectRelation('File', cardinality='?*', composite='subject') |
|
33 |
|
34 In some view code we might want to show these attributes/relations and |
|
35 allow the user to edit each of them in turn without having to leave |
|
36 the current page. We would write code as below: |
|
37 |
|
38 .. sourcecode:: python |
|
39 |
|
40 company.view('reledit', rtype='name', default_value='<name>') # editable name attribute |
|
41 company.view('reledit', rtype='boss') # editable boss relation |
|
42 company.view('reledit', rtype='status') # editable attribute-like relation |
|
43 |
|
44 If one wanted to edit the company from a boss's point of view, one |
|
45 would have to indicate the proper relation's role. By default the role |
|
46 is `subject`. |
|
47 |
|
48 .. sourcecode:: python |
|
49 |
|
50 person.view('reledit', rtype='boss', role='object') |
|
51 |
|
52 Each of these will provide with a different editing widget. The `name` |
|
53 attribute will obviously get a text input field. The `boss` relation |
|
54 will be edited through a selection box, allowing to pick another |
|
55 `Person` as boss. The `status` relation, given that it defines Company |
|
56 as a composite entity with one file inside, will provide additional actions |
|
57 |
|
58 * to `add` a `File` when there is one |
|
59 * to `delete` the `File` (if the cardinality allows it) |
|
60 |
|
61 Moreover, editing the relation or using the `add` action leads to an |
|
62 embedded edition/creation form allowing edition of the target entity |
|
63 (which is `File` in our example) instead of merely allowing to choose |
|
64 amongst existing files. |
|
65 |
|
66 The `reledit_ctrl` rtag |
|
67 *********************** |
|
68 |
|
69 The behaviour of reledited attributes/relations can be finely |
|
70 controlled using the reledit_ctrl rtag, defined in |
|
71 :mod:`cubicweb.web.views.uicfg`. |
|
72 |
|
73 This rtag provides four control variables: |
|
74 |
|
75 * ``default_value``: alternative default value |
|
76 The default value is what is shown when there is no value. |
|
77 * ``reload``: boolean, eid (to reload to) or function taking subject |
|
78 and returning bool/eid This is useful when editing a relation (or |
|
79 attribute) that impacts the url or another parts of the current |
|
80 displayed page. Defaults to false. |
|
81 * ``rvid``: alternative view id (as str) for relation or composite |
|
82 edition Default is 'incontext' or 'csv' depending on the |
|
83 cardinality. They can also be statically changed by subclassing |
|
84 ClickAndEditFormView and redefining _one_rvid (resp. _many_rvid). |
|
85 * ``edit_target``: 'rtype' (to edit the relation) or 'related' (to |
|
86 edit the related entity) This controls whether to edit the relation |
|
87 or the target entity of the relation. Currently only one-to-one |
|
88 relations support target entity edition. By default, the 'related' |
|
89 option is taken whenever the relation is composite and one-to-one. |
|
90 |
|
91 Let's see how to use these controls. |
|
92 |
|
93 .. sourcecode:: python |
|
94 |
|
95 from logilab.mtconverter import xml_escape |
|
96 from cubicweb.web.views.uicfg import reledit_ctrl |
|
97 reledit_ctrl.tag_attribute(('Company', 'name'), |
|
98 {'reload': lambda x:x.eid, |
|
99 'default_value': xml_escape(u'<logilab tastes better>')}) |
|
100 reledit_ctrl.tag_object_of(('*', 'boss', 'Person'), {'edit_target': 'related'}) |
|
101 |
|
102 The `default_value` needs to be an xml escaped unicode string. |
|
103 |
|
104 The `edit_target` tag on the `boss` relation being set to `related` will |
|
105 ensure edition of the `Person` entity instead (using a standard |
|
106 automatic form) of the association of Company and Person. |
|
107 |
|
108 Finally, the `reload` key accepts either a boolean, an eid or a |
|
109 unicode string representing a url. If an eid is provided, it will be |
|
110 internally transformed into a url. The eid/url case helps when one |
|
111 needs to reload and the current url is inappropriate. A common case is |
|
112 edition of a key attribute, which is part of the current url. If one |
|
113 user changed the Company's name from `lozilab` to `logilab`, reloading |
|
114 on http://myapp/company/lozilab would fail. Providing the entity's |
|
115 eid, then, forces to reload on something like http://myapp/company/42, |
|
116 which always work. |
|
117 |
|
118 |
|
119 Disable `reledit` |
|
120 ***************** |
|
121 |
|
122 By default, `reledit` is available on attributes and relations displayed in |
|
123 the 'attribute' section of the default primary view. If you want to disable |
|
124 it for some attribute or relation, you have use `uicfg`: |
|
125 |
|
126 .. sourcecode:: python |
|
127 |
|
128 from cubicweb.web.views.uicfg import primaryview_display_ctrl as _pvdc |
|
129 _pvdc.tag_attribute(('Company', 'name'), {'vid': 'incontext'}) |
|
130 |
|
131 To deactivate it everywhere it's used automatically, you may use the code snippet |
|
132 below somewhere in your cube's views: |
|
133 |
|
134 .. sourcecode:: python |
|
135 |
|
136 from cubicweb.web.views import reledit |
|
137 |
|
138 class DeactivatedAutoClickAndEditFormView(reledit.AutoClickAndEditFormView): |
|
139 def _should_edit_attribute(self, rschema): |
|
140 return False |
|
141 |
|
142 def _should_edit_attribute(self, rschema, role): |
|
143 return False |
|
144 |
|
145 def registration_callback(vreg): |
|
146 vreg.register_and_replace(DeactivatedAutoClickAndEditFormView, |
|
147 reledit.AutoClickAndEditFormView) |
|
148 |
|
149 |