Creating a Rico LiveGrid

Rico LiveGrid displays data in a scrolling table, with the data buffered in a 2-dimensional JavaScript array. As the user scrolls vertically through the grid, data is dynamically copied from the array onto the grid. The buffer can can be loaded from:

an HTML table
an XML file
a SQL database query

Usage Model 1: Loading data from an HTML table

Define an HTML table with the headings in a <thead> section and the data in a <tbody> section.

<table id="data_grid">
  <thead>

  <tr>
    <th>First column name</th>
    <th>Second column name</th>
    ...
    <th>Last column name</th>
  </tr>

  </thead>

  <tbody>

  <tr>
    <td>Row 1, column 1 data</td>
    <td>Row 1, column 2 data</td>
    ...
    <td>Row 1, last column data</td>
  </tr>

  <tr>
    <td>Row 2, column 1 data</td>
    <td>Row 2, column 2 data</td>
    ...
    <td>Row 2, last column data</td>
  </tr>

  ...

  <tr>
    <td>Row n, column 1 data</td>
    <td>Row n, column 2 data</td>
    ...
    <td>Row n, last column data</td>
  </tr>

  </tbody>
</table>

Load the Rico javascript and css files necessary to display the grid.
```
Rico.loadModule('LiveGrid','LiveGridMenu','greenHdg.css');
```
LiveGrid
This loads the Rico javascript and css files necessary to display a LiveGrid with a static buffer (no AJAX).
LiveGridMenu
This loads the default grid menu. This menu provides access to all of the LiveGrid capabilities. It adjusts the selections presented to the user based on the column selected and the type of buffer used. You can also choose to use the grid with no menu at all, or to create your own menu customized to the needs of your application.
greenHdg.css
Rico comes with several sample grid styles: coffee-with-milk, grayedout, greenHdg, iegradient (Internet Explorer only), tanChisel, and warmfall. You may choose one of the included styles or create one of your own.

Load the table's data rows into a Rico Buffer object:

var buffer = new Rico.Buffer.Base($('data_grid').tBodies[0]);

Finally, instantiate the LiveGrid, passing in the DOM id of the HTML table, the Rico.Buffer instance, and any options (in this case the first column gets a width of 50 pixels and the second column gets a width of 80 pixels).
```
var grid_options = { columnSpecs: [ {width:50}, {width:80} ] };
var grid = new Rico.LiveGrid('data_grid', buffer, grid_options);
```

Rico.loadModule may finish after the window.onload event. So to ensure that the grid initialization runs after the Rico modules have loaded, you must pass the initialization function to the Rico.onLoad method. Putting all of the javascript together would look like this:

<script type='text/javascript'>
Rico.loadModule('LiveGrid','LiveGridMenu','greenHdg.css');

Rico.onLoad( function() {
  var buffer = new Rico.Buffer.Base($('data_grid').tBodies[0]);
  var grid_options = { columnSpecs: [width:50, width:80] };
  var grid = new Rico.LiveGrid('data_grid', buffer, grid_options);
});
</script>

Usage Model 2: Loading data from an XML file

Define an HTML table, supplying the table header cells, but no table body cells.

<table id="data_grid">
  <tr>

    <th>First column name</th>
    <th>Second column name</th>

  </tr>
</table>

Load the Rico javascript and css files necessary to display the grid.
```
Rico.loadModule('LiveGridAjax','LiveGridMenu','greenHdg.css');
```
LiveGridAjax
This loads the Rico javascript and css files necessary to display a LiveGrid with an AJAX-enabled buffer.
LiveGridMenu
This loads the default grid menu. This menu provides access to all of the LiveGrid capabilities. It adjusts the selections presented to the user based on the column selected and the type of buffer used. You can also choose to use the grid with no menu at all, or to create your own menu customized to the needs of your application.
greenHdg.css
Rico comes with several sample grid styles: coffee-with-milk, grayedout, greenHdg, iegradient (Internet Explorer only), tanChisel, and warmfall. You may choose one of the included styles or create one of your own.

Create a Rico Buffer, which fetches data to populate the table.

var buffer = new Rico.Buffer.AjaxXML('/controller/action?format=xml');

The URL ("/controller/action?format=xml" in this example) must return data in the following format:

