Export ▼

More actions ▼

Extensions Wiki » Extensions Wiki » Livetable Macro

Livetable Macro

Last modified by Vincent Massol on 2012/03/17

Comments (2) · Annotations (0) · Attachments (0) · History · Information

Displays a dynamic, filterable and sortable table of data

Type	Macro (Velocity)
Developed by	XWiki Development Team
License	GNU Lesser General Public License 2.1

Bundled With	XWiki Enterprise, XWiki Enterprise Manager
Compatibility	XWiki Enterprise >= 1.9M2

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 :

#livetable($id $columns $columnsProperties $options)

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

#set($myTableOptions = {
   "className":"XWiki.XWikiUsers",
   "translationPrefix" : "xe.index.users.",
   "tagCloud" : true,
   "rowCount": 10
})

All accepted values

Option name	Description	Default value	Since
className	The full name of the XWiki page holding the class definition for the type of data to display in the table. For example: XWiki.XWikiUsers to display pages with objects of type users. If no className is given (nor any of the resultPage or url options - see below), the table will display all pages of the wiki. *This parameter can be ignored by a custom data source if either the resultPage* or the url parameters are used.**	None
resultPage	The full name of the page to use as a JSON data provider for the table. This option allows to use a different data source than the default one (XWiki.LiveTableResults) for specific needs not handled by LiveTableResults (for example: complex cross-classes queries, external data retrieved with a groovy script, etc.). *This parameter will be ignored if the url* parameter is used.**	None
url	This is similar to resultPage, except that it accepts an URL instead of the full name of the page to obtain results from. This allows for example to add extra query parameters.	None
selectedColumn	The name of the column on which to sort the live table by default. If this option is absent, the first sortable column met in the `$columns` array will be used.	None
defaultOrder	The default order to sort on the selected column. Accepted values are `asc` and `desc`	`asc`
rowCount	The maximum number of rows to display in one page of the table.	`15`
maxPages	The maximum number of pages links to display in the pagination UI (Not including the links to the first and last pages that will always be displayed).	`10`
translationPrefix	A string to prefix table translation keys with (for names of columns for example) in order to have different display messages (translated strings) for different tables.	None
tagCloud	Display a tag cloud filter and display interface to allow users to see entries matching particular tags and to see which tags match the current filter selection	`false`
callback	An advanced option to pass the name of a JavaScript method as custom handler of matched rows, leaving the responsibility of the DOM construction of the row entry, and its injection in the table to this method. This option should be used when complex manipulations are needed to construct row entries, which is not possible to do using the default handler. You can see an usage example of this option in the "All Attachments" UI in the XWiki Enterprise document index.	None
extraParams	Used to add extra parameters to the Ajax request for the resultPage which generates the JSON data. Must start with an "&". Example: "extraParams" : "&page=MySpace.PageName". You can also use this option to retrieve all the documents from a certain space ("extraParams" : "&space=${doc.space}"), from a certain parent ("extraParams" : "&parent=${doc.parent}") or all the objects that have a specific value for a property ("extraParams" : "&yourProperty=yourValue" - note that in this particular case, yourProperty has to be declared in the $columns array)	None
topFilters	HTML fragment that will be placed in a "top filter" area in the same fashion as the Tag Cloud filter. All filters elements (`input`, `select`) in this fragment will be automatically used as filters for the livetable.	None	2.3 RC 1
pageSize	Display a selection box to allow users to change the number of rows displayed per page in the table	`true`	2.4 M1
pageSizeBounds	Defines 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, which means 10, 20, 30, ..., 90 and 100 in the proposed list of sizes.	`[10,100,10]`	2.4 M1

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

#set($myColumns = ["_avatar", "first_name", "last_name", "email", "doc.creationDate", "_actions"])

All accepted values

