Displays a dynamic, filterable and sortable table of data

Description

The most common use case of the livetable macro is displaying a table of documents that contains an XWiki Object of a certain class. This is a powerful way for in-wiki applications developers to offer a mining interface on their application data (for example Contacts in a CRM/Contact manager, Bills in a Billing application, etc.).

Usage

The signature of the macro is the following :

Each parameter allows to control the output generated by the macro. Namely:

• $id is a string identifier that allows to distinguish this table from others. This permits to have several tables on the same page. This id is used in the generated HTML as prefix for some elements' ids.
• $columns is an array that holds the ordered list of columns to display in the table.
• $columnsProperties is a hash of properties (options) to customize the behavior of each of the columns
• $options is a hash with general options (as opposed to columns options) for the table.

The following sections give more details and examples about the last three parameters, $options, $columns and $columnsProperties.

Parameter $options

Example

All accepted values

Parameter $columns

This parameter allows to define the columns of the Live Table. There are 3 major types of columns a table can declare: document columns, which will be displaying (and filtering on) metadata on the document (such as its author, date of last modification, etc.), object properties columns, for the case the table is bound to an XWiki Class, and special columns, for columns which are not handled by the first two types, such as the list of attachments of a document, the actions that can be performed. The table below in the example summarizes all the possible values that can be passed to the $columns array.

Example

All accepted values

Parameter $columnsProperties

Example

All accepted values

• Document and object fields options:

  Name	Descriptions	Default value	Since
  displayName	The name to display as a column header for this column (wins over the translationPrefix table option) (Note: available starting with XE 2.3)	None	2.3
  filterable	Should the column present a filter on its header?	true12
  sortable	Should the column be available as a sort key?	true
  type	For filterable columns, the type of filter for the column. Valid values are: hidden (allows to hide a column) text list number boolean since 8.2M2 multilist since 8.2M2 (allows the user to filter on multiple values of a list) date since 9.5RC1  suggest since 9.8 (supported by Database List, List of Users and List of Groups property types).	None (no type)
  match	(6.3M1+) For filterable columns, specifies how the filter value should be matched against the stored value. Possible values are: exact, partial, prefix. The default live table results page is currently supporting this option for the following property types: StringProperty, LargeStringProperty and DBStringListProperty. Custom live table results pages might not provide this option.	None (depends on the column data type)
  size	The size of the filter field. CSS might override this value to make the field 100%.	None
  link	The type of link to use for this column. The following options are available, in order: auto: link to the URL provided by the <columnName>_url row property from the JSON results, if present, otherwise fall back on the doc_url property field: same as auto but without the fallback; this can be used for instance with Database List properties in order to link the column value to the corresponding XWiki document editor: link to edit the corresponding object property (requires LiveTable Property Editor) <property>: link to the URL provided by the doc_<property>_url row property from the JSON results, if present, otherwise fall back on the doc_url property. The following properties are currently supported by the default live table results JSON: author, space, wiki, XWiki 9.1+ edit, copy, delete, rename, rights. You can of course use other properties as long as you add doc_<property>_url to your custom JSON results. Note that you need to set the doc_viewable row property to true in order for these values to be taken into account. Leave this empty or don't specify it at all if you don't want to link the column value.	None (no link)
  html	Should the returned value be treated as HTML and injected as is in the row ?	false
  headerClass	The name of an optional CSS class to add to the column HTML table column header.	None	2.3 RC 1
  class	Specifies the full name of the XWiki class for the type of data to display in the table. Used by the filtering options in the live table header, when the $options hash has resultPage key instead of className or when the column comes from a different object than the one pointed to by className .	None