<ajax-response>
<response type='object' id='data_grid_updater'>
<rows update_ui='true' offset='0'>
<tr><td>Data for row 1, cell 1</td><td>Data for row 1, cell 2</td></tr>
<tr><td>Data for row 2, cell 1</td><td>Data for row 2, cell 2</td></tr>
</rows>
</response>
</ajax-response>

Finally, instantiate the LiveGrid, passing in the DOM id of the HTML table, the Rico.Buffer instance, and any options (columnSpecs is not required, but shown here as a placeholder for customization of the columns).
```
var grid_options = { columnSpecs: [,] };
var grid = new Rico.LiveGrid('data_grid', buffer, grid_options);
```

<script type='text/javascript'>
Rico.loadModule('LiveGridAjax','LiveGridMenu','greenHdg.css');

Rico.onLoad( function() {
  var buffer = new Rico.Buffer.AjaxXML('/controller/action?format=xml');
  var grid_options = { columnSpecs: [,] };
  var grid = new Rico.LiveGrid('data_grid', buffer, grid_options);
});
</script>

Usage Model 3: Loading data from an SQL database query

The descriptions below apply directly to the ASP and PHP implementations of LiveGrid. The concepts are the same in .net, but the implementation is quite different (examine ex2simple.aspx to see how this gets implemented in .net).

Define a session variable that contains the query to be run. The variable name must match the id of the table below. When requesting data, the grid will pass its id to ricoXMLquery, and ricoXMLquery will use it to get the query text from the session variable.
- ASP:
```
<%
session.contents("data_grid")="select ID,Name,City from customers"
%>
```
- PHP:
```
<? 
$_SESSION['data_grid']="select ID,Name,City from customers";
?>
```

Define an HTML table, supplying the table header cells, but no table body cells.

<table id="data_grid">
  <tr>

    <th>Customer #</th>
    <th>Customer Name</th>
    <th>City</th>

  </tr>
</table>

Load the Rico javascript and css files necessary to display the grid.
```
Rico.loadModule('LiveGridAjax','LiveGridMenu','greenHdg.css');
```
LiveGridAjax
This loads the Rico javascript and css files necessary to display a LiveGrid with an AJAX-enabled buffer.
LiveGridMenu
This loads the default grid menu. This menu provides access to all of the LiveGrid capabilities. It adjusts the selections presented to the user based on the column selected and the type of buffer used. You can also choose to use the grid with no menu at all, or to create your own menu customized to the needs of your application.
greenHdg.css
Rico comes with several sample grid styles: coffee-with-milk, grayedout, greenHdg, iegradient (Internet Explorer only), tanChisel, and warmfall. You may choose one of the included styles or create one of your own.

Create a Rico Buffer, which fetches data to populate the table.

var buffer = new Rico.Buffer.AjaxSQL('ricoXMLquery.asp');

The URL ("ricoXMLquery.asp" in this example) utilizes one of the included plug-ins to fetch data from the database and return it to the grid in this XML format:

<ajax-response>
<response type='object' id='data_grid_updater'>
<rows update_ui='true' offset='0'>
<tr><td>Data for row 1, cell 1</td><td>Data for row 1, cell 2</td></tr>
<tr><td>Data for row 2, cell 1</td><td>Data for row 2, cell 2</td></tr>
</rows>
</response>
</ajax-response>

Finally, instantiate the LiveGrid, passing in the DOM id of the HTML table, the Rico.Buffer instance, and any options (columnSpecs is not required, but shown here as a placeholder for customization of the columns).
```
var grid_options = { columnSpecs: [,,] };
var grid = new Rico.LiveGrid('data_grid', buffer, grid_options);
```

<script type='text/javascript'>
Rico.loadModule('LiveGridAjax','LiveGridMenu','greenHdg.css');

Rico.onLoad( function() {
  var buffer = new Rico.Buffer.AjaxSQL('ricoXMLquery.asp');
  var grid_options = { columnSpecs: [,,] };
  var grid = new Rico.LiveGrid('data_grid', buffer, grid_options);
});
</script>

Debugging

Rico 2.0 includes the ability route time-stamped debug messages to a message log. The log may be an html textarea or the browser's javascript console.

If a textarea exists with the id of the LiveGrid table plus '_debugmsgs', i.e.
```
<textarea cols="100" rows="5" id="data_grid_debugmsgs" />
```
then this textarea will be used for the message log.

Alternatively, the textarea may be designated by a call to Rico.setDebugArea()

