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

Changes log (txt file) Using custom CSS from 13.3 to 14.0 Upgrading from 9.3 to 10.0 Upgrading from 5.9 to 6.0

Using in JavaScript frameworks

Angular Ember Express React Svelte Vue Other frameworks NodeJS server SalesForce LWC

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 Data from JavaScript 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

Cell basics

Cell type Cell format Dynamic format Dynamic type Cell value Reading / writing attributes by API Cell HTML Cell default 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 Dynamic editing Locking Defaults list Suggest list (auto complete) Tags input 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) Defined names Actions for choosing cells Conditional functions Lookup functions Cell reference functions Logical functions Informational functions Mathematical functions Trigonometry functions Rounding numbers Number conversions 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 Sizing and scaling - responsive design Dynamic cell style attributes Cell CSS class Cell background color Dynamic cell border Cell HTML style Row color alteration Cell mouse cursor

Editable cell images

Insert image Edit image

Cell types
Automatic type - Auto 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 EHtml type (editable) Icon type Abs type List type Editable Link type Editable Img type DropCols type Upload File type


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

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
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

Introduction and export types Basic settings Styling export XLSX export Gantt export CSV export Old XLS / XHTML export Export API Communication with server Client export Server export

Import from Excel

Basic settings Sheets manipulation

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 (custom JavaScript objects) 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 Containers for more 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

Media rules - responsive design

Language & regional setup (Text.xml) Translate texts dynamically Change language

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 menus Configuration menu - options Configuration menu - columns Configuration menu - print / PDF Configuration menu - export Default toolbar Useful API function Help file


Animations base Row animations Column animations Cell animations Animations for undo / redo Animations for server side changes Dialog animations

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 Action name suffix 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

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

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>
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>
function Create(){ TreeGrid( { Data:{ Url:"Data.xml" } },"Main" ); }

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.


<HTML tag>


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>


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 17.0 global func. TGrid


(object Source, string tag = "", object param = null)
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 html 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.
Since 17.0 the tag can be also the same object as Source and will be merged to the Source. It can contain attribute Tag as the main div tag.
param are (since 14.1) the attributes that will be set to the created grid and will be preserved during reload similarly to attributes in KeepReload.
It is useful to pass here some link to the parent object that creates TreeGrid, e.g. this.Grid = TreeGrid({Data:{Url:"Test.xml"}},"Main",{id:"TestGrid",Component:this});
The param can contain id attribute or the param can be a string to be used as the id attribute.
The id is the unique id of the grid, used to identify it, to access the grid object globally by Grids[id].
The id is also used in saving configuration to the cookies if not set CfgId attribute.
If the id is not set in/by param, the id of the grid can be set in the Source or input XML by attribute <Cfg id/> or it is autogenerated.
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.
Since 14.1 if used GridED.js on demand script instead of GridE.js static script, the function downloads the GridE.js asynchronously and always returns before the TreeGrid is initialized and loaded - the returned grid object has set only its Source attribute.
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.
upd 14.1 global func. void


( )
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.
Since 14.1 if used GridED.js on demand script instead of GridE.js static script, the function downloads the GridE.js asynchronously and next processes the <treegrid> / <bdo> tags.


upd 6.0 API method void


( )
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


( )
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


( )
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()).


chg 14.1 upd 16.0 API method TGrid


(object Source = null, string id = null, int type = 1, string message = null)
Reloads and re-renders the whole grid.
Returns the actual grid object or false if cannot reload or null for reloading error (if Source is corrupt).
Since 14.1 the grid object is reused, but completely cleared, only attributes in Cfg KeepReload are preserved. Prior 14.1 the grid object was newly created and the old grid object was deleted and could not be used after reload..
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.
type is a bit array of flags to control the reloading.
type, 1. bit &1 = 0, it never asks a user about reloading.
type, 2. bit &2 = 2, (new 13.0) it preserves grid configuration like style or print settings.
type, 3. bit &4 = 4, (new 13.0) it preserves data configuration like filter settings or column widths.
type, 4. bit &8 = 8, (new 16.0) it clears xlsx if loaded.
(Since 13.0) If set message (either to empty string) and SuppressMessage >= 1, it shows the message and does not clear the grid html and does not show other messages during loading.
API event bool


(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


(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.
new 14.1 <Cfg> string[]


Comma separated list grid object attributes their values are preserved when reloading grid by Reload method / action.
chg 14.1 <Actions>


Attached to event OnClickButtonReload
Reloads the grid, cancels changes, see Reload method.
Since 14.1 the grid object is reused, but completely cleared, none of its original attributes are preserved. Prior 14.1 the grid object was newly created and the old grid object was deleted and could not be used after reload..
new 13.0 <Actions>


Not attached any to event
Reloads the grid, cancels changes, but preserves the grid configuration.
new 13.0 <Actions>


Not attached any to event
Reloads the grid, cancels changes, but preserves the grid and data configuration.
API method void


(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


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


new 6.4 <treegrid,bdo> bool


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


(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


(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


(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


(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


(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


(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


(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


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


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 upd 13.1 API method void


(bool scroll, bool sync)
Asynchronously renders the whole grid into main tag's innerHTML. Or it renders synchronously if set <treegrid Sync='1'/>.
Calls Render asynchronously or synchronously.
Since 13.1 if set scroll, it preserves actual scroll position.
Since 13.1 if set sync to 0 or 1, it renders synchronously or asynchronously regardless on Sync attribute value.
API method void


( )
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


( )
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[ ]


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[ ]


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


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


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


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


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


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


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