[infodrom/rico3] / documentation / LiveGrid.html
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">\r
2 <html>\r
3 <head>\r
4 <meta http-equiv="Content-Type" content="text/html;charset=utf-8">
5 <title>Rico LiveGrid</title>\r
6 <link href="ricoDocs.css" rel="Stylesheet" type="text/css">
7 </head>\r
8 \r
9 <body>\r
10 <h1>Creating a Rico LiveGrid</h1>\r
11 \r
12 <p>Rico LiveGrid displays data in a scrolling table, with the data buffered in a \r
13 2-dimensional JavaScript array. As the user scrolls\r
14 vertically through the grid, data is dynamically copied from the array onto the grid.\r
15 The buffer can can be loaded from:\r
16 <ol>\r
17 <li><a href='#model1'>a javascript array</a>\r
18 <li><a href='#model2'>an HTML table</a>\r
19 <li><a href='#model3'>an XML file</a>\r
20 <li><a href='#model4'>a SQL database query</a>\r
21 <li><a href='#model5'>a custom javascript callback function</a>\r
22 </ol>\r
23 \r
24 \r
25 <h2><a name='model1'>Usage Model 1: Loading data from a javascript array</a></h2>\r
26 \r
27 <ul><li>Load the data to be displayed into a javascript array.\r
28 <pre>\r
29   var myData = [\r
30     [1,'Cell 1:2','Cell 1:3','Cell 1:4','Cell 1:5'],\r
31     [2,'Cell 2:2','Cell 2:3','Cell 2:4','Cell 2:5'],\r
32     [3,'Cell 3:2','Cell 3:3','Cell 3:4','Cell 3:5'],\r
33     [4,'Cell 4:2','Cell 4:3','Cell 4:4','Cell 4:5']\r
34   ];\r
35 </pre>\r
36 \r
37 <li>Load the Rico javascript and css files necessary to display the grid.\r
38 <pre>\r
39 Rico.loadModule('LiveGrid','LiveGridMenu','greenHdg.css');\r
40 </pre>\r
41 <dl>\r
42 <dt>LiveGrid\r
43 <dd>This loads the Rico javascript and css files necessary to display a LiveGrid \r
44 with a static buffer (no AJAX).\r
45 <dt>LiveGridMenu\r
46 <dd>This loads the default grid menu. This menu provides access to all of the LiveGrid capabilities.\r
47 It adjusts the selections presented to the user based on the column selected \r
48 and the type of buffer used.\r
49 You can also choose to use the grid with no menu at all, or to create your own menu\r
50 customized to the needs of your application.\r
51 <dt>greenHdg.css\r
52 <dd>Rico comes with several sample grid styles: coffee-with-milk,\r
53 grayedout, greenHdg, iegradient (Internet Explorer only), tanChisel, and warmfall. \r
54 You may choose one of the included styles or create one of your own. \r
55 </dl>\r
56 \r
57 <li>Load the array into a Rico Buffer object:\r
58 <pre>\r
59   var buffer=new Rico.Buffer.Base();\r
60   buffer.loadRowsFromArray(myData);\r
61 </pre>\r
62 \r
63 <li>Define the grid's options, including the grid headings:\r
64 <pre>\r
65   var opts = {  \r
66     defaultWidth : 90,\r
67     visibleRows  : 'data',\r
68     frozenColumns: 1,\r
69     columnSpecs  : [{Hdg:'Column 1',type:'number', ClassName:'alignright'},\r
70                     {Hdg:'Column 2'},\r
71                     {Hdg:'Column 3'},\r
72                     {Hdg:'Column 4'},\r
73                     {Hdg:'Column 5'}]\r
74   };\r
75 </pre>\r
76 \r
77 <li>Instantiate the LiveGrid, passing in the base id for the grid, \r
78 the Rico.Buffer instance, and the grid options.\r
79 <pre>\r
80   var ex1=new Rico.LiveGrid ('ex1', buffer, opts);\r
81 </pre>\r
82 \r
83 <li>To enable the default pop-up menu for the grid, assign the grid's\r
84 menu property to an instance of Rico.GridMenu.\r
85 <pre>\r
86   ex1.menu=new Rico.GridMenu();\r
87 </pre>\r
88 \r
89 <li>Rico.loadModule may finish <em>after</em> the window.onload event.\r
90 So to ensure that the grid initialization runs after the Rico modules\r
91 have loaded, you must pass the initialization function to the\r
92 Rico.onLoad method. Putting all of the javascript together would look like this:\r
93 <pre>\r
94 &lt;script type='text/javascript'&gt;\r
95 Rico.loadModule('LiveGrid','LiveGridMenu','greenHdg.css');\r
96 \r
97 Rico.onLoad( function() {\r
98   var myData = [\r
99     [1,'Cell 1:2','Cell 1:3','Cell 1:4','Cell 1:5'],\r
100     [2,'Cell 2:2','Cell 2:3','Cell 2:4','Cell 2:5'],\r
101     [3,'Cell 3:2','Cell 3:3','Cell 3:4','Cell 3:5'],\r
102     [4,'Cell 4:2','Cell 4:3','Cell 4:4','Cell 4:5']\r
103   ];\r
104   var opts = {  \r
105     defaultWidth : 90,\r
106     visibleRows  : 'data',\r
107     frozenColumns: 1,\r
108     columnSpecs  : [{Hdg:'Column 1',type:'number', ClassName:'alignright'},\r
109                     {Hdg:'Column 2'},\r
110                     {Hdg:'Column 3'},\r
111                     {Hdg:'Column 4'},\r
112                     {Hdg:'Column 5'}]\r
113   };\r
114   var buffer=new Rico.Buffer.Base();\r
115   buffer.loadRowsFromArray(myData);\r
116   var ex1=new Rico.LiveGrid ('ex1', buffer, opts);\r
117   ex1.menu=new Rico.GridMenu();\r
118 });\r
119 &lt;/script&gt;\r
120 </pre>\r
121 \r
122 <li>Finally, place a div element in your HTML markup at the position where the grid should go.\r
123 Including the markup for the bookmark will cause the grid's scroll position to be displayed.\r
124 <pre>\r
125 &lt;p class="ricoBookmark"&gt;&lt;span id="ex1_bookmark"&gt;&nbsp;&lt;/span&gt;&lt;/p&gt;\r
126 &lt;div id="ex1"&gt;&lt;/div&gt;\r
127 </pre>\r
128 \r
129 \r
130 \r
131 </ul>\r
132 \r
133 \r
134 <h2><a name='model2'>Usage Model 2: Loading data from an HTML table</a></h2>\r
135 \r
136 <ul><li>Define an HTML table with the headings in a <code>&lt;thead&gt;</code> section\r
137 and the data in a <code>&lt;tbody&gt;</code> section.\r
138 Including the markup for the bookmark will cause the grid's scroll position to be displayed.\r
139 <pre>\r
140 &lt;p class="ricoBookmark"&gt;&lt;span id="data_grid_bookmark"&gt;&nbsp;&lt;/span&gt;&lt;/p&gt;\r
141 &lt;table id="data_grid"&gt;\r
142   &lt;thead&gt;\r
143 \r
144   &lt;tr&gt;\r
145     &lt;th&gt;First column name&lt;/th&gt;\r
146     &lt;th&gt;Second column name&lt;/th&gt;\r
147     ...\r
148     &lt;th&gt;Last column name&lt;/th&gt;\r
149   &lt;/tr&gt;\r
150 \r
151   &lt;/thead&gt;\r
152 \r
153   &lt;tbody&gt;\r
154 \r
155   &lt;tr&gt;\r
156     &lt;td&gt;Row 1, column 1 data&lt;/td&gt;\r
157     &lt;td&gt;Row 1, column 2 data&lt;/td&gt;\r
158     ...\r
159     &lt;td&gt;Row 1, last column data&lt;/td&gt;\r
160   &lt;/tr&gt;\r
161 \r
162   &lt;tr&gt;\r
163     &lt;td&gt;Row 2, column 1 data&lt;/td&gt;\r
164     &lt;td&gt;Row 2, column 2 data&lt;/td&gt;\r
165     ...\r
166     &lt;td&gt;Row 2, last column data&lt;/td&gt;\r
167   &lt;/tr&gt;\r
168 \r
169   ...\r
170 \r
171   &lt;tr&gt;\r
172     &lt;td&gt;Row n, column 1 data&lt;/td&gt;\r
173     &lt;td&gt;Row n, column 2 data&lt;/td&gt;\r
174     ...\r
175     &lt;td&gt;Row n, last column data&lt;/td&gt;\r
176   &lt;/tr&gt;\r
177 \r
178   &lt;/tbody&gt;\r
179 &lt;/table&gt;\r
180 </pre>\r
181 \r
182 <li>Load the Rico javascript and css files necessary to display the grid.\r
183 <pre>\r
184 Rico.loadModule('LiveGrid','LiveGridMenu','greenHdg.css');\r
185 </pre>\r
186 <dl>\r
187 <dt>LiveGrid\r
188 <dd>This loads the Rico javascript and css files necessary to display a LiveGrid \r
189 with a static buffer (no AJAX).\r
190 <dt>LiveGridMenu\r
191 <dd>This loads the default grid menu. This menu provides access to all of the LiveGrid capabilities.\r
192 It adjusts the selections presented to the user based on the column selected \r
193 and the type of buffer used.\r
194 You can also choose to use the grid with no menu at all, or to create your own menu\r
195 customized to the needs of your application.\r
196 <dt>greenHdg.css\r
197 <dd>Rico comes with several sample grid styles: coffee-with-milk,\r
198 grayedout, greenHdg, iegradient (Internet Explorer only), tanChisel, and warmfall. \r
199 You may choose one of the included styles or create one of your own. \r
200 </dl>\r
201 \r
202 <li>Load the table's data rows into a Rico Buffer object:\r
203 <pre>\r
204 var buffer = new Rico.Buffer.Base($('data_grid').tBodies[0]);\r
205 </pre>\r
206 \r
207 <li>Finally, instantiate the LiveGrid, passing in the DOM id of the HTML table\r
208 (this allows the LiveGrid to load the column headings from the table's thead section), \r
209 the Rico.Buffer instance, and any options (in this case the first column gets\r
210 a width of 50 pixels and the second column gets a width of 80 pixels).\r
211 <pre>\r
212 var grid_options = { columnSpecs: [ {width:50}, {width:80} ] };\r
213 var grid = new Rico.LiveGrid('data_grid', buffer, grid_options);\r
214 </pre>\r
215 \r
216 <li>Rico.loadModule may finish <em>after</em> the window.onload event.\r
217 So to ensure that the grid initialization runs after the Rico modules\r
218 have loaded, you must pass the initialization function to the\r
219 Rico.onLoad method. Putting all of the javascript together would look like this:\r
220 <pre>\r
221 &lt;script type='text/javascript'&gt;\r
222 Rico.loadModule('LiveGrid','LiveGridMenu','greenHdg.css');\r
223 \r
224 Rico.onLoad( function() {\r
225   var buffer = new Rico.Buffer.Base($('data_grid').tBodies[0]);\r
226   var grid_options = { columnSpecs: [width:50, width:80] };\r
227   var grid = new Rico.LiveGrid('data_grid', buffer, grid_options);\r
228 });\r
229 &lt;/script&gt;\r
230 </pre>\r
231 \r
232 </ul>\r
233 \r
234 \r
235 <h2><a name='model3'>Usage Model 3: Loading data from an XML file</a></h2>\r
236 \r
237 <ul><li>Define an HTML table, supplying the table header cells, but no table body cells.\r
238 Including the markup for the bookmark will cause the grid's scroll position to be displayed.\r
239 <pre>\r
240 &lt;p class="ricoBookmark"&gt;&lt;span id="data_grid_bookmark"&gt;&nbsp;&lt;/span&gt;&lt;/p&gt;\r
241 &lt;table id="data_grid"&gt;\r
242   &lt;tr&gt;\r
243 \r
244     &lt;th&gt;First column name&lt;/th&gt;\r
245     &lt;th&gt;Second column name&lt;/th&gt;\r
246 \r
247   &lt;/tr&gt;\r
248 &lt;/table&gt;\r
249 </pre>\r
250 \r
251 <li>Load the Rico javascript and css files necessary to display the grid.\r
252 <pre>\r
253 Rico.loadModule('LiveGridAjax','LiveGridMenu','greenHdg.css');\r
254 </pre>\r
255 <dl>\r
256 <dt>LiveGridAjax\r
257 <dd>This loads the Rico javascript and css files necessary to display a LiveGrid \r
258 with an AJAX-enabled buffer.\r
259 <dt>LiveGridMenu\r
260 <dd>This loads the default grid menu. This menu provides access to all of the LiveGrid capabilities.\r
261 It adjusts the selections presented to the user based on the column selected \r
262 and the type of buffer used.\r
263 You can also choose to use the grid with no menu at all, or to create your own menu\r
264 customized to the needs of your application.\r
265 <dt>greenHdg.css\r
266 <dd>Rico comes with several sample grid styles: coffee-with-milk,\r
267 grayedout, greenHdg, iegradient (Internet Explorer only), tanChisel, and warmfall. \r
268 You may choose one of the included styles or create one of your own. \r
269 </dl>\r
270 \r
271 <li>Create a Rico Buffer, which fetches data to populate the table.\r
272 The AjaxXML buffer makes just one request for data to the supplied URL\r
273 at grid startup.\r
274 <pre>\r
275 var buffer = new Rico.Buffer.AjaxXML('/controller/action?format=xml');\r
276 </pre>\r
277 \r
278 The URL ("/controller/action?format=xml" in this example) must return data in the following format:\r
279 <pre>\r
280 &lt;ajax-response&gt;\r
281 &lt;response type='object' id='data_grid_updater'&gt;\r
282 &lt;rows update_ui='true' offset='0'&gt;\r
283 &lt;tr&gt;&lt;td&gt;Data for row 1, cell 1&lt;/td&gt;&lt;td&gt;Data for row 1, cell 2&lt;/td&gt;&lt;/tr&gt;\r
284 &lt;tr&gt;&lt;td&gt;Data for row 2, cell 1&lt;/td&gt;&lt;td&gt;Data for row 2, cell 2&lt;/td&gt;&lt;/tr&gt;\r
285 &lt;/rows&gt;\r
286 &lt;/response&gt;\r
287 &lt;/ajax-response&gt;\r
288 </pre>\r
289 \r
290 <li>Finally, instantiate the LiveGrid, passing in the DOM id of the HTML table, \r
291 the Rico.Buffer instance, and any options (columnSpecs is not required, \r
292 but shown here as a placeholder for customization of the columns).\r
293 <pre>\r
294 var grid_options = { columnSpecs: [,] };\r
295 var grid = new Rico.LiveGrid('data_grid', buffer, grid_options);\r
296 </pre>\r
297 \r
298 <li>Rico.loadModule may finish <em>after</em> the window.onload event.\r
299 So to ensure that the grid initialization runs after the Rico modules\r
300 have loaded, you must pass the initialization function to the\r
301 Rico.onLoad method. Putting all of the javascript together would look like this:\r
302 <pre>\r
303 &lt;script type='text/javascript'&gt;\r
304 Rico.loadModule('LiveGridAjax','LiveGridMenu','greenHdg.css');\r
305 \r
306 Rico.onLoad( function() {\r
307   var buffer = new Rico.Buffer.AjaxXML('/controller/action?format=xml');\r
308   var grid_options = { columnSpecs: [,] };\r
309   var grid = new Rico.LiveGrid('data_grid', buffer, grid_options);\r
310 });\r
311 &lt;/script&gt;\r
312 </pre>\r
313 </ul>\r
314 \r
315 \r
316 <h2><a name='model4'>Usage Model 4: Loading data from an SQL database query</a></h2>\r
317 \r
318 <p>The descriptions below apply directly to the ASP and PHP implementations of the Rico LiveGrid plug-ins.\r
319 The concepts are the same in .net, but the implementation is quite different \r
320 (examine ex2simple.aspx to see how this gets implemented in .net).\r
321 \r
322 <ul>\r
323 <li>Define a session variable that contains the query to be run. The variable name must\r
324 match the id of the table below. When requesting data, the grid will pass its id \r
325 to ricoXMLquery, and ricoXMLquery will use it to get the query text from\r
326 the session variable.\r
327 <ul>\r
328 <li>ASP:\r
329 <pre>\r
330 &lt;%\r
331 session.contents("data_grid")="select ID,Name,City from customers"\r
332 %&gt;\r
333 </pre>\r
334 \r
335 <li>PHP:\r
336 <pre>\r
337 &lt;? \r
338 $_SESSION['data_grid']="select ID,Name,City from customers";\r
339 ?&gt;\r
340 </pre>\r
341 \r
342 <li>.net:\r
343 <pre>\r
344 Sub Page_Load(Sender As object, e As EventArgs)\r
345   data_grid.sqlQuery="select ID,Name,City from customers"\r
346   ' session variable is set by the control\r
347 End Sub\r
348 </pre>\r
349 </ul>\r
350 \r
351 \r
352 <li>Define an HTML table, supplying the table header cells, but no table body cells.\r
353 Including the markup for the bookmark will cause the grid's scroll position to be displayed.\r
354 <pre>\r
355 &lt;p class="ricoBookmark"&gt;&lt;span id="data_grid_bookmark"&gt;&nbsp;&lt;/span&gt;&lt;/p&gt;\r
356 &lt;table id="data_grid"&gt;\r
357   &lt;tr&gt;\r
358 \r
359     &lt;th&gt;Customer #&lt;/th&gt;\r
360     &lt;th&gt;Customer Name&lt;/th&gt;\r
361     &lt;th&gt;City&lt;/th&gt;\r
362 \r
363   &lt;/tr&gt;\r
364 &lt;/table&gt;\r
365 </pre>\r
366 \r
367 <li>Load the Rico javascript and css files necessary to display the grid.\r
368 <pre>\r
369 Rico.loadModule('LiveGridAjax','LiveGridMenu','greenHdg.css');\r
370 </pre>\r
371 <dl>\r
372 <dt>LiveGridAjax\r
373 <dd>This loads the Rico javascript and css files necessary to display a LiveGrid \r
374 with an AJAX-enabled buffer.\r
375 <dt>LiveGridMenu\r
376 <dd>This loads the default grid menu. This menu provides access to all of the LiveGrid capabilities.\r
377 It adjusts the selections presented to the user based on the column selected \r
378 and the type of buffer used.\r
379 You can also choose to use the grid with no menu at all, or to create your own menu\r
380 customized to the needs of your application.\r
381 <dt>greenHdg.css\r
382 <dd>Rico comes with several sample grid styles: coffee-with-milk,\r
383 grayedout, greenHdg, iegradient (Internet Explorer only), tanChisel, and warmfall. \r
384 You may choose one of the included styles or create one of your own. \r
385 </dl>\r
386 \r
387 <li>Create a Rico Buffer, which fetches data to populate the table.\r
388 Unlike the AjaxXML buffer which fetches all grid data at once, the AjaxSQL\r
389 buffer fetches data in chunks. This makes it possible for LiveGrid to\r
390 efficiently display query results containing thousands, or even hundreds of thousands\r
391 of rows.\r
392 <pre>\r
393 var buffer = new Rico.Buffer.AjaxSQL('ricoXMLquery.asp');\r
394 </pre>\r
395 \r
396 The URL ("ricoXMLquery.asp" in this example) utilizes one of the included plug-ins to\r
397 fetch data from the database and return it to the grid in this XML format:\r
398 <pre>\r
399 &lt;ajax-response&gt;\r
400 &lt;response type='object' id='data_grid_updater'&gt;\r
401 &lt;rows update_ui='true' offset='0'&gt;\r
402 &lt;tr&gt;&lt;td&gt;Data for row 1, cell 1&lt;/td&gt;&lt;td&gt;Data for row 1, cell 2&lt;/td&gt;&lt;/tr&gt;\r
403 &lt;tr&gt;&lt;td&gt;Data for row 2, cell 1&lt;/td&gt;&lt;td&gt;Data for row 2, cell 2&lt;/td&gt;&lt;/tr&gt;\r
404 &lt;/rows&gt;\r
405 &lt;rowcount&gt;99&lt;/rowcount&gt;\r
406 &lt;/response&gt;\r
407 &lt;/ajax-response&gt;\r
408 </pre>\r
409 \r
410 The &lt;rowcount&gt; tag is optional, but should be returned whenever the "get_total"\r
411 querystring parameter is present in the request.\r
412 \r
413 <li>Finally, instantiate the LiveGrid, passing in the DOM id of the HTML table, \r
414 the Rico.Buffer instance, and any options (columnSpecs is not required, \r
415 but shown here as a placeholder for customization of the columns).\r
416 <pre>\r
417 var grid_options = { columnSpecs: [,,] };\r
418 var grid = new Rico.LiveGrid('data_grid', buffer, grid_options);\r
419 </pre>\r
420 \r
421 <li>Rico.loadModule may finish <em>after</em> the window.onload event.\r
422 So to ensure that the grid initialization runs after the Rico modules\r
423 have loaded, you must pass the initialization function to the\r
424 Rico.onLoad method. Putting all of the javascript together would look like this:\r
425 <pre>\r
426 &lt;script type='text/javascript'&gt;\r
427 Rico.loadModule('LiveGridAjax','LiveGridMenu','greenHdg.css');\r
428 \r
429 Rico.onLoad( function() {\r
430   var buffer = new Rico.Buffer.AjaxSQL('ricoXMLquery.asp');\r
431   var grid_options = { columnSpecs: [,,] };\r
432   var grid = new Rico.LiveGrid('data_grid', buffer, grid_options);\r
433 });\r
434 &lt;/script&gt;\r
435 </pre>\r
436 </ul>\r
437 \r
438 \r
439 <h2><a name='model5'>Usage Model 5: Loading data using a custom callback function</a></h2>\r
440 \r
441 <p>This model works the same way as models 3 and 4 except that, rather than fetching\r
442 data using an xmlHTTPrequest, the data is fetched using javascript callback functions.\r
443 This allows you to do creative things in the callback function - like call Google Gears.\r
444 Setting up the callback is very easy. Rather than passing a string containing the data provider's URL\r
445 to the AjaxXML or AjaxSQL constructor, you just pass the callback function instead.\r
446 \r
447 <p>The code that follows is taken from \r
448 <a href='client/gridJSbuffer.html'>examples/client/gridJSbuffer.html</a>, \r
449 which uses the AjaxXML buffer. The "jsfetch" callback function\r
450 returns a 2-dimensional array that is 100 rows long by 5 columns wide.\r
451 Note that AjaxXML only loads its buffer once (at grid startup), so\r
452 jsfetch will only be called once.\r
453 The options hash is identical in structure to the options hash used\r
454 by Prototype's <a href='http://prototypejs.org/api/ajax/options'>Ajax.Request</a> method.\r
455 \r
456 <pre>\r
457 buffer=new Rico.Buffer.AjaxXML(<strong>jsfetch</strong>);\r
458 \r
459 function <strong>jsfetch</strong>(options) {\r
460   Rico.writeDebugMsg("jsfetch");\r
461   var newRows=[], offset=options.parameters.offset;\r
462   for (var r=0; r<100; r++) {\r
463     var row=[];\r
464     row.push(offset.toString());\r
465     row.push(new Date().toString());\r
466     for (var c=2; c<5; c++) row.push('cell '+r+':'+c);\r
467     newRows.push(row);\r
468   }\r
469   options.onComplete(newRows);
470 }\r
471 </pre>\r
472 \r
473 <p>The code that follows is taken from \r
474 <a href='client/gridJSbuffer2.html'>examples/client/gridJSbuffer2.html</a>, \r
475 which uses the AjaxSQL buffer. The "jsfetch" callback function\r
476 simulates a 2-dimensional array that is 500 rows long by 5 columns wide.\r
477 However, only a section of that array is returned during any one callback --\r
478 just the rows from <code>options.parameters.offset</code> to\r
479 <code>options.parameters.offset + options.parameters.page_size</code>.\r
480 \r
481 <pre>\r
482 buffer=new Rico.Buffer.AjaxSQL(<strong>jsfetch</strong>);\r
483 \r
484 function <strong>jsfetch</strong>(options) {\r
485   var newRows=[], totrows=500;\r
486   var offset=options.parameters.offset;\r
487   var limit=Math.min(totrows-offset,options.parameters.page_size)\r
488   for (var r=0; r&lt;limit; r++) {\r
489     var row=[];\r
490     row.push(new Date().toString());\r
491     row.push(offset.toString());\r
492     for (var c=2; c&lt;5; c++) row.push('cell '+(r+offset)+':'+c);\r
493     newRows.push(row);\r
494   }\r
495   options.onComplete(newRows,false,totrows);
496 }\r
497 </pre>\r
498 \r
499 <p>options.onComplete takes the following parameters:\r
500 <ul>\r
501 <li>newRows - 2-dimensional array where each item is a string\r
502 <li>newAttr - 2-dimensional array where each item is an object containing acceptAttr values for the cell,\r
503 or false if acceptAttr is not being used\r
504 <li>totalRows - an integer representing the total number of rows in the dataset\r
505 <li>errMsg - if an error occurs, this is the message text to be displayed to the user\r
506 </ul>\r
507 \r
508 \r
509 <h2><a name='debug'></a>Debugging</h2>\r
510 <p>Rico 2.0 includes the ability to route time-stamped debug messages to a message log.\r
511 The log may be an html textarea or the browser's javascript console.\r
512 <ul>\r
513 <li>If a textarea exists with the id of the LiveGrid table plus '_debugmsgs', i.e.\r
514 <pre style='margin:3px;'>&lt;textarea cols="100" rows="5" id="data_grid_debugmsgs" /&gt;</pre>\r
515 then this textarea will be used for the message log.\r
516 <li>Alternatively, the textarea may be designated by a call to Rico.setDebugArea()\r
517 \r
518 <pre>\r
519 &lt;textarea id='debug' rows='5' cols='80'&gt;&lt;/textarea&gt;\r
520 &lt;script type='text/javascript'&gt;\r
521 Rico.setDebugArea('debug');\r
522 &lt;/script&gt;\r
523 </pre>\r
524 \r
525 <li>If no textarea is designated, Rico will attempt to use the browser's\r
526 built-in javascript console. The following consoles are known to work:\r
527   <ul>\r
528   <li>The console in Firefox's <a href='http://www.getfirebug.com/'>Firebug</a> add-on\r
529   <li>The Opera javascript console\r
530   <li>The Safari javascript console\r
531   <li>The console in <a href='http://blogs.msdn.com/ie/archive/2008/09/03/developer-tools-in-internet-explorer-8-beta-2.aspx'>IE8's Developer Toolbar</a> (under the Script tab)\r
532   </ul>\r
533 </ul>\r
534 \r
535 <p>LiveGrid is programmed to send a number of messages to the message log that may prove helpful in debugging.\r
536 You can also send your own messages by using Rico.writeDebugMsg(). For example:\r
537 <pre>\r
538 Rico.writeDebugMsg('My debug message');\r
539 </pre>\r
540 \r
541 <h2>Grid Menus</h2>\r
542 \r
543 <p>Rico LiveGrids come with a lot of functionality built in. To access that functionality,\r
544 Rico includes a default set of menus -- defined in ricoLiveGridMenu.js.\r
545 To use the default menu, simply load the 'LiveGridMenu' module and then\r
546 assign the grid's menu property to an instance of the Rico.GridMenu class.\r
547 <pre>\r
548   Rico.loadModule('LiveGridMenu');\r
549   ...\r
550   var ex1=new Rico.LiveGrid ('ex1', buffer, grid_options);\r
551   ex1.menu=new Rico.GridMenu();\r
552 </pre>\r
553 <p>By default, the menu will open when a user double-clicks on a grid cell.\r
554 To change the event that opens the menu, assign a value to the grid's\r
555 <a href='#menuEvent'>menuEvent</a> option. The following code will open the menu on a right-click:\r
556 <pre>\r
557   Rico.loadModule('LiveGridMenu');\r
558   ...\r
559   var grid_options = {\r
560     menuEvent: 'contextmenu'\r
561   }\r
562   var ex1=new Rico.LiveGrid ('ex1', buffer, grid_options);\r
563   ex1.menu=new Rico.GridMenu();\r
564 </pre>\r
565 <p>Rico.GridMenu provides a callback (dataMenuHandler) so that additional menu items can be added.\r
566 The grid menu is always built dynamically -- customized to the row and column the user\r
567 has clicked on. So the callback function is called every time the menu is invoked and\r
568 must add the desired menu items at each invocation.\r
569 <pre>\r
570   Rico.loadModule('LiveGridMenu');\r
571   ...\r
572   var ex1=new Rico.LiveGrid ('ex1', buffer, grid_options);\r
573   ex1.menu=new Rico.GridMenu();\r
574   ex1.menu.options.dataMenuHandler=myCustomMenuItems;\r
575   ...\r
576 function myCustomMenuItems(grid,r,c,onBlankRow) {\r
577   if (buffer.getWindowValue(r,c)=='Special Value')\r
578     grid.menu.addMenuItem("Special menu item", specialAction);
579 }\r
580 function specialAction() {\r
581   ...\r
582 }
583 </pre>\r
584 \r
585 <p>It is also possible to create completely custom menus. For an example,\r
586 see ex5.php/asp/aspx.\r
587 \r
588 \r
589 <h2>Notes</h2>\r
590 \r
591 <ul>\r
592 <li>If you create an element with a DOM id matching the name of the LiveGrid table \r
593 plus '_bookmark', it will be updated with text indicating \r
594 the number of records displayed in the grid. The LiveGrid examples typically use\r
595 this markup:\r
596 <pre>\r
597 &lt;p class="ricoBookmark"&gt;&lt;span id="data_grid_bookmark"&gt;&nbsp;&lt;/span&gt;&lt;/p&gt;\r
598 </pre>\r
599 <li>In order to display properly, a browser displaying a LiveGrid must be operating in \r
600 <a href="http://www.quirksmode.org/css/quirksmode.html">strict (aka standards) mode</a>.\r
601 Therefore, you must include a doctype declaration just before the \r
602 <code> &lt;html&gt; </code> tag. For example:\r
603 <pre>\r
604 &lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" \r
605  "http://www.w3.org/TR/html4/strict.dtd"&gt;\r
606 </pre>\r
607 </ul>\r
608 \r
609 \r
610 <h2>Reference</h2>\r
611 \r
612 <h3>Constructor</h3>\r
613 <pre>\r
614 \r
615   var grid = new Rico.LiveGrid (table_id, rico_buffer, grid_options);\r
616 \r
617 </pre>\r
618 \r
619 <ul>\r
620 <li><strong>table_id</strong> is the DOM id of the table (or div) that will be replaced by a LiveGrid\r
621 <li><strong>rico_buffer</strong> is a Rico Buffer object, e.g.\r
622   <ul>\r
623   <li>Rico.Buffer.Base (for non-AJAX tables)\r
624   <li>Rico.Buffer.AjaxXML\r
625   <li>Rico.Buffer.AjaxSQL\r
626   <li>Rico.Buffer.AjaxJSON\r
627   </ul>\r
628 <li><strong>grid_options</strong> (see below)\r
629 </ul>\r
630 \r
631 <h3><a name="options"></a>Options</h3>\r
632 \r
633 \r
634 <h4>Grid Size</h4>\r
635 <dl>\r
636 <dt>visibleRows (rows in .net plug-in)\r
637 <dd>How many rows of the grid are made visible?\r
638 A positive integer specifies that the grid should always contain exactly that many rows.\r
639 <p>Negative values have the following meanings:\r
640   <ul>\r
641   <li>-1: size grid to client window (default)\r
642   <li>-2: size grid to whichever is smaller: the client window or the data\r
643   <li>-3: size grid so that the page body does not have a scrollbar\r
644   <li>-4: size grid to the parent node in the DOM\r
645   </ul>\r
646 <p>String values have the following meanings:\r
647   <ul>\r
648   <li>'window': size grid to client window (default)\r
649   <li>'data': size grid to whichever is smaller: the client window or the data\r
650   <li>'body': size grid so that the page body does not have a scrollbar\r
651   <li>'parent': size grid to the parent node in the DOM\r
652   <li>'XX%': size grid to XX percent of the total window height\r
653   <li>'XXpx': size grid to XX pixels\r
654   </ul>\r
655   \r
656 <dt>minPageRows\r
657 <dd>Minimum # of visible rows. Used only when visibleRows < 0. (default: 2 - after Rico 2b3, 1 - up to Rico 2b3)\r
658 \r
659 <dt>maxPageRows\r
660 <dd>Maximum # of visible rows. Used only when visibleRows < 0. (default: 50)\r
661 \r
662 <dt><a name="defaultWidth"></a>defaultWidth\r
663 <dd>An integer used in setting the initial width of columns. \r
664 See the <a href='#width'>column width option</a> for an explanation.\r
665 (default: -1 if initializing from an HTML table, 100 otherwise)\r
666 \r
667 <dt>scrollBarWidth\r
668 <dd>For some calculations, LiveGrid needs to know the width of scrollbars on the page. (default: 19)\r
669 \r
670 <dt>minScrollWidth\r
671 <dd>Minimum scroll area width in pixels when width of frozen columns exceeds window width. (default: 100)\r
672 </dl>\r
673 \r
674 \r
675 <h4>Grid Data</h4>\r
676 <dl>\r
677 <dt>offset<dd>First row of data to be displayed (default: 0)\r
678 <dt>prefetchBuffer<dd>Load the buffer (and therefore the grid) on page load? (default: true)\r
679 <dt>sortCol<dd>Name or index of column for initial sort\r
680 <dt>sortDir<dd>Direction of initial sort\r
681   <br>possible values: 'ASC', 'DESC'\r
682 <dt>getQueryParms<dd>If true, check the web page's query string for filter parameters and apply\r
683 any filter that is found.  Filter parameters must be of the form "f[x]=" where x is the column index.\r
684 (default: false)\r
685 </dl>\r
686 \r
687 <h4>Header Configuration</h4>\r
688 <dl>\r
689 <dt>frozenColumns\r
690 <dd>number of columns on the left side of the grid that should be\r
691     frozen (like Excel). \r
692 \r
693 <dt>headingSort\r
694 <dd>A string that defines how headings are displayed to facilitate sorting.\r
695   <ul>\r
696   <li>'link' -- make headings a link that will sort columns (default)\r
697   <li>'hover' -- user can click in any part of the heading cell to sort. \r
698        Heading changes background color when cursor hovers over cell.\r
699   <li>'none' -- events on headings are disabled\r
700   </ul>\r
701 \r
702 <dt>hdrIconsFirst\r
703 <dd>Put sort and filter icons before or after header text (default: true)\r
704 \r
705 <dt><a name='allowColResize'>allowColResize</a>\r
706 <dd>Allow columns to be resized by the user? If true, then resizing for individual columns \r
707 can be disabled using <a href='#noResize'>noResize</a> in columnSpecs[].\r
708 \r
709 <dt>panels\r
710 <dd>An array of strings that can serve as secondary headings.\r
711 In LiveGrid Forms, they also serve as the headings for the tabbed panels on the input form.\r
712 \r
713 <dt>PanelNamesOnTabHdr\r
714 <dd>Set to 'true' for the strings in panels[] to be used as secondary headings.\r
715 In LiveGrid Forms, it may be set to 'false' so that panels[] is only used on the input form.\r
716 \r
717 <dt><a name='FilterLocation'>FilterLocation</a>\r
718 <dd>Specifies the heading row where filters should be placed.\r
719 -1 causes a new row to be appended to the header and that new row used for filtering.\r
720 See also the <a href='#filterUI'>filterUI</a> option.\r
721 \r
722 <dt>FilterAllToken\r
723 <dd>Token in select filters used to indicate "show all values" (default: "___ALL___").\r
724 </dl>\r
725 \r
726 <h4>Images</h4>\r
727 <dl>\r
728 <dt>resizeBackground\r
729 <dd>Image to use for column resize handle. (default: 'resize.gif')\r
730 \r
731 <dt>sortAscendImg\r
732 <dd>Image to use to indicate that the column is sorted in ascending order. (default: 'sort_asc.gif')\r
733 \r
734 <dt>sortDescendImg\r
735 <dd>Image to use to indicate that the column is sorted in descending order. (default: 'sort_desc.gif')\r
736 \r
737 <dt>filterImg\r
738 <dd>Image used to indicate an active filter on a column. (default: 'filtercol.gif')\r
739 </dl>\r
740 \r
741 \r
742 <h4>Cookie options</h4>\r
743 <dl>\r
744 \r
745 <dt><a name='saveColumnInfo'>saveColumnInfo</a>\r
746 <dd>Specifies which details to save in the grid's cookie. Only one cookie is used for each grid.\r
747 Note that the width setting includes the hide/show status of the column. \r
748 (default: {width:true, filter:false, sort:false})\r
749 <br>In the .net plug-in, this option is represented by 3 separate properties:\r
750 saveColumnWidth, saveColumnFilter, saveColumnSort\r
751 \r
752 <dt>cookiePrefix\r
753 <dd>A string that is prepended to the cookie name. (default: 'RicoGrid.')\r
754 \r
755 <dt>cookieDays\r
756 <dd>Number of days before the cookie expires. \r
757 If you don't specify it, then the cookie is only maintained for the current session. (default: null)\r
758 \r
759 <dt>cookiePath\r
760 <dd>Sets the top level directory from which the grid cookie can be read.\r
761 If you don't specify it, it becomes the path of the page that sets the cookie. (default: null)\r
762 \r
763 <dt>cookieDomain\r
764 <dd>Tells the browser to which domain the cookie should be sent. \r
765 If you don't specify it, it becomes the domain of the page that sets the cookie. (default: null)\r
766 \r
767 </dl>\r
768 \r
769 <h4>Highlighting and selection</h4>\r
770 <dl>\r
771 \r
772 <dt>highlightElem\r
773 <dd>a string that specifies what gets highlighted/selected\r
774   <ul>\r
775   <li>'cursorRow' -- the grid row under the cursor\r
776   <li>'cursorCell' -- the grid cell under the cursor\r
777   <li>'menuRow' -- the grid row where the menu is displayed\r
778   <li>'menuCell' -- the grid cell where the menu is displayed\r
779   <li>'selection' -- allow the user to select cells\r
780   <li>'none' -- never highlight\r
781   </ul>\r
782 \r
783 <dt>highlightSection\r
784 <dd>an integer that specifies which section of the table is highlighted\r
785   <ul>\r
786   <li>1 -- frozen\r
787   <li>2 -- scrolling\r
788   <li>3 -- all (default)\r
789   <li>0 -- none\r
790   </ul>\r
791 \r
792 <dt>highlightMethod\r
793 <dd>Method used to highlight cells &amp; rows. Possible values:\r
794   <ul>\r
795   <li>'outline' -- least CPU-intensive on client-side\r
796   <li>'class' -- adds CSS class to highlighted cell/row (default)\r
797   <li>'both' -- highlight using both outline and class\r
798   </ul>\r
799 \r
800 <dt>highlightClass\r
801 <dd>When highlighting by class, this is the class name used (default: 'ricoLG_selection')\r
802 </dl>\r
803 \r
804 \r
805 <h4>Export and print</h4>\r
806 <dl>\r
807 \r
808 <dt>maxPrint\r
809 <dd>The maximum number of rows that the user is allowed\r
810 to Print/Export.  Set to 0 to disable print/export. (default: 1000)\r
811 \r
812 <dt>exportWindow\r
813 <dd>Options string passed to <a href='http://www.w3schools.com/htmldom/met_win_open.asp'>window.open()</a>\r
814 when the export window is created. (default: "height=400,width=500,scrollbars=1,menubar=1,resizable=1")\r
815 \r
816 <dt>exportStyleList\r
817 <dd>An array of CSS attributes that will be extracted from the first visible row of the grid and used\r
818 to format all rows of the exported table. \r
819 (default: ['background-color', 'color', 'text-align', 'font-weight', 'font-size', 'font-family'])\r
820 </dl>\r
821 \r
822 \r
823 <h4>Behavior Defaults</h4>\r
824 <dl>\r
825 <dt><a name='canHideDefault'>canHideDefault</a>\r
826 <dd>Controls whether columns can be hidden/shown (default: true). \r
827 Hide/show can be disabled for individual columns using the <a href='#canHide'>canHide</a> property in columnSpecs.\r
828 \r
829 <dt><a name='canSortDefault'>canSortDefault</a>\r
830 <dd>Controls whether columns can be sorted (default: true).\r
831 Sorting can be disabled for individual columns using the <a href='#canSort'>canSort</a> property in columnSpecs.\r
832 \r
833 <dt><a name='canFilterDefault'>canFilterDefault</a>\r
834 <dd>Controls whether columns can be filtered (default: true).\r
835 Filtering can be disabled for individual columns using the <a href='#canFilter'>canFilter</a> property in columnSpecs.\r
836 \r
837 <dt><a name='dndMgrIdx'>dndMgrIdx</a>\r
838 <dd>Specifies which drag-and-drop management zone should be used for drag operations (default: 0).\r
839 This only needs to be specified if the web page uses multiple distinct zones.\r
840 \r
841 </dl>\r
842 \r
843 \r
844 <h4>Event control</h4>\r
845 <dl>\r
846 <dt><a name='menuEvent'>menuEvent</a>\r
847 <dd>A string that specifies when the grid's menu should be invoked\r
848   <ul>\r
849   <li>'click' -- invoke menu on single-click\r
850   <li>'dblclick' -- invoke menu on double-click (default)\r
851   <li>'contextmenu' -- invoke menu on right-click\r
852   <li>'none' -- no pop-up menu\r
853   </ul>\r
854 \r
855 <dt>windowResize\r
856 <dd>A boolean value specifying whether to resize the grid during a window.resize event.\r
857 This should be set to false when the grid is embedded in an accordian. (default: true)\r
858 </dl>\r
859 \r
860 \r
861 <h4>Event handles</h4>\r
862 <dl>\r
863 <dt style='font-weight:normal;'>Event handlers cannot be passed in options to the constructor, but may be set after the LiveGrid has been constructed.\r
864 <dt>sortHandler<dd> (default: Rico.LiveGridMethods.sortHandler -- bound)\r
865 <dt>filterHandler<dd> (default: Rico.LiveGridMethods.filterHandler -- bound)\r
866 <dt>onRefreshComplete<dd> (default: Rico.LiveGridMethods.bookmarkHandler -- bound)\r
867 <dt>rowOverHandler<dd> (default: Rico.LiveGridMethods.rowMouseOver -- bound as event listener)\r
868 <dt>mouseDownHandler<dd> (default: Rico.LiveGridMethods.selectMouseDown -- bound as event listener)\r
869 <dt>mouseOverHandler<dd> (default: Rico.LiveGridMethods.selectMouseOver -- bound as event listener)\r
870 <dt>mouseUpHandler<dd> (default: Rico.LiveGridMethods.selectMouseUp -- bound as event listener)\r
871 <dt>onscroll<dd> called whenever the grid is scrolled vertically. (default: null)\r
872 <dt>onscrollidle<dd> called 1.2 seconds after the grid is scrolled vertically. (default: null)\r
873 <dt>click<dd> called when a grid cell is clicked. (default: null, unless menuEvent='click')\r
874 <dt>dblclick<dd> called when a grid cell is double-clicked. (default: null, unless menuEvent='dblclick')\r
875 <dt>contextmenu<dd> called when a grid cell is right-clicked. (default: null, unless menuEvent='contextmenu')\r
876 </dl>\r
877 \r
878 <h4><a name="column"></a>Per-column configuration</h4>\r
879 <dl>\r
880 <dt style='font-weight:normal;'>Options for each individual column are contained in the columnSpecs option.\r
881 columnSpecs is an array with an entry for each column. \r
882 Each column entry can either be:\r
883 <ul>\r
884 \r
885 <li>null (default) --  in which case the column is formatted according to the spec in Rico.TableColumn.DEFAULT.\r
886 If most columns in your grid share common formatting, then it may make sense to override\r
887 the default column spec for that grid:\r
888 <pre>\r
889 Rico.TableColumn.DEFAULT = {ClassName:'aligncenter', width:50};\r
890 </pre>\r
891 In this case, any column with no spec will have content aligned to the center and a width of 50 pixels.\r
892 \r
893 <li>a string -- provides a simple way to specify a column format.\r
894 These values are built-in: DOLLAR, EURO, PERCENT, QTY, DEFAULT.\r
895 It is also possible to define your own. This example, which defines a temperature format,\r
896 is taken from weather.php:\r
897 <pre>\r
898 Rico.TableColumn.TEMP = {type:'number', decPlaces:0, \r
899   ClassName:'alignright', suffix:'&amp;deg;C', width:50};\r
900 var opts = {  \r
901   frozenColumns : 1,
902   columnSpecs   : [{width:120},{width:70},{width:70},{width:100},\r
903                    'TEMP','TEMP','TEMP',\r
904                    {width:150},{width:200},{width:60}]\r
905 };\r
906 </pre>\r
907 \r
908 <li>an object -- containing entries for one or more of the properties listed below.\r
909 Here is an example that contains specifications for columns 0, 1, and 3.\r
910 Column 2 would get the default spec.\r
911 <pre>\r
912 columnSpecs : [{canSort:false, noResize:true, ClassName:'alignright'},\r
913                {ClassName:'aligncenter'},\r
914                ,\r
915                {visible:false}]\r
916 </pre>\r
917 </ul>\r
918 \r
919 <dt>Hdg\r
920 <dd>An alternate way of specifying the heading text for a column.\r
921 Only used by LiveGrid if the grid id refers to a &lt;div&gt; instead of an html table.\r
922 \r
923 <dt><a name='canSort'>canSort</a>\r
924 <dd>Column can be sorted. (default: <a href='#canSortDefault'>grid.options.canSortDefault</a>)\r
925 \r
926 <dt><a name='canFilter'>canFilter</a>\r
927 <dd>Column can be filtered. (default: <a href='#canFilterDefault'>grid.options.canFilterDefault</a>)\r
928 \r
929 <dt>canDrag\r
930 <dd>Column cells can serve as the source for a drag-n-drop operation. The "DragAndDrop" module must be loaded. \r
931 The temporary drag objects have a class of "LiveGridDraggable".\r
932 For an example, see <a href='client/drag_and_drop_grid.html'>drag_and_drop_grid.html</a>. (default: false)\r
933 \r
934 <dt><a name='canHide'>canHide</a>\r
935 <dd>Column can be hidden/unhidden. (default: <a href='#canHideDefault'>grid.options.canHideDefault</a>)\r
936 \r
937 <dt>visible\r
938 <dd>Controls whether the column is visible at grid startup (default: true). \r
939 If <a href='#saveColumnInfo'>grid.options.saveColumnInfo.width</a> is true\r
940 and there is a value in the cookie for this column, the cookie value will take precedence.\r
941 \r
942 <dt><a name='width'>width</a>\r
943 <dd>An integer specifying the initial width (in pixels) for the column. \r
944 Here is the algorithm LiveGrid uses for setting the initial width of each column:\r
945 <ol>\r
946 <li>If <a href='#saveColumnInfo'>options.saveColumnInfo.width</a> is true and column information is present in the grid's cookie \r
947 (due to the user previously performing a resize on that grid's column), \r
948 then the width in the cookie is used. Otherwise...\r
949 \r
950 <li>If there is a width spec for the column in options.columnSpecs[], then the width in the spec is used. For an example, see ex3.php/asp/aspx. Otherwise...\r
951 \r
952 <li>If <a href='#defaultWidth'>options.defaultWidth</a> is true (default) and the grid header is initialized from an html table, then the column's width in the html table is used. \r
953 You can usually control the column widths of the initial table by using col tags (e.g. &lt;col style='width:40px;' &gt;). \r
954 If the total table width is less than the browser width then this works; however if it is greater, then the browser often ignores &lt;col width&gt; \r
955 and tries to squeeze all of the columns into the available window width. Thus, using this method to set the column width is unreliable. Otherwise...\r
956 \r
957 <li>If <a href='#defaultWidth'>options.defaultWidth</a> is false, then the column's width is set to options.defaultWidth (which defaults to 100).\r
958 </ol>\r
959 Therefore, the most reliable way to set column widths in LiveGrid and SimpleGrid is to specify a width for every column in options.columnSpecs[]. \r
960 If many columns share a common width, then you can shortcut this somewhat by setting options.defaultWidth=false, \r
961 and setting options.defaultWidth to the common width.\r
962 \r
963 <dt><a name='noResize'>noResize</a>\r
964 <dd>Allow column to be resized? (default <a href='#allowColResize'>grid.options.allowColResize</a> )\r
965 \r
966 <dt>ClassName\r
967 <dd>By default, LiveGrid assigns a unique CSS class name to each\r
968 column, which follows the naming convention: table_id + '_col' + column_index.\r
969 For example, the fourth column in the grid 'mygrid' would have the class name\r
970 'mygrid_col3'. The value of the ClassName option overrides this default name.\r
971 The ClassName option is most commonly used to specify column alignment via the\r
972 Rico-provided 'alignright' and 'aligncenter' classes. \r
973 So, if you wanted the first 3 columns in your grid to be displayed with white\r
974 text on a red background, you could do either of the following:\r
975 \r
976 <pre>\r
977 In CSS:\r
978 .mygrid_col0 div.ricoLG_cell, \r
979 .mygrid_col1 div.ricoLG_cell, \r
980 .mygrid_col2 div.ricoLG_cell {\r
981   color: white;\r
982   background-color: red;\r
983 }\r
984 </pre>\r
985 \r
986 OR\r
987 \r
988 <pre>\r
989 In CSS:\r
990 .WhiteOnRed div.ricoLG_cell {\r
991   color: white;\r
992   background-color: red;\r
993 }\r
994 \r
995 In javascript:\r
996 columnSpecs : [{ClassName:'WhiteOnRed'},\r
997                {ClassName:'WhiteOnRed'},\r
998                {ClassName:'WhiteOnRed'},\r
999                ...\r
1000 </pre>\r
1001 \r
1002 Finally, please note that this ClassName is not applied to the grid headings - \r
1003 use a align="right" on the &lt;th&gt; tag to accomplish the header alignment.\r
1004 \r
1005 <dt>type (DataType in .net plug-in)\r
1006 <dd>A string containing one of these values: \r
1007 <ul>\r
1008 <li>text - any tags in the column value are removed before being displayed to the user.\r
1009 <li>showTags - any tags in the column value are displayed to the user as text.\r
1010 <li>number - column value is treated as a number, \r
1011 and any <a href='#NumberFormatting'>number formatting options</a> \r
1012 supplied in the column specification are applied.\r
1013 <li>datetime - column value is treated as a date &amp; time, \r
1014 and any <a href='#DateFormatting'>date formatting options</a> \r
1015 supplied in the column specification are applied.\r
1016 <li>UTCasLocalTime - column/database value is treated as a GMT/UTC date &amp; time, and any <a href='#DateFormatting'>date formatting options</a> \r
1017 supplied in the column specification are applied. Before display, the value is converted to the user's local time zone.\r
1018 <li>date - column value is treated as a date, and any <a href='#DateFormatting'>date formatting options</a> \r
1019 supplied in the column specification are applied.\r
1020 <li>raw (default) - column values are displayed directly to the grid cell. \r
1021 Any HTML markup gets copied into the cell.\r
1022 </ul>\r
1023 </dd>\r
1024 \r
1025 <dt><a name='control'></a>control\r
1026 <dd>An object that can be used to provide special formatting for a column.\r
1027 Several column controls are provided with LiveGrid. The code for them\r
1028 resides in ricoLiveGridControls.js. Here is a brief description of the\r
1029 provided controls:\r
1030 \r
1031 <dl style='font-size:smaller;'>\r
1032 <dt>Rico.TableColumn.checkboxKey(showKey)\r
1033 <dd>Display unique key column as: &lt;checkbox&gt; &lt;key value&gt;
1034 and keep track of which keys the user selects.
1035 Key values should not contain &lt;, &gt;, or &amp;.
1036 \r
1037 <dt>Rico.TableColumn.checkbox(checkedValue, uncheckedValue, defaultValue, readOnly)\r
1038 <dd>Display column as checkboxes. Database column should contain only two-values  (e.g. yes/no).
1039 The following code is taken from ex7 (column values are 1 and 0):\r
1040 <pre>\r
1041 columnSpecs: [{canHide:false,\r
1042                control:new Rico.TableColumn.checkbox('1','0'),\r
1043                ClassName:'aligncenter'},\r
1044               'specQty'],\r
1045 </pre>\r
1046 \r
1047 <dt>Rico.TableColumn.textbox(boxSize, boxMaxLen, readOnly)\r
1048 <dd>Display the column value in a text box.\r
1049 \r
1050 <dt>Rico.TableColumn.HighlightCell(chkcol,chkval,highlightColor,highlightBackground,chkop)\r
1051 <dd>Highlight a grid cell when a particular value is present in the specified column.\r
1052 chkop optionally specifies the comparison to be performed: ==, !=, &lt;, &lt;=, &gt;, &gt;=.\r
1053 If not specified, then == is used.\r
1054 The following code is taken from ex2highlight and highlights the entire row when column 1\r
1055 contains "HANAR":\r
1056 <pre>\r
1057 var CustId='HANAR';\r
1058 var CustIdCol=1;\r
1059 var highlight=Rico.TableColumn.HighlightCell;\r
1060 ...\r
1061 columnSpecs: [\r
1062 { control:new highlight(CustIdCol,CustId,'red','yellow') },\r
1063 { control:new highlight(CustIdCol,CustId,'red','yellow') },\r
1064 { control:new highlight(CustIdCol,CustId,'red','yellow') },\r
1065 { control:new highlight(CustIdCol,CustId,'red','yellow') },\r
1066 { control:new highlight(CustIdCol,CustId,'red','yellow') },\r
1067 { type:'date', control:new highlight(CustIdCol,CustId,'red','yellow') },\r
1068 { type:'date', control:new highlight(CustIdCol,CustId,'red','yellow') }]\r
1069 </pre>\r
1070 \r
1071 <dt>Rico.TableColumn.bgColor()\r
1072 <dd>Database value contains a css color name/value\r
1073 \r
1074 <dt>Rico.TableColumn.link(href,target)\r
1075 <dd>Database value contains a url to another page.\r
1076 The href parameter may contain references to grid values by including "{x}" in the string,\r
1077 where x is a column number. The following code is taken from ex6:\r
1078 <pre>\r
1079 columnSpecs: [,\r
1080 {control:new Rico.TableColumn.link('ex2.asp?id={0}','_blank'),\r
1081  width:250},\r
1082 ,'specQty']\r
1083 </pre>\r
1084 \r
1085 <dt>Rico.TableColumn.image()\r
1086 <dd>Database value contains a url to an image.\r
1087 The following code is taken from photos.php:\r
1088 <pre>\r
1089 imgctl=new Rico.TableColumn.image();\r
1090 ...\r
1091 columnSpecs: [\r
1092 {control:imgctl,width:90},,,\r
1093 {type:'datetime'},{width:200}]\r
1094 </pre>\r
1095 \r
1096 <dt>Rico.TableColumn.lookup(map, defaultCode, defaultDesc)\r
1097 <dd>Map a database value to a display value\r
1098 \r
1099 <dt>Rico.TableColumn.MultiLine()\r
1100 <dd>Overcomes issues when displaying multi-line content (i.e. content with &lt;br&gt; tags) in IE6 and IE7\r
1101 \r
1102 </dl>\r
1103 \r
1104 <br>It is also possible to write your own column control, which\r
1105 implements logic specific to your application. Here is an example:\r
1106 <pre>\r
1107 // Display values white on black if\r
1108 //   first column contains the value "reverse"\r
1109 // Usage: { control:new MyCustomColumn() }
1110 MyCustomColumn = Class.create();
1112 MyCustomColumn.prototype = {
1113   initialize: function() {},
1115   _clear: function(gridCell,windowRow) {
1116     gridCell.style.color='';
1117     gridCell.style.backgroundColor='';
1118     gridCell.innerHTML='&amp;nbsp;';
1119   },
1121   _display: function(v,gridCell,windowRow) {
1122     var col0=this.liveGrid.buffer.getWindowValue(windowRow,0);\r
1123     if (col0=="reverse") {\r
1124       gridCell.style.color='white';
1125       gridCell.style.backgroundColor='black';\r
1126     } else {\r
1127       gridCell.style.color='';
1128       gridCell.style.backgroundColor='';
1129     }
1130     gridCell.innerHTML=this._format(v);
1131   }
1132 }
1133 </pre>\r
1134 \r
1135 <dt><a name='filterUI'></a>filterUI\r
1136 <dd>If a <a href='#FilterLocation'>FilterLocation</a> option is specified for the grid, then filterUI will control\r
1137 how each column is filtered. If filterUI is:\r
1138 <ul>\r
1139 <li>null or omitted, then no filter is displayed for the column.\r
1140 <li>'t' - will generate a text box filter and the records being displayed\r
1141 are filtered as the user types. \r
1142 <br>May optionally be followed by a caret (^) to\r
1143 indicate that text box values should match the beginning of the column value.\r
1144 Otherwise, they can match anywhere in the column's value.\r
1145 <br>May also be followed by a number to indicate the size of the text box (default size is 10).\r
1146 <pre>\r
1147 filterUI:'t^20' \r
1148 // will create a text box that is 20 characters wide\r
1149 // text typed into the box will be compared to\r
1150 //    the beginning of each column value\r
1151 </pre>\r
1152 <li>'s' - will generate a select list filter with all possible column values contained in the list.\r
1153 Populated using a 'select distinct' query if the grid's source is a SQL query.\r
1154 </ul>\r
1155 \r
1156 <dt></a>filterCol\r
1157 <dd>Specifies that the filter should be applied to a different column. For example, ex3livegrid.asp/aspx/php\r
1158 uses this feature to filter the order and ship date columns by year. The full date is shown in the column\r
1159 in which the filter appears; however, there is another hidden, calculated column containing "year(orderdate)"\r
1160 to which the filter is applied.\r
1161 </dl>\r
1162 \r
1163 <dl>\r
1164 <dt style='color:navy;'><a name='NumberFormatting'></a><em>Number formatting:</em>\r
1165 \r
1166 <dt>multiplier\r
1167 <dd>The value is multiplied by this number before it is displayed. (default: 1)\r
1168 \r
1169 <dt>decPlaces\r
1170 <dd>Number of places to the right of the decimal point. (default: 0)\r
1171 \r
1172 <dt>decPoint\r
1173 <dd>Decimal point symbol. (default: '.' but overridden in the translation files)\r
1174 \r
1175 <dt>thouSep\r
1176 <dd>Symbol for thousands separator. (default: ',' but overridden in the translation files)\r
1177 \r
1178 <dt>negSign\r
1179 <dd>Specifies how negative numbers should be displayed. Possible values:\r
1180 <ul>\r
1181 <li>L=leading minus (default)\r
1182 <li>T=trailing minus\r
1183 <li>P=parentheses\r
1184 </ul>\r
1185 \r
1186 <dt>prefix\r
1187 <dd>A string added to the beginning of the number. Typically a currency symbol.\r
1188 \r
1189 <dt>suffix\r
1190 <dd>A string added to the end of a number. For example, a "%" symbol.</dd>\r
1191 </dl>\r
1192 \r
1193 <dl>\r
1194 <dt style='color:navy;'><a name='DateFormatting'></a><em>Date formatting:</em>\r
1195 \r
1196 <dt>dateFmt\r
1197 <dd>A string specifying how the date or datetime should be displayed. Default is "translateDate", which means\r
1198 that the dateFmt and timeFmt strings in the RicoTranslate object are used \r
1199 (this defaults to "mm/dd/yyyy" for dates and "mm/dd/yyyy hh:nn:ss a/pm" for datetimes, \r
1200 but is overridden by the various language translation files). \r
1201 If dateFmt="localeDate", then the value is formatted using javascript's built-in toLocaleDateString() function. \r
1202 If dateFmt="localeDateTime", then the value is formatted using javascript's built-in toLocaleString() function. \r
1203 The dateFmt string may contain the following special character sequences:\r
1204 \r
1205 <ul>\r
1206 <li>yyyy - 4 digit year
1207 <li>yy - 2 digit year
1208 <li>mmmm - month name
1209 <li>mmm - 3 character month name abbreviation. In Asian languages this often doesn't make sense - in these cases it returns the full month name (same as mmmm).
1210 <li>mm - 2 digit month number (zero padded)
1211 <li>m - 1 or 2 digit month number
1212 <li>dddd - day-of-the-week
1213 <li>ddd - 3 character day-of-the-week abbreviation
1214 <li>dd - 2 digit day number (zero padded)
1215 <li>d - 1 or 2 digit day number
1216 <li>hh - 2 digit hour, 12-hour clock (zero padded)
1217 <li>h - 1 or 2 digit hour, 12-hour clock
1218 <li>HH - 2 digit hour, 24-hour clock (zero padded)
1219 <li>H - 1 or 2 digit hour, 24-hour clock
1220 <li>nn - 2 digit minutes (zero padded)
1221 <li>ss - 2 digit seconds (zero padded)
1222 <li>a/p - a or p (for am or pm)
1223 </ul>\r
1224 \r
1225 <pre>\r
1226 // display first column as "month year"\r
1227 columnSpecs : [{type:date, dateFmt:'mmm yyyy'}]\r
1228 </pre>\r
1229 </dd>\r
1230 \r
1231 <dt>prefix\r
1232 <dd>A string added to the beginning of the date.\r
1233 \r
1234 <dt>suffix\r
1235 <dd>A string added to the end of a date. For example, you could use this to include a time zone:\r
1236 <pre>\r
1237 // indicate that times are GMT/UTC\r
1238 columnSpecs : [{type:datetime, suffix:' UTC'}]\r
1239 </pre>\r
1240 </dl>\r
1241 \r
1242 </body>\r
1243 </html>\r