XWiki Grid Component Tutorial

The XWiki Grid Component is a very powerfull AJAX component which allows to implement a progressive navigation inside documents from a specific XWiki Class within minutes. It is quite configurable to allow to use the wished columns and provide some behavior for each column data when it is shown. The components allows on the fly filtering and sorting as well as in place editing of a property of on of the displayed documents. 

This document describes how to use and configure the grid component.

Demo of Grid component

A demo of the Grid component is available on the incubator 

Example of a Grid component call in XWiki Syntax 1.0

## syntax 1.0 example
#includeMacros("XWiki.GridExtensionMacros")
## optional GWT prop editor. This is needed if the link "editor" is used
#gwtpropeditor()
#set($collist = [ "first_name", "last_name","blog", "imtype", "email", "doc.creator", "_attachment", "_avatar"])
#set($colprops = {
                   "first_name" : { "type" : "text" , "size" : 10, "link" : "view"}, 
                   "last_name" : { "type" : "text" , "size" : 10, "link" : "view"},
                   "blog" : { "type" : "text" , "size" : 20, "link" : "none"},
                   "imtype" : { "type" : "list" , "size" : 1, "link" : "none"},
                   "email" : { "type" : "text" , "size" : 20, "link" : "editor"},
                   "doc.creator" : { "type" : "text" , "size" : 20, "link" : "field"},
                   "_attachment" : { "type" : "none" , "size" : 20, "link" : "none", "html" : "true" },
                   "_photolist" : { "type" : "none" , "size" : 20, "link" : "none", "html" : "true" },
                   "_avatar" : { "type" : "none" , "size" : 20, "link" : "none", "html" : "true" }
                 })
## id of the div, list of columns, columns properties, default column to sort for, class name
## protect with pre
#grid("users" $collist $colprops "last_name" "asc" "user_" "XWiki.XWikiUsers" 4)
## protect with /pre

Example of a Grid component call in XWiki Syntax 2.0

{{velocity}}
{{include document="XWiki.GridExtensionMacros2" /}}
## optional GWT prop editor
#gwtpropeditor()
#set($collist = [ "first_name", "last_name","blog", "imtype", "email", "doc.creator", "_attachment", "_avatar"])
#set($colprops = {
                   "first_name" : { "type" : "text" , "size" : 10, "link" : "view"}, 
                   "last_name" : { "type" : "text" , "size" : 10, "link" : "view"},
                   "blog" : { "type" : "text" , "size" : 20, "link" : "none"},
                   "imtype" : { "type" : "list" , "size" : 1, "link" : "none"},
                   "email" : { "type" : "text" , "size" : 20, "link" : "editor"},
                   "doc.creator" : { "type" : "text" , "size" : 20, "link" : "field"},
                   "_attachment" : { "type" : "none" , "size" : 20, "link" : "none", "html" : "true" },
                   "_photolist" : { "type" : "none" , "size" : 20, "link" : "none", "html" : "true" },
                   "_avatar" : { "type" : "none" , "size" : 20, "link" : "none", "html" : "true" }
                 })
## id of the div, list of columns, columns properties, default column to sort for, class name 
#grid("users" $collist $colprops "last_name" "asc" "user_" "XWiki.XWikiUsers" 4)
{{/velocity}}

Documentation

• Grid Column list

#set($collist = [ "first_name", "last_name","blog", "imtype", "email", "doc.creator", "_attachment", "_avatar"])

List of colums to use in the grid. The columns need to be part of the class used in the grid macro. There are some special columns:

• doc.creator Creator
• doc.creationDate Creation Date
• doc.date Update Date
• doc.author Author
• doc.version Version
• _avatar Avatar if the page is a user
• _attachment List of attachments to the page. "html" : "true" is required in column properties.
• _photolist List of photos attached to the page. "html" : "true" is required in column properties.
• _rating Rating of the document (if ratings plugin installed)
• Grid Column properties

#set($colprops = {
                   "first_name" : { "type" : "text" , "size" : 10, "link" : "view"}, 
                   "last_name" : { "type" : "text" , "size" : 10, "link" : "view"},
                   "blog" : { "type" : "text" , "size" : 20, "link" : "none"},
                   "imtype" : { "type" : "list" , "size" : 1, "link" : "none"},
                   "email" : { "type" : "text" , "size" : 20, "link" : "editor"},
                   "doc.creator" : { "type" : "text" , "size" : 20, "link" : "field"},
                   "_attachment" : { "type" : "none" , "size" : 20, "link" : "none", "html" : "true" },
                   "_photolist" : { "type" : "none" , "size" : 20, "link" : "none", "html" : "true" },
                   "_avatar" : { "type" : "none" , "size" : 20, "link" : "none", "html" : "true" }
                 })

The column properties lists for each column a set of properties

• Grid macro call

#grid("users" $collist $colprops "last_name" "asc" "user_" "XWiki.XWikiUsers" 4)

Advanced Grid functions

• gridwithdatapage sets a specific Data Page for returning data for the grid

#gridwithdatapage($divid $collist $colprops $colselected $colselectedorder $transprefix $className $customresultpage $nb)

This page can use the grid results macros. See Grid Results functions.

• gridwithdatapage sets a specific URL for returning data for the grid

#gridwithdataurl($divid $collist $colprops $colselected $colselectedorder $transprefix $dataurl $className $nb)

Advanced Grid results functions

• Standard gridresult

#includeMacros("XWiki.GridExtensionResultMacros")
## protected with pre
#gridresult($request.classname $request.collist.split(","))
## protected with /pre

• Advanced gridresult

#includeMacros("XWiki.GridExtensionResultMacros")
## protected with pre
#gridresultwithfilter($request.classname $request.collist.split(",") ", IntegerProperty as propactive", " and obj.id=propactive.id.id and propactive.id.name='active' and propactive.value=1")
## protected with /pre

The advanced grid result allows to extend the query used to retrieve data.