Name	Description
doc.name	The name of the document (for example, WebHome, in Sandbox.WebHome).
doc.title	The title of the document.
doc.space	The space of the document (for example, Sandbox, in Sandbox.WebHome).
doc.fullName	The full name of the document (for example Sandbox.WebHome).
doc.creationDate	The date at which the document was created.
doc.creator	The username of the user that created the document.
doc.author	The username of the last author of the document.
doc.date	The date at which the document has been last modified.
${propertyName}	Any property of an XWiki Class the table is bound to. (See the `className` parameter of the `$option` argument for more information on how to bind a table to a XWiki Class).
_images	A special column to display all images attached to the retrieved document.
_attachments	A special column to display links to all attachments of the retrieved document.
_actions	A special column to display a list of actions that can be performed by administrators on the matched documents.
_avatar	A special column to display the user avatar. Works only for a table bound to the XWiki.XWikiUsers XWiki class.

Parameter `$columnsProperties`

Example

#set($columnsProperties = {
   "_avatar" : { "type" : "none", "link" : "none", "html" : "true", "sortable":false },
   "first_name" : { "type" : "text" , "size" : 20, "link" : "view"},
   "last_name" : { "type" : "text", "link" : "view"},
   "email" : { "type" : "text" }
})

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?	`true`¹
`sortable`	Should the column be available as a sort key?	`true`
`type`	For filterable columns, the type of filter for the column. Also allows to hide a column. Possible values in `hidden`, `text`, `list`, `number`.	None (no 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 the field value, in `view`, `field`, `none`. "view" links to the page corresponding to the row. "field" links to the page corresponding to the field value (for DBListClass). "hidden" hides the column. "none" has not link.	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`.	None

Examples

The user directory

#set($columns = ["_avatar", "first_name", "last_name", "email", "doc.creationDate", "_actions"])
#set($columnsProperties = {
    "_avatar" : { "type" : "none", "link" : "none", "html" : "true", "sortable":false },
    "first_name" : { "type" : "text" , "size" : 20, "link" : "view"},
    "last_name" : { "type" : "text", "link" : "view"},
    "email" : { "type" : "text" }
})
#set($options = {
   "className":"XWiki.XWikiUsers",
   "translationPrefix" : "xe.index.users.",
   "tagCloud" : true,
   "rowCount": 10
})
#livetable("userdirectory" $columns $columnsProperties $options)

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

#set($options = {
   "url" : "$xwiki.getURL('XWiki.LiveTableResults', 'get', 'outputSyntax=plain&transprefix=xe.index.users.&classname=XWiki.XWikiUsers&collist=_avatar,first_name,last_name,email,doc.creationDate')",
   "translationPrefix" : "xe.index.users.",
   "tagCloud" : true,
   "rowCount": 10
})

Demo (Video)

Document Index

#set($collist = ['doc.name', 'doc.space', 'doc.date', 'doc.author'])
#set($colprops = {
'doc.name' : { 'type' : 'text' , 'size' : 30, 'link' : 'view' },
'doc.space' : { 'type' : 'text', 'link' : 'space' },
'doc.date' : { 'type' : 'date' },
'doc.author' : { 'type' : 'text', 'link' : 'author' }
})
#set($options = {
'translationPrefix' : 'xe.index.',
'rowCount' : 15,
'description' : 'This table lists all the documents found on this wiki. The columns can be sorted and some can be filtered.'
})
#if(!$isGuest)
#set($discard = $collist.add('_actions'))
#set($discard = $colprops.put('_actions', { 'actions' : ['copy', 'delete', 'rename', 'rights'] }))
#end
#livetable('alldocs' $collist $colprops $options)

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.

#set($columns = ["org_name", "org_domain"])
#set($columnsProperties = {
    "org_name" : { "type" : "text" , "size" : 20, "link" : "view"},
    "org_domain" : { "type" : "list", "class": "MySpace.OrganizationClass"}
})

#set($options = {
   "resultPage":"MySpace.ListOrganizationJSON",
   "translationPrefix" : "",
   "rowCount": 10
})
#livetable("organization_directory" $columns $columnsProperties $options)

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

{{include document="XWiki.LiveTableResultsMacros" /}}

{{velocity}}
#gridresultwithfilter("MySpace.OrganizationClass" $request.collist.split(",") "" " and doc.name<>'OrganizationSheet' and doc.name<>'OrganizationTemplate'")
{{/velocity}}

All Attachments

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

{{velocity}}
#set($ok = $xwiki.jsx.use('XWiki.AllAttachments'))
##
#set($collist = ["filename", "doc.name","doc.space", "doc.date", "doc.author", "type"])
#set($colprops = {
                   "filename" : { "type" : "text" , "size" : 10 },
                   "doc.name" : { "type" : "text" , "size" : 10 },
                   "doc.space" : { "type" : "text" , "size" : 10 },
                   "doc.date" : { "type" : "date" , "size" : 10, "filterable":false},
                   "doc.author": { "type" : "text" , "size" : 10 },
                   "type" : {"sortable": false}
                 })
#set($options = { "url":"$xwiki.getURL('XWiki.AllAttachmentsResults')?xpage=plain&outputSyntax=plain",
                  "callback" : "XWiki.index.displayAttachmentEntry",
                  "translationPrefix" : "xe.index.attachments." })
#livetable('allattachments' $collist $colprops $options)

(% id="inaccessibleDocsMessage" class="hidden" %)
(((
{{info}}$msg.get("rightsmanager.documentrequireviewrights"){{/info}}
)))
{{/velocity}}

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

XWiki.index.displayAttachmentEntry = function (row, i, table) {
  var inaccessibleDocs = false;
if(row.acclev == true) {
    var fileLink = new Element('a', {'href' : row.fileurl}).update(row.filename);
    var tr = new Element('tr').update(new Element('td').update(fileLink));
    var pageLink = new Element('a', {'href' : row.url}).update(row.page);
    tr.appendChild(new Element('td', {'class' : 'pagename'}).update(pageLink));
    var spaceLink = new Element('a', {'href' : row.spaceurl}).update(row.space);
    tr.appendChild(new Element('td', {'class' : 'spacename'}).update(spaceLink));
    tr.appendChild(new Element('td').update(row.date));
    var aa = new Element('a', {'href' : row.authorurl}).update(row.authorname);
    tr.appendChild(new Element('td').update(aa));
    var type = new Element('td').update(getMimeTypeImage(row.type));
    tr.appendChild(type);
   return tr;
  } else {
    var tr = new Element('tr');
    var page = row.fullname;
    var td1 = new Element('td').update("unavailable");
    var td2 = new Element('td', {'class' : 'pagename'}).update(page + "*");
    var td3 = new Element('td').update(" ");
    var td4 = new Element('td').update(" ");
    var td5 = new Element('td').update(" ");
    var td6 = new Element('td').update(" ");
    tr.appendChild(td1);
    tr.appendChild(td2);
    tr.appendChild(td3);
    tr.appendChild(td4);
    tr.appendChild(td5);
    tr.appendChild(td6);
    $('inaccessibleDocsMessage').removeClassName('hidden');
   return tr;
  }
}

Custom JSON

Here's a minimal working example, displaying two fields ("user" and "message").

Page using the livetable:

{{velocity}}
#set($columns = [ "user" , "message" ])
#set($columnsProperties = {
    "user" : { "type" : "text" },
    "message" : { "type" : "text"}
})

#set($options = {
    "resultPage":"Space.MyJSON"
})

#livetable("twitter" $columns $columnsProperties $options)
{{/velocity}}

Space.MyJSON Page:

{{velocity}}
#if("$!{request.xpage}" == 'plain')
  $response.setContentType('application/json')
#end
##==============================
## Offset = item # at which to start displaying data
##==============================
#set($offset = $util.parseInt($request.get('offset')))
## offset starts from 0 in velocity and 1 in javascript
#set($offset = $offset - 1)
#if($offset < 0)
  #set($offset = 0)
#end
##==================
## Limit = # of items to display
##==================
#set($limit = $util.parseInt($request.get('limit')))
##==================
## Tag = one parameter per tag
##==================
#if($request.tag)
  #foreach($tag in $request.getParameterValues('tag'))
    ## TODO: Add code to filter items based on the selected tags
  #end
#end
##==========
## Sort direction
##==========
#set($order = "$!request.sort")
#if($order != '')
  #set($orderDirection = "$!{request.get('dir').toLowerCase()}")
  #if("$!orderDirection" != '' && "$!orderDirection" != 'asc')
    #set($orderDirection = 'desc')
  #end
#end
## ===========
## Filter Data here...
## ===========
## TODO: Add code to filter data
## Each column can be filtered and the filter for a column can be retrieved with:
## #set($filterValue = "$!{request.get(<columnname>)}")

## ===
## JSON
## ===
{
"totalrows": 1,
"matchingtags": {},
"tags" : [],
"returnedrows": 1,
"offset": 1,
"reqNo": $util.parseInt($request.reqNo),
"rows": [{
  "doc_viewable" : true,
  "user" : "vincent",
  "message" : "my message"
}]
}
{{/velocity}}

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:

http://localhost:8080/xwiki/bin/get/Space/MyJSON?outputSyntax=plain&transprefix=&classname=&collist=user,message&offset=1&limit=15&reqNo=4&message=t&sort=user&dir=asc

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:

{{include document="XWiki.LiveTableResultsMacros" /}}

{{velocity}}
#if("$!{request.xpage}" == 'plain')
  $response.setContentType('application/json')
#end
##==================
## Initialize the map that will store the JSON data.
##==================
#set($map = {})
##==================
## Build the JSON in memory using the previous map
##==================
#gridresult_buildJSON("$!request.classname" $request.collist.split(',') $map)
##==================
## Modify the JSON data from the map or add new data.
##==================
#set($discard = $map.put('new_table_property', 'some value'))
#foreach($row in $map.get('rows'))
  #if($row.get('doc_hasedit'))
    ## Add an additional constraint for the edit right (just an example).
    #set($rowDoc = $xwiki.getDocument($row.get('doc_fullName')))
    #if($rowDoc.getObject('SomeSpace.SomeClass').getProperty('foo').value != 'bar')
      #set($discard = $row.put('doc_hasedit', false))
    #end
  #end
  #set($discard = $row.put('new_row_property', 'some other value'))
#end
##==================
## Serialize the map in the JSON format.
##==================
$jsontool.serialize($map)
{{/velocity}}

This example is purely fictional and you should do something like this for real since it would slow down your wiki a lot as it loads Document objects for a lot of row for each Livetable request!

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:

xwikiorg.extensions.emptyvalue = No value specified
xwikiorg.extensions.[yourValue] = Some other value

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

xwikiorg.extensions.emptyvalue =

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.)

How do I filter on doc.title

It's not possible to filter on doc.title.

^ except for doc.title, because filtering on doc.title is not possible

Tags: table UI Component appearance

Created by Asiri Rathnayake on 2009/09/10

Livetable Macro

Description

Usage

Parameter $options

Example

All accepted values

Parameter $columns

Example

All accepted values

Parameter $columnsProperties

Example

All accepted values

Examples

The user directory

Demo (Video)

Document Index

Filter organizations by domain

All Attachments

Custom JSON

FAQ

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

How do I translate the action buttons

How do I filter on doc.title

Download XWiki

My Recent Modifications

About

Projects

XWiki Enterprise

Extensions

XWiki Office

XWiki Manager

XWiki Eclipse

Other

Platform

User Guide

Admin Guide

Developer Guide

Contribute

Status

Under the Hood

Practices

Get Involved

Support

Get Connected

Parameter `$options`

Parameter `$columns`

Parameter `$columnsProperties`