<textarea id='debug' rows='5' cols='80'></textarea>
<script type='text/javascript'>
Rico.setDebugArea('debug');
</script>

If no textarea is designated, Rico will attempt to use the browser's built-in javascript console. The following consoles are known to work:
- The console in Firefox's Firebug add-on
- The Opera javascript console
- The Safari javascript console

Notes

If you create an element with a DOM id matching the name of the LiveGrid table plus '_bookmark', it will be updated with text indicating the number of records displayed in the grid. The LiveGrid examples typically use this markup:
```
<p class="ricoBookmark"><span id="data_grid_bookmark"> </span></p>
```
In order to display properly, a browser displaying a LiveGrid must be operating in strict (aka standards) mode. Therefore, you must include a doctype declaration just before the <html> tag. For example:
```
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" 
 "http://www.w3.org/TR/html4/strict.dtd">
```

Reference

Constructor


  var grid = new Rico.LiveGrid (table_id, rico_buffer, grid_options);

table_id is the DOM id of the table to be populated by LiveGrid
rico_buffer is a Rico Buffer, e.g.
- Rico.Buffer.Base (for non-AJAX tables)
- Rico.Buffer.AjaxXML
- Rico.Buffer.AjaxSQL
grid_options (see below)

Options

Grid Size

visibleRows (rows in .net)

How many rows of the grid are made visible? A positive integer specifies that the grid should always contain exactly that many rows. Negative values have the following meanings:

-1: size grid to client window (default)
-2: size grid to whichever is smaller: the client window or the data
-3: size grid so that the page body does not have a scrollbar
-4: size grid to the parent node in the DOM

minPageRows

Minimum # of visible rows. Used only when visibleRows < 0. (default: 2 - after Rico 2b3, 1 - up to Rico 2b3)

maxPageRows

Maximum # of visible rows. Used only when visibleRows < 0. (default: 50)

Grid Data

offset: First row of data to be displayed (default: 0)
prefetchBuffer: Load the buffer (and therefore the grid) on page load? (default: true)
sortCol: Name or index of column for initial sort
sortDir: Direction of initial sort
possible values: 'ASC', 'DESC'
getQueryParms: If true, check the web page's query string for filter parameters and apply any filter that is found. Filter parameters must be of the form "f[x]=" where x is the column index. (default: false)

Header Configuration

headingSort

A string that defines how headings are displayed to facilitate sorting.

'link' -- make headings a link that will sort columns (default)
'hover' -- user can click in any part of the heading cell to sort. Heading changes background color when cursor hovers over cell.
'none' -- events on headings are disabled

hdrIconsFirst

Put sort and filter icons before or after header text (default: true)

panels

An array of strings that can serve as secondary headings. In LiveGrid Forms, they also serve as the headings for the tabbed panels on the input form.

PanelNamesOnTabHdr

Set to 'true' for the strings in panels[] to be used as secondary headings. In LiveGrid Forms, it may be set to 'false' so that panels[] is only used on the input form.

Images

resizeBackground: Image to use for column resize handle. (default: 'resize.gif')
sortAscendImg: Image to use to indicate that the column is sorted in ascending order. (default: 'sort_asc.gif')
sortDescendImg: Image to use to indicate that the column is sorted in descending order. (default: 'sort_desc.gif')
filterImg: Image used to indicate an active filter on a column. (default: 'filtercol.gif')

Cookie options

saveColumnInfo: Specifies which details to save in the grid's cookie. Only one cookie is used for each grid. Note that the width setting includes the hide/show status of the column. (default: {width:true, filter:false, sort:false})
cookiePrefix: A string that is prepended to the cookie name. (default: 'RicoGrid.')
cookieDays: Number of days before the cookie expires. If you don't specify it, then the cookie is only maintained for the current session. (default: null)
cookiePath: Sets the top level directory from which the grid cookie can be read. If you don't specify it, it becomes the path of the page that sets the cookie. (default: null)
cookieDomain: Tells the browser to which domain the cookie should be sent. If you don't specify it, it becomes the domain of the page that sets the cookie. (default: null)

Highlighting and selection

highlightSection

which section of the table is highlighted

1 -- frozen
2 -- scrolling
3 -- all (default)
0 -- none

highlightMethod

Method used to highlight cells & rows. Possible values:

'outline' -- least CPU-intensive on client-side
'class' -- adds CSS class to highlighted cell/row (default)
'both' -- highlight using both outline and class

highlightClass

