Protoplasm

4.5

Rating: 4.5/5 (36 votes)

Live Grid

A live grid control that provides a dynamic, scrollable view into large datasets. Data is loaded on demand as the user scrolls through the list, saving server resources and client memory. This control was originally developed by Rico, but has undergone major changes.

Use the scrollbar at the right to scroll through the data set; although it may not be noticeable, the data is being loaded via AJAX as it is needed. To sort the list, click on a table header. To select rows, you can click, click and drag, or Ctrl / Shift click. Double click to trigger the open event.

Demo

Viewing 1 to 10 of 100 results

ID	Name	Contact Number	Date Added

Selected rows: None

Source Example

<html> <head> <script language="javascript" src="protoplasm.js"></script> <script language="javascript"> Protoplasm.use('livegrid').transform('#livegrid', 10, 100, getData, { sortHeader: 'livegrid_header' }); }); </script> </head> <body> <table id="livegrid_header" cellspacing="0" cellpadding="0" border="0"> <tr> <th id="id" style="width:50px;">ID</th> <th id="name" style="width:300px;">Name</th> <th id="phone" style="width:200px;">Contact Number</th> <th id="added" style="width:165px;">Date Added</th> </tr> </table> <div style="float: left;"> <table id="livegrid" cellspacing="0" cellpadding="0" border="0"> <tbody> <tr> <td style="width:50px;"></td> <td style="width:300px;"></td> <td style="width:200px;"></td> <td style="width:165px;"></td> </tr> </tbody> </table> </div> </body> </html>

Usage

To create live grids out of all elements that match a given CSS rule:

Protoplasm.use('livegrid').transform(selector, rows, count, dataHandler[, options]);

Parameters:

Parameter

Required

Description

selector

yes

A CSS rule matching the tables to turn into live grids

rows

yes

The number of rows to display in the grid

count

yes

The total number of records in the dataset

dataHandler

yes

A callback function that fetches new data on demand

options

An object (hash) containing name/value pairs of additional options.

Available options:

prefetchBuffer	Prefetch nearby rows to simulate quicker response
captureKeyEvents	Capture keypress events for the page to allow keyboard navigation of the list
onscroll	A function to call when the user scrolls the list (useful for updating labels)
selectable	Whether the rows are selectable or readonly (default false)
selectedClass	The CSS class for selected rows (default "selected")
rowIdPrefix	The prefix to add to each row's CSS id (to prevent DOM conflicts)
onrowselect	A function to call when the user selects a row
onrowopen	A function to call when the user double-clicks a row
sortHeader	The CSS id of the table that controls list sorting
sortField	The default field to sort by
sortDir	The default direction to sort by

HTML Structure

The HTML must be structured as follows when creating a LiveGrid.

Sorting Header:

<table id="livegrid_header" cellspacing="0" cellpadding="0" border="0">
    <tr>
        <th id="id" style="width:50px;">ID</th>
        <th id="name" style="width:300px;">Name</th>
        <th id="phone" style="width:200px;">Contact Number</th>
        <th id="added" style="width:165px;">Date Added</th>
    </tr>
</table>

The cell CSS id will be passed to the data handler as the sort field name when sorting is performed.

Live Grid:

<div style="float: left;">
    <table id="livegrid" cellspacing="0" cellpadding="0" border="0">
        <tbody>
            <tr>
                <td style="width:50px;"></td>
                <td style="width:300px;"></td>
                <td style="width:200px;"></td>
                <td style="width:165px;"></td>
            </tr>
        </tbody>
    </table>
</div>

The floating outer div is to allow the scrollbar to be positioned properly. It is important that you provide a blank "template row" for LiveGrid to learn from; it will use it to copy styles and classes from as it creates the data grid. You can of course set the cell widths in the above example to whatever you wish; the important thing is to make them match between the header and the data tables.

Data Handler

The data handling function takes the following parameters:

offset - the offset of the first row to return
limit - the number of rows to return
sortField - the field to sort the data by
sortDirection - the sort direction ("asc" or "desc")
callback - the function to pass the data to (takes a single parameter, an array of rows - see below)

It is up to you how you get the data inside the function (although AJAX calls to the server is generally what makes this class useful), but the structure of the callback data must be similar to the following:

var data = [
    { id: 1, columns: [ 1, 'Jeremy Jongsma', '123-456-7890', '02-15-2006'] },
    { id: 1, columns: [ 1, 'Bob Jongsma', '111-222-3333', '05-02-2005'] },
    { id: 1, columns: [ 1, 'Sue Jongsma', '444-555-6666', '12-23-2007'] }
  ];

Below is a sample data retrieval function that makes an AJAX request to the server. Assume that getData.php is sending the data back in JSON notation, in the structure described above. Otherwise, you should format the data properly in the onComplete handler below before sending it to the callback function.

function getData(offset, limit, sortField, sortDir, callback) {
    new Ajax.Request('/data/getData.php', {
                parameters: {
                    'offset': offset,
                    'limit': limit,
                    'sort': sortField,
                    'dir': sortDir
                },
                onComplete: function(transport) {
                    callback(eval('(' + transport.responseText + ')'));
                }
            });
}

Advanced Usage

If you want more control over creation and destruction of the live grid, you can instantiate it manually instead of using Protoplasm.transform.

In your <head> section:

Protoplasm.use('livegrid');

To create a live grid:

var grid = new Control.LiveGrid(element, rows, count, dataHandler[, options]);

For more details, see the API documentation for Control.LiveGrid.