1 Table views |
|
2 ----------- |
|
3 |
|
4 .. automodule:: cubicweb.web.views.tableview |
|
5 |
|
6 Example |
|
7 ``````` |
|
8 |
|
9 Let us take an example from the timesheet cube: |
|
10 |
|
11 .. sourcecode:: python |
|
12 |
|
13 class ActivityResourcesTable(EntityView): |
|
14 __regid__ = 'activity.resources.table' |
|
15 __select__ = is_instance('Activity') |
|
16 |
|
17 def call(self, showresource=True): |
|
18 eids = ','.join(str(row[0]) for row in self.cw_rset) |
|
19 rql = ('Any R,D,DUR,WO,DESCR,S,A, SN,RT,WT ORDERBY D DESC ' |
|
20 'WHERE ' |
|
21 ' A is Activity, A done_by R, R title RT, ' |
|
22 ' A diem D, A duration DUR, ' |
|
23 ' A done_for WO, WO title WT, ' |
|
24 ' A description DESCR, A in_state S, S name SN, ' |
|
25 ' A eid IN (%s)' % eids) |
|
26 rset = self._cw.execute(rql) |
|
27 self.wview('resource.table', rset, 'null') |
|
28 |
|
29 class ResourcesTable(RsetTableView): |
|
30 __regid__ = 'resource.table' |
|
31 # notice you may wish a stricter selector to check rql's shape |
|
32 __select__ = is_instance('Resource') |
|
33 # my table headers |
|
34 headers = ['Resource', 'diem', 'duration', 'workpackage', 'description', 'state'] |
|
35 # I want a table where attributes are editable (reledit inside) |
|
36 finalvid = 'editable-final' |
|
37 |
|
38 cellvids = {3: 'editable-final'} |
|
39 # display facets and actions with a menu |
|
40 layout_args = {'display_filter': 'top', |
|
41 'add_view_actions': None} |
|
42 |
|
43 To obtain an editable table, you may specify the 'editable-table' view identifier |
|
44 using some of `cellvids`, `finalvid` or `nonfinalvid`. |
|
45 |
|
46 The previous example results in: |
|
47 |
|
48 .. image:: ../../images/views-table-shadow.png |
|
49 |
|
50 In order to activate table filter mechanism, the `display_filter` option is given |
|
51 as a layout argument. A small arrow will be displayed at the table's top right |
|
52 corner. Clicking on `show filter form` action, will display the filter form as |
|
53 below: |
|
54 |
|
55 .. image:: ../../images/views-table-filter-shadow.png |
|
56 |
|
57 By the same way, you can display additional actions for the selected entities |
|
58 by setting `add_view_actions` layout option to `True`. This will add actions |
|
59 returned by the view's :meth:`~cubicweb.web.views.tableview.TableMixIn.table_actions`. |
|
60 |
|
61 You can notice that all columns of the result set are not displayed. This is |
|
62 because of given `headers`, implying to display only columns from 0 to |
|
63 len(headers). |
|
64 |
|
65 Also Notice that the `ResourcesTable` view relies on a particular rql shape |
|
66 (which is not ensured by the way, the only checked thing is that the result set |
|
67 contains instance of the `Resource` type). That usually implies that you can't |
|
68 use this view for user specific queries (e.g. generated by facets or typed |
|
69 manually). |
|
70 |
|
71 |
|
72 So another option would be to write this view using |
|
73 :class:`~cubicweb.web.views.tableview.EntityTableView`, as below. |
|
74 |
|
75 .. sourcecode:: python |
|
76 |
|
77 class ResourcesTable(EntityTableView): |
|
78 __regid__ = 'resource.table' |
|
79 __select__ = is_instance('Resource') |
|
80 # table columns definition |
|
81 columns = ['resource', 'diem', 'duration', 'workpackage', 'description', 'in_state'] |
|
82 # I want a table where attributes are editable (reledit inside) |
|
83 finalvid = 'editable-final' |
|
84 # display facets and actions with a menu |
|
85 layout_args = {'display_filter': 'top', |
|
86 'add_view_actions': None} |
|
87 |
|
88 def workpackage_cell(entity): |
|
89 activity = entity.reverse_done_in[0] |
|
90 activity.view('reledit', rtype='done_for', role='subject', w=w) |
|
91 def workpackage_sortvalue(entity): |
|
92 activity = entity.reverse_done_in[0] |
|
93 return activity.done_for[0].sortvalue() |
|
94 |
|
95 column_renderers = { |
|
96 'resource': MainEntityColRenderer(), |
|
97 'workpackage': EntityTableColRenderer( |
|
98 header='Workpackage', |
|
99 renderfunc=worpackage_cell, |
|
100 sortfunc=worpackage_sortvalue,), |
|
101 'in_state': EntityTableColRenderer( |
|
102 renderfunc=lambda w,x: w(x.cw_adapt_to('IWorkflowable').printable_state), |
|
103 sortfunc=lambda x: x.cw_adapt_to('IWorkflowable').printable_state), |
|
104 } |
|
105 |
|
106 Notice the following point: |
|
107 |
|
108 * `cell_<column>(w, entity)` will be searched for rendering the content of a |
|
109 cell. If not found, `column` is expected to be an attribute of `entity`. |
|
110 |
|
111 * `cell_sortvalue_<column>(entity)` should return a typed value to use for |
|
112 javascript sorting or None for not sortable columns (the default). |
|
113 |
|
114 * The :func:`etable_entity_sortvalue` decorator will set a 'sortvalue' function |
|
115 for the column containing the main entity (the one given as argument to all |
|
116 methods), which will call `entity.sortvalue()`. |
|
117 |
|
118 * You can set a column header using the :func:`etable_header_title` decorator. |
|
119 This header will be translated. If it's not an already existing msgid, think |
|
120 to mark it using `_()` (the example supposes headers are schema defined msgid). |
|
121 |
|
122 |
|
123 Pro/cons of each approach |
|
124 ````````````````````````` |
|
125 :class:`EntityTableView` and :class:`RsetableView` provides basically the same |
|
126 set of features, though they don't share the same properties. Let's try to sum |
|
127 up pro and cons of each class. |
|
128 |
|
129 * `EntityTableView` view is: |
|
130 |
|
131 - more verbose, but usually easier to understand |
|
132 |
|
133 - easily extended (easy to add/remove columns for instance) |
|
134 |
|
135 - doesn't rely on a particular rset shape. Simply give it a title and will be |
|
136 listed in the 'possible views' box if any. |
|
137 |
|
138 * `RsetTableView` view is: |
|
139 |
|
140 - hard to beat to display barely a result set, or for cases where some of |
|
141 `headers`, `displaycols` or `cellvids` could be defined to enhance the table |
|
142 while you don't care about e.g. pagination or facets. |
|
143 |
|
144 - hardly extensible, as you usually have to change places where the view is |
|
145 called to modify the RQL (hence the view's result set shape). |
|