News in version
TreeGrid Gantt chart SpreadSheet Examples Documentation Download Development Licensing Prices References Contacts Buy Try it free
Documentation
Search in documentation
TreeGrid versions compatibility

Changes log (txt file) Upgrading from 9.3 to 10.0 Upgrading from 5.9 to 6.0

Creating grid

Simple examples Basic information Creating grid Deleting grid Reloading grid Rendering grid Accessing grid by API

Data & communication
Data communication with server

Communication types AJAX communication AJAX SOAP envelope Submit communication Directly included data Cross domain / local load by JSONP Sessions (AJAX) Server response (AJAX) Synchronous communication (AJAX) Caching (AJAX) API (AJAX)

Download data

Settings for data download Layout XML structure Data XML structure

Upload data

Settings for data upload API for upload XML structure sent to server

Changing data from server

XML structure of download changes XML structure of request for a cell Synchronizing data with server

Input / output data formats

Complete list of tags Internal XML format Short XML format Extra short XML format DTD XML format JSON format

Cells
Cell basics

Cell type Cell format Dynamic format and type Cell value Reading / writing attributes by API Cell HTML Range or more values in one cell Cell with link URL Cell hint Cell tooltip / title Cell popup menu

Cell editing and changing values

Cell editability Defaults list Suggest list (auto complete) Changing cell value Mass cell change Clearing cells Editing cells Controlling <input> tag by JavaScript Input validation and restrictions Side checkbox Cell selecting

Calculations - cell formulas

Basics Formulas Mathematical functions Aggregate functions Special functions for actions Custom functions

Calculations - editable cell formulas

Basics Suggest list (auto complete) Mathematical functions String functions Date functions Summary functions Custom functions

Cell side buttons

Introduction Right side Button Left side Icon

Cell spanning

Column span Row span Dynamic spanning

Cell style and color

Basic grid style Special cell style attributes Cell CSS class Cell background color Dynamic cell border Cell HTML style Row color alteration Cell mouse cursor

Cell types
String - Text, Lines & Pass
Number - Int & Float

Format Localization

Date and time - Date

Format Calendar component Dates dialog Localization

List & combo - Enum & Radio

Introduction Definition Related lists Enum specific Radio specific

Checkbox - Bool
Action button - Button

Introduction Basic clickable button Switch button Radio / tab button Menu button Combo switch button Combo radio / tab button Special Space rows with buttons

Panel with more buttons - Panel

Definition Standard fast panel Custom panel

HTML and special types

Html type Icon type Abs type List type Editable Link type Editable Img type DropCols type Upload File type

Columns

Column basics Column index Column visibility Column visibility menu Column selecting Column tree Column position and moving Column adding and copying Column deleting Column width Column API

Rows
Row basics

Rows by functionality Rows by position Row name Row id Row index

Default rows

Description Example of default rows Example of changing default row Attributes

Row tree

Tree attributes Actions & API for expand / collapse

Row identification

Setting row id attribute Row id attribute in tree Row id created from cell values API for row ids

Row visibility
Row adding and copying

Five ways of adding rows to grid Adding and copying restrictions Adding new empty rows Copying existing rows

Row deleting Row moving and dragging Row selecting Row height Row API Space rows
Features
Sorting rows

Sort settings Controlling sort position Comparing strings Sorting actions Sorting API

Grouping rows to tree

Group settings Creating groups Comparing strings Created group rows <D Group='1'/> User interface to choose grouping Grouping actions and API

Filtering rows

Filter settings Comparing strings User interface to choose filter Filter actions and API

Searching in rows and cells

Search settings User interface for search Search actions and API

Printing grid

Print settings Choosing items to print Page size Print API

Print / export to PDF

Introduction Client side settings Printing options Client side API Server side API Data sent from client to server

Export to Excel or CSV

Basic settings Export API Client export Server export

Copy & paste rows via clipboard

Copy & paste permissions Copying to clipboard Pasting from clipboard

Master - detail grids

Introduction External master - detail grids Nested master - detail grids Synchronizing grids Other attributes for master - detail

Pivot tables

Pivot attributes & API Pivot formulas

External objects (like Adobe Flash) Undo & Redo
Gantt and bar chart
Gantt objects

Gantt objects list Display settings Edit settings

Main bar

Definition of main bar and plans Main bar as Task Edit settings Main bar content and side html Tip on mouse hover Vertical position and height Style specific attributes API to manipulate Main bars Actions Side text (deprecated) Real Flow (deprecated)

Run bar