When highlighting by class, this is the class name used (default: 'ricoLG_selection')

Export and print

maxPrint: The maximum number of rows that the user is allowed to Print/Export. Set to 0 to disable print/export. (default: 1000)

Event-handling

sortHandler: (default: Rico.LiveGridMethods.sortHandler -- bound)
filterHandler: (default: Rico.LiveGridMethods.filterHandler -- bound)
onRefreshComplete: (default: Rico.LiveGridMethods.bookmarkHandler -- bound)
rowOverHandler: (default: Rico.LiveGridMethods.rowMouseOver -- bound as event listener)
mouseDownHandler: (default: Rico.LiveGridMethods.selectMouseDown -- bound as event listener)
mouseOverHandler: (default: Rico.LiveGridMethods.selectMouseOver -- bound as event listener)
mouseUpHandler: (default: Rico.LiveGridMethods.selectMouseUp -- bound as event listener)
onscroll: called whenever the grid is scrolled vertically. (default: null)
onscrollidle: called 1.2 seconds after the grid is scrolled vertically. (default: null)

Per-column configuration

Hdg: An alternate way of specifying the heading text for a column. Only used by LiveGrid if the grid id refers to a <div> instead of an html table.
canSort: Column can be sorted. (default: grid.options.canSortDefault)
canFilter: Column can be filtered. (default: grid.options.canFilterDefault)
canHide: Column can be hidden/unhidden. (default: grid.options.canHideDefault)
visible: Column is initially unhidden. If grid.options.saveColumnInfo.width is true and there is a value in the cookie for this column, the cookie value will take precedence. (default: true)
width: Initial width for column. If grid.options.saveColumnInfo.width is true and there is a value in the cookie for this column, the cookie value will take precedence. (default: grid.options.defaultWidth)
noResize: Allow column to be resized? (default grid.options.allowColResize )
ClassName: Set this to 'alignright' or 'aligncenter' as needed - see example. Note that this does not align the header - use a align="right" on the <th> line to accomplish the header alignment. (default: table_id + '_col' + column_index)
format: possible values: dollar, euro, percent, qty, default
type: possible values: text, showTags, number, datetime, date, control, raw (default)
control: If type=control, then this is the object used to format data in the column.

Number formatting:

multiplier

The value is multiplied by this number before it is displayed. (default: 1)

decPlaces

Number of places to the right of the decimal point. (default: 0)

decPoint

Decimal point symbol. (default: '.' but overridden in the translation files)

thouSep

Symbol for thousands separator. (default: ',' but overridden in the translation files)

negSign

Specifies how negative numbers should be displayed. Possible values:

L=leading minus (default)
T=trailing minus
P=parentheses

prefix

A string added to the beginning of the number. Typically a currency symbol.

suffix

A string added to the end of a number. For example, a "%" symbol.

Date formatting:

dateFmt

A string specifying how the date or datetime should be displayed. Default is "translateDate", which means that the dateFmt and timeFmt strings in the RicoTranslate object are used (this defaults to "mm/dd/yyyy" for dates and "mm/dd/yy hh:mm:ss a/pm" for datetimes, but is overridden by the various language translation files). If dateFmt="localeDate", then the value is formatted using javascript's built-in toLocaleDateString() function. If dateFmt="localeDateTime", then the value is formatted using javascript's built-in toLocaleString() function. The dateFmt string may contain the following special character sequences:

yyyy - year
mmmm - month name
mmm - 3 character month name abbreviation
mm - 2 digit month number (zero padded)
m - 1 or 2 digit month number
dddd - day-of-the-week
ddd - 3 character day-of-the-week abbreviation
dd - 2 digit day number (zero padded)
d - 1 or 2 digit day number
hh - 2 digit hour, 12-hour clock (zero padded)
h - 1 or 2 digit hour, 12-hour clock
HH - 2 digit hour, 24-hour clock (zero padded)
H - 1 or 2 digit hour, 24-hour clock
nn - 2 digit minutes (zero padded)
ss - 2 digit seconds (zero padded)
a/p - a or p (for am or pm)

// display first column as "month year"
columnSpecs : [{type:date, dateFmt:'mmm yyyy'}]

prefix

A string added to the beginning of the date.

suffix

A string added to the end of a date. For example, you could use this to include a time zone:

// indicate that times are GMT/UTC
columnSpecs : [{type:datetime, suffix:' UTC'}]