Special XML conversion code for Firefox >= 20.0
[infodrom/rico3] / documentation / grids.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 Grid Overview</title>\r
6 <link href="ricoDocs.css" rel="Stylesheet" type="text/css">
7 </head>\r
8 \r
9 <body>\r
10 <h1>Rico Grids</h1>\r
11 \r
12 <p>The Rico library supports 2 different types of grids: \r
13 <strong>LiveGrid</strong> and <strong>SimpleGrid</strong>. \r
14 LiveGrid data is always buffered in a 2-dimensional JavaScript array. As the user scrolls\r
15 vertically through the grid, data is dynamically copied from the array onto the grid.\r
16 SimpleGrids on the other hand are unbuffered -- all data for the grid exists in the \r
17 <a href="http://en.wikipedia.org/wiki/Document_Object_Model">DOM</a>, not\r
18 in a JavaScript data structure.\r
19 \r
20 <p>Both types of grids share some common features, including:\r
21 <ul>\r
22 <li>column headings that stay fixed and don't scroll off the top of the screen\r
23 <li>frozen columns on the left side of the grid\r
24 <li>resizable columns\r
25 <li>common css styling - styles developed for LiveGrids also work for SimpleGrids and vice versa\r
26 <li>compatibility with languages that read right-to-left (rtl) - \r
27 <a href="asp/rtl/ex1.asp">ASP</a> &amp; <a href="php/rtl/ex1.php">PHP</a> examples are included\r
28 <li>compatibility with Rico pop-up (context) menus\r
29 </ul>\r
30 \r
31 <hr>\r
32 <h2>LiveGrid</h2>\r
33 <p>Rico provides lots of support for loading a LiveGrid buffer. The buffer can can be loaded from:\r
34 <ul>\r
35 <li>a SQL database query\r
36 <li>an XML file\r
37 <li>an HTML table\r
38 <li>a javascript array\r
39 </ul>\r
40 \r
41 <h3>Connecting LiveGrid to a database</h3>\r
42 <p>To simplify the task of loading a LiveGrid with SQL query results, Rico comes with a set of "plug-ins" which\r
43 connect your database to your LiveGrid. Rico plug-ins have been tested with the following\r
44 databases:\r
45 \r
46 <p><table border='1' cellspacing='0' cellpadding='4' class='compat' style='margin-bottom:0px'>\r
47 <thead>\r
48 <tr>\r
49 <th>&nbsp;</th>\r
50 <th>MySQL</th>\r
51 <th>Oracle</th>\r
52 <th>DB2</th>\r
53 <th>SQL Server</th>\r
54 <th>MS Access</th>\r
55 </tr>\r
56 </thead>\r
57 <tbody>\r
58 <tr>\r
59 <th>PHP</th>\r
60 <td><img src='images/checkmark.gif' alt='checkmark'></td>\r
61 <td><img src='images/checkmark.gif' alt='checkmark'></td>\r
62 <td>&nbsp;</td>\r
63 <td><img src='images/checkmark.gif' alt='checkmark'></td>\r
64 <td><img src='images/checkmark.gif' alt='checkmark'></td>\r
65 </tr>\r
66 <tr>\r
67 <th>ASP</th>\r
68 <td><img src='images/checkmark.gif' alt='checkmark'></td>\r
69 <td><img src='images/checkmark.gif' alt='checkmark'></td>\r
70 <td><img src='images/checkmark.gif' alt='checkmark'></td>\r
71 <td><img src='images/checkmark.gif' alt='checkmark'></td>\r
72 <td><img src='images/checkmark.gif' alt='checkmark'></td>\r
73 </tr>\r
74 <tr>\r
75 <th>.net</th>\r
76 <td><img src='images/checkmark.gif' alt='checkmark'></td>\r
77 <td><img src='images/checkmark.gif' alt='checkmark'></td>\r
78 <td><img src='images/checkmark.gif' alt='checkmark'></td>\r
79 <td><img src='images/checkmark.gif' alt='checkmark'></td>\r
80 <td><img src='images/checkmark.gif' alt='checkmark'></td>\r
81 </tr>\r
82 </tbody>\r
83 </table>\r
84 <p style='font-size:8pt; margin:0px;'>Rico plug-in/database compatibility as of Nov 2007\r
85 <br>\r
86 <br>* The ASP plug-in uses ADO and the .net plug-in uses ADO.net,\r
87 <br>and thus should be able to connect with any data source that is compatible with ADO</p>\r
88 \r
89 <p>LiveGrid uses <a href="http://en.wikipedia.org/wiki/Ajax_%28programming%29">AJAX</a> \r
90 technology so that only a portion of the SQL query result is\r
91 sent to the client at a time. As the user scrolls the grid, the JavaScript code determines\r
92 which portion of the query results are required and sends an AJAX request back to the plug-in.\r
93 The plug-in retrieves those results from the database and returns them back to the client.\r
94 So whether your query returns 10 rows or 100,000 rows, LiveGrid can display the results\r
95 quickly and easily with an intuitive user interface.\r
96 \r
97 <p>Finally, if your users are allowed to make changes to the data, the Rico plug-ins \r
98 make that easy too. Just define your grid using <strong>LiveGrid Forms</strong> -- \r
99 Add, Edit, and Delete record\r
100 selections will be added to the grid's context (popup) menu. \r
101 \r
102 <ul>\r
103 <li>When Add or Edit is selected, a popup\r
104 form will be presented to the user. \r
105 <li>When the user "saves" the form, the data is posted back\r
106 to the original script, which writes the results back to the database. \r
107 </ul>\r
108 \r
109 <p>If it sounds complicated, don't worry! All of this work is handled by the plug-in. \r
110 See the "ex2edit" example\r
111 for a demonstration of how easy it is, both for the user and the programmer.\r
112 "ex4edit" demonstrates how to make multiple grids on a page editable.\r
113 \r
114 <h3>Populating LiveGrid with XML</h3>\r
115 \r
116 <p>While plug-ins make it easy to load data into a LiveGrid, they are not required.\r
117 A LiveGrid buffer can be loaded with XML data from any source, as long as the data follows this format:\r
118 \r
119 <pre>\r
120 &lt;ajax-response&gt;\r
121 &lt;response type='object' id='MyGridId_updater'&gt;\r
122 &lt;rows update_ui='true' offset='0'&gt;\r
123 &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
124 &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
125 &lt;/rows&gt;\r
126 &lt;/response&gt;\r
127 &lt;/ajax-response&gt;\r
128 </pre>\r
129 \r
130 <p>See the weather and photo examples, which retrieve data from Yahoo Weather and Flickr respectively and reformat the data\r
131 into the structure shown above. These examples are currently available in PHP and .net versions, but not ASP.\r
132 \r
133 <h3>Populating LiveGrid with data from an HTML table</h3>\r
134 \r
135 <p>A LiveGrid can also be easily created on a web page that contains a traditional HTML table.\r
136 Just assign an id to the table and pass that id in during LiveGrid initialization. Headings\r
137 will be taken from the table's thead section and data from the tbody. No AJAX is\r
138 performed in this case, but the data is still buffered in a JavaScript array. Several\r
139 examples are included in the Rico distribution, look for the ones marked "LiveGrid-Static Buffer"</p>\r
140 \r
141 <hr>\r
142 <h2>SimpleGrid</h2>\r
143 \r
144 <p>SimpleGrid's are new to Rico 2.0 and share some of the same functionality as LiveGrids - \r
145 resizable columns, frozen columns, and frozen headings. \r
146 However, unlike a LiveGrid, the data is static and resides in the DOM -\r
147 so no buffering, no AJAX refreshes, no sorting, no filtering.\r
148 Why would you use a SimpleGrid? \r
149 <ol>\r
150 <li>Because it is more flexible in what each cell can contain - \r
151 cells in a column do not all have to be of the same type.\r
152 <li>In some circumstances, it can perform better on the client than LiveGrid; \r
153 particularly on a slow client displaying a grid with many columns.\r
154 <li>Finally, a SimpleGrid can contain input elements (checkboxes, select lists, etc). \r
155 While a LiveGrid can also contain input elements, because the element values are stored in the\r
156 LiveGrid buffer, submitting the values back to the server can be tricky.\r
157 SimpleGrids do not suffer from this problem. You can simply surround the\r
158 entire grid with standard &lt;form&gt;&lt;/form&gt; tags and any\r
159 input elements within the grid will be submitted back to the server.\r
160 </ol>\r
161 \r
162 <p>The most sophisticated example of a SimpleGrid is the spreadsheet\r
163 included with this distribution. You can enter formulas and it will\r
164 recalculate when you change the inputs - just like a commercial spreadsheet.\r
165 A link to the spreadsheet example can be found under the "HTML Examples" section\r
166 of the examples menu.\r
167 When in the spreadsheet, click the <img alt="help" style="vertical-align:top;" src="images/sheet/help.gif"> button to see all it can do.\r
168 \r
169 <p>SimpleGrids can be created either of two ways:\r
170 <ul>\r
171 <li>By using one of the SimpleGrid plug-ins. Plug-ins exist for PHP, ASP, and .net.\r
172 <li>By using XSLT. Rico includes an XSL file that will convert a standard\r
173 HTML table to a SimpleGrid.\r
174 </ul>\r
175 \r
176 <h3>Creating a SimpleGrid by using a plug-in</h3>\r
177 \r
178 <p>Each plug-in defines a SimpleGrid class. Within the class, there are methods\r
179 to start header rows and data rows - just call one of these methods everywhere\r
180 you would put a &lt;tr&gt; tag in an HTML table. There is also a method to\r
181 create a cell - just call it everywhere\r
182 you would put a &lt;th&gt; or &lt;td&gt; tag in an HTML table.\r
183 When you are done defining the table content, just call the render method\r
184 (except in the .net plugin where render is called automatically).\r
185 It's that easy!\r
186 \r
187 <h3>Creating a SimpleGrid by using XSLT</h3>\r
188 \r
189 <p>If your web page is XHTML compliant, then there is another way to generate a SimpleGrid.\r
190 Just use the XSL stylesheet "ricoSimpleGrid.xsl" to transform tables in your page\r
191 to SimpleGrids. The stylesheet looks for tables with a class name of "ricoSimpleGrid" \r
192 and then does the transformation for you. At one time, Rico supported doing this\r
193 transformation on the client. However, due to changes in the Prototype library, this\r
194 is no longer possible. Therefore, if you choose to use this approach, the XSLT transform\r
195 must be performed on the server.\r
196 \r
197 </body>\r
198 </html>\r