GanttRun Definition Extended definition Run bar as Task Edit settings Save format Selecting Run boxes Run box content and side html Tip on mouse hover Box identification Vertical position and height Style specific attributes Overlaid (Error) boxes Dragging - moving and resizing API to manipulate Run boxes Actions Run special formulas

Summary task

Main for Main Main for Run Editable Main Editable Run

Gantt icons - Flag & Point

Flag - icon with text Point - math points

Gantt display objects

Header - column captions Cell and column Background Vertical movable Line Mark & Progress line

Gantt zoom

Zoom options Chart size limits Zoom selection Paging in Gantt chart

Dependency, constraints & schedule

Introduction Data units Defining dependencies Dependency colors and shapes Changing dependencies Correcting dependencies Scheduling algorithm Project date constraints Task date constraints Critical path - Slack (Float)

Gantt calendars

Global base calendar Local calendar Calendar list Calendars dialog Other settings

Gantt resources

Resources list Resources assign Resources filter Resources calculations Availability chart Resource usage chart Generated resource usage chart

Gantt popup menu Gantt API
Line and XY points charts

Charts in grid cells Chart JSON definition Base chart settings Basic attributes Size Axis and caption Individual chart lines Data sources Visual settings API for standalone usage

Paging in large grids
Paging root rows

Paging types and attributes Auto adding root pages API for paging

Pager components

Side pager Side pager type Pages Side pager type Gantt Side pager type Custom Pager with navigation buttons & edit Pager as list of page indexes

Paging in tree

ChildPaging - load / render on expand MaxChildren - limit children count ChildParts - load / render on scroll

Paging columns

Paging types and attributes Auto adding column pages API for column paging

Server paging

Server paging for root rows Server communication in root paging Root paging in very large tables Server paging in tree Server communication in tree paging XML Request for Data in root paging XML Download Data in root paging XML Request for root Page / children XML Download root Page / children API for server paging

TreeGrid DLL/SO for server paging

Introduction Compatibility with TreeGrid control Using TreeGrid server DLL/SO ASP.NET C# ASP.NET VB PHP JSP Java TreeGrid server concepts Function reference Calculations

JSON menus and dialogs
JSON menu description JSON menu definition example
Menu settings

Base attributes Visual settings Key navigation Behavior Size and scroll

Menu item settings

Base attributes Clickable item Inactive caption Collapsible sub level Popup sub menu Columns Bool item Enum item Edit item

Custom menu in JavaScript

Show custom menu Custom menu position Custom menu advanced settings Custom menu JavaScript events Custom menu JavaScript methods

Calendar dialog Custom calendar & JavaScript events Custom dialog in JavaScript
Global grid settings
Grid size and scroll

Default behavior Maximize grid height and width Update size according to the content Let a user to control the grid size Widths of individual sections Other scrolling attributes and API

Grid cursor - Focus & hover

Focused cell and row Focused cell range Move and copy focused cells Filling cell values by dragging Tabulator navigation Key navigation Cursor look - focus & hover

Selecting rows, cells and columns

Selecting base Selecting rows Selecting cells Selecting columns

Global settings

Status messages Configuration menu Default toolbar Language & regional setup (Text.xml) Useful API function Help file

Grid configuration in cookies
Mouse & key events & actions

List of event handler types TreeGrid mouse events Mouse event names Key and mouse button prefixes Touch event names Event targets Assigning event actions / callbacks Event action parameters Calling actions from JavaScript Creating custom actions Focused vs. Actual cell TreeGrid key events JavaScript API events

Mouse API event TreeGrid files
Debugging and testing

Debug window Automated testing

Creating TreeGrid

TreeGrid documentation

Basics
The simplest page with TreeGrid:
<html>
<head>
<script src="GridE.js"> </script> <!-- including TreeGrid script -->
</head>
<body>
<div style="width:100%;height:500px;"> <!-- TreeGrid main div tag -->
<treegrid Data_Url="Data.xml"> </treegrid> <!-- TreeGrid data source definition -->
</div>
</body>
</html>


Synchronous creating
To fully create and render TreeGrid during page loading you can use such HTML code:
<div id="Main" style="width:100%;height:500px;"> <!-- TreeGrid main div tag with id -->
<script> TreeGrid('<treegrid Sync="1" Data_Url="Data.xml"> </treegrid>',"Main"); </script>
</div>
Remember, all JavaScript code, API events, support functions and so on must be defined before the TreeGrid call, but not inside the Main tag.

