Back to the index of articles and examples

Customizing YUI Library's DataTable

This is an example on how you can customize a DataTable and the DataSource to work your way. Both have not only existing properties customized but I have also added methods to both.

Ut is meant as sample file for my articles on the YUI blog on the using the DataTable, Part 1 and Part 2.

The example is made of this file plus myDataTable.js containing the modified DataTable, myServer.php which handles the back end and ajaxServices.php which handles the back and forth ajax messages plus a few icons. The whole is zipped into file

New records can be added by clicking on the icon, deleted by clicking on the icon and edited with several in-line editors which pops when clicking on a cell.

All changes are transmitted to the server and reflected on the DataTable only when the server approves. For example, the server won't accept deleting records which have an even numbered Id. The record insertion combines defaults from the client and some, such as the database table primary key which the server sends back to the client.

Cell editing is possible on most fields with different editors. All edits are sent and have to be accepted by the server. Just to show that the server can say something about such edits, it will turn into uppercase all strings and will always change the Date field to the current date except when the date is the one being edited.

If you have any tools to monitor the traffic in between the client and the server (in Firebug, the Net tab) you will see the exchange of messages in between them. All messages to the server go as POST with the data URL-encoded, all replies come within a fixed envelope and can be any of the following:

// Plain Ok response
{   "replyCode":200, "replyText":"Ok" }

// Ok with extra data
    "replyCode":201, "replyText":"Data Follows", 
    "data":[{ ..., ..  } , ... ] 
    // or  "data":{ ..., ... } if only a single record.


// Something went wrong
{ "replyCode":500, "replyText":"Something really bad happened" }

Perhaps the most noticeable effect of this customizing in the source code in this very page is how short it is. It is basically an instantiation of my own customized DataTable, called SATYAM.DataTable. The only arguments provided are the container that will hold it, the columns definition and the optional configuration attributes. The DataSource is missing but, no worries, it will be there.

The columns definitions also have some extra properties:

It specifies the data type of a column. This value is the key to a table which defines information about:
It will set the formatter of the column
It will set the parser for this field in the DataSource.responseSchema.fields entry
It will set the editor to the corresponding editor taken from YAHOO.widget.DataTable.Editors
Options to be used as arguments in the instantiation of the editor above
A function to be called to convert the value when concatenating it into the url-encoded message to the server. The value returned will be further url-escaped
A formatter to be used when showing the value in the cell editor. For example, the Price column which is shown in European style with comma as a decimal separator, needs this to show it with the same decimal separator in the textbox editor. You can also enter the value either with comma or dot as a decimal separator but don't use thousands separator, otherwise it will get messed up.
The following types are defined:
  • number
  • currency
  • date
  • string
The string value is a catch-all for non-typed columns. You can add further type definitions in the SATYAM.DataTable.types hash table. For example, the currency definition uses some of the same properties as number except that it uses a formatter with two decimals, thousands separator and a currency sign. You can freely add your own field types
Since the type of editor comes out of the type above you only need to say whether the column is editable or not
When the client needs to send the data to the server, it has to identify the record it belongs to. The columns (one or more) that contain the values that make the Primary Key of the database table to be identified so the client can always send them along any other field that is being modified
Some fields are not relevant to the user. By setting noShow the column won't be displayed. The values for this column will still be available in the Record object
When the user inserts a new record into the DataTable, this values will be inserted plus any that the server might send. In this case, the server will always provide the id value since it is the primary key of the new record, produced from an auto-increment field, which the client cannot guess in advance
The column is made up in the client side, no data comes from the server, no data is sent to the server for these columns
Some of the made up columns are intended for the DataTable to execute some actions. Currently my custom DataTable accepts only two actions, insert and delete

The file myDataTable.js contains further comments. The article A PHP back end to YUI explains how the file ajaxServices.php works and how it is used in myServer.php. This last one lacks access to any database so the database access functions won't work. All the data is generated at random.