This tutorial will show you how to set up the TreeGrid component for the client and server.
Client
Setting Up TreeGrid in Your XHTML Page
The first thing to do is to define the Nitobi XML namespace in the <html> tag.
<html xmlns:ntb>
Inside the <head> tag, be sure to include the CSS style sheet. We ship several different styles which you can choose from. These styles are all imported into the CSS file installed in the style folder. Make sure that you copy the entire style folder to your web directory.
<link type="text/css" rel="stylesheet" href="styles/nitobi.treegrid.css"></link>
Now, include the JavaScript file for the TreeGrid control.
<script type="text/javascript" src="script/nitobi.treegrid.js"></script>
In order for the TreeGrid to appear on the page, we must initialise it. This is done with a small piece of JavaScript code. Usually we do this with the BODY onLoad event, but it can be done some other time. The argument for the loadComponent method is what the id will be for the TreeGrid you will create. In this example, we will call it, 'myTreeGrid'.
<body onLoad="nitobi.loadComponent('myTreeGrid');">
The last part of the client side code is to put the TreeGrid on the page. This can be done by using a HTML-like declarative markup that allows you to define all the attributes for TreeGrid in an easy and concise to use format. The format for TreeGrid is very similiar to Grid, but with some key differences
<ntb:treegrid id="TreeGrid" width="630" height="500" mode="standard" rowsperpage="20" gethandler="load_customers.php" rootcolumns="customers" theme="nitobi"> <ntb:columns id="customers"> <ntb:expandcolumn childcolumnset="orders" width="50"></ntb:expandcolumn> <ntb:textcolumn label="Customer Name" xdatafld="CustomerName" width="130"></ntb:textcolumn> <ntb:textcolumn label="Contact Name" xdatafld="ContactName" width="130"></ntb:textcolumn> <ntb:textcolumn label="Email" xdatafld="ContactEmail" width="150"></ntb:textcolumn> <ntb:textcolumn label="Phone Number" xdatafld="PhoneNumber"></ntb:textcolumn> </ntb:columns> <ntb:columns id="orders" gethandler="load_orders.php" savehandler="save_orders.php"> <ntb:textcolumn label="Order ID" editable="false" xdatafld="OrderID" width="80"></ntb:textcolumn> <ntb:textcolumn label="Product Name" xdatafld="ProductName" width="200"></ntb:textcolumn> <ntb:textcolumn label="Order Date" xdatafld="OrderDate" width="120"></ntb:textcolumn> <ntb:textcolumn label="Shipped Date" xdatafld="ShippedDate" width="120"></ntb:textcolumn> </ntb:columns> </ntb:treegrid>
In this example, we have two levels of data: Customers and Orders. So in our declaration we have two sets of columns corresponding to the data.
We can indicate that the customers column set has a child set using the <ntb:expandcolumn> and its childcolumnset attribute. The <ntb:expandcolumn> is like other column types (e.g. ntb:textcolumn), but it is responsible for rendering the control to toggle the child set of data.
The orders column set has gethandler and savehandler attributes. Like the same attributes on the Tree Grid, these are urls to some server code responsible for retrieving data to the component and saving changes from the client to the server.
Server
Setting Up the Server to Load and Save Data
We will need three files, 'load_Customers.php', 'load_Orders.php', and 'save_Orders.php', to handle loading and saving the data. In this tutorial, we will use PHP though any of the other supported server technologies are conceptually the same. The files, 'load_Customers.php', 'load_Orders.php', and 'save_Orders.php' are available for download.
Looking at the TreeGrid definition above, we see that the customer's getHandler points to 'load_Customers.php'. And that the order's getHander is 'load_Orders.php' and saveHandler is 'save_orders.php'. Essentially, these files handle the connecting to the database, pulling information from the appropriate tables, and ensuring that the information from the table associates with the table in the TreeGrid that we made.
Because of the length of the files, this tutorial will only highlight the important parts for each file that are necessary for the TreeGrid to function properly.
load_Customers.php
This file is the same as a gethandler for the regular Nitobi Grid.
load_Orders.php
This script is essentially the same as load_customers.php, but with one key difference. When the Tree Grid component in the browser sends the request for data to load_orders.php, it will also send, as query string parameters, the data from the customer row whose orders we want. We can use that data in load_orders.php ensure we get the correct orders data corresponding to the desired customer.
1) Get the CustomerID from the query string parameters sent from the Tree Grid component:
$customerID = $_GET["CustomerID"];
2) Create the MySQL statement using the CustomerID:
$myQuery = "SELECT * FROM tblorders WHERE CustomerID=" . $customerID . " ORDER BY " . $sortColumn . " " . $sortDirection ." LIMIT ". $ordinalStart .",". ($pageSize) .";";
3) Set the foreign key field and the foreign key value on the gethandler object:
$getHandler->DefineForeignKey("CustomerID");
$getHandler->DefineForeignKeyValue($customerID);
This is necessary for the Tree Grid to be able to properly handle row inserts. When we insert an Order record on the client side, we need to know which Customer to associate it with when we send a save request to the server. The Tree Grid on the client is agnostic to how your database is configured when it is initialized, so we define the association as above to inform the component.
N.B. If you do not need to insert records, you do not need to define the foreign key field or value.
N.B. You must set the $getHandler->SetTotalRowCount(numberOfRowsReturned); otherwise the TreeGrid will not load.
save_Orders.php
Again, this handler looks like any other savehandler but with one change. When we process inserts, we need to get the value for the foreign key (which is the CustomerID we set in load_Orders.php). We do that with a call to the ReturnForeignKeyValue method:
$myQuery = "INSERT INTO tblorders (CustomerID, ProductName, OrderDate, ShippedDate) VALUES (" .
"'" . $saveHandler->ReturnForeignKeyValue($currentRecord) . "'," .
"'" . $saveHandler->ReturnInsertField($currentRecord, "ProductName") . "', " .
"'" . $saveHandler->ReturnInsertField($currentRecord,"OrderDate") . "', " .
"'" . $saveHandler->ReturnInsertField($currentRecord,"ShippedDate") . "'" .
"); ";
// Now we execute this query
mysql_query($myQuery);
In order for ReturnForeignKeyValue to work properly, you must call setForeignKey and setForeignKeyValue in the corresponding gethandler (which is load_Orders.php in this example).
Full Sample Code
You can download the full sample code here.
