Developer Area/Core Subsystems/Table Renderer

Example Usage

You simply create an instance of the TableRenderer object (in javascript), passing some parameters defining your table.

var myReference = new TableRenderer(id, source, colspec)

where ...

• id is the id of the TABLE element you wish to put the data in
• source is a url to the json script providing the data in the specified structure (see below)
• colspec is an array defining the columns of the table (see below)

var grouplist = new TableRenderer(
    'grouplist',
    'index.json.php',
    [
        'name',
        'count',
        function(r) { return TD(null,A({'href':'edit.php?id=' + r.id}, 'edit')); }
    ]
);

grouplist.updateOnLoad();


followed by the html table ...

{str tag="groupname"}	{str tag="membercount"}

note: your tables should always include thead for the heading, and tbody for the content, the table renderer will completly replace tbody with each data load.

Your table should also have a class of 'tablerenderer', to add designers.

JSON Specification

The JSON script acting as the data source for a given table renderer should always send arrays of records formatted as follows ...

$data = array(
    'limit'           => 10,
    'offset'          => 0,
    'count'           => 235,
    'otherstatevar'   => 'randomdata',
    'otherglobaldata' => array(
        // ...
    ),
    'data' => array(
        array(    // single record
            'field1' => 'value1',
            'field2' => 'value2',
            'field3' => 'value3',
        ),
        array(    // single record
            'field1' => 'value1',
            'field2' => 'value2',
            'field3' => 'value3',
        ),
        // ...
    ),
);


The data key specifies the data for the actual table, this combined with the column specification defines the bulk of the table appearence. The other keys are read as either state variables, or not at all (except perhaps by the column definition). Both these cases are discussed below.

Column Specification

The column specification (in javascript) defines how records from the JSON data source are rendered into table cells. The column spec is an array where each element defines a single table cell.

Each element can either be a string (in which case that key is extracted from the record and placed in the cell, of a function, in which case the function is passed the record, and the root-level JSON data as parameters in that order. If a function is used, it needs to manually return the TD() element itself.

Additional state

By default, the table renderer will only send offset and limit parameters to your JSON script. If you want to send additional variables to the JSON script, you want to have additional state.

For example, in a search results table, you may want to have the query remain intact while pagination is happening, and for this to work, you need to send the query along with the limit and offset to the json script.

To add a state variable to the table renderer instance, you push the name of the variable onto the statevars array of the object. Additionaly you may want to set an initial value for the state var ...

results.statevars.push('query');
results.query = 'frumpy';


It is best to do this before the call to updateOnLoad().

Triggering updates

If you do something on the page that makes you want to trigger an update of the table content (say the user has entered a new search query), then you can call the doupdate() function. This optionally takes an object parameter defining new values for the state keys (that will be sent to the JSON script). For any keys that are omitted, the existing state values will be used.

Pretend we're on the second page of search results for "frumpy", and the user enters a new search for "flooble". We have 3 state vars (limit=20, offset=20, query="frumpy"). We call doupdate as follows ...

results.doupdate({'offset': 0, 'query': 'flooble'});


This resets the offset to 0, the query to 'flooble', and keeps the limit at it's previous value (although it's still sent to the JSON script).

Pagination

By default, the table renderer will display pagination controls at the top and bottom of the table (using thead and tfoot). If you want to disable (or modify) this behaviour, the following variables are available (although they should be set immediately after creating the table object.

myTableRenderer.paginate = false; // disables pagination entirely
myTableRenderer.paginate_simple = false; // disables the "next" and "previous" page buttons
myTableRenderer.paginate_firstlast = false; // disables the "first" and "last" page buttons


Avoiding empty tables

If you want the table to be replaced by something else when it receives no data from the json script, set the emptycontent field:

results.emptycontent = 'No results found';


When the table updates and gets no data, it hides the table element and displays the contents of this field enclosed in a DIV.