Events

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.

<!doctype html>

<head>

<title>Simple</title>

type="text/css" />

type="text/css" />

$(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" enablePrint="true" enablePreferencePersistence="true" enableExport="true" forcePagerRow="true" pageSize="50" enableFilters="true" enableFooters="true" enablePaging="true">' +

' <level>' +

' <columns>' +

' <column type="checkbox"/>'+

' <column dataField="id" headerText="ID" filterControl="TextInput" filterOperation="Contains" footerLabel="Sum: " footerOperation="sum" footerOperationPrecision="2"/>' +

' <column dataField="type" headerText="Type" filterControl="TextInput" filterOperation="Contains" />' +

' </columns>' +

' </level>' +

' ' +

' </grid>',

dataProvider: [

{ "id": "5001", "type": "None", "active": true },

{ "id": "5002", "type": "Glazed", "active": true },

{ "id": "5005", "type": "Sugar", "active": true },

{ "id": "5007", "type": "Powdered Sugar", "active": false },

{ "id": "5006", "type": "Chocolate with Sprinkles", "active": true },

{ "id": "5003", "type": "Chocolate", "active": false },

{ "id": "5004", "type": "Maple", "active": true }

]

});

</script>

</head>

<body>

</div>

</body>

</html>

When you run this example, and click on a row, you should see the following

Followed by something similar to:

What you just observed was event callbacks in action. 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 events is available below:

afterExport

Dispatched when the grid is finished exporting. At this point, the textWritten variable of the dispatched event is available to you, to customize the generated text if you need to. Event Type:com.flexicious.export.ExportEvent

autoRefresh

Dispatched when the autorefresh interval is hit. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

beforeExport

Dispatched when the grid is about to be exported Event Type:com.flexicious.export.ExportEvent

beforePrint

Dispatched when the grid is about to be generated for the print, or the preview. The event has a handle to the grid that is being printed, as well as the PrintDataGrid instance. This lets you perform custom logic on the PrintDataGrid before the print occurs. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridPrintEvent

beforePrintProviderSet

Dispatched before the beforePrint event, right prior to the data provider being set. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridPrintEvent

cellRendered

Dispatched when the cell is rendered completely. That is, the background and borders are drawn, the renderers are placed Use this event to perform post processing of the cell after the grid has applied all its formatting and positioning Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

change

Dispatched when row selection or cell selection changes. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

clearPreferences

Fired when the grid needs to clear its preferences. Event Type:com.flexicious.grids.events.PreferencePersistenceEvent

columnsResized

Dispatched when the columns at this level are resized Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

columnsShift

Dispatched when columns are dragged and dropped to change their position Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

componentsCreated

Dispatched when all the cells snap to the calculated column widths. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

dynamicAllLevelsCreated

When enableDynamicLevels=true, this event is dispatched whenever all the dynamic levels are created. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

dynamicLevelCreated

When enableDynamicLevels=true, this event is dispatched whenever a new level is created. This event can be used to initialize the newly created level. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

filterPageSortChange

Dispatched when the grid's page, sort or filter state changes. Also Dispatched when an item, that was not previously opened is opened. Used in lazy loaded (filterPageSortMode=server) grids, to load a specific page of data from the backend. Event Type:com.flexicious.nestedtreedatagrid.events.ExtendedFilterPageSortChangeEvent

headerClicked

Dispatched when any header cell is clicked Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

iconClick

Dispatched when user clicks on an icon enabled via the enableIcon flag on a column Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

iconMouseOut

Dispatched when user mouse outs on an icon enabled via the enableIcon flag on a column Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

iconMouseOver

Dispatched when user mouseovers on an icon enabled via the enableIcon flag on a column Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

itemClick

Dispatched when user clicks on a row in row selection mode or cell in cell selection mode Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

itemClose

Dispatched when the use clicks on the disclosure icon to collapse a previously opened item. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

itemClosing

Dispatched when an item is about to close. If you call preventDefault() on the event, the item will not close Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

itemDoubleClick

Dispatched when user double clicks on a row in row selection mode or cell in cell selection mode Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

