JavaScripTools Manual

JavaScripTable

Table properties

JavaScripTable has many properties that allow you to customize the table according to your needs.

The categories are:

• Look and feel
• The table working modes
• Row display
• Row selection
• Callbacks
• Messages
• Additional headers and footers

Look and Feel

There are many look and feel options, so, there is a separate chapter for it.

The table working modes: client and server

The table may be used on both client side or server side modes. This is set using the operationMode property, that can be set to JST_CLIENT_SIDE or JST_SERVER_SIDE. The default value is determined by the JST_DEFAULT_OPERATION_MODE constant.

On client side mode, the table assumes that all rows it contains are all existing rows, so it can handle paging and sorting automatically.

The server side mode requires additional information. The table assumes that the rows it contains belong to the current page, and other rows exists. The rowCount property must be set to the number of total rows. Also, the updateTableFunction must be set to a function reference, and will be called whenever the table must load another page, or change sorting. The function will receive the table reference as argument, and can read from there properties like currentPage, pageSize, sortColumn and ascSort.

There is a specific sample for working with server-side tables here. Here are some examples:

//We need a function to process the table update
function updateTable(table) {
    //Reload with the new page number
    self.location = "mypage?page=" + table.currentPage;
}
var table = new JavaScripTable(...);
table.operationMode = JST_SERVER_SIDE;
table.updateFunction = updateTable;
table.rowCount = 100; //The server script must know how many rows exists
table.addColumn(...); //Add all columns
table.addRow(...); //Add all rows
table.render();

If you do not want allow the user to change sorting (it would have to be handled at server side), you can set each column sortable property to false.

Row display

The row count may be limited using the maxRows property. -1 means no limit, and the default value is determined by the JST_DEFAULT_MAX_ROWS constant.

Rows may be displayed by pages or not (showing all rows). This is set by the usePaging property to a boolean value (defaults to JST_DEFAULT_USE_PAGING). If set to true, the results are paged. When paging is used, the pageSize (defaults to JST_DEFAULT_PAGE_SIZE) is used to determine how many rows are displayed per page. The currentPage property reflects the page the user is viewing. The getMaxPage() method may be used to return the page count. Paging may be changed by the user on the navigation bar

Row selection

JavaScripTable offers full control over row selection, offering 3 selection styles:

Selection type	Constant	Control type
No selection	JST_SEL_NONE	None
Single row	JST_SEL_SINGLE	Radio Button
Miltiple row	JST_SEL_MULTIPLE or JST_SEL_MULTI	Checkbox

The selection type is defined using the selectionType property, that has the default value by the JST_DEFAULT_SELECTION_TYPE constant.

It is possible to determine the control name, so, if the table is inside a form, and the form is submitted, it is possible to retrieve the selected rows on the request. this is done with the selectionName property (JST_DEFAULT_SELECTION_NAME is the default value constant). If selectionName is null, a name will be generated. The value for each radio or checkbox is the row identifier.

One last possible customization on selection is the property selectionValign, that determine the vertical align for selection cells, and have the default value determined by JST_DEFAULT_SELECTION_VALIGN.

Callbacks

There are several callbacks that may be used to respond to table events:

• Row functions: A function called when the user clicks on a row. Set the table's rowFunction to the function reference. The arguments passed to the function are the row identifier and the table reference.
• Cell functions: A function called when the user clicks on a cell of a given column. Set the column's cellFunction to the function reference. The arguments are the row identifier, the column index and the table reference.
• Table render event: A callback called when the table is rendered (drawn). Set the table's onRender property to the function reference, and, when the table is rendered, the function is called, passing the table reference as argument
• Selection change event: A callback called when the user changes the table selection. Set the table's onSelectionChange property to the function reference, and, when the use clicks on a row selection control, the function is called, passing the row identifier, a flag indicating whether the row is selected or not and the table reference as arguments. If the function returns false, the selection is not changed




Messages

Several messages may be displayed to the user (their defalt value is determined by the constant between parenthesis):

• A header and footer text may be displayed by setting the headerText (JST_DEFAULT_HEADER_TEXT) and footerText (JST_DEFAULT_FOOTER_TEXT) properties.
• A text may be displayed instead of an empty table by setting the emptyTableText (JST_DEFAULT_EMPTY_TABLE_TEXT) property.
• A text may be displayed when data is being rendered, by setting the waitText (JST_DEFAULT_WAIT_TEXT) property.
• ascLabel (JST_DEFAULT_ASC_LABEL) and descLabel (JST_DEFAULT_DESC_LABEL) are images or text displayed after the sort column header. Their default values are Image objects. If you want to change them to a text, simply assign a string to the properties. To change the image location, set the src property to the desired image location.
• trueLabel (JST_DEFAULT_TRUE_LABEL) and falseLabel JST_DEFAULT_FALSE_LABEL work like the former item, but define images or strings that will be shown to display boolean true and false values.




Additional headers and footers

Besides to the headerText and footerText that generates, respectively, a header and a footer occupying all visible columns, additional header and footer rows may be added.

The method addHeader and addFooter may be called to add another header or footer row. They return a cell container, which offer a method called add that takes 2 arguments: the text and an optional object containing arbitrary properties that will be generated as the <td> element attributes. The addHeader may also receive arbitrary arguments as objects, containing a text property that will generate the cell text and the other properties that will generate the cell attributes.

Note that the content is written without taking in account the number of visible columns, so, it's up to the developer to generate the correct number of cells, as well as correct values for colspan / rowspan attributes.

Here is an example:

//Assume table is a valid instance. This may be before or after adding columns / rows

//Adding cells after the addHeader() method
var header = table.addHeader();
header.add("Customer data", {colspan: 3, class: "MyCustomClass"});
header.add("Product data", {colspan: 2});

//Adding cells inline - note the text attribute
table.addHeader(
    {text: "Identification", colspan: 2}, 
    {text: "Last purchase", nowrap: true},
    {text: "Price"},
    {text: "Amount", align: "right"});

//Add a footer on a with statement
with (table.addFooter()) {
    add("Total", {colspan: 3, align: "right"});
    add("827.232,12");
}
...
table.render();

Also, there are other methods related to additional headers and footers: getHeaderCount, clearHeaders, getFooterCount and clearFooters, all self explanatory.



---

Previous: Working with the JavaScripTable

Table of Contents

Next: Manipulating the table