git.infodrom.org Git - infodrom/rico3/blob - documentation/SimpleGrid.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 SimpleGrid</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 SimpleGrid</h1>\r
  11 \r
  12 <p>SimpleGrid's are new to Rico 2.0 and share some of the same functionality as LiveGrids - \r
  13 resizable columns, frozen columns, and frozen headings. \r
  14 However, unlike a LiveGrid, the data is static and resides in the DOM -\r
  15 so no buffering, no AJAX refreshes, no sorting, no filtering.\r
  16 Why would you use a SimpleGrid? \r
  17 <ul>\r
  18 <li>Because it is more flexible in what each cell can contain - \r
  19 cells in a column do not all have to be of the same type.\r
  20 <li>In some circumstances, it can perform better on the client than LiveGrid; \r
  21 particularly on a slow client and there are many columns in the grid.\r
  22 <li>Finally, a SimpleGrid can contain input elements (checkboxes, select lists, etc). \r
  23 While a LiveGrid can also contain input elements, because the element values are stored in the\r
  24 LiveGrid buffer, submitting the values back to the server can be tricky.\r
  25 SimpleGrids do not suffer from this problem. You can simply surround the\r
  26 entire grid with standard <code>&lt;form&gt;...&lt;/form&gt;</code> tags and any\r
  27 input elements within the grid will be submitted back to the server.\r
  28 </ul>\r
  29 \r
  30 <p>SimpleGrids can be created either of two ways:\r
  31 <ol>\r
  32 <li>By using one of the SimpleGrid plug-ins. Plug-ins exist for PHP, ASP, and .net.\r
  33 <li>By using XSLT. Rico includes an XSL file that will convert a standard\r
  34 HTML table to a SimpleGrid.\r
  35 </ol>\r
  36 \r
  37 <h2>Usage Model 1: Using a SimpleGrid plug-in</h2>\r
  38 <p>This section describes the examples simplegrid.php/asp/aspx, \r
  39 which are included in the Rico distribution.\r
  40 <ul>\r
  41 <li>In PHP:\r
  42 <ul>\r
  43 <li>First, create a reference to the SimpleGrid plug-in:\r
  44 <pre>\r
  45 require "../../plugins/php/SimpleGrid.php";\r
  46 </pre>\r
  47 <li>Create an instance of the SimpleGrid plug-in class (server side):\r
  48 <pre>\r
  49 $grid=new SimpleGrid();\r
  50 </pre>\r
  51 \r
  52 <li>Create the grid's headings. Passing 'true' to AddHeadingRow indicates\r
  53 that this is the main heading row - the one that will get the resizers.\r
  54 The number of columns in the main heading row <em>must</em> be the same\r
  55 as the number of data columns. Other heading rows may include "colspan" tags\r
  56 to cover multiple columns. If you have multiple heading rows, one and only one\r
  57 row may be designated as the main row.\r
  58 <pre>\r
  59 $grid->AddHeadingRow(true);\r
  60 for ($c=1; $c<=$numcol; $c++) {\r
  61   $grid->AddCell("Column $c");\r
  62 }\r
  63 </pre>\r
  64 \r
  65 <li>Populate the grid's data section. Call AddDataRow() everywhere you would normally\r
  66 place a <code>&lt;tr&gt;</code> tag in a standard html table. Call AddCell() everywhere you would\r
  67 place a <code>&lt;td&gt;</code> tag.\r
  68 <pre>\r
  69 for ($r=1; $r<=100; $r++) {\r
  70   $grid->AddDataRow();\r
  71   $grid->AddCell($r);\r
  72   for ($c=2; $c<=$numcol; $c++) {\r
  73     $grid->AddCell("Cell $r:$c");\r
  74   }\r
  75 }\r
  76 </pre>\r
  77 \r
  78 <li>Render the table (generate the html output). The first parameter is the grid id, and the\r
  79 second parameter is the number of frozen columns.\r
  80 <pre>\r
  81 $grid->Render("ex1", 1);\r
  82 </pre>\r
  83 \r
  84 </ul>\r
  85 \r
  86 <li>In ASP:\r
  87 <ul>\r
  88 <li>First, create a reference to the SimpleGrid plug-in:\r
  89 <pre>\r
  90 &lt;!-- #INCLUDE FILE = "../../plugins/asp/SimpleGrid.vbs" --&gt;\r
  91 </pre>\r
  92 \r
  93 <li>Create an instance of the SimpleGrid plug-in class (server side):\r
  94 <pre>\r
  95 set grid=new SimpleGrid\r
  96 </pre>\r
  97 \r
  98 <li>Create the grid's headings. Passing 'true' to AddHeadingRow indicates\r
  99 that this is the main heading row - the one that will get the resizers.\r
 100 The number of columns in the main heading row <em>must</em> be the same\r
 101 as the number of data columns. Other heading rows may include "colspan" tags\r
 102 to cover multiple columns. If you have multiple heading rows, one and only one\r
 103 row may be designated as the main row.\r
 104 <pre>\r
 105 grid.AddHeadingRow true\r
 106 for c=1 to numcol\r
 107   grid.AddCell "Column " & c\r
 108 next\r
 109 </pre>\r
 110 \r
 111 <li>Populate the grid's data section. Call AddDataRow() everywhere you would normally\r
 112 place a <code>&lt;tr&gt;</code> tag in a standard html table. Call AddCell() everywhere you would\r
 113 place a <code>&lt;td&gt;</code> tag.\r
 114 <pre>\r
 115 for r=1 to 100\r
 116   grid.AddDataRow\r
 117   grid.AddCell r\r
 118   for c=2 to numcol\r
 119     grid.AddCell "Cell " & r & ":" & c\r
 120   next\r
 121 next\r
 122 </pre>\r
 123 \r
 124 <li>Render the table (generate the html output). The first parameter is the grid id, and the\r
 125 second parameter is the number of frozen columns.\r
 126 <pre>\r
 127 grid.Render "ex1", 1\r
 128 </pre>\r
 129 </ul>\r
 130 \r
 131 <li>In .net:\r
 132 <ul>\r
 133 <li>First, create a reference to the SimpleGrid plug-in:\r
 134 <pre>\r
 135 &lt;%@ Register TagPrefix="Rico" TagName="SimpleGrid" \r
 136     Src="../../plugins/dotnet/SimpleGrid.ascx" %&gt;\r
 137 </pre>\r
 138 \r
 139 <li>Create an instance of the SimpleGrid plug-in class (server side):\r
 140 <pre>\r
 141 &lt;Rico:SimpleGrid runat='server' id='ex1' FrozenCols='1' /&gt;\r
 142 </pre>\r
 143 \r
 144 <li>Create the grid's headings - usually within the Page_Load event. \r
 145 Passing 'true' to AddHeadingRow indicates\r
 146 that this is the main heading row - the one that will get the resizers.\r
 147 The number of columns in the main heading row <em>must</em> be the same\r
 148 as the number of data columns. Other heading rows may include "colspan" tags\r
 149 to cover multiple columns. If you have multiple heading rows, one and only one\r
 150 row may be designated as the main row.\r
 151 <pre>\r
 152   ex1.AddHeadingRow(true)\r
 153   for c=1 to numcol\r
 154     ex1.AddCell("Column " & c)\r
 155   next\r
 156 </pre>\r
 157 \r
 158 <li>Populate the grid's data section. Call AddDataRow() everywhere you would normally\r
 159 place a <code>&lt;tr&gt;</code> tag in a standard html table. Call AddCell() everywhere you would\r
 160 place a <code>&lt;td&gt;</code> tag.\r
 161 <pre>\r
 162   for r=1 to 100\r
 163     ex1.AddDataRow()\r
 164     ex1.AddCell(r)\r
 165     for c=2 to numcol\r
 166       ex1.AddCell("Cell " & r & ":" & c)\r
 167     next\r
 168   next\r
 169 </pre>\r
 170 \r
 171 <li>Unlike the other plug-ins, rendering happens automatically in the .net control.\r
 172 </ul>\r
 173 \r
 174 <li>Finally, regardless of the plug-in used, you need to \r
 175 initialize the javascript SimpleGrid object (client side):\r
 176 <pre>\r
 177 &lt;script type='text/javascript'&gt;\r
 178 Rico.loadModule('SimpleGrid','greenHdg.css');\r
 179 \r
 180 Rico.onLoad( function() {\r
 181   var opts = {  \r
 182     columnSpecs: ['specQty']  // display first column as a numeric quantity\r
 183   };\r
 184   var ex1=new Rico.SimpleGrid ('ex1', opts);\r
 185 });\r
 186 &lt;/script&gt;\r
 187 </pre>\r
 188 \r
 189 </ul>\r
 190 \r
 191 \r
 192 <h2>Usage Model 2: Using the XSLT transform</h2>\r
 193 \r
 194 <p>If your web page is XHTML compliant, then it is possible to turn a standard html table\r
 195 on that page into a SimpleGrid using the XSL stylesheet "ricoSimpleGrid.xsl". \r
 196 At one time, Rico supported doing this\r
 197 transformation on the client; however, due to changes in the Prototype library, this\r
 198 is no longer possible. Therefore, if you choose to use this approach, the XSLT transform\r
 199 <em>must</em> be performed on the server. Instructions for doing a server-side transform:\r
 200 <ul>\r
 201 <li><a href="http://www.php.net/manual/en/ref.xsl.php">using PHP5</a>\r
 202 <li><a href="http://www.topxml.com/dotnet/articles/xslt/default.asp">using .net</a>\r
 203 </ul>\r
 204 \r
 205 <p>The tranform will only convert tables with a class of "ricoSimpleGrid".\r
 206 <pre>\r
 207 &lt;table id='test1' class='ricoSimpleGrid'&gt;\r
 208 </pre>\r
 209 \r
 210 <p>Headings for frozen columns must have class="ricoFrozen"\r
 211 in the <code>&lt;th&gt;</code> tag. If there are multiple heading rows,\r
 212 then the main heading row should have an id ending in "_main" (this is the\r
 213 row that will display resizing handles). The transform\r
 214 will look for grid headings in the table's <code>&lt;thead&gt;</code> section.\r
 215 If no thead section exists, then the transform will assume the first row of the table\r
 216 is the heading row.\r
 217 <pre>\r
 218 &lt;table id="test1" class="ricoSimpleGrid"&gt;\r
 219 \r
 220   &lt;thead&gt;\r
 221      &lt;tr id="customer_livegrid_main"&gt;\r
 222         &lt;th class="ricoFrozen"&gt;ID&lt;/th&gt;\r
 223         &lt;th&gt;Customer&lt;/th&gt;\r
 224         &lt;th&gt;Address&lt;/th&gt;\r
 225         &lt;th&gt;City&lt;/th&gt;\r
 226      &lt;/tr&gt;\r
 227   &lt;/thead&gt;\r
 228 \r
 229   &lt;tbody&gt;\r
 230     &lt;!-- grid data --&gt;\r
 231   &lt;/tbody&gt;\r
 232 &lt;/table&gt;\r
 233 </pre>\r
 234 \r
 235 <p>Finally, the SimpleGrid javascript object must be declared and initialized in a CDATA section.\r
 236 The call to ricoInit() is generated by the XSLT transform.\r
 237 <pre>\r
 238 &lt;script type="text/javascript"&gt;\r
 239 //&lt;![CDATA[\r
 240 \r
 241 function ricoInit() {\r
 242   try {\r
 243   Rico.loadModule('SimpleGrid');\r
 244   Rico.onLoad(ricoInit2);\r
 245   } catch(e) { alert(e.message); }\r
 246 }\r
 247 \r
 248 var grid1\r
 249 function ricoInit2() {\r
 250   try {\r
 251   grid1=new Rico.SimpleGrid ('test1',{maxHt:180});\r
 252   } catch(e) { alert(e.message); }\r
 253 }\r
 254 //]]&gt;\r
 255 &lt;/script&gt;\r
 256 </pre>\r
 257 \r
 258 \r
 259 \r
 260 <h2>Reference</h2>\r
 261 \r
 262 <h3>Constructor</h3>\r
 263 <pre>\r
 264 \r
 265   var grid = new Rico.SimpleGrid (table_id, grid_options);\r
 266 \r
 267 </pre>\r
 268 <ul><li><strong>table_id</strong> is the DOM id of the table to be populated by LiveGrid\r
 269 <li><strong>grid_options</strong> (see below)\r
 270 </ul>\r
 271 \r
 272 <h3>Options</h3>\r
 273 <h4>General options</h4>\r
 274 <dl>\r
 275 \r
 276 <dt>frozenColumns\r
 277 <dd>Number of frozen columns on the left side of the grid (default: 0)\r
 278 \r
 279 <dt>maxHt\r
 280 <dd>Maximum height of a SimpleGrid in pixels. (default: null)\r
 281 \r
 282 <dt>windowResize\r
 283 <dd>Resize grid on window.resize event?\r
 284 Set to false when embedded in an Accordian. (default: true)\r
 285 \r
 286 <dt>useUnformattedColWidth\r
 287 <dd>Use column widths in source html table when configuring the grid? (default: true)\r
 288 \r
 289 <dt>scrollBarWidth\r
 290 <dd>Used in positioning, does not actually change the width of the scrollbar. (default: 19)\r
 291 \r
 292 <dt>minScrollWidth\r
 293 <dd>When the width of the frozen columns exceeds the client window width, \r
 294 how wide should the total width of the scrolling columns be?\r
 295 \r
 296 <dt>highlightElem\r
 297 <dd>What gets highlighted in the grid. Possible values: \r
 298 <ul>\r
 299 <li>cursorRow - the grid row under the cursor\r
 300 <li>cursorCell - the grid cell under the cursor\r
 301 <li>menuRow - the relevant row when the user opens the grid's context menu\r
 302 <li>menuCell - the relevant cell when the user opens the grid's context menu\r
 303 <li>selection - the cells selected by the user\r
 304 <li>none - nothing is highlighted (default)\r
 305 </ul>\r
 306 \r
 307 <dt>exportWindow\r
 308 <dd>Option string that gets passed to window.open() when the user exports data from the grid.\r
 309 (default: "height=300,width=500,scrollbars=1,menubar=1,resizable=1")\r
 310 \r
 311 <dt>exportStyleList\r
 312 <dd>An array of CSS attributes that will be extracted from the each cell in the grid\r
 313 and used to format the exported table. \r
 314 (default: ['background-color', 'color', 'text-align', 'font-weight', 'font-size', 'font-family'])\r
 315 \r
 316 <dt>exportImgTags\r
 317 <dd>Boolean value that specifies whether img text should be included in the export. img text\r
 318 is the alt text if it exists, otherwise it is the title text, otherwise it is the src value. (default: true)\r
 319 \r
 320 <dt>exportFormFields\r
 321 <dd>Boolean value that specifies whether form fields should be included in the export. (default: true)\r
 322 </dl>\r
 323 \r
 324 \r
 325 <h4>Images</h4>\r
 326 <dl>\r
 327 <dt>resizeBackground\r
 328 <dd>Image to use for column resize handle. (default: 'resize.gif')\r
 329 \r
 330 <dt>sortAscendImg\r
 331 <dd>Image to use to indicate that the column is sorted in ascending order. (default: 'sort_asc.gif')\r
 332 \r
 333 <dt>sortDescendImg\r
 334 <dd>Image to use to indicate that the column is sorted in descending order. (default: 'sort_desc.gif')\r
 335 </dl>\r
 336 \r
 337 \r
 338 <h4>Menu and event-handling options</h4>\r
 339 <dl>\r
 340 \r
 341 <dt>contextmenu\r
 342 <dd>Action to take when the user right-clicks on a grid cell (default: null)\r
 343 \r
 344 <dt>menuEvent\r
 345 <dd>Event that triggers menus. Possible values: \r
 346 <ul>\r
 347 <li>click\r
 348 <li>dblclick (default)\r
 349 <li>contextmenu\r
 350 <li>none\r
 351 </ul>\r
 352 \r
 353 <dt>click\r
 354 <dd>Action to take when the user single-clicks on a grid cell (default: null)\r
 355 \r
 356 <dt>dblclick\r
 357 <dd>Action to take when the user double-clicks on a grid cell (default: null)\r
 358 \r
 359 </dl>\r
 360 \r
 361 <h4>Cookie options</h4>\r
 362 <dl>\r
 363 \r
 364 <dt>saveColumnInfo\r
 365 <dd>Specifies which details to save in the grid's cookie. Only one cookie is used for each grid.\r
 366 Note that the width setting includes the hide/show status of the column. \r
 367 (default: {width:true, filter:false, sort:false})\r
 368 \r
 369 <dt>cookiePrefix\r
 370 <dd>A string that is prepended to the cookie name. (default: 'RicoGrid.')\r
 371 \r
 372 <dt>cookieDays\r
 373 <dd>Number of days before the cookie expires. \r
 374 If you don't specify it, then the cookie is only maintained for the current session. (default: null)\r
 375 \r
 376 <dt>cookiePath\r
 377 <dd>Sets the top level directory from which the grid cookie can be read.\r
 378 If you don't specify it, it becomes the path of the page that sets the cookie. (default: null)\r
 379 \r
 380 <dt>cookieDomain\r
 381 <dd>Tells the browser to which domain the cookie should be sent. \r
 382 If you don't specify it, it becomes the domain of the page that sets the cookie. (default: null)\r
 383 \r
 384 </dl>\r
 385 \r
 386 <h4>Column defaults</h4>\r
 387 <dl>\r
 388 <dt style='font-weight:normal;'>Each of these items can be overridden \r
 389 on a per-column basis via the columnSpecs option.\r
 390 \r
 391 <dt>canSortDefault\r
 392 <dd>Are columns sortable by default? (LiveGrid default: true, SimpleGrid default: false)\r
 393 \r
 394 <dt>canFilterDefault\r
 395 <dd>Can the column be filtered? \r
 396 (LiveGrid default: RicoBuffer.options.canFilter, SimpleGrid default: false) \r
 397 \r
 398 <dt>canHideDefault\r
 399 <dd>Columns can be hidden/unhidden (default: true)\r
 400 \r
 401 <dt>allowColResize\r
 402 <dd>Allow user to resize columns (default: true)\r
 403 \r
 404 <dt>defaultWidth\r
 405 <dd>Default width of each column in pixels (default: 100)\r
 406 \r
 407 </dl>\r
 408 \r
 409 <h4>Per-column configuration</h4>\r
 410 <dl>\r
 411 <dt style='font-weight:normal;'>Options for each individual column are contained in the columnSpecs option.\r
 412 columnSpecs is an array with an entry for each column. \r
 413 Each column entry can either be:\r
 414 <ul>\r
 415 <li>null (default) --  in which case the column is formatted according to the spec in Rico.TableColumn.DEFAULT.\r
 416 <li>a string -- specifying one of the pre-defined formats: QTY, PERCENT, DOLLAR, or EURO\r
 417 <li>an object -- containing entries for one or more of the properties listed below.\r
 418 </ul>\r
 419 <p>Here is an example that contains specifications for columns 0, 1, and 3:\r
 420 <pre>\r
 421 columnSpecs : [{noResize:true, ClassName:'alignright'},\r
 422                {ClassName:'aligncenter'},\r
 423                ,\r
 424                {visible:false}]\r
 425 </pre>\r
 426 \r
 427 <dt>canHide\r
 428 <dd>Column can be hidden/unhidden. (default: grid.options.canHideDefault)\r
 429 \r
 430 <dt>visible\r
 431 <dd>Column is initially unhidden. If grid.options.saveColumnInfo.width is true\r
 432 and there is a value in the cookie for this column, the cookie value will take precedence.\r
 433 (default: true)\r
 434 \r
 435 <dt>width\r
 436 <dd>Initial width for column. If grid.options.saveColumnInfo.width is true\r
 437 and there is a value in the cookie for this column, the cookie value will take precedence.\r
 438 (default: grid.options.defaultWidth)\r
 439 \r
 440 <dt>noResize\r
 441 <dd>Allow column to be resized? (default grid.options.allowColResize )\r
 442 \r
 443 <dt>ClassName\r
 444 <dd>Set this to 'alignright' or 'aligncenter' as needed - see example. \r
 445 Note that this does not align the header - \r
 446 use a align="right" on the &lt;th&gt; line to accomplish the header alignment.\r
 447 (default: table_id + '_col' + column_index)\r
 448 \r
 449 </dl>\r
 450 \r
 451 </body>\r
 452 </html>\r