itemEditBegin

Dispatched when the editor is instantiated. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridItemEditEvent

itemEditBeginning

Dispatched when the user attempts to edit an item. If you call preventDefault on this event, the edit session will not begin. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridItemEditEvent

itemEditCancel

Dispatched when the edit session is cancelled. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridItemEditEvent

itemEditEnd

Dispatched when the edit session ends. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridItemEditEvent

itemEditValueCommit

Dispatched just before committing the value of the editorDataField property of the editor to the property specified by the datafield property of the column of the item being edited. If you call preventDefault on the event, the value will not be committed. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridItemEditEvent

itemFocusIn

Dispatched when the item editor receives focus. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridItemEditEvent

itemLoad

Dispatched only in server mode, when an item opens for the first time. Used to wire up an event handler to load the next level of data in lazy loaded grids.

Event Type:com.flexicious.nestedtreedatagrid.events.ExtendedFilterPageSortChangeEvent

itemOpen

Dispatched when the user clicks on the disclosure icon to expand a previously collapsed item. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

itemOpening

Dispatched when an item is about to open. If you call preventDefault() on the event, the item will not open Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

itemRollOut

Dispatched when user rolls out of a row in row selection mode or cell in cell selection mode (only if rollover on a different item) Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

itemRollOver

Dispatched when user rolls over a row in row selection mode or cell in cell selection mode (only if rollover on a different item) Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

loadPreferences

Fired In preferencePersistenceMode=server , when the grid needs to load its preferences. Fired In preferencePersistenceMode=client , when the grid has successfully loaded preferences. Event Type:com.flexicious.grids.events.PreferencePersistenceEvent

pageSizeChanged

Dispatched whenever the page size is changed.

pdfBytesReady

Dispatched when the user clicks the 'Generate PDF' button on the Print Preview. In response to this user action, the grid simply prints it output to a byte array of page images. This byte array can then be sent to any pdf generation library either on the client or the server, for example Alive PDF. We provide integration code for AlivePDF out of the box. Event Type:com.flexicious.print.PrintPreviewEvent

persistPreferences

Fired when the grid needs to persist its preferences. Event Type:com.flexicious.grids.events.PreferencePersistenceEvent

placingSections

Dispatched prior to the widths, heights, x, and y of the various sections are calculated. By sections, we mean the left locked,right locked and unlocked content, header, footer, and body sections. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

prebuiltFilterRun

Dispatched by the grid when a prebuilt filter is run. Event Type:com.flexicious.grids.events.WrapperEvent

preferencesLoading

Fired right before preferences are being loaded and applied. Event Type:com.flexicious.grids.events.PreferencePersistenceEvent

printComplete

Dispatched when the grid is sent to the printer. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridPrintEvent

printExportDataRequest

Dispatched only in server mode, when the grid needs to print or export more data than is currently loaded in memory. Event Type:com.flexicious.grids.events.PrintExportDataRequestEvent

rendererInitialized

Dispatched when the renderer is initialized.

Please note, any changes you made to the renderer stay in place when the renderer is recycled. So if you make any changes, please ensure that the changes are rolled back in the event handler first. For example, if you set the text to bold if a condition is met, then you should first set it to normal, check for the condition, and then set it to bold. This will ensure that if the renderer was previously used to display something that match the condition, and the current item does not, then we do not display bold text. Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

rowChanged

When enableTrackChanges is set to true, this event is dispatched when any change (add,delete or update) is made to the grid. Only the updates made via the grid editors are tracked.

scroll

Dispatched when the content is scrolled. Event Type:mx.events.ScrollEvent

selectAllCheckBoxChanged

Dispatched when the top level select checkbox is changed

Event Type:com.flexicious.nestedtreedatagrid.events.FlexDataGridEvent

toolbarActionExecuted

Dispatched when any toolbarAction is executed. Wrapper events' data contains the action being executed. If you call prevent default in this event, the default handling code does not execute

Event Type:com.flexicious.grids.events.WrapperEvent

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.