Wiki source code of Live Table component
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | #info("This document is a work in progress") | ||
| 2 | |||
| 3 | 1 Live Table component | ||
| 4 | |||
| 5 | #warning("This section documents a feature that is only available starting with XWiki Enterprise 1.9M2. This version is not released yet. You can [stay in touch with the Roadmap>http://enterprise.xwiki.org/xwiki/bin/view/Main/Roadmap#HXWikiEnterprise19] or [grab a snapshot>http://maven.xwiki.org/snapshots/com/xpn/xwiki/products/xwiki-enterprise-jetty-hsqldb/1.9-SNAPSHOT/].") | ||
| 6 | |||
| 7 | #toc("" "" "") | ||
| 8 | |||
| 9 | 1.1 Summary | ||
| 10 | |||
| 11 | The *"Live Table"* component is a dynamic table loading data lazily using ajax requests as the user browse the table, in order to scale easily the display of very large amounts of data. Users can browse the table thanks to a pagination system. Filters on columns are available to search for specific entries. Columns can be made sortable in both direction. Below | ||
| 12 | |||
| 13 | 1.1 How to use | ||
| 14 | |||
| 15 | The Live Table component is made available in several ways to [Applications>code:Applications.WebHome] developers and developers of the [XWiki platform and products>dev:Main.WebHome], depending on their specific needs. The simplest, and most of the times preferred, way to embed a Live Table component is to use the <tt>#livetable</tt> velocity macro, available in all pages of your wiki. With only one call to this macro, you will be able to display a live table of the data of your choice! For more specific needs, in the cases you need more control on the table behavior, or to build another component on top of the live table, it is possible to instantiate the live table from JavaScript. In this case, you, as opposed to the velocity macro, you will need to construct the HTML elements the JavaScript component expects yourself, either from JavaScript, either writing the [HTML directly in your wiki page>platform:Main.XWikiSyntax] | ||
| 16 | |||
| 17 | 1.1.1 Using the Velocity <tt>#livetable</tt> macro | ||
| 18 | |||
| 19 | One velocity macro call is enough to display a live table of wiki data. The most common use case is displaying a table of documents that contains an [XWiki Object of a certain class>platform:DevGuide.DataModel]. 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.). Since Users in XWiki are managed and stored using the Class and Object abstraction of [XWiki Data Model>platform:DevGuide.DataModel], we will illustrate usages of the <tt>#livetable</tt> velocity macro to create a dynamic user directory. | ||
| 20 | |||
| 21 | The signature of the macro is the following : | ||
| 22 | |||
| 23 | {code} | ||
| 24 | #macro(livetable $id $columns $columnsProperties $options) | ||
| 25 | {code} | ||
| 26 | |||
| 27 | Each parameter allows to control the output generated by the macro. Namely: | ||
| 28 | |||
| 29 | * <tt>$id</tt> is a string identifier that allows to distinguish this table from others. This permits to have several tables on the same pages. This id is used in the generated HTML as prefix for some elements ids. | ||
| 30 | * <tt>$columns</tt> is an array that holds the list of columns to display in the table. | ||
| 31 | * <tt>$columnsProperties</tt> is a hash of properties (options) to customize the behavior of each of the columns | ||
| 32 | * <tt>$options</tt> is a hash with general options (as opposed to columns options) for the table. | ||
| 33 | |||
| 34 | The following sections give more details and examples about the three last parameters, <tt>$options</tt>, <tt>$columns</tt> and <tt>$columnsProperties</tt>. | ||
| 35 | |||
| 36 | 1.1.1.1 Parameter <tt>$options</tt> | ||
| 37 | |||
| 38 | 1.1.1.1.1 Example | ||
| 39 | |||
| 40 | {code} | ||
| 41 | #set($myTableOptions = { | ||
| 42 | "className":"XWiki.XWikiUsers", | ||
| 43 | "translationPrefix" : "xe.index.users.", | ||
| 44 | "tagCloud" : true, | ||
| 45 | "rowCount": 10 | ||
| 46 | }) | ||
| 47 | {code} | ||
| 48 | |||
| 49 | 1.1.1.1.1 All accepted values | ||
| 50 | |||
| 51 | {table} | ||
| 52 | Option name|Description|Default value | ||
| 53 | *className*|The full name of the XWiki page holding the class definition for the type of data to display in the table. For example: <em>XWiki.XWikiUsers</em> to display pages with objects of type users. If no className is precised (and none of the *resultPage* or *url* option is precised as well - see below), the table will display all pages of the wiki|<em>None</em> | ||
| 54 | *resultPage*|The full name of the page to use as a JSON data provider for the table. This options 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 a <em>className</em>* parameter has been precised.|<em>None</em> | ||
| 55 | *url*|This is similar as *resultPage*, except that it accepts a URL in place of the full name of the page to obtain results from. This allows for example to add extra query parameters. *This parameter will be ignored if at least one of the <em>className</em> or <em>resultPage</em> is precised.*|<em>None</em> | ||
| 56 | *selectedColumn*|The name of the column on which to sort the live table by default. If none is precised, the first sortable column met in the <tt>$columns</tt> array will be used.|<em>None</em> | ||
| 57 | *defaultOrder*|The default order to sort on the selected column. Accepted values are <tt>asc</tt> and <tt>des</tt>|<tt>asc</tt> | ||
| 58 | *rowCount*|The maximum number of rows to display in one page of the table.|<tt>15</tt> | ||
| 59 | *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).|<tt>10</tt> | ||
| 60 | *translationPrefix*|The 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.|<em>None</em> | ||
| 61 | *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|<tt>false</tt> | ||
| 62 | *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 are 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.|<em>None</em> | ||
| 63 | {table} | ||
| 64 | |||
| 65 | 1.1.1 HTML + JavaScript |