Creating by API
TreeGrid is created after click to button Create:
<div id="Main" style="width:100%;height:500px;"> </div> <!-- TreeGrid main div tag with id -->
<button onclick='Create()'>Create</button>
<script>
function Create(){ TreeGrid( { Data:{ Url:"Data.xml" } },"Main" ); }
</script>

Version upgrade
When you are upgrading to new version or registered license or newly compiled script you can add some version info as query string to GridE.js to ensure using the new one and suppress caching the old one, for example:
<script src="../Grid/GridE.js?Version=6.0.24"> </script>

Basic information

TreeGrid can be placed to HTML page by tag <treegrid> or <bdo> or can be created dynamically by API function TreeGrid.
The <treegrid> or <bdo> tags must always have enclosing tag (<treegrid> </treegrid> or <bdo> </bdo>).
In <treegrid / <bdo> tag or TreeGrid function you define data sources to download XML data from and upload data to.
TreeGrid can download data from remote server, local server, local files or from XML placed directly in the source HTML page.
TreeGrid can upload data to remote or local server or include the data to HTML page and submit it.

TreeGrid can be fully deleted from page by calling Dispose method.
TreeGrid can be reloaded by calling Reload method. Or you can reload only body rows by calling ReloadBody.
TreeGrid can is accessible by API by Grids array.

By default is the communication asynchronous, you can set <treegrid Sync='1'/> to use synchronous communication.
The synchronous communication is faster, but disables the whole page usage during loading.

Encoding strings in XML. If you want to store any string to xml, you need to encode these characters: <, & and " or ' depending on quotations used in your xml attribute.
And if you want to store this xml data to html page in any attribute as string you have to make the same encoding once more (you again stores string in xml/html). The only exception is that HTML accepts < character in attribute values, but if you encode it, it will be better.

Creating

<HTML tag>

<treegrid>

Basic TreeGrid definition on page
Places one grid to HTML page and defines base grid attributes, the data sources to download XML data from and upload to.

The <treegrid> tag is placed to parent div tag that is called Main tag. The Main tag can be also any server control to control this tag from server script, but it always needs to be a block (not inline) tag.
All content of the Main tag will be overridden by TreeGrid content after the grid is created.
The Main tag is partially controlled by TreeGrid, especially its size and overflow (depending on size and scroll settings), but all other properties can be set as to standard HTML tag.

When the page is loaded (in body onload event), all <treegrid> tags on page are processed and replaced by appropriate grid.
To process the <treegrid> tags later, call StartTreeGrid method.
To create grid dynamically by API call TreeGrid method.
All the attributes are accessible by API by grid.Source attribute.
The <treegrid>tag must always have enclosing tag (<treegrid> </treegrid> not <treegrid/> ).
<HTML tag>

<bdo>

An alternative to <treegrid> tag
You can use <bdo> tag instead of <treegrid> to support some old browsers like Safari 3.x that don't accept non HTML tags.
<bdo> is a standard HTML tag to setting text direction, but without its dir attribute has no sense and can be used as TreeGrid definition.
The <bdo>tag must always have enclosing tag (<bdo> </bdo> not <bdo /> ).
upd 6.0 global func. TGrid

TreeGrid

(object Source, string tag = "", string id = "")
Creates and renders new grid by API according to settings in Source.
Source can be:
a) string with <treegrid> or <bdo> tag with all settings like it is included directly to HTML
Example: TreeGrid("<treegrid Data_Url='Grid2.xml'></treegrid>","Main");
b) string with XML to create the grid from. The grid will have only Data_Data source defined.
Example: TreeGrid("<Grid><Cols><C Name='A'/></Cols><Body><B><I A='xxx'/></B></Body></Grid>","Main");
c) object with parsed <treegrid> / <bdo> tag.
All multilevel attributes (data sources) containing '_' must be set as nested objects, split by the '_',
for example Data_Param_Test is accessed as Source.Data.Param.Test and set as {Data:{Param:{Test:'val'}}}
Eample: TreeGrid({Layout:{Url:"Grid2Def.xml"},Data:{Url:"Grid2.xml"}},"Main");
tag is the main div tag to render grid into. The tag can be an id of the tag or the HTMLElement itself. The htm tag must exist in time of calling the function.
If the parameter is missing, the id of the tag must be set in input XML by attribute <Cfg Tag/>. See <treegrid> tag description.
id is the unique id of the grid, used to identify it, especially in saving configuration to the cookies.
If the parameter is missing, the id of the grid can be set in input XML by attribute <Cfg id/>
The function returns created TGrid object as main TreeGrid object. Remember, loading and rendering is asynchronous by default, so at the moment of function return, the grid is not fully loaded and rendered yet. You can change it by setting Sync to 1.
It returns null for fatal error. It fails if the Source is null or cannot be used as one of the three options.
After finish will be fired OnRenderFinish and OnRenderPageFinish or OnLoadError event.
The Source is accessible by API by grid.Source attribute.
global func. void

StartTreeGrid

( )
Creates all grids on page from all HTML tags <treegrid> / <bdo>.
The grid creating is asynchronous procedure by default, so in time of function return the grids are not fully created yet.
By default it is called from window.onload event.
Call this function after you place new <treegrid> / <bdo> tag to your page.
This function creates grid in place of <treegrid> / <bdo> tag and destroys it, so it can be called as many times as you want.

Deleting

upd 6.0 API method void

Dispose

( )
Completely removes the grid from page.
It frees memory allocation for the TreeGrid by calling Clear() and removes the Grid from Grids array.
The disposed grid must not be used.
The indexes of disposed grids are not used again, except if was called DisposeGrids function.
new 6.0 global func. void

DisposeGrids

( )
Completely removes all grid from page. Calls for all grids Dispose().
Sets also Grids.length to 0 to start indexing new grids from 0.
upd 6.0 API method void

Clear

( )
Frees memory allocation for the TreeGrid. If you delete grid from JavaScript, call this function to free browser's memory.
It is used especially to avoid memory leaks in IE.
TreeGrid calls this function automatically when reloading or when window is closing.
The cleared can be only reloaded (called grid.Reload()).

Reloading

upd 7.0 API method TGrid

Reload

(object Source = null, string id = null, bool confirm = true)
Reloads and re-renders the whole grid.
Returns newly created grid or null for error or cannot reload.
The actual grid object is cleared and must not be used after reload! It can be only again reloaded if the Reload function failed.
By default it is asynchronous and returns before the loading starts (like TreeGrid function). You can set Sync=1 in Source to reload synchronously.
After finish will be fired OnRenderFinish and OnRenderPageFinish or OnLoadError event.

The Source is data source settings for grid, the same as in TreeGrid function. If the source is null, it is used original grid data source Source.
This function can be called to reload data from the same source to get the newest one or to reload another data from another source.
The id is new id to change the grid id, under this id will be now the grid accessible in Grids array. (Since 7.0) To preserve old grid id, set it to null, to load id from new data, set it to empty string.
If there are some pending changes in grid, it confirms reloading by a user. The user can cancel reloading and the method returns false.
If set confirm = false, it never asks a user about reloading.
API event bool

OnReload

(TGrid grid)
Called from Reload method or when user clicks to reload icon on toolbar.
Return true to suppress reloading.
chg 11.0 API event bool

OnCanReload

(TGrid grid, int changed, bool cancel)
Called when reload is requested - called from Reload method and when changed server side sorting/filtering/grouping/searching/export.
Called instead of confirming message to a user.
Return false to cancel action. Return true to confirm reloading.
(since 11.0) Return null to ignore the event and show the confirm message to user if changed.
changed = bit array, &1 - grid contains changed rows, &2 - grid contains selected rows.
cancel is true if changes should be canceled (called from Reload method), false if changes should be saved (server side request).
To save changes call Save function from this event.
<Actions>

Reload

Attached to event OnClickButtonReload
Reloads the grid, cancels changes, see Reload method.
API method void

ReloadBody

(function Func)
Reloads whole body (from source grid.Source.Data), all variable rows.
By default it is asynchronous and returns before the reloading finishes. You can set Sync=1 in Source.Data to reload body synchronously.
After finish, it calls function Func. function Func (int code).
The grid.Source.Data source can contain only variable rows (<Grid><Body>... </Body></Grid>), all other definitions like columns, fixed rows and so on must be defined in Source.Layout.
new 11.0 API method void

ClearBody

( )
Removes all body rows in the grid. The rows are removed permanently, not only deleted.

Rendering

new 6.4 <treegrid,bdo> bool

Hidden

[0]
If set to 1 the grid is never rendered and can be used as invisible data source for other grids or other page components.
The hidden grid has not set MainTag and cannot be shown at all.
API event bool

OnRenderStart

(TGrid grid)
Called before rendering or re-rendering of whole grid started.
It is called on create grid, from Render method, but also in various other situations where the grid is re-rendered.
Return true to cancel rendering.
API event void

OnRenderFinish

