News in version
Buy Try it free
TreeGrid Gantt chart SpreadSheet Examples Documentation Download Development Licensing Prices References Contacts Buy Try it free
TreeGrid SpreadSheet Examples Documentation References
Gantt chart Download Licensing & prices Contacts
TreeGrid Examples Download
Gantt chart Documentation References
SpreadSheet Licensing & prices Contacts
Documentation
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

Cells
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

Columns

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

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

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
Languages

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

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

Download data

TreeGrid documentation

This document describes TreeGrid data sources for download and XML structure for download.
For basic information about TreeGrid communication settings (AJAX, AJAX SOAP, submit, direct) see Data communication with server.
For information about creating TreeGrid see Creating TreeGrid.

TreeGrid can download data from remote server, local server, local files or from XML placed directly in the source HTML page.

TreeGrid by default downloads from these basic data sources in this order: Text, Defaults, Base, Layout, Data.
The data source names and count can be changed by Source attribute.
It does not matter what setting is defined in which data source, but it is recommended to return data from the data source according to its meaning as described below.
If used server paging or reloading body the Data source can contain only variable rows definition (<Body> tag).
new 12.1 <treegrid,bdo> string

Source

["Defaults+Text,Base,Layout;Data"]
List of source names for download on start. It does not define the Page source and sources for upload.
The source name is used as prefix_ if defined by <treegrid> / <bdo> or object name if defined by TreeGrid() function.
There are more separators to separate the individual items:
';' semicolonseparates layout and data sources. If no ';' is present, the last item is taken as data source. To distinguish layout and data sources is important for server paging and for ReloadBody API.
',' commaseparates the sources loaded one by one, the second one starts loading after the first one is finished. Use if the order of loading is important.
'+' plusseparates the sources loaded all at once. Use if the order of loading is irrelevant.
<treegrid,bdo> prefix

Text_

Data source to download all texts and language settings. It is loaded as the first data source.
By default it is set Text_Url="Text.xml" Text_Method="Get" Text_Static='Text' Text_Relative='1' to download the predefined TreeGrid texts from file Text.xml. The Text.xml file is searched in directory with GridE.js script.
You can translate and update the Text.xml for all languages you want and provide the appropriate file based on user language settings.
It is required source, but you can keep the default value "Text.xml".
chg 7.0 <treegrid,bdo> string

Text_Start

["Initializing ..."]
Message displayed on grid initialization, when TreeGrid texts are loading.
Only if SuppressMessage is not set.
Since 7.0 its default value is "Initializing ...", so it is displayed by default. To hide only this message, set it to empty string.
In time of the message display TreeGrid styles are not loaded yet, so it uses internal message setting in the Standard style. To re-style this message, define GridMessage CSS class in page <head>.
The default message width is 140, it can be changed by Text_MessageWidth attribute.
It is always attribute of Text data source, even if the Text data source is not included in the Source.
<treegrid,bdo> string

Text_StartErr

Message displayed if TreeGrid texts failed to load and TreeGrid hangs.
It is always attribute of Text data source, even if the Text data source is not included in the Source.
<treegrid,bdo> prefix

Defaults_

Data source to download system predefined values of all parameters in TreeGrid. It is loaded as the second data source.
This file is required for TreeGrid to work properly. This file should not be modified and must be from the same version as GridE.js script itself.
By default it is set Defaults_Url="Defaults.xml" Defaults_Method="Get" Defaults_Static="Defaults" Defaults_Relative='1' to download the predefined TreeGrid values from file Defaults.xml. The Defaults.xml file is searched in directory with GridE.js script.
It is required source, but you can keep the default value "Defaults.xml".
<treegrid,bdo> prefix

Base_

Data source to download custom predefined values of some parameters in TreeGrid. It is loaded as the third data source.
By default is set Base_Method="Get".
It is optional source, to have some predefined values for all TreeGrids on site or in application.
<treegrid,bdo> prefix

Layout_

Data source to download grid structure (configuration, columns, header, filter, group, search, fixed rows, pager, ...). It is loaded as the fourth data source.
By default is set Layout_Method="Get".
It is optional source, all the layout can be included in Data source instead.
It is required source for server paging and / or ReloadBody usage.
<treegrid,bdo> prefix

Data_

Data source to download grid data (variable rows or fixed data rows). It is loaded as the fifth data source.
It can contain also all grid data structure if Layout data source is not used (not possible for server paging or ReloadBody).
For server paging it should contain only pages definition (<B> tags).
By default is set Data_Method="Get" Data_Data="Data"
It is required source, you need to set at least this data source.
<treegrid,bdo> prefix

Page_

Data source to download data for individual page or child page. It is loaded on request, when the page is being displayed.
It can return only variable row within requested page. The requested page can be find out from request configuration XML sent in Data parameter.
By default is set Page_Method="Form" Page_Data="Data".
Used only for server paging or server child paging.
Can be used only with AJAX communication, set attribute Page_Url.
It is required source for server paging or server child paging.
For other paging types is not used at all.
<treegrid,bdo> string

BasePath

[path_to_GridE.js]
Base path to all TreeGrid base files required files: Defaults.xml, Text.xml, Grid.css, Gantt.css, Help.html.
The default value is the path to GridE.js file, it is usual to place all the required files along to the GridE.js.
The BasePath is add also to <treegrid Defaults_Url and Text_Url>, but not to <Cfg CSS and HelpFile/>.
It must end with '/' if contains standard directory path.
API event bool

OnReadData

(TGrid grid, object source, function Func)
Called before data are requested by any method (AJAX, submit, ...) from source Defaults, Text, Base, Layout or Body.
source is the data source that is accessed, for example grid.Source.Layout. The source.Name contains the name of source, e.g. "Layout".
It can return true to suppress the loading and provide the downloading by custom way and must call function Func (int result), where result<0 is error code or 0 for ok.
API method void

ReadData

(object source, function Func)
Reads data from given source according to its _Url/_Tag/_Data parameters.
source is the data source to be is accessed, for example grid.Source.Layout.
After finish calls function Func: function Func (int result), result<0 is error code and >=0 is success.
API variable bool

Loading

[0]
It is set to 1 during downloading and updating base data - when creating grid, reloading grid, or reloading body of grid.
When Loading is set, no API function that reads or changes grid data can be called.
See also Rendering variable.
new 14.1 API event bool

OnInit

(TGrid grid, bool reload)
Called before the TreeGrid object is initialized. It is called before it is added to Grids array.
reload is true when called on reloading (by Reload method/action, but not by ReloadBody), false when called on creating.
The grid has already set attributes Source and MainTag, these attributes can be changed in the event.
Return true to not create the grid, in this case the TreeGrid function returns null.
Useful to link TreeGrid object to JavaScript component that creates it using <treegrid> tag.
upd 10.0 API event bool

OnLoaded

(TGrid grid, function next)
Called after all data has been loaded successfully, when creating or reloading grid.
It is called before the grid data has been updated, so you cannot call any row or column manipulation function.
Since 10.0 you can return true to not continue, if required some asynchronous action. And after finish call next( ) to continue.
API event void

OnLoadError

(TGrid grid)
Called when data cannot be downloaded and the grid cannot render and shows fatal error.
There is always called OnLoaded or OnLoadError event.
new 6.1 API event void

OnUpdated

(TGrid grid)
Called after all grid data were prepared for use, but before the grid calculated, filtered, sorted, grouped and rendered.
Here you can call any data manipulation API methods to update the data before they are calculated and sorted/grouped/filtered.
new 6.0 API event void

OnReady

(TGrid grid, bool start)
Called after all grid data were prepared for use, before the grid is rendered.
It is called when creating or reloading grid (start = 1) or when reloading body or updating detail grid (start = 0).
Here you can call any data manipulation API methods to update the data before they are rendered.
It is the only time during grid creating when both the Loading and Rendering properties are false. Do not call here API methods that render grid or update grid view!
new 6.0 <Cfg> int

CacheTimeout

[10]
How long TreeGrid waits for its CSS style (Grid.css and Gantt.css files) to be completely loaded, in seconds.
If the timeout expires, TreeGrid shows fatal error.
<Cfg> bool

Prepared

[0]
You can prepare input xml data for grid to speed up loading grid. If input xml data are prepared, set in them Prepared to 1.
In prepared xml data:
Date type values must be set as count of milliseconds from 1/1/1970 00:00:00.000, see also GMT attribute.
Float values must be set in standard English format, without leading zero, but with leading zero for values between -1 and 1.
All Int, Float and Date type cells must have set its value (or set value in its default row cell).

Layout XML structure

Layout XML defines all parts in TreeGrid except data rows and cells.
It is sent from server to grid. It is generated by server script. It is usually static XML file.
Used when downloading grid for first time or reloading all data for the grid (function Reload).
Used as response from data sources Text, Defaults, Base, Layout.
For small grids it can be merged with Data XML and returned in Data response.

The columns are merged by their Name - if there is already defined some column <C> with the same Name, it is updated, no new column is added.
The defaults are merged by their Name - if there is already defined some default row <D> with the same Name, it is updated, no new default is added.
The fixed and space rows are merged by their id - if there is already defined some fixed or space row with the same id, it is updated, no new row is added.

To specify position of the main Header row place to <Head> or <Foot> section a tag with id='Header' on the appropriate position.
To specify position of the main Toolbar row place to <Solid> section a tag with id='Toolbar' on the appropriate position and also set its Space attribute.
You cannot change position of the main left side Panel column, but you can hide it by <Panel Visible='0'/> and define new column(s) with Type="Pane" on the appropriate position in columns section.

<Grid> (Root tag, can accept any count of introduced child tags in any order, only one tag Grid per response is permitted)

<IO ... attributes ... /> (a server response)

<Cfg ... attributes ... /> (base grid settings)

<Actions ... attributes ... /> (assigned global actions)

<Colors ... attributes ... /> (cell background color setting for various row states)

<Def> (list of default settings for rows or columns)
<D Name='name of default' ... row and cell attributes ... />
... More tags <D> ...
</Def>

<Panel ... attributes ... /> (one predefined most left side column Type="Panel")

<LeftCols> (Columns fixed to the left side, not horizontally scrollable)
<C Name='column name' ... attributes ... /> (individual columns)
... more tags <C> for other columns ...
</LeftCols>
<Cols> (Variable columns, between left and right, horizontally scrollable)
<C Name='column name' ... attributes ... /> (individual columns)
... more tags <C> for other columns ...
</Cols>
<RightCols> (Columns fixed to the right side, not horizontally scrollable)
<C> Name='column name' ... attributes ... /> (individual columns)
... more tags <C> for other columns ...
</RightCols>

<Header ... row and cell attributes ... /> (predefined first "main" header, by default with id="Header")

<Head> (List of top fixed rows, not vertically scrollable, rows cannot contain children rows)
<Filter ... row and cell attributes ... /> (special row with user interface for filtering rows by column(s))
<Header ... row and cell attributes ... /> (other headers or main header with id="Header")
<I ... row and cell attributes ... /> (data row)
... More tags <I>, <Filter>,<Header> ...
</Head>

<Foot> (List of bottom fixed rows, not vertically scrollable, rows cannot contain children rows)
<Filter ... row and cell attributes ... /> (special row with user interface for filtering rows by column(s))
<Header ... row and cell attributes ... /> (other headers or main header with id=”Header”)
<I ... row and cell attributes ... /> (data row)
... More tags <I>, <Filter>,<Header> ...
</Foot>

<Solid> (List of special solid rows, these rows can be positioned in more locations in table)
<Group ... group row and cell attributes ... /> (special row with user interface for grouping)
<Search ... search row and cell attributes ... /> (special row with user interface for search and advanced filter)
<Toolbar ... toolbar row and cell attributes ... /> (special row with toolbar buttons, or main toolbar with id="Toolbar")
<Space ... row and cell attributes ... /> (special row with no special interface, just to display custom cells)
... More tags <>Space> <Group> <Search> <Toolbar> ...
</Solid>

<Toolbar ... attributes ... /> (predefined first "main" toolbar, by default with id="Toolbar")
<MenuCfg ... attributes ... /> (settings for configuration menu)
<MenuColumns ... attributes ... /> (settings for columns visibility menu)
<Pager ... attributes ... /> (right side pager settings)

<Script> (JavaScript code to run once)
<S Name='name of script' > JavaScript code to run after the data source is loaded </S>
... More tags <S> ...
</Script>

<Debug Message='Message to display in debug window' />

<Lang> (All language depended texts and formats)
<Alert ... attributes ... /> (texts for alert messages, only plain text, no HTML tags)
<Text ... attributes ... /> (html text for messages and other use)
<Gantt ... attributes ... /> (Gantt chart texts)
<MenuButtons ... attributes ... /> (button captions in all popup menus)
<MenuCopy ... attributes ... /> (copy menu item captions)
<MenuFilter ... attributes ... /> (filter operator menu item captions)
<MenuCfg ... attributes ... /> (configuration menu item names and values)
<Format ... attributes ... /> (number and date formats and regional settings)
</Lang>

</Grid>

Data XML structure

Data XML defines body (data) rows. Here is listed the structure for no or client paging. For server paging see the server paging.
It is sent from server to grid. It is generated by server script. It is usually generated from server database.
Used when downloading grid for first time or reloading all data for the grid (function Reload) or reloading only body (function ReloadBody).
Used as response from data source Data.
For small grids it can be merged with Layout XML.
It can also contain some parts from Layout XML, like fixed rows or configuration settings if they need to generate dynamically to let the rest of the layout to be in static file.
It can also contain configuration settings like sort, filter or group if you want to change them when reloading body.

The body rows are not updated by their id attribute - no two body rows should have the same id. It is due speed reason.

For server child paging some or all rows with children can have set Count attribute as the count of the expected children instead of the children themselves. The children will be downloaded on demand. In this case the row must have set also its id or Rows attribute to identify it on server.

<Grid>
<Par> (list of prepared parameters for short formats)
<P Name="list name" List="parameter names, comma separated"/>
</Par>
 <Body>
<B> (Only one page with all rows)
<I ... row and cell attributes ... > (data row)
<I ... row and cell attributes ... > (data row)
<I ... row and cell attributes ... > (data row)
... More tags <I>, with possible children tags <I> with possible children and so on - unlimited levels of tree ...
</I>
... More tags <I> ...
</I>
... More tags <I> ...
</I>
... More tags <I> ...
</B>
</Body>
</Grid>