--- a/doc/book/en/devweb/views/table.rst Mon Jul 06 17:39:35 2015 +0200
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,145 +0,0 @@
-Table views
------------
-
-.. automodule:: cubicweb.web.views.tableview
-
-Example
-```````
-
-Let us take an example from the timesheet cube:
-
-.. sourcecode:: python
-
- class ActivityResourcesTable(EntityView):
- __regid__ = 'activity.resources.table'
- __select__ = is_instance('Activity')
-
- def call(self, showresource=True):
- eids = ','.join(str(row[0]) for row in self.cw_rset)
- rql = ('Any R,D,DUR,WO,DESCR,S,A, SN,RT,WT ORDERBY D DESC '
- 'WHERE '
- ' A is Activity, A done_by R, R title RT, '
- ' A diem D, A duration DUR, '
- ' A done_for WO, WO title WT, '
- ' A description DESCR, A in_state S, S name SN, '
- ' A eid IN (%s)' % eids)
- rset = self._cw.execute(rql)
- self.wview('resource.table', rset, 'null')
-
- class ResourcesTable(RsetTableView):
- __regid__ = 'resource.table'
- # notice you may wish a stricter selector to check rql's shape
- __select__ = is_instance('Resource')
- # my table headers
- headers = ['Resource', 'diem', 'duration', 'workpackage', 'description', 'state']
- # I want a table where attributes are editable (reledit inside)
- finalvid = 'editable-final'
-
- cellvids = {3: 'editable-final'}
- # display facets and actions with a menu
- layout_args = {'display_filter': 'top',
- 'add_view_actions': None}
-
-To obtain an editable table, you may specify the 'editable-table' view identifier
-using some of `cellvids`, `finalvid` or `nonfinalvid`.
-
-The previous example results in:
-
-.. image:: ../../images/views-table-shadow.png
-
-In order to activate table filter mechanism, the `display_filter` option is given
-as a layout argument. A small arrow will be displayed at the table's top right
-corner. Clicking on `show filter form` action, will display the filter form as
-below:
-
-.. image:: ../../images/views-table-filter-shadow.png
-
-By the same way, you can display additional actions for the selected entities
-by setting `add_view_actions` layout option to `True`. This will add actions
-returned by the view's :meth:`~cubicweb.web.views.tableview.TableMixIn.table_actions`.
-
-You can notice that all columns of the result set are not displayed. This is
-because of given `headers`, implying to display only columns from 0 to
-len(headers).
-
-Also Notice that the `ResourcesTable` view relies on a particular rql shape
-(which is not ensured by the way, the only checked thing is that the result set
-contains instance of the `Resource` type). That usually implies that you can't
-use this view for user specific queries (e.g. generated by facets or typed
-manually).
-
-
-So another option would be to write this view using
-:class:`~cubicweb.web.views.tableview.EntityTableView`, as below.
-
-.. sourcecode:: python
-
- class ResourcesTable(EntityTableView):
- __regid__ = 'resource.table'
- __select__ = is_instance('Resource')
- # table columns definition
- columns = ['resource', 'diem', 'duration', 'workpackage', 'description', 'in_state']
- # I want a table where attributes are editable (reledit inside)
- finalvid = 'editable-final'
- # display facets and actions with a menu
- layout_args = {'display_filter': 'top',
- 'add_view_actions': None}
-
- def workpackage_cell(entity):
- activity = entity.reverse_done_in[0]
- activity.view('reledit', rtype='done_for', role='subject', w=w)
- def workpackage_sortvalue(entity):
- activity = entity.reverse_done_in[0]
- return activity.done_for[0].sortvalue()
-
- column_renderers = {
- 'resource': MainEntityColRenderer(),
- 'workpackage': EntityTableColRenderer(
- header='Workpackage',
- renderfunc=worpackage_cell,
- sortfunc=worpackage_sortvalue,),
- 'in_state': EntityTableColRenderer(
- renderfunc=lambda w,x: w(x.cw_adapt_to('IWorkflowable').printable_state),
- sortfunc=lambda x: x.cw_adapt_to('IWorkflowable').printable_state),
- }
-
-Notice the following point:
-
-* `cell_<column>(w, entity)` will be searched for rendering the content of a
- cell. If not found, `column` is expected to be an attribute of `entity`.
-
-* `cell_sortvalue_<column>(entity)` should return a typed value to use for
- javascript sorting or None for not sortable columns (the default).
-
-* The :func:`etable_entity_sortvalue` decorator will set a 'sortvalue' function
- for the column containing the main entity (the one given as argument to all
- methods), which will call `entity.sortvalue()`.
-
-* You can set a column header using the :func:`etable_header_title` decorator.
- This header will be translated. If it's not an already existing msgid, think
- to mark it using `_()` (the example supposes headers are schema defined msgid).
-
-
-Pro/cons of each approach
-`````````````````````````
-:class:`EntityTableView` and :class:`RsetableView` provides basically the same
-set of features, though they don't share the same properties. Let's try to sum
-up pro and cons of each class.
-
-* `EntityTableView` view is:
-
- - more verbose, but usually easier to understand
-
- - easily extended (easy to add/remove columns for instance)
-
- - doesn't rely on a particular rset shape. Simply give it a title and will be
- listed in the 'possible views' box if any.
-
-* `RsetTableView` view is:
-
- - hard to beat to display barely a result set, or for cases where some of
- `headers`, `displaycols` or `cellvids` could be defined to enhance the table
- while you don't care about e.g. pagination or facets.
-
- - hardly extensible, as you usually have to change places where the view is
- called to modify the RQL (hence the view's result set shape).