Zentable is a plug-in for the jQuery Javascript library. It allows
to show and manipulate tabulated data on a web page but with functionalities typically expected from
native applications, as scrolling with the mouse wheel, resizing column widths or using keys to move
through the data. It can be used with or without AJAX, but is using AJAX where this plug-in really shines.
Usage:
This plugin requires Draggable from jQuery UI, jquery mousewheel plugin and jquery timers, all of them bundled
with the zentable package, so we include in the header all the scripts and classes needed:
<link rel="stylesheet" type="text/css" href="/css/zentable.css">
<script type="text/javascript" src="/js/jquery.mousewheel.min.js"></script>
<script type="text/javascript" src="/js/jquery-ui-1.7.2.custom.min.js"></script>
<script type="text/javascript" src="/js/jquery.timers-1.1.2.js"></script>
<script type="text/javascript" src="/js/jquery.zentable.min.js"></script>
First create a div with class table in the place where table must show:
<div id="mytable" class="table"></div>
Finally, we invoke the Javascript code that will invoke the plugin:
$("#zentable").zentable({
options...
});
Options:There are several options that allow to change table behaviour and customize it:
- cols
An array containing columns. This is only used when data is embedded in the HTML itself.
Otherwise, when data is retrieved through AJAX requests, this information is got from the XML. Each
column has, at the same time, more options:
name: Name of the column shown in header
id: Name of the column in database (used for sorting or editing)
html: By default false. If true, cells on this column can contain HTML code.
width: Column width in pixels. If not specified, the autowidth algorihtm is used.
editable: If true, this column is editable. Option onedit must be provided.
orderable: True by default. If true, clicking on the header sorts table by that column.
clss: A CSS class to be added to that column.
hidden: A hidden column. May be used to store values that are not going to be shown.
- data
When this option contains an array of rows, being each row an array of columns, the data
shown in the table is got from here. When this option contains an string, it is used as the URL for
making AJAX requests to retrieve the data. If this options is empty, the table is also shown empty.
- hideIfEmpty
Hide completely the table if it is empty. It is true by default.
- filters
An array of strings containing the names of the columns that can be filtered. For each filter,
an input text, checkbox or select box must exists with the column name as id. Each time the value is changed
in the input text, checkbox or select, table data is updated through AJAX.
- onclick
A function that is invoked when a click is done on a cell.
- onedit
A function that is invoked when a cell is edited. For a cell to be editable, this option
must not be undefined and the column has to be created with the editable option.
- order
Which field is used for ordering. Only works when table is AJAXed.
- rows
Maximum number of visible rows (by default 10). If there are more data rows than this option,
the scrollbar is shown. The number of visible rows can be changed on the fly dragging vertically the status
bar of the table.
- stylesInRows
If true, rows can have class.
- totalsRow
If true, a row for showing totals is added at the end of the table.
Methods:
- .zentable('get'): Returns the zentable instance
- .zentable('focus'): Puts the focus on this zentable. Focused table is the one that receives key events.
Using zentable with AJAX: For using zentable with AJAX, provide a string with the URL of the
AJAX data source. This URL must accept at least these parameters:
start: First row to be retrieved (first one is 0)
pagesize: How many rows retrieve
order: Which column use for order
Additionally, for each filter a new parameter with the name of that filter will be sent in the URL.
The AJAX request is expected to return an XML with the next form:
<data>
<headers>
<col id=String [orderable=Boolean] [html=Boolean] [width=Integer]
[editable=Boolean] [class=String]>(Value)</col>+
</headers>+
<row [class=String] >
<col [link=String]>(Value)</col>+
</row>+
[<totals>
<col>(Value)</col>+
</totals>]
<offset>(Value)</offset>
<totalrows>(Value)</totalrows>
</data>
Brackets mean an optional element, and plus means that the node can be repeated N times.
offset will contain the same value as input parameter start, and totalrows contains
the total number of rows (not the number of rows contained in the XML, that will be the same
as pagesize parameter, but the total number of rows that can be viewed scrolling).