• _actions options:

  Name	Descriptions	Default value	Since
  actions	The list of actions to display on this column. An action can be specified as a string (the action name) or as a map with more advanced action properties. The following list of actions are supported by the default live table results page: view, edit, copy, rename, delete, rights. The action URL for each row is specified by the doc_actionName_url field in the live table JSON. E.g.: 'actions': [  'edit', 'delete',   {    'id': 'custom',    'label': 'Custom',    'icon': 'eye',    'async': true,    'callback': 'callSomeJavaScriptFunction()'   }, {     ...   } ]	[]

Examples

The user directory

The url option can also be used to generate the user directory:

Demo (Video)

Document Index

Filter organizations by domain

The organization class in the example below has two properties: an org_name of type String and an org_domain of type StaticList. The organization domain can have values like Software or Hardware, which will be used in the live table as filter options.

The content of MySpace.ListOrganizationJSON (using syntax 2.0): 

All Attachments

The livetable rows can also be created using a Javascript callback function. For example, the Attachments tab on Document Index:

The callback function created the columns for each row using the JSON generated by the url parameter:

Documents with date range

The following code will display a Livetable listing all documents that have been modified in the last 2 days. Requires XWiki 9.5RC1+

Custom JSON

Here's a minimal working example, displaying two fields ("user" and "message"). A slightly more elaborate example can be found in the code of the Link Checker extension.

Page using the livetable:

Generate new JSON

Space.MyJSON Page:

Note that in order to support paging, filtering and sorting you'll need to handle the following URL parameters:

• offset: value at which to start displaying data in the livetable
• limit: number of items to display in the livetable
• <columnFilter>: a filtering string entered for the column named columnFilter
• sort: the name of the column on which to sort
• dir: the sorting direction ("asc" or "desc")

For example here's the request sent if you typed the letter t in the message column:

Also note, that doc_viewable row attribute is notably use to display an info message about hidden pages when set to false, and might used for some options, so better to always specify it. 

Modify the default JSON

Starting with XWiki Enterprise 4.0 you can modify the default JSON before it is sent to the client side to feed the live table. Space.MyJSON page could look like this:

Responsiveness

Since 6.2.2, with the Flamingo Skin, the livetable is responsive to the screen size. So if there is not enough place to display the table properly (for example: on a smartphone), the livetable will look differently.

Javascript events

Since the livetable is a dynamic javascript based widget, as a developer, you may want to add some specific handling on various events of the livetable. See the dedicated section of the javascript API documentation for information about the available events.

FAQ

How do I translate "emptyvalue" found in cells and column titles

Create a translation page that you register as a Document Resource Bundle and use the translationPrefix value as the key prefix. For example if you've used "translationPrefix" : "xwikiorg.extensions." then use:

If you don't want to display any text use:

How do I translate the action buttons

Create a translation page that you register as a Document Resource Bundle and use the following translation keys as the key prefix for the _actions column:

• <translationPrefix>._actions.<action>
• platform.livetable._actions.<action>

The translationPrefix refers to the livetable option parameter and the action refers the values of the _actions  column parameters ( rename, rights, delete, copy, etc.)

What is the issue with filtering on doc.title not working "as expected"

This is explained in detail here: Why does filtering on doc title in a livetable not work as expected.

How is possible to add preview links next to Office documents listed in the _attachments column

Need to modify XWiki.LiveTableResultsMacros. In this page existing macro livetable_getAttachmentsList with original source code:

This macro should be changed like this:

How to debug an issue with the Livetable display

You need to check the returned JSON first and verify it's valid. To get the JSON use Firebug for Firefox or Developer Tools for Chrome and go the Network view. You'll see a request such as:

Open this URL in your browser, this will give you the JSON. Copy-paste it on the  JSONLint page for example and validate it.
If it's invalid then you need the JSON generation code.
(Add &sql=1 at previous URL to see query computed and parameters)

1. ^ note that filtering on doc.title does not work as expected and was disabled before XWiki 10.9
2. ^ Before 9.5RC1 only list, text, number are filterable. Since 9.5RC1, date type columns can also be filtered. If you are on an older version, you can try out the extension for a date filter.