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