One of the strongest selling points of HTMLTreeGrid is the ability to work with its extensive API. We designed the product to be extremely developer friendly, and since it has grown from years of experience a lot of thought has gone into making it possible for you to customize its behavior, and program logic around its features. Event Handlers and Function Callbacks are a prime example of this paradigm.

The grid, at various points in its lifecycle dispatches events. These are quite similar to HTML Dom events, and if you are coming to HTMLTreegrid from our other products should be quite straight forward to you conceptually. Even if you are new to HTMLTreeGrid in theory, it is quite simple to grasp. Something of interest happens, an event is dispatched. Anyone interested in these events can listen for them. There are different points in the grids lifecycle that it will dispatch these events, from initialization, to dataProviderSet, to rendered, to mouse interactions like mouseover, mouse out, item click, edit begin, edit end, etc.. Let’s take a look at a quick example. Pay close attention to the markup in yellow highlight.

 

Lets take a quick look at an example

        $(document).ready(function () {

            myCompanyNameSpace.onChange = function (evt) {

                var grid = evt.target;

                var selectedItems = grid.getSelectedObjects();

                alert("selected objects: " + flexiciousNmsp.UIUtils.extractPropertyValues(selectedItems,"id"));

            }

            myCompanyNameSpace.onItemClick = function (evt) {

                var grid = evt.target;

                alert('You clicked on ' + evt.item.id);

            }

            var grid = new flexiciousNmsp.FlexDataGrid(document.getElementById("gridContainer"),

                    {

 

                        configuration: '<grid id="grid" itemClick="myCompanyNameSpace.onItemClick" change="myCompanyNameSpace.onChange"

...

This should show you :

In this example we just wired up a couple events, itemClick and change. Although they are not related, but they notify you of two different things, one that the user clicked on a row and the second that the selection of the grid has changed. Another important point to notice, is that the functions that are defined as the call backs, are defined under the “myCompanyNameSpace”. This way, all your callbacks can be defined in a way that is accessible to the grid as it navigates through the markup XML. The same concept is used for itemRenderers (which point to functions that are classes), and call back functions that we cover later in this chapter. These are just a couple examples of a very rich set of events and notifications that the grid knows to dispatch

 

 

A Full list of these events can be found on our docs: Some of these events are also dispatched by the Column and the Level, and you can review the entire list of events in the docs. http://htmltreegrid.com/docs/classes/flexiciousNmsp.FlexDataGrid.html http://htmltreegrid.com/docs/classes/flexiciousNmsp.FlexDataGridColumn.html http://htmltreegrid.com/docs/classes/flexiciousNmsp.FlexDataGridColumnLevel.html All of these event names can be used in the configuration XML. Note, that the callback handler usually gets an event object, which contains a lot more information about the specific type of the event being dispatched.

 

 

Function Callbacks:

In addition to events, there are a number of API variables that are of type Function. This basically means that you can provide a function that executes your own logic. These differ from events primarily in the fact that the grid is asking something of you instead of just notifying you that something happened. For example, there is a function callback, cellBackgroundColorFunction that will pass you a cell, and expect a return value of a color, that you can then use to execute custom logic to provide the background color for the cells. Let’s take a quick look at an example:

 

myCompanyNameSpace.getCellBackground = function (cell) {

                if (!cell.getRowInfo().getIsDataRow()) {

                    return null;

                }

                if (cell.getColumn().getDataField() == "type") {

                    return 0x0000ff;

                } else if (cell.getRowInfo().getData().type == "Glazed") {

                    return 0x00ff00;

                }

                return null; //this makes the grid use whatever color it would have by default.

            }

            var grid = new flexiciousNmsp.FlexDataGrid(document.getElementById("gridContainer"),

                    {

 

                        configuration: '<grid id="grid" itemClick="myCompanyNameSpace.onItemClick" change="myCompanyNameSpace.onSelectAll" cellBackgroundColorFunction="myCompanyNameSpace.getCellBackground"

This gives you: