Livetable Macro

The "Livetable" macro is mostly used for displaying a table of documents containing an XWiki Object.


The signature of the {{livetable /}} macro is: #livetable($id $columns $columnsProperties $options).

  • $id is a string identifier that allows you to distinguish this table from others and this way it allows you to have several tables on the same page. This id is used in the generated HTML as a 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 needed to customize the behavior of each column.
  • $options is a hash with general options for the table. 

The $columns Parameter

This parameter allows you to define the livetable columns.

There are 3 major types of columns a table can declare: 

  • document columns for displaying and filtering the metadata of the document, such as the author, the last modification date.
  • object properties columns for a table bound to an XWiki class.
  • special columns for columns which are not handled by the first two types, such as the list of attachments, the actions that can be performed. 

Accepted Values

doc.nameThe name of the document.
doc.titleThe title of the document.
doc.spaceThe space of the document.
doc.fullNameThe full name of the document. 
doc.creationDateThe creation date.
doc.creatorThe username of the author.
doc.authorThe username of the last author.
doc.dateThe date of the last change on the document.
${propertyName}Any class property the table is bound to. (See the className parameter of the $option argument for more information on how to bind a table to an XWiki class).
_imagesA special column to display all images attached to the retrieved document.
_attachmentsA special column to display links to all the attachments of the retrieved document.
_actionsA special column to display a list of actions that can be performed by administrators on the matched documents.
_avatarA special column to display the user avatar. This works only for a table bound to the "XWiki.XWikiUsers" class.

The $columnsProperties Parameter

Accepted Values

NameDescriptionsDefault value
displayNameThe pretty name of the column header.None
filterabletrue if the column has a filter header.true
sortabletrue if the column is available as a sort key.true 

For filterable columns it represents the filter type and it also allows you to hide a column. The possible values are:

  • hidden
  • text
  • list
  • number
  • boolean
  • multilist - allows to filter on multiple values from a list
  • date
  • suggest - supported by Database List, List of Users and List of Groups property types
None (no type)
sizeThe size of the filter field. CSS might override this value to make the field 100%.None 
linkThe type of link to use for the field value. The possible values are:
  • auto - link to the URL provided by the <columnName>_url row property from the JSON results; falls back on the doc_url property
  • view - link to the page corresponding to the row
  • field - link to the page corresponding to the field value (for DatabaseList properties)
  • editor - link to edit the corresponding object property
  • author - link to the URL provided by the doc_author_url row property from the JSON results
  • space - link to the URL provided by the doc_space_url row property from the JSON results
  • wiki - link to the URL provided by the doc_wiki_url row property from the JSON results
None (no link)
htmltrue if the returned value will be treated as HTML and injected into the row.false 
headerClassThe name of an optional CSS class to add to the column header of a HTML table.None
classSpecifies the full name of the XWiki class for the type of data displayed in the table. This is used by the filtering options of the live table header, when the $options hash has a resultPage key instead of className.None
matchDedicated parameter for filterable columns which specifies how the filter should be matched against the stored value. The default live table results page is currently supporting this option for the following 3 property types: StringProperty, LargeStringProperty and DBStringListProperty. The possible values are:
  • exact
  • partial
  • prefix
None because it depends on the column data type.

The $options Parameter

Accepted Values

Option nameDescriptionDefault value
classNameThe full name of the XWiki page holding the class definition for the type of data to display in the table.
For instance: "XWiki.XWikiUsers" displays pages containing user objects. If no className is given  the table will display all the wiki pages.
resultPageThe full name of the page to use as a JSON data provider for the table. This option allows you to use a data source, other than the default one which is "XWiki.LiveTableResults". This parameter will be ignored if a className parameter is present.None 
urlThis is similar to resultPage, except that it accepts an URL instead of the full name of the page it will obtain results from. This option allows you to add extra query parameters. The parameter will be ignored if at least one of the optionsclassName or resultPage is present.None 
selectedColumnThe name of the column on which to sort the live table by default. If this option is not present, the first sortable column from the $columns array will be used.None 
defaultOrderThe default order to sort on the selected column. The accepted values are asc and desc.asc
rowCountThe maximum number of rows to display in one page of the table.15 
maxPagesThe maximum number of links to pages displayed in the pagination UI (Not counting the links to the first and last pages that will always be displayed).10 
translationPrefixA string to prefix the table translation keys with (for names of columns for example) in order to have different display messages (translated strings) for different tables.None 
tagCloudDisplays a tag cloud filter and an interface which allows users to see entries matching particular tags and the tags matching the current filter selection.false 
callbackAn advanced option for passing the name of a JavaScript method as custom handler of the matched rows. This method takes care of the row entry DOM construction and of its injection into the table.None 
extraParamsUsed to add extra parameters to the Ajax request for the resultPage which generates the JSON data.
Example: "extraParams" : "page=MySpace.PageName".
topFiltersThe HTML fragment that will be placed into a "top filter" area in the same way as the Tag Cloud filter. All filter elements (input, select) in this fragment will be automatically used as filters for the livetable.None
pageSizeDisplay a selection box for users to change the number of rows displayed per page in the table.true
pageSizeBoundsDefines the page sizes available in the selection box that allows users to change the number of rows displayed per page in the table. This should be a valid initialization of a JavaScript array of 3 integer values: the minimum page size, the maximum page size, and the steps between proposed page sizes. The default value propose a selection between 10 and 100 with a step of 10.[10,100,10]
outputOnlyHtmlIf set to true, it ensures that the output of the livetable macro is only HTML markup without the syntax specific wrappers ({{html}}{{/html}} macro wrapper for syntax 2.0 or {pre}{/pre} wrappers for syntax 1.0). It is most useful when using the livetable macro inside filesystem velocity templates. false


Related Pages

Trying to decide between Cloud and On Premise? See the comparison on the XWiki Help Center.

Search this space