Wiki source code of Live Table component
Version 121.2 by Vincent Massol on 2009/09/14
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | = Live Table component = | ||
| 2 | |||
| 3 | {{velocity filter="indent"}} | ||
| 4 | {{html clean="false" wiki="true"}} | ||
| 5 | #warning("This document is a draft.") | ||
| 6 | |||
| 7 | #warning("This section documents a feature that is only available starting with XWiki Enterprise 1.9M2.") | ||
| 8 | |||
| 9 | {{toc start=2 depth=6 numbered=false scope=page /}} | ||
| 10 | |||
| 11 | == Summary == | ||
| 12 | |||
| 13 | 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. For a demonstration of the main capabilities of the live table component check out this [[video>>http://vimeo.com/4474332]]. | ||
| 14 | |||
| 15 | == 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 | === Using the Velocity livetable macro === | ||
| 20 | |||
| 21 | Please refer [[Live Table Macro>>code:Macros.LiveTableMacro]] reference. | ||
| 22 | |||
| 23 | === HTML + JavaScript === | ||
| 24 | |||
| 25 | This is a dynamic component which must me used carefully because of performance issues. The HTML content of the Live Table is automatically updated using Javascript and [[JSON>>http://www.json.org]] code generated with the [[Live Table Macro>>code:Macros.LiveTableMacro]]. | ||
| 26 | The Live Table component is build using the Prototype library as a class representing an AJAX-populated live table. The default variable name generated in XWiki Enterprise is **ta** and you can use it, for example to manipulate the display of the component's rows by calling <tt>ta.showRows()</tt>. | ||
| 27 | |||
| 28 | For more details, check the Javascript file **livetable.js** on your wiki at **{{{http://localhost:8080/xwiki/bin/skin/resources/js/xwiki/table/livetable.js}}}**. | ||
| 29 | |||
| 30 | === Example === | ||
| 31 | |||
| 32 | #warning("You need the Ratings plugin in your wiki to make the most of the example below.") | ||
| 33 | |||
| 34 | The Live Table component could be extended with a special column containing the ratings of some documents from the wiki. | ||
| 35 | The first step would be to generate the JSON code of the column we want to add. In order to achieve this goal we need to modify the result page of the velocity live table macro with our custom page **TutorialsCode.LiveTableRatings**: | ||
| 36 | |||
| 37 | {{code}} | ||
| 38 | #* | ||
| 39 | #set($collist = ["doc.name", "_ratings", "doc.date", "doc.author", "_actions"]) | ||
| 40 | |||
| 41 | #set($colprops = { | ||
| 42 | "doc.name" : { "type" : "text" , "size" : 30, "sortable":true, "filterable":true}, | ||
| 43 | "_ratings" : { "sortable":false}, | ||
| 44 | "doc.date" : { "type" : "date" }, | ||
| 45 | "doc.author" : { "type" : "text", "link" : "author"}, | ||
| 46 | "_actions" : { "actions": ["copy","delete","rename","rights"]} | ||
| 47 | }) | ||
| 48 | #set($options = { "resultPage":"TutorialsCode.LiveTableRatings", | ||
| 49 | "tagCloud" : true, | ||
| 50 | "translationPrefix" : "xe.index.", | ||
| 51 | "rowCount": 10 }) | ||
| 52 | #set($ok = $xwiki.ssx.use("TutorialsCode.LiveTableRatings")) | ||
| 53 | #set($ok = $xwiki.jsx.use("TutorialsCode.LiveTableRatings")) | ||
| 54 | #livetable("alldocs" $collist $colprops $options) *# | ||
| 55 | {{/code}} | ||
| 56 | |||
| 57 | If we want to display the rated documents from a certain space, e.g. **Tutorials**, the last parameter of the <tt>#gridresultwithfilter</tt> must contain the query we need. | ||
| 58 | |||
| 59 | {{code}} | ||
| 60 | #includeMacros("TutorialsCode.LiveTableResultsMacros") | ||
| 61 | |||
| 62 | #gridresultwithfilter("" $request.collist.split(",") "" "doc.space='Tutorials' and doc.name<>'WebHome' and doc.name<>'WebPreferences'") | ||
| 63 | |||
| 64 | {{/code}} | ||
| 65 | |||
| 66 | The page at **TutorialsCode.LiveTableResultsMacros** should contain a copy of the default code (the page is located at **XWiki.LiveTableResultsMacro**) for the live table result page. The next step implies extracting the rating information from the wiki pages located the **Tutorials** space. We add a new velocity macro which will test the presence of the rating object with class **XWiki.AverageRatingsClass** and extract the rating value. | ||
| 67 | |||
| 68 | {{code}} | ||
| 69 | ## | ||
| 70 | ## list ratings | ||
| 71 | ## | ||
| 72 | #macro(grid_ratings $udoc) | ||
| 73 | #set($ratings = "") | ||
| 74 | #set($ratingObj = "") | ||
| 75 | #set($ratingObj = $udoc.getObject("XWiki.AverageRatingsClass")) | ||
| 76 | #if("$!ratingObj" != "") | ||
| 77 | #set($ratings = $ratingObj.get("averagevote")) | ||
| 78 | #end | ||
| 79 | #end | ||
| 80 | {{/code}} | ||
| 81 | |||
| 82 | The continue our extension of this component, we need to add a test for the presence of our custom column to call the <tt>grid_ratings</tt> macro when generating the JSON: | ||
| 83 | {{/html}} | ||
| 84 | {{/velocity}} | ||
| 85 | |||
| 86 | {{code}} | ||
| 87 | ... | ||
| 88 | #elseif($colname=="_images") , | ||
| 89 | #grid_photolist($udoc) | ||
| 90 | "${colname}" : "${photolist}" | ||
| 91 | #elseif($colname=="_ratings"), | ||
| 92 | #grid_ratings($udoc) | ||
| 93 | "${colname}" : "${ratings}" | ||
| 94 | #else , | ||
| 95 | ... | ||
| 96 | {{/code}} | ||
| 97 | |||
| 98 | #info("Firebug can be a useful tool when testing the JSON code generated.") | ||
| 99 | |||
| 100 | Transforming the rating information to a nice star display requires using Javascript to replace the content of that column with the proper HTML. Attach the image below to your **TutorialsCode.LiveTableRatings** page to change the default white background when hovering on the stars. | ||
| 101 | |||
| 102 | [[image:star-table.gif||style="margin-right: 1em;"]] | ||
| 103 | |||
| 104 | |||
| 105 | Add an on-demand Javascript Extension with a content which can be parsed and use the code below to enrich your component: | ||
| 106 | |||
| 107 | {{code}} | ||
| 108 | /** Display ratings in the live table on row event */ | ||
| 109 | document.observe("xwiki:livetable:newrow", function(ev) { | ||
| 110 | $$('._ratings').each(function (el) { | ||
| 111 | // update content | ||
| 112 | var avgvote = 0.0; | ||
| 113 | if (el.innerHTML !== "") { | ||
| 114 | avgvote = parseFloat(el.innerHTML); | ||
| 115 | } | ||
| 116 | var wstyle = 0; | ||
| 117 | if (avgvote > 0) { | ||
| 118 | wstyle = avgvote * 20; | ||
| 119 | el.innerHTML="<div class='avg-rating'><div class='rating-stars'><ul class='small-star-rating'><li style='width: " + wstyle +"%;' class='current-rating'/><li><a class='one-star' href='#' onclick='return false;'>1</a></li><li><a class='two-stars' href='#' onclick='return false;'>2</a></li><li><a class='three-stars' href='#' onclick='return false;'>3</a></li><li><a class='four-stars' href='#' onclick='return false;'>4</a></li><li><a class='five-stars' href='#' onclick='return false;'>5</a></li></ul></div></div>"; | ||
| 120 | } else if(el.innerHTML === ""){ | ||
| 121 | el.innerHTML="<div class='avg-rating'><div class='rating-stars'><ul class='small-star-rating'><li style='width: 0%;' class='current-rating'/><li><a class='one-star' href='#' onclick='return false;'>1</a></li> <li><a class='two-stars' href='#' onclick='return false;'>2</a></li><li><a class='three-stars' href='#' onclick='return false;'>3</a></li><li><a class='four-stars' href='#' onclick='return false;'>4</a></li><li><a class='five-stars' href='#' onclick='return false;'>5</a></li></ul></div></div>"; | ||
| 122 | } | ||
| 123 | }); | ||
| 124 | document.fire("xwiki:livetable:ready", { | ||
| 125 | }); | ||
| 126 | }); | ||
| 127 | /** Update ratings images on hover event aka mouse over and mouse out.*/ | ||
| 128 | document.observe("xwiki:livetable:ready", function(levent) { | ||
| 129 | $$('.xwiki-livetable-display-body tr').each(function (elem) { | ||
| 130 | Event.observe(elem, 'mouseover', function (ev) { | ||
| 131 | var ratings = elem.down('._ratings'); | ||
| 132 | if(ratings) { | ||
| 133 | // update default white stars background | ||
| 134 | var elt = ratings.down(2); | ||
| 135 | elt.setStyle({ | ||
| 136 | backgroundImage: 'url($xwiki.getDocument("TutorialsCode.LiveTableRatings").getAttachmentURL("star-table.gif"))', | ||
| 137 | backgroundPosition: '0% 0%' | ||
| 138 | }); | ||
| 139 | // update votes background | ||
| 140 | elt = ratings.down(3); | ||
| 141 | elt.setStyle({ | ||
| 142 | backgroundImage: 'url($xwiki.getDocument("TutorialsCode.LiveTableRatings").getAttachmentURL("star-table.gif"))', | ||
| 143 | backgroundPosition: '0% 50%' | ||
| 144 | }); | ||
| 145 | } | ||
| 146 | }); | ||
| 147 | Event.observe(elem, 'mouseout', function (ev) { | ||
| 148 | var ratings = elem.down('._ratings'); | ||
| 149 | if(ratings) { | ||
| 150 | // restore default white stars background | ||
| 151 | var elt = ratings.down(2); | ||
| 152 | elt.setStyle({ | ||
| 153 | backgroundImage: 'url($xwiki.getDocument("XWiki.Ratings").getAttachmentURL("star.gif"))', | ||
| 154 | backgroundPosition: '0% 0%' | ||
| 155 | }); | ||
| 156 | // restore votes background | ||
| 157 | elt = elem.down('._ratings').down(3); | ||
| 158 | elt.setStyle({ | ||
| 159 | backgroundImage: 'url($xwiki.getDocument("XWiki.Ratings").getAttachmentURL("star.gif"))', | ||
| 160 | backgroundPosition: '0% 50%' | ||
| 161 | }); | ||
| 162 | } | ||
| 163 | }); | ||
| 164 | |||
| 165 | }); | ||
| 166 | }); | ||
| 167 | {{/code}} | ||
| 168 | |||
| 169 | Also, add some CSS in an on-demand Stylesheet extension with a content which can be parsed to polish the custom column display: | ||
| 170 | |||
| 171 | {{code}} | ||
| 172 | /* ratings for live table */ | ||
| 173 | .small-star-rating, | ||
| 174 | .small-star-rating .current-rating { | ||
| 175 | background: url($xwiki.getDocument("XWiki.Ratings").getAttachmentURL("star.gif")) left -1000px repeat-x; | ||
| 176 | } | ||
| 177 | .small-star-rating{ | ||
| 178 | position:relative; | ||
| 179 | width:125px; | ||
| 180 | height:25px; | ||
| 181 | overflow:hidden; | ||
| 182 | list-style:none; | ||
| 183 | margin:0px !important; | ||
| 184 | padding:0px !important; | ||
| 185 | background-position: left top; | ||
| 186 | } | ||
| 187 | .small-star-rating li{ | ||
| 188 | display: inline; | ||
| 189 | } | ||
| 190 | .small-star-rating a, | ||
| 191 | .small-star-rating .current-rating{ | ||
| 192 | position:absolute; | ||
| 193 | top:0; | ||
| 194 | left:0; | ||
| 195 | text-indent:-1000em; | ||
| 196 | height:25px; | ||
| 197 | line-height:25px; | ||
| 198 | outline:none; | ||
| 199 | overflow:hidden; | ||
| 200 | border: none; | ||
| 201 | } | ||
| 202 | .small-star-rating .current-rating{ | ||
| 203 | z-index:1; | ||
| 204 | background-position: left center; | ||
| 205 | } | ||
| 206 | .small-star-rating:hover, | ||
| 207 | .small-star-rating:active, | ||
| 208 | .small-star-rating:focus { | ||
| 209 | background-image: url($xwiki.getDocument("TutorialsCode.LiveTableRatings").getAttachmentURL("star-table.gif")); | ||
| 210 | background-repeat: repeat-x; | ||
| 211 | background-position: top left; | ||
| 212 | } | ||
| 213 | .small-star-rating a.one-star{ | ||
| 214 | width:20%; | ||
| 215 | z-index:6; | ||
| 216 | } | ||
| 217 | .small-star-rating a.two-stars{ | ||
| 218 | width:40%; | ||
| 219 | z-index:5; | ||
| 220 | } | ||
| 221 | .small-star-rating a.three-stars{ | ||
| 222 | width:60%; | ||
| 223 | z-index:4; | ||
| 224 | } | ||
| 225 | .small-star-rating a.four-stars{ | ||
| 226 | width:80%; | ||
| 227 | z-index:3; | ||
| 228 | } | ||
| 229 | .small-star-rating a.five-stars{ | ||
| 230 | width:100%; | ||
| 231 | z-index:2; | ||
| 232 | } | ||
| 233 | .rating-stars { | ||
| 234 | display: inline; | ||
| 235 | float: left; | ||
| 236 | clear: none; | ||
| 237 | } | ||
| 238 | {{/code}} | ||
| 239 | |||
| 240 | The final result should look like this: | ||
| 241 | |||
| 242 | [[image:livetabel.png||style="margin-right: 1em;"]] |