(TGrid grid)
Called when rendering or re-rendering of grid is finished and grid is ready to work. Use if you need to do some post-render actions.
When used (client or server) paging (<Cfg Paging>1), the body rows are not rendered yet in time of this handler call.
Use OnRenderPageFinish that is called after specific page is rendered.
When used child parts (<Cfg ChildParts='1'), not all rows in tree are rendered yet in time of this handler call.
Use OnRenderChildPartFinish that is called after specific part of child page is rendered.
API event void

OnRenderPageStart

(TGrid grid, TRow row)
Called before rendering of the root page or child page started rendering.
When used child paging (<Cfg ChildPaging>), this event is fired before start of rendering children when a parent row is being expanded.
API event void

OnRenderPageFinish

(TGrid grid, TRow row)
Called after the root page or child page is fully rendered and ready.
When used child paging (<Cfg ChildPaging>), this event is fired after children are rendered when a parent row is being expanded.
new 6.0 API event void

OnRenderChildPartStart

(TGrid grid, TRow row, int index)
Called before rendering of a part of children is started rendering.
The index is an index of the part from 0.
new 6.0 API event void

OnRenderChildPartFinish

(TGrid grid, TRow row, int index)
Called after the part of children is rendered and ready.
The index is an index of the part from 0.
new 7.0 API event void

OnRenderColPageStart

(TGrid grid, int sec)
Called before rendering of the column page.
The sec is the section index to ColNames.
new 7.0 API event void

OnRenderColPageFinish

(TGrid grid, int sec)
Called the column page is fully rendered and ready.
The sec is the section index to ColNames.
API variable bool

Rendering

It is set during render or other function that updates grid HTML.
It is set to not update grid layout by Update method during such function.
Set it if you manipulate more rows or columns to not to update grid layout to speed up the action. After that you must call the Update() method.
new 6.0 API method void

Rerender

( )
Asynchronously renders the whole grid into main tag's innerHTML. Or it renders synchronously if set <treegrid Sync='1'/>.
Calls Render asynchronously or synchronously.
API method void

Render

( )
Synchronously renders whole grid into main tag's innerHTML.
The previous grid HTML is cleared, it takes care about memory leaks.
This function may be slow, if many rows are present.
If used paging, the pages are rendered asynchronously.
Call it if you want to do many changes in grid to speed up the action - do not show the changes and after finish render the grid.
renamed 6.0 API method void

RenderBody

( )
Re-renders the whole body.
In paging, call it to clear all already rendered pages and render them again.
Call it if you want to do many changes in body rows to speed up the action - do not show the changes and after finish render the body.

Accessing by API

global variable TGrid[ ]

Grids

read only
This is global array of all created grids on page.
The individual grid can be accessed by Grids["id"] where the id is an <treegrid id> or <Cfg id> attribute.
The individual grid can be also accessed by Grids[Index], where the Index is grid index that got assigned in creating process.
Accessing individual grids by index is not recommended if more grids are on page.
To iterate all grids on page use such loop: for(var i=0;i<Grids.length;i++) { var G = Grids[i]; if(G){ ... } }, remember some indexes can be missing.
The grids are added to the array by creating grids on start or by function TreeGrid ( ) or StartTreeGrid ( ).
Existing grid can be removed by Dispose ( ).
new 6.0 global func. TGrid[ ]

GetGrids

( )
Returns all grids on page.
<treegrid,bdo> string

id

An id of the grid. By this id the grid can be accessed from JavaScript as Grids[id]. This parameter can be also set in data, in <Cfg id /> attribute.
If the id is set neither in <treegrid id> nor in <Cfg id />, it is created default as "Table"+grid_index.
If the id is set in both <treegrid id> and <Cfg id />, the <treegrid id /> is used.
By this id the grid saves configuration to cookies, if two grids have the same id, they share their configuration in cookies.
<Cfg> string

id

An id of the grid, see the <treegrid id> attribute description.
API variable string

id

read only
An id of the grid set by <treegrid id> or <Cfg id> or created as "Table"+Index.
API variable int

Index

read only
Unique index of the grid in global array Grids. Newly created grid gets the first available index (from 0).
By this index you can access the grid, but you should rather use its id.
The indexes of disposed grids are not used again, except if was called DisposeGrids function.
renamed 6.0 API variable object

Source

The actual data sources settings. It is the parsed <treegrid> attribute or the source set in TreeGrid function.
You can change the individual settings to download or upload data from different location.
For example: grid.Source.Data.Url = "new.xml"; grid.ReloadBody();
For example: grid.Source.Upload.Sync = 1; grid.Source.Upload.Url = "save.jsp"; grid.Save();
API variable object

MainTag

read only
The main tag where the grid is rendered inside.
It is set during creating. It is the HTMLElement object itself.