Wiki source code of Live Table component
Version 7.1 by ElenaOanaTabaranu on 2009/07/06
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | 1 Live Table component | ||
| 2 | |||
| 3 | #warning("This section documents a feature that is only available starting with XWiki Enterprise 1.9M2.") | ||
| 4 | |||
| 5 | #toc("" "" "") | ||
| 6 | |||
| 7 | 1.1 Summary | ||
| 8 | |||
| 9 | 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. The video below demonstrate the main capabilities of the live table component: | ||
| 10 | |||
| 11 | {pre} | ||
| 12 | <object width="640" height="401"><param name="allowfullscreen" value="true" /><param name="allowscriptaccess" value="always" /><param name="movie" value="http://vimeo.com/moogaloop.swf?clip_id=4474332&server=vimeo.com&show_title=1&show_byline=0&show_portrait=0&color=ffffff&fullscreen=1" /><embed src="http://vimeo.com/moogaloop.swf?clip_id=4474332&server=vimeo.com&show_title=1&show_byline=0&show_portrait=0&color=ffffff&fullscreen=1" type="application/x-shockwave-flash" allowfullscreen="true" allowscriptaccess="always" width="640" height="401"></embed></object> | ||
| 13 | {/pre} | ||
| 14 | |||
| 15 | 1.1 How to use | ||
| 16 | |||
| 17 | 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] | ||
| 18 | |||
| 19 | 1.1.1 Using the Velocity <tt>#livetable</tt> macro | ||
| 20 | |||
| 21 | 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. | ||
| 22 | |||
| 23 | |||
| 24 | The signature of the macro is the following : | ||
| 25 | |||
| 26 | {code} | ||
| 27 | #macro(livetable $id $columns $columnsProperties $options) | ||
| 28 | {code} | ||
| 29 | |||
| 30 | Each parameter allows to control the output generated by the macro. Namely: | ||
| 31 | |||
| 32 | * <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. | ||
| 33 | * <tt>$columns</tt> is an array that holds the ordered list of columns to display in the table. | ||
| 34 | * <tt>$columnsProperties</tt> is a hash of properties (options) to customize the behavior of each of the columns | ||
| 35 | * <tt>$options</tt> is a hash with general options (as opposed to columns options) for the table. | ||
| 36 | |||
| 37 | The following sections give more details and examples about the three last parameters, <tt>$options</tt>, <tt>$columns</tt> and <tt>$columnsProperties</tt>. | ||
| 38 | |||
| 39 | 1.1.1.1 Parameter <tt>$options</tt> | ||
| 40 | |||
| 41 | 1.1.1.1.1 Example | ||
| 42 | |||
| 43 | {code} | ||
| 44 | #set($myTableOptions = { | ||
| 45 | "className":"XWiki.XWikiUsers", | ||
| 46 | "translationPrefix" : "xe.index.users.", | ||
| 47 | "tagCloud" : true, | ||
| 48 | "rowCount": 10 | ||
| 49 | }) | ||
| 50 | {code} | ||
| 51 | |||
| 52 | 1.1.1.1.1 All accepted values | ||
| 53 | |||
| 54 | {table} | ||
| 55 | Option name|Description|Default value | ||
| 56 | *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> | ||
| 57 | *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> | ||
| 58 | *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> | ||
| 59 | *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> | ||
| 60 | *defaultOrder*|The default order to sort on the selected column. Accepted values are <tt>asc</tt> and <tt>desc</tt>|<tt>asc</tt> | ||
| 61 | *rowCount*|The maximum number of rows to display in one page of the table.|<tt>15</tt> | ||
| 62 | *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> | ||
| 63 | *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> | ||
| 64 | *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> | ||
| 65 | *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> | ||
| 66 | {table} | ||
| 67 | |||
| 68 | 1.1.1.1 Parameter <tt>$columns</tt> | ||
| 69 | |||
| 70 | This parameters allows to define columns the Live Table should be presenting. 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 a 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 perfomed. The table below the example summarize all possible values that can be passed to the <tt>$columns</tt> array. | ||
| 71 | |||
| 72 | 1.1.1.1.1 Example | ||
| 73 | |||
| 74 | {code} | ||
| 75 | #set($myColumns = ["_avatar", "first_name", "last_name", "email", "doc.creationDate", "_actions"]) | ||
| 76 | {code} | ||
| 77 | |||
| 78 | 1.1.1.1.1 All accepted values | ||
| 79 | |||
| 80 | {table} | ||
| 81 | Name|Description | ||
| 82 | doc.name|The name of the document (for example, *WebHome*, in Sandbox.WebHome). | ||
| 83 | doc.title|The title of the document. | ||
| 84 | doc.space|The space of the document (for example, *Sandbox*, in Sandbox.WebHome). | ||
| 85 | doc.fullName|The full name of the document (for example *Sandbox.WebHome*). | ||
| 86 | doc.creationDate|The date at which the document was created. | ||
| 87 | doc.creator|The username of the user that created the document. | ||
| 88 | doc.author|The username of the last author of the document. | ||
| 89 | doc.date|The date at which the document has been last modified. | ||
| 90 | *${propertyName}*|Any property of an XWiki Class the table is bound to. (See the <tt>className</tt> parameter of the <tt>$option</tt> argument for more information on how to bind a table to a XWiki Class). | ||
| 91 | _images|A special column to display all images attached to the retrieved document. | ||
| 92 | _attachments|A special column to display links to all attachments of the retrieved document. | ||
| 93 | _actions|A special column to display a list of actions that can be performed by administrators on the matched documents. | ||
| 94 | _avatar|A special column to display the user avatar. Work only for a table bound to the <em>XWiki.XWikiUsers</em> XWiki class. | ||
| 95 | {table} | ||
| 96 | |||
| 97 | 1.1.1.1 Parameter <tt>$columnsProperties</tt> | ||
| 98 | |||
| 99 | 1.1.1.1.1 Example | ||
| 100 | |||
| 101 | {code} | ||
| 102 | #set($columnsProperties = { | ||
| 103 | "_avatar" : { "type" : "none", "link" : "none", "html" : "true", "sortable":false }, | ||
| 104 | "first_name" : { "type" : "text" , "size" : 20, "link" : "view"}, | ||
| 105 | "last_name" : { "type" : "text", "link" : "view"}, | ||
| 106 | "email" : { "type" : "text" } | ||
| 107 | }) | ||
| 108 | {code} | ||
| 109 | |||
| 110 | 1.1.1.1.1 All accepted values | ||
| 111 | |||
| 112 | * Document and object fields options: | ||
| 113 | |||
| 114 | {table} | ||
| 115 | Name|Descriptions|Default value | ||
| 116 | <tt>filterable</tt>|Should the column present a filter on its header?|<tt>true</tt> | ||
| 117 | <tt>sortable</tt>|Should the column be available as a sort key?|<tt>true</tt> | ||
| 118 | <tt>type</tt>|For filtarable columns, the type of filter for the column. Also allows to hide a column. Possible values in <tt>hidden</tt>, <tt>text</tt>, <tt>list</tt>, <tt>number</tt>.|<em>None</em> (no type) | ||
| 119 | <tt>size</tt>|The size of the filter field. CSS might override this value to make the field 100%.|<em>None</em> | ||
| 120 | <tt>link</tt>|The type of link to use for the field value, in <tt>view</tt>, <tt>field<tt>, <tt>none</tt>. "view" links to the page corresponding to the row. "field" links to hte page corresponding to the field value (for DBListClass). "hidden" hides the column. "none" has not link.|<em>None</em> (no link) | ||
| 121 | <tt>html</tt>|Should the returned value be treated as HTML and injected as is in the row ?|<tt>false</tt> | ||
| 122 | {table} | ||
| 123 | |||
| 124 | ## 1.1.1 HTML + JavaScript ## |
