Introduction
============
The `ftw.table` package provides a utility for generating HTML tables of
dicts, catalog brains and other objects.
It comes with a jQuery plugin installable with a Plone Generic Setup profile,
providing features such as sorting, filter, grouping checkboxes and more.
Purpose
-------
The main purpose of this library package is to abstract the table generation
for the `ftw.tabbedview`_ package but it can also be used in a plain
plone / zope installation.
Table generator utility
-----------------------
The table generator utility can generate HTML or JSON output.
It expects a list of data objects, accessible either in dict-like syntax by
using ``item.get(attrname)`` or in a object-like syntax by using
``item.attrname``.
It also expects a column configuration indicating which columns / attributes
are displayed in the table and how they are presented.
Examples:
>>> from ftw.table.interfaces import ITableGenerator
>>> from zope.component import getUtility
>>>
>>> generator = getUtility(ITableGenerator, name="ftw.tablegenerator")
>>>
>>> data = [
... {'id': 1,
... 'name': 'Ptolemy I Soter',
... 'dates': '305-285 BC',
... },
... {'id': 2,
... 'name': 'Ptolemy II Philadelphos',
... 'dates': '288-246 BC',
... }]
>>>
>>> columns = ['id', 'name', 'dates']
>>> print generator.generate(data, columns)
<table class="listing">
<colgroup>
<col class="col-id" />
<col class="col-name" />
<col class="col-dates" />
</colgroup>
<thead>
<tr>
<BLANKLINE>
<th id="header-id">
<span>id</span>
</th>
<BLANKLINE>
<BLANKLINE>
<th id="header-name">
<span>name</span>
</th>
<BLANKLINE>
<BLANKLINE>
<th id="header-dates">
<span>dates</span>
</th>
<BLANKLINE>
</tr>
</thead>
<tbody>
<tr>
<td>
1
</td>
<td>
Ptolemy I Soter
</td>
<td>
305-285 BC
</td>
</tr>
<tr>
<td>
2
</td>
<td>
Ptolemy II Philadelphos
</td>
<td>
288-246 BC
</td>
</tr>
</tbody>
</table>
<BLANKLINE>
>>> columns = ['id', 'name', 'dates']
>>> print generator.generate(data, columns, output='json')
{"totalCount": 2, "rows": [{"dates": "305-285 BC", "id": 1, "name": "Ptolemy I Soter"}, {"dates": "288-246 BC", "id": 2, "name": "Ptolemy II Philadelphos"}], "metaData": {"fields": [{"type": "string", "name": "id"}, {"type": "string", "name": "name"}, {"type": "string", "name": "dates"}], "translations": {"dragDropLocked": "dragDropLocked", "sortDescText": "sortDescText", "columnsText": "columnsText", "showGroupsText": "showGroupsText", "groupByText": "groupByText", "itemsSingular": "itemsSingular", "sortAscText": "sortAscText", "selectedRowen": "selectedRowen", "itemsPlural": "itemsPlural"}, "totalProperty": "totalCount", "root": "rows", "config": {"sort": null, "dir": "ASC", "gridstate": null}, "columns": [{"header": "id", "hidden": false, "sortable": true, "groupable": true, id": "id", "dataIndex": "id"}, {"header": "name", "hidden": false, "sortable": true, "groupable": true, "id": "name", "dataIndex": "name"}, {"header": "dates", "hidden": false, "sortable": true, "groupable": true, "id": "dates", "dataIndex": "dates"}]}}
**Defining columns**
The column definition can be either a list of attribute names or a dict with
a more complex configuration:
>>> advanced_columns = [
... {'column': 'the_attribute_name',
... 'column_title': 'Title to display',
... 'condition': lambda: True,
... 'sort_index': 'sortable_title',
... 'transform': lambda item, value: str(value)}
... ]
**Sorting**
The *sortable* argument adds a "sortable" css class is added to each
column header in HTML output mode.
>>> 'sortable' in generator.generate(data, columns, sortable=True)
True
Data sources and configurations
-------------------------------
For generating listing tables from a data source such as the Plone Catalog
there is an advanced abstraction layer.
It allows to create generic listing views of different sources such as the
Plone Catalog, SQL Alchemy or python dictionaries.
A table source is an adapter retrieving data for a table source configuration.
It is a generic way to get the data. For example there is a built-in catalog
source which has the Plone Catalog as source.
The table source config specifies which data the source has to load and how
the are sorted and presented.
See the interfaces definitions and the built in sources and configurations
for further details.
Uninstall
=========
This package provides an uninstall Generic Setup profile, however, it will
not uninstall the package dependencies.
Make sure to uninstall the dependencies if you no longer use them.
Links
=====
- Github: https://github.com/4teamwork/ftw.table
- Issues: https://github.com/4teamwork/ftw.table/issues
- Pypi: http://pypi.python.org/pypi/ftw.table
- Continuous integration: https://jenkins.4teamwork.ch/search?q=ftw.table
Copyright
=========
This package is copyright by `4teamwork <http://www.4teamwork.ch/>`_.
``ftw.table`` is licensed under GNU General Public License, version 2.
.. _ftw.tabbedview: https://github.com/4teamwork/ftw.tabbedview
Changelog
=========
1.22.0 (2019-03-06)
-------------------
- Add Plone 5.1 support. [mbaechtold, jone]
- Drop support for Plone 4.2.
Only Plone 4.3 is supported now. [busykoala]
1.21.0 (2018-09-28)
-------------------
- CatalogTableSource: Exclude searchroot from results. [lgraf]
1.20.0 (2018-08-28)
-------------------
- Refactor TableGenerator to make it thread safe. [njohner]
- Fix concurrency bug in generator: data was leaking between threads. [jone]
1.19.1 (2018-04-04)
-------------------
- Hide batching navi when no content displayed. [phgross]
1.19.0 (2018-01-24)
-------------------
- Allow registering extjs static-containers based on classes instead only for ids to prevent duplicated ids in html [elioschmutz]
- Remove dependency on ftw.testing[splinter] (has been dropped in ftw.testing). [lgraf]
1.18.1 (2017-04-24)
-------------------
- Use absolute urls to set and reset the grid-state to fix an issue if
using the table on a non-folderish content in plone. Plone does not add a
trailing slash in the html base-tag for non-folderish content. This means,
relative urls will resolve to the parent object.
[elioschmutz]
1.18.0 (2017-03-16)
-------------------
- Support for "groupable" key in column definitions (dict).
[jone]
- Drop Plone 4.1 support. [jone]
1.17.0 (2016-06-27)
-------------------
- Expose `viewReady` event to DOM.
[Kevin Bieri]
1.16.0 (2015-10-19)
-------------------
- Use plones IContentIcon adapter when available.
[jone]
- Flush `groupBy` params during the table destroy, to avoid invalid
groupBy values.
[phgross]
1.15.2 (2014-10-24)
-------------------
- Fix an issue with unparsable query strings.
[deiferni]
1.15.1 (2014-08-20)
-------------------
- Fix encoding error in "linked" helper with solr flairs.
[jone]
1.15.0 (2014-06-03)
-------------------
- Fix ftwtable.extjs.js (missing semicolon).
[mathias.leimgruber]
- Add ftw.labels filtering support to catalog source.
[jone]
- Removed left over closing multiline comment from #33 in ftwtable.extjs.js.
[lgraf]
- Implement uninstall profile.
[deif]
1.14.2 (2014-05-04)
-------------------
- Replace multiline JS comments with single line ones to prevent minification
issues.
[lgraf]
1.14.1 (2014-04-30)
-------------------
- BugFix: Prevent scroll on row selection.
[mathias.leimgruber]
1.14 (2014-03-20)
-----------------
- Fix readable_date_text helper, if there is no valid date like the init value
of a Archetype DateTimeField (EffectiveDate returns 1000/01/01).
[mathias.leimgruber]
- Add English translations.
[jone]
1.13 (2014-01-10)
-----------------
- Cleanup tests. Remove all mocktests and replace them with integration tests
[elioschmutz]
- Update readable_author method. It now links
the readable author just:
1. if a the author really exists
2. if a user is logged in
3. as an anonymous users if the allowAnonymousViewAbout-property is true
[elioschmutz]
1.12.4 (2013-11-28)
-------------------
- Fixes IE9 bug where content grows when hovering over dynamically generated content.
See http://blog.brianrichards.net/post/6721471926/ie9-hover-bug-workaround for details
[Julian Infanger]
1.12.3 (2013-10-16)
-------------------
- Fix a Products.ATContentTypes bug in icon helper.
[mathias.leimgruber]
1.12.2 (2013-07-18)
-------------------
- Fix bug which caused custom templates to be stored permanently.
[jone]
1.12.1 (2013-07-09)
-------------------
- Fix regression from better "sortable" support (1.12), which
resulted in AttributeErrors when having the table template
customized.
Use `view.sortable_class(th)` instead of `view.sortable_class(th['sort_index'])`
in custom table templates.
[jone]
1.12 (2013-07-09)
-----------------
- Support setting "sortable" to false for a column in non-ExtJS mode.
[jone]
- HTML style: support "width" of column definition as <col> width.
[jone]
- ExtJS style: fix improper layout.
Also show dummy column in table body using the same width used in the header.
[Julian Infanger]
1.11 (2013-05-06)
-----------------
- Do not hide dummy column in extJs tables, its used for easy resize.
[Julian Infanger]
- Fix unicode decode error in helper
[elio.schmutz]
1.10 (2013-04-04)
-----------------
- Implement "callable" values - implemented in get_value method of TableGenerator.
[mathias.leimgruber]
1.9 (2013-01-28)
----------------
- Plone 4.3 compatibility: fix imports.
[jone]
- Fix "linked" helper, pass href as attribute.
[mathias.leimgruber]
- Fix javascript order in ExtJS profile (this time for real).
Not only does ftwtable.extjs.js need to be loaded after jquery.ftwtable.js,
but also jquery.ftwtable.js after ExtJS (collective.js.extjs-resources/js/ext-all.js).
[lgraf]
- Fix javascript order in ExtJS profile.
[jone]
- Support for "hidden" key in column definitions (dict).
[jone]
- Support for "sortable" key in column definitions (dict).
[jone]
- Modify link helper - show icon only.
[mathias.leimgruber]
1.8.2 (2012-11-28)
------------------
- Fixed base url getter, when the url doesn't ends with a slash.
[phgross]
1.8.1 (2012-11-05)
------------------
- Adjust javscripts: Use $ instead of deprecated jq.
[phgross]
- Increase extjs timeout from 0.5 to 2 minutes.
[jone]
- Use the base tag instead of the `kss-base-url` rel tag to get the base url.
[phgross]
1.8 (2012-10-16)
----------------
- Fixed decoding errors in the readable_author helper.
[phgross]
- Added zcml condition for extjs profile.
[Julian Infanger]
- Improve the dummy-column hack for improving the resize handle size of the
last column.
[jone]
- Ext JS: remove forceFit support (stretching column width) because we are now
able to define the column width in the definition, which is a more accurate
solution.
[jone]
- Support for defining column widths in dict-style columns using keyword "width".
[jone]
1.7.10 (2012-08-21)
-------------------
- Add a link() helper for creating a configured helper on the fly.
[jone]
1.7.9 (2012-05-16)
------------------
- Javascript: optimize reload table so that it does not make unecessary requests.
[jone]
1.7.8 (2012-05-09)
------------------
- Adjust comment in ITableSource inteface.
[eschmutz]
- Reduce duplicate request when using with tabbedview in non-extjs mode.
[jone]
1.7.7 (2012-03-28)
------------------
- Remove registerPackage directive.
[jone]
1.7.6 (2012-03-12)
------------------
- Improve spinner integration with tabbedview, use new helper functions.
[jone]
- Fix extjs bug when switching between listing tabs and non-listing with tabbed view.
[jone]
1.7.5 (2012-03-05)
------------------
- Fixed helpers, so they works with solr flares.
[Julian Infanger]
- Get portal_url in helpers with getToolByName
[Julian Infanger]
- Icon helper should not return a image if no icon is defined for this type.
[Julian Infanger]
1.7.4 (2012-02-28)
------------------
- Fixed stray single-quote in path_checkbox and path_radiobutton helpers
[lgraf]
- Show contenttype class in linked-helper if there is no icon for this type.
[Julian Infanger]
- Add extjs reset_grid_state function.
[jone]
1.7.3 (2012-02-27)
------------------
- removed contenttype span tag for sprites.
[mathias.leimgruber]
- Adjust different helpers: Made sure the tag content, and tag titles are correctly escaped.
[phgross]
1.7.2 (2012-02-24)
------------------
- Added Tests
[mathias.leimgruber]
- Add nosort class to all Columns that aren't sortable.
[ttschanz]
- Added some French translations
[ttschanz]
- Wrap icon class around objects icon.
[Julian Infanger]
- Show html structure in table header.
[Julian Infanger]
- Add support for condition functions in dict-based column definitions.
[jone]
- Add missing features of the default ftwtable jquery plugin implementation:
- Implement selecting of checkboxes.
- Use prepared features of the jquery plugin for supporting both implementations (extjs + default) better.
- Trigger events properly.
- Various javascript cleanup, remove unused stuff.
[jone]
1.7.1 (2011-11-17)
------------------
- Fix readable_author: should also work if fullname of user is None.
[jone]
1.7 (2011-10-07)
----------------
- fixed translations for extjs-table
[eschmutz]
1.6 (2011-09-29)
----------------
- adjust all translations, so that they use now the zope.i18n translate method
[eschmutz]
- added test-buildout for plone 4.1
[eschmutz]
1.5 (2011-07-13)
----------------
- enabled resizable also for the last column
[fsprenger]
- fixed batching_enabled attribute for the CatalogTableSource
[phgross]
1.4
---
- cleaned up package, moved it to github (https://github.com/4teamwork/ftw.table)
and prepared for release on pypi
[jbaumann]
1.3
---
- removed umlauts
[fsprenger]
1.2
---
- IE8 fix for selecting rows
[fsprenger]
1.1
---
- Make date helper methods failsave, if there's no valid date return None.
[25.01.2011, mathias.leimgruber]
1.1c11
------
1.1c10
------
- fixed translations
[ttschanz]
1.1c9
-----
- Extjs: fixed updating of static contents.
[jbaumann]
1.1c8
-----
- Do not show "groupBy" column in column menu -> make it not hideable.
[jbaumann]
- Do not allow to sort by "draggable" and to group at the same - this is contradicting.
[jbaumann]
- Extjs Checkbox: Protect-Layer was too small (firefox)
[jbaumann]
- Extjs: Fix for making batching work even when grouping enabled
[jbaumann]
- Extjs: removed ftwtable-prefix for state storage, since this is used for guessing the view later.
Also fixed typo in tabbedview check.
[jbaumann]
1.1c7
-----
- Fixed bug in extjs implementation: do not expect tabbedview to be there, but use it if it is
[jbaumann]
1.1c6
-----
- Do not allow to sort descending on the "draggable" column in extjs, because it does not make sense at may break the ordering.
[jbaumann]
- Fix ordering bug, which caused that the ID of the row was missing in the extjs store
[jbaumann]
- Read sort_on attribute from grid storage
[jbaumann]
1.1c5
-----
- Implemented server-side grouping in table sources.
[jbaumann]
1.1c4
-----
1.1c3
-----
- Disabled translation of column titles in template, since it would not work in json mode too.
You need to switch from tuple column definition to dict column definition or to Column-object
definition where you can translate the column title in your own domain using Message objects.
[jbaumann]
1.1
---
- added htmlentities replacing in the linked and quick_preview helper
[phgross]
1.0a5
-----
- added quick_preview helper
[phgross]
1.0a4
-----
- changed TableGenerator to use without the standard listing template and use a specific template
[pgross]
1.0a3
-----
1.0a2
-----
1.0
---
- Initial release