There are two ways to bind Grid to data. One is to static data contained on the page, and the other is to use Ajax to call back to the server for it. Nitobi Grid uses XMLHttp to load and save data to remote datasources. An API is provided to format data according to the Nitobi XML schema in a variety of platforms including Java, PHP, Classic ASP, and Coldfusion.
Parts of a Databound Grid
There are several key components to a databound grid. Each of these is represented by an actual page sitting on the server which is called by the Grid at runtime.
getHandler - Loads data from the database and converts it to XML for the grid
saveHandler - Takes updategrams from the grid and converts them to UPDATE's, INSERT's, and DELETE's for the database. This is an optional feature.
keyGenerator - Tells the grid what primary keys to use for newly inserted records. Without this, the grid will assign its own random keys to new rows, which need to be put into the database. The keygenerator is only needed if you are allowing users to insert new rows into the database.
Writing a getHandler
Gethandlers provide data to the Grid and to editors like Lookups and Listboxes. The first step now is to write a gethandler which is in this case an ASP script that outputs XML. Grid calls this page using XMLHttp and displays the data in the grid. The first step is to define it in the grid tag.
Then, we create an Java, PHP, or ASP document that listens for several querystring parameters that tell us where to start returning data:
StartRecordIndex - Which record (ordinally) to start returning data on.
PageSize - How many records to return
SortColumn - Which is the currently sorted column (could be blank)
SortDirection - (Asc or Desc) The direction of sorting
TableId - The datatable being used (by default is _default)
For information on writing getHandlers, choose your platform:
How do we debug our gethandler? Try calling your page with test parameters like this:
.. and go View-source. Make sure you see nicely formatted XML. Alternatively, you can use a tool like FireBug for Firefox to watch the actual XMLHttp requests and view the response (if you aren't getting data in the grid).
Writing a saveHandler
The Savehandler accepts Ajax form posts with XML as the form contents and converts those into SQL instructions to update the datatable. First, we define our savehandler in the Grid tag.
Then we use the Nitobi XML API to assist converting this xml updategram to SQL statements.
For information on writing saveHandlers, choose your platform:
Just like a database table, every record needs a primary key. When inserting new records into a grid we instantly have a small problem in that the Grid needs to assign a primary key to that record in order to keep track of it and synchronize with the database. For this purpose Grid supports a KeyGenerator.
A KeyGenerator is a JavaScript function that executes when you save and must return a primary key for each row. Grid will take this key and assign it to the record and use it to refer to that record from now on. Note: if you do not specify a keygenerator, grid will assign a random key to that record.
There are may ways to tackle this problem, but one way that reduces the amount of legwork on the server is to actually insert the record to the database in the KeyGenerator, not the savehandler and return its primary key. Then, in the savehandler, simply update your already inserted record instead of inserting it.
GetNewRecordID()
Then you need to write a servelet, php script, or asp script to return a number that can be used as the primary key for the record. This number will be returned from GetNewRecord() and put into the Grid data.
