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) 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 React Vue Other frameworks NodeJS server

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

Data communication with server

TreeGrid documentation

This document contains basic information about TreeGrid data communication.
TreeGrid can download data from remote server, local server, local files, from XML placed directly in the source HTML page or from JavaScript variable.
TreeGrid can upload data to remote or local server or include the data to HTML page and submit it.

The communication type, urls and other settings are specified by base <treegrid> or <bdo> tag that defines TreeGrid on HTML page or by global TreeGrid function that creates TreeGrid dynamically by API.

There are possible communication types:
AJAX - Background communication without reloading page. Supports all TreeGrid communication features like server paging.
AJAX SOAP - AJAX communication with XML in SOAP envelope. Supports all TreeGrid communication features like server paging.
Submit - Old communication style by submitting and reloading the whole page. It does not support TreeGrid server paging, auto update and reloading body.
Direct - XML data directly included in <treegrid> / <bdo> tag attribute values or JSON data in JavaScript object. It does not support uploading to server and server paging.
All these communications can be combined in one grid, e.g. use Direct communication for downloading layout and data and AJAX for uploading changes to server.

Every data source has its own prefix before its attribute name (for example Data_Url, Data_ is prefix and Url is attribute name).
new 15.0 <treegrid,bdo> int

Json

[0/1/2]
Presets TreeGrid to use XML or JSON / JSONP formats.

0 - xml
Loads Defaults.xml Text.xml from Grid/ directory except they are explicitly defined by Defaults_ or Text_ data sources.
Loads language xml files from Grid/Languages/ directory, as they are referenced in Defaults.xml.
Upload format is set to Internal XML except it is explicitly defined by xxx_Format in the data source.
It is default value if some data source contains .xml extension or no data source contains .js / .json extension and no data source uses _Jsonp postfix and no data source has set Format="JSON".

1 - json
Loads Defaults.js and Text.js from Grid/Json/ directory except they are explicitly defined by Defaults_ or Text_ data sources.
Loads language json files from Grid/Json/Languages/ directory, as they are referenced in Defaults.js.
Upload format is set to JSON except it is explicitly defined by xxx_Format in the data source.
It is default value if some data source has set Format="JSON" or contains .js or .json extension and no data source contains .xml extension and no data source uses _Jsonp postfix.

2 - jsonp
Loads Defaults.js and Text.js from Grid/Json/ directory using JSONP except they are explicitly defined by Defaults_ or Text_ data sources.
Loads language json files from Grid/Json/Languages/ directory using JSONP, as they are referenced in Defaults.js.
Loads all data sources using Url Layout_Url and Data_Url that use Get Method as JSONP like from _Jsonp source.
Upload format is set to JSON except it is explicitly defined by xxx_Format in the data source.
It is default value if some data source uses _Jsonp postfix.

AJAX communication

Modern background communication without reloading page. Supports all TreeGrid communication features like server paging or reload body.

For AJAX communication you must specify the URL where the data will be downloaded from and optionally sent to, for example Layout_Url = "../app/getLayout.jsp".
Other attributes are optional and often work with the default settings.

Example TreeGrid with structure downloaded from static file. Data is downloaded from aspx web page, with parameter Do = "Load".
Changed data is uploaded to the same aspx page, with parameters TGData="changed data in XML", Do="Save".
Exported data is uploaded to export aspx page, with parameters TGData="the exported data", File="Export.xls", the aspx page is expected just to return this data to client in the file specified.

<treegrid
Layout_Url="TreeGridSampleDef.xml"
Data_Url="TreeGridSample.aspx" Data_Param_Do="Load"
Upload_Url="TreeGridSample.aspx" Upload_Data="TGData" Upload_XML="1" Upload_Param_Do="Save"
Export_Url="TreeGridExport.aspx" Export_Data="TGData" Export_Param_File="Export.xls" >
</treegrid>
<treegrid,bdo> string

xxx_Url

Postfix to data source (e.g. Data_Url)
An URL to connect to. From this URL are data downloaded or to this URL are data uploaded.
This URL can be an URL of static file to download or any web page or web service.
This URL must be in the same domain as the page where TreeGrid is shown. It cannot be changed, because of browser security restrictions for AJAX. In this case use Jsonp instead.
If this URL is relative, it is relative to the actual page URL, see xxx_Relative.
For download it can contain parameters for GET method only (beyond the '?').
For upload it cannot contain parameters (beyond the "?"), because the POST method used.

This attribute value can contain wildcards to change it according to grid or page settings. All these strings will be replaced by appropriate runtime value:
*Sort0, *Sort1, *Sort2Column name according to is grid sorted. With prefix '-' for descendant sorting
If grid is not sorted or Sort count is less than 3, the not used wildcards are removed.
*idRow or page id (only for Page_Url)
*PosPage position (only for Page_Url)
*RowsPage's attribute Rows (only for Page_Url), this attribute can be set to anything, for example to generate the whole URL.
For example Data_Url='..\Source\Body*Sort0.xml' Page_Url='..\Source\Page*Pos.xml'
new 9.2 <treegrid,bdo> bool

xxx_Relative

[0/1]
Where the relative xxx_Url or xxx_Jsonp will be related to.
0 - to the actual page URL (defined in window.location). It means nothing is added before the relative url.
1 - to the Grid/ folder, where main TreeGrid script GridE.js is placed. Before url is added the path to Grid folder from actual location.
By default it is 0 for all data sources. Only Defaults and Text data sources without Url / Jsonp attribute set have Relative set to 1.
Relative url is an url that starts neither with protocol (xxx://) nor by slash (/).
<treegrid,bdo> string

xxx_Data

["Data"] Postfix to data source (e.g. Data_Data)
Name of parameter where to store uploaded data or data of request. Default value is "Data".
In this parameter can be read the data on server, similar to name of the <input> tag in submitting <form>.
chg 6.0 <treegrid,bdo> string

xxx_Method

["GET"/"POST"] Postfix to data source (e.g. Data_Method)
HTTP method of uploading data to server. Case insensitive.
It is default GET for sources Defaults, Text, Base, Layout. It is GET also for Data if used client or no paging (<Cfg Paging<=2>)
It is default POST for sources Upload, Page, Export, Cell. It is POST also for Data if used server paging (<Cfg Paging=3>)

GETFor download data only. Uses HTTP method GET. No data is sent in parameter Data - no configuration or uploaded changes.
Params and Param settings are coded into URL string after '?'.
 
POSTFor download or upload. Uses HTTP method POST. The data is sent in parameter Data - the configuration in request or uploaded changes.
Params and Param settings are sent also in body of the HTTP request.
The HTTP data format is application/x-www-form-urlencoded, the same as submitting <form>.
The HTTP charset is always UTF8: charset=UTF-8
 
SOAPFor download or upload. Uses HTTP method POST and uploads data in SOAP XML envelope. See AJAX SOAP.
chg 6.0 upd 6.6 <treegrid,bdo> string

xxx_Format

["Internal"] Postfix to data source (e.g. Data_Format)
Upload format. Used for uploading data or for request, input data format is always automatically recognized.
If set to "DTD", the uploaded XML will be in DTD format instead of the Internal.
If set to "JSON", the uploaded data will be JSON string.
<treegrid,bdo> string

xxx_Bonus

Postfix to data source (e.g. Data_Bonus)
A string with direct XML or JSON data for TreeGrid. This data is read and added after main data in Url/Tag/Data are read to change some default behavior.
For download sources only (Text, Defaults, Base, Layout, Data)
<treegrid,bdo> int

xxx_Timeout

[60] Postfix to data source (e.g. Data_Timeout)
Timeout in seconds. How long the grid will wait for server response. 0 means forever.
If the timeout expires, the grid asks a user if he wants to wait or cancel the communication. Depends on Repeat settings.
<treegrid,bdo> int

xxx_Repeat

[1] Postfix to data source (e.g. Data_Repeat)
Behavior when Timeout expires.
0 - alerts the problem to user ("Cannot download / upload data, timeout expired"), but does not let user to try it again.
1 - does not alert anything to user, just silent error.
2 - alerts the problem to user ("Cannot download / upload data, server timeout ! Do you want to repeat request ?") and let him to choose to repeat the attempt.
3 - Automatically repeats the attempt.
<treegrid,bdo> bool

xxx_Xml

[0] Postfix to data source (e.g. Data_Xml)
If the uploaded data will be sent as is or will be sent with coded entities.
For 0 (default) are uploaded data encoded to string (& and <,> are replaced by &amp; &lt; &gt;). The web service's parameter is type of string.
The 0 is required value when submitting form due security validation in some server script like ASP.NET.
For 1 data are uploaded as XML without any change, the web service's parameter is type of XmlDocument (or similar type).
<treegrid,bdo> string

xxx_Param_xxx

Postfix to data source and prefix to parameter name (e.g. Data_Param_Test)
This is second prefix for custom parameters to send with the request.
The case sensitivity of parameter name is unsure, the name is always converted to format "First letter upper, other letters lower" !
For example: Data_Param_Test="12" => it added custom parameter named "Test" with value "12".
<treegrid,bdo> string

xxx_Params

Postfix to data source (e.g. Data_Params)
All custom parameters in one string, just to be added to data being sent. Its format varies according to used Method.
Use this attribute instead of Param prefix if you need exact case sensitivity of the parameter names.
For methods GET and POST it contains standard parameters for URL, "paramname=paramvalue&paramname2=paramvalue2". Without the first "?".
For example "name=peter&value=smith". The string is encoded by JavaScript encodeURI function.
For method SOAP: It contains XML nodes in format <ParamName>ParamValue</ParamName><ParamName2>ParamValue2</ParamName2>
new 12.0 <treegrid,bdo> string

xxx_Header_xxx

Postfix to data source and prefix to parameter name (e.g. Data_Header_Authorization)
This is second prefix for custom http headers to send with the request.
The case sensitivity of parameter name is unsure, the name is always converted to format "First letter upper, other letters lower" !
For example: Data_Header_Authorization="Basic login:password" => it added custom http header named "Authorization" with value "Basic login:password".
<treegrid,bdo> int

xxx_Cache

[0] Postfix to data source (e.g. Data_Cache)
Caching setting for individual data source. See Cache attribute.

new 7.0 <treegrid,bdo> string

xxx_Static

[???] Postfix to data source (e.g. Data_Cache)
Caches static data under this name to not load the data from source. Caches them for all grids on page.
It should be used only for static files like Defaults.xml.
By default it is set to Defaults_ and Text_ data sources if they have not set the _Url.

AJAX SOAP envelope

AJAX communication with XML in SOAP envelope.
Similar to standard AJAX communication, but uploads the request XML in SOAP XML envelope.
Uses all listed AJAX attributes above and these attributes for specifying SOAP Envelope:

Example TreeGrid with structure downloaded from static file. Data is downloaded from soap webservice, method string Load (string Grid), with parameter Grid = "Grid1".
Data is uploaded to soap web service, method string Save (XmlDocument Data, string Grid, int Test), with parameters TGData="changed data in XML", Grid="Grid1", Test=12.
<treegrid
Layout_Url="TreeGridSampleDef.xml"
Data_Url="TreeGridSample.asmx" Data_Method="Soap" Data_Function="Load"
Data_Namespace="www.treegrid.com" Data_Param_Grid="Grid1"
Upload_Url="TreeGridSample.asmx" Upload_Method="Soap" Upload_Function="Save"
Upload_Namespace="www.treegrid.com" Upload_Data="TGData" Upload_XML="1"
Upload_Param_Grid="Grid1" Upload_Param_Test="12" >
</treegrid>


SOAP envelope request structure
Data are sent as "text/xml; charset=UTF-8".
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<Function xmlns="Namespace">
<Data>... uploaded data if any, in string (if Xml is 0) or in xml (if Xml is 1) ...</Data>
<Param1>... parameter value ...</Param1>
<Param2>... parameter value ...</Param2>
... next parameters ...
</Function>
</soap:Body>
</soap:Envelope>

Where Function, Namespace and Data are values of these attributes of <treegrid> tag.
Where Param1, Param2, ... are attribute prefix names, e.g. for "Data_Param_P1" is "P1". Remember that parameter names must have the first letter uppercase and other lowercase!
In request is also sent HTTP header attribute SOAPAction=Namespace/Function

Usual SOAP envelope response structure
Data are in the tag <FunctionResult> as string.
This is the standard output of the XML web service, if function returns string and data were sent as SOAP XML envelope.
Usual envelope (the full XML response) is:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<Function xmlns="Namespace">
<FunctionResult>... returned xml data in string (escaped entities) or in xml (not escaped) ...</FunctionResult>
</Function>
</soap:Body>
</soap:Envelope>

Where Function and Namespace are values of these attributes of <treegrid> tag.
TreeGrid does not parse the SOAP envelope response, it just searches for inner <Grid> tag or <Grid> in text node.
chg 6.0 <treegrid,bdo> string

xxx_Method

["GET"/"POST"] Postfix to data source (e.g. Data_Method)
Set the Method to "SOAP" for SOAP communication.
<treegrid,bdo> string

xxx_Function

Postfix to data source (e.g. Data_Function)
Name of SOAP function. This function will be called in the web service.
<treegrid,bdo> string

xxx_Namespace

Postfix to data source (e.g. Data_Namespace)
Name of SOAP namespace. The namespace the Function belongs to.
<treegrid,bdo> string

xxx_Envelope

Postfix to data source (e.g. Data_Envelope)
Envelope tag for SOAP. Set it if default envelope cannot be used by provider.
Default value is:
'<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">'

The Envelope can be used also to place AuthHeader with UserName and Password like:
'<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Header><AuthHeader xmlns="http://tempuri.org/"><UserName>username</UserName><Password>password</Password></AuthHeader></soap:Header>'

Submit communication

Old communication style by submitting and reloading the whole page. It does not support TreeGrid server paging, auto update and reloading body.
In download are data read from hidden input. The input value is cleared after reading.
In upload are data set into hidden input value and the <form> where the input is placed is submitted to server.

Example
TreeGrid with structure read direct from string, data downloaded from static file, uploaded by form submit in hidden input GridData.
<input type="hidden" name="grid" id="GridData">
<div style="width:100%;height:100%;">
<treegrid
Layout_Data="<Grid><Cols><C Name='C1'/></Cols></Grid>"
Data_Url="../data/TreeGridSample.xml"
Upload_Tag="GridData">
</treegrid>
</div>
<treegrid,bdo> string

xxx_Tag

Postfix to data source (e.g. Data_Tag)
An id of tag (usually hidden input).
In download are data read from its attribute value. When data are read, the value is cleared.
In upload to this value are changes written when submitting form.
This is alternative to Url and cannot be set both. For upload this must be id of <input> tag.
If set for upload, data are uploaded by form submit and TreeGrid Auto update option cannot be used.
When uploading, don't forget to place this hidden input on HTML form with specified Action attribute as usual, when uploading forms to sever.
When user clicks Save button, the input's value is filled by changed data and form to which the input belongs is submitted to server.
When the form to which the input belongs is submitted by any other way, before submit, the input value is filled by changed data.
By default are uploaded data html encoded (&,<,> to entities) because of security validation in server scripts, you can change it by Xml attribute.

Global prop. int

Grids.NoTryActiveX

When set to 1 in IE does not try to create ActiveX objects, event if it is possible and uses slower script XML parsing,
but don't show any message to a user about ActiveX.
This property has sense only if is not used AJAX and all data, include Defaults.xml and Text.xml, are included in HTML page.

Directly included data

XML or JSON data directly included in <treegrid> / <bdo> tag attribute values.
It can be used only for download and also does not support server paging and reloading body.
It can be used for grids generated by JavaScript on client.
Remember, the including xml or json directly to html page can be combined with other communication types, especially for upload.

Example
Simple TreeGrid with data directly included
<treegrid
Data_Data="<Grid><Cols><C Name='A'/></Cols><Body><B><I A='1'/></B></Body></Grid>"
>
</treegrid>
upd 15.0 <treegrid,bdo> string

xxx_Data

Postfix to data source (e.g. Data_Data)
String with direct data for TreeGrid.
It is alternative to Url and Tag and can be set only one from them.
For download only.
Remember, when including XML into HTML attribute, you should encode the HTML entities.
If you include some &, < " or' into XML attribute value, you need to convert it twice, if you include it to HTML.
For example: <treegrid Data_Data="<Grid><Body><B><I Col1='One &amp;amp; Two &amp;lt; Four'/></B></Body></Grid>"></treegrid>

If TreeGrid is created by TreeGrid() function with first parameter as source object, the xxx:{ Data:...} can contain JavaScript object with JSON data or since 15.0 if set Format='xlsx', it can contain xlsx in blob.

Data from JavaScript

new 6.6 chg 13.0 <treegrid,bdo> string

xxx_Script

Postfix to data source (e.g. Data_Script)
JavaScript code that returns the data in XML string or JSON string or object or xlsx blob to use. Or the JavaScript code asynchronously calls callback function with the data.
The JavaScript code can use these variables:
Grid as the calling grid.
Source as the data source part object, e.g. Grid.Data.Layout or Grid.Data.Page, the Source.Name contains name of the source, e.g. "Layout".
Data as the data in string that TreeGrid wants to send to server.
Func as the callback function, format: function Func(code,data), where code is integer, negative as error code, 0 or positive for success. data are the data to load.
If the code does not contain 'return' and also no '{' and ';' characters, the return keyword is added before the code.

It is alternative to Url and Tag and can be set only one from them.
Before 13.0 it could be only global JavaScript variable name containing the data and could be used for download only.

Example with static data
<script>
var TGData1 = {Cols:{A:{}},Body:[[{A:1}]]};
</script>
<treegrid
Data_Script="TGData1"
</treegrid>


Example with dynamic data
<script>
function LoadMyData(url,callback){
AjaxCall(url,function(code,data){callback(code,data);});
}
</script>
<treegrid
Data_Script="LoadMyData('MyUrl',Func);"
</treegrid>

Cross domain or local communication by JSONP

Data loaded in JSONP format, loaded by added dynamically <script src='...'> tag into the page.
This method provides access to different domains and also loading local files without server (page run in file:// protocol). Normally these two options are restricted in AJAX communication in the most browsers.
Usable only for download!
Accepts also attributes xxx_Relative, xxx_Bonus, xxx_Timeout, xxx_Repeat, xxx_Cache, xxx_Static, xxx_Param, xxx_Params.
The JSONP data are always loaded one by one, even if there are more grids. If one data is missing, it waits for timeout until it loads the next one.
new 9.2 <treegrid,bdo> string

xxx_Jsonp

Postfix to data source (e.g. Data_Jsonp)
URL to JSONP file in format:
a) TreeGridLoaded({the JSON data}), e.g. TreeGridLoaded ( { Cols: [ { Name:"A" ] } , Body: [ [ { A:"value \"A&1\"" } ] ] } )
b) TreeGridLoaded("the XML data"), e.g. TreeGridLoaded("<Grid><Cols><C Name='A'/></Cols><Body><B><I A='Value \"A&1\"'/></B></Body></Grid>")
The Jsonp has the same format as xxx_Url.

The data must not contain any syntax error, otherwise they are ignored!
new 9.2 global func. void

TreeGridLoaded

(type Input)
Function called from JSONP script file to add the JSON or XML data to grid.
Can be called only in JSONP script, not in any other code.

Sessions (AJAX)

How to identify one continuous access (session) to server.
<treegrid,bdo> string

Session

Initial identity for communication session. The session identity is sent in every request to server in <IO Session/> attribute to identify the session.
If server returns in its response the <IO Session/> attribute, the session identity is set to this attribute value to start new session.
By default the Session value is not persistent, therefore if user reloads page, the Session value is lost and new session is started.
You can let TreeGrid to store Session value to hidden input or to cookies by <Cfg SaveSession/> attribute.
The session is not used by TreeGrid on client, it is intended only to identify the client on server in your server code.
<IO> string

Session

If session identity has been set for this grid, it is sent to server in every request in the <IO Session/> to identify the client session.
The session identity can be set by <treegrid Session> on session start or can be set or changed by any server response(s) by the <IO Session/>.
Remember, the IO is not sent to server if <treegrid *_Method='Get'> is used.
By default the Session value is not persistent, therefore if user reloads page, the Session value is lost.
You can let TreeGrid to store Session value to hidden input or to cookies by <Cfg SaveSession/> attribute.
<Cfg> string

SaveSession

It can be set to '1' to save Session attribute value to cookies. It saves Session regardless of values of SuppressCfg and Version.
Or it can be set to id of hidden input, it stores Session attribute value to this input to be persistent for page reloading.
Only some browsers preserve input values for page reloading.
The hidden input must be placed to page in HTML and not by JavaScript. Also don't place it into TreeGrid main tag.
This attribute should not be set in data xml, only in layout.
API method void

SetSession

(string Session)
Sets grid Session attribute that identifies it in server requests. Saves the Session according to the SaveSession setting.
Usable especially to clear the Session when wants to start new session with new data.

Server response (AJAX)

chg 7.0 <IO> int

Result

General result of the server response.
TreeGrid distinguishes only two values:
>= 0 as OK, the communication succeeded. The data sent from server have been accepted. For upload, all pending changes were accepted.
< 0 as Error, the communication failed. The data sent from server have been discarded. For upload, all pending changes are still pending.
Values -1 to -9 should be reserved to TreeGrid.
Since 7.0 for results -2 to -9 in save response is displayed error alert. To not show it, remove the ErrorSave value from Text.xml
You can define API event OnDataReceive where you can access or change the Result by grid.IO.Result before it is processed by grid.
Here you can read also any other custom IO attributes set by server to get more information about response status.
<IO> string

Message

Server response message.
If it is set, this text is alerted to user, independently on Result value and before OnDataReceive event.
It is intended to inform a user about some error or important change sent from server.
new 7.0 <IO> string

HtmlMessage

Server response message that can contain HTML code.
It is shown to user by TreeGrid modal ShowMessage inside TreeGrid main tag. It can be shown only for time specified by HtmlMessageTime.
If it is set, this text is shown to a user independently on Result value and after the incoming data is added to grid or discarded.
It is intended to inform a user about some error or important change sent from server.
new 7.0 <IO> int

HtmlMessageTime

How long will be the HtmlMessage shown, in milliseconds.
If not set or set to 0, the message is shown forever with OK button to hide it.
If set to negative number, the message is shown for the (positive) time, but also with OK button to hide it.
<IO> int

Reload

If set to 1 reloads all body rows / pages.
It is useful to regenerate pages for server paging when pages were changed on server.
It can be also used if there are many updates on server and is faster to reload them all from server.
Remember, when set to 1, Data source xml can contain only variable rows, all other definitions like columns, fixed rows and so on must be in Layout source xml.
The reload body is done after OnDataReceive event, you can change this parameter in this event.
<IO> string

ReloadMessage

Server response confirm message for reload.
If it is set, shows confirm dialog before reloading, to confirm this action by user.
It is independent on Result value and is displayed before OnDataReceive event.
new 15.0 <IO> string

ReloadHtmlMessage

Server response confirm message for reload.
It is the same as ReloadMessage, but can contain HTML code and it is displayed by TreeGrid message instead of browser alert.
<IO> string

UpdateMessage

Server response confirm message for accepting changes sent from server.
If it is set, shows confirm dialog before the changes received from server are added to grid, to confirm this action by user.
It can be used especially when used checking for updates function.
It is independent on Result value and is displayed before OnDataReceive event.
new 15.0 <IO> string

UpdateHtmlMessage

Server response confirm message for accepting changes sent from server.
It is the same as UpdateMessage, but can contain HTML code and it is displayed by TreeGrid message instead of browser alert.
API variable object

IO

A response <IO> tag accessible by API.
It is accessible in event OnDataReceive to check the server response result and confirm or reject the downloaded data and changes.
Remember, the IO object is reset for every response got from server, even if this response does not contain <IO> tag.

Synchronous communication (AJAX)

By default TreeGrid loads all AJAX data asynchronously, one by one.
After load it updates data, sorts, filters, groups them and so on. Every this action is done also asynchronously one by one.
The advantage of asynchronous communication is that the page with TreeGrid is still accessible for user. TreeGrid also shows status messages to inform user what it is doing.
But asynchronous communication is slower, especially for smaller grids.
The grid can be completely downloaded and rendered synchronously by setting Sync attribute. The grid can be even fully created and rendered during page load.
The changes can be also uploaded to server synchronously to not let user to change any data unless the upload finishes, set Upload_Sync attribute.
chg 6.0 upd 9.2 <treegrid,bdo> int

Sync

If set to 1, TreeGrid is created and rendered fully synchronously.
If created by TreeGrid function, it is rendered in time the function returns.
TreeGrid can be created and rendered synchronously also during HTML page loading.
If TreeGrid is created synchronously it does not display any message during loading and updating.
If TreeGrid is created synchronously it loads its CSS style sheet by AJAX, you should not include the CSS style to page in this case.
This attribute value does not affect uploading and loading pages in server paging! For these you must set the Upload_Sync and / or Page_Sync.
The synchronous creating is faster, especially for small grids, but disables browser during creating.
Individual data loading can be controlled by xxx_Sync attribute of the given data source.

If set to 2 (since 8.0), it loads data asynchronously, but permits only one request per html page. It always waits to finish actual request before starting new request.
It affects all grids at page and all their requests. It does not permit simultaneous data requests to server.
Since 9.2 it queues the requests, so they are always processed in the order they are started.
Useful to not create more new threads on server side for the page.
It must be set when using TreeGrid server DLL with PHP FastCGI to not create more instances of the DLL.
<treegrid,bdo> bool

Page_Sync

Sets synchronous download of page or child page in server paging.
The grid is disabled during load and waits for server response.
<treegrid,bdo> bool

Upload_Sync

Sets synchronous upload for AJAX communication.
The grid is disabled during upload and waits for server response.
<treegrid,bdo> bool

xxx_Sync

Postfix to data source (e.g. Data_Sync)
Sets synchronous download of given data source when used AJAX communication.
The grid is disabled during load and waits for server response.
You can set Sync attributes for data sources Defaults, Text, Base, Layout and Data by <treegrid Sync/> attribute.
<Cfg> int

SynchroCount

[100]
When count of rendered rows (RowCount) is higher than this value, many actions like sorting, grouping, column resizing and so on are done asynchronously, grid is disabled and message is displayed.
See also ExportRows and PrintRows attributes.
These actions run asynchronously also when Paging is used regardless to SynchroCount settings.

Caching (AJAX)

There is known problem that browsers sometimes does not download the newest data, even if they were changed and use the old ones from their cache.
TreeGrid by default solves this problem by forcing browser to not cache the items at all.
The not caching files is useful especially during development when the files are changed frequently.
For final version you should consider letting browser to cache some files to speed up the communication.
chg 6.0 <treegrid,bdo> int

Cache

[0]
How source files are cached / refreshed.
The default value is 0 that is expected for development. For final release you should set higher value to speed up the communication.
It affects all TreeGrid required files - Defaults.xml, Text.xml, Grid.css, Gantt.css, Help.html.
It affects also all data source files downloaded by AJAX, but only by method Get. Individual data source can be cached according to its attribute Cache.
It affects all cells of type Img.
Remember, the only file that is not affected by Cache setting is main script GridE.js, you should control its caching by yourself.
0 - Never cache - files are always downloaded from server when they are requested. Useful for development when the files are changed frequently.
1 - Component version - files are downloaded only when TreeGrid is upgraded to new version or build otherwise is used standard browser cache.
2 - Cache version - files are downloaded only when CacheVersion attribute changes otherwise is used standard browser cache.
3 - Standard cache - caching depends on browser and server settings, files are usually downloaded when they are modified.
<treegrid,bdo> int

CacheVersion

[0]
Version for caching when Cache=2. When the value is increased, the files are forced to download.

API (AJAX)

upd 6.0 API event type

OnDataSend

(TGrid grid, object source, string data, function Func)
Called before the request or changed data are sent to server by AJAX.
source is the data source that is accessed, for example grid.Source.Layout. The source.Name contains the name of source, e.g. "Layout".
data is XML in string that will be sent to server, it can be XML with request or changes to upload.
Func is function that must be called if (and only if) the handler returns true for custom communication. function Func (int result), result < 0 error, >=0 success.

In this event handler you can do: Update parameters to be sent with the data, by source.Param and source.Params and return null to continue
Modify the XML/JSON data string to sent and return string with the modified XML/JSON.
Do your own communication and return true to not continue. You must call the Func after the custom communication finishes. Use function AddDataFromServer to add your own data to grid.
new 9.0 API event bool

OnCustomAjax

(TGrid grid, object source, string data, function Func)
Use it for custom AJAX communication to replace TreeGrid built-in AJAX routine. Return true for the custom communication.
source is a copy of the data source that is accessed, for example copy of grid.Source.Layout. The source.Name contains the name of source, e.g. "Layout".
When downloading page or row children, it has set source.Row as the page or parent row.
It is the copy of source, because there can be more simultaneous requests for one source with different Row settings.
data is XML or JSON in string that should be sent to server, it can be XML or JSON with request or changes to upload.

After your communication finishes, call function Func (code, result);
code is the integer error code, negative for error, 0 or positive for success
result is a) returned data string with XML or JSON for code >=0 or b) error message string for code < 0

Simple example: Grids.OnCustomAjax = function(G,IO,data,func){ var ret = AjaxCall(IO.Url,data); if(ret<0) func(ret,"Error"); else func(0,ret); return true; }
new 14.0 API event string

OnDataParse

(TGrid grid, object source, string data)
Called when received successful server response with correct data in AJAX communication.
This event is called before the <IO> tag is parsed and before the input data structure is checked.
source is the data source that is accessed, for example grid.Source.Layout. The source.Name contains the name of source, e.g. "Layout".
For Page data source the source.Row contains the row or page the data are loaded for.
data is input data in string received from server as the server response.
Use to convert any input string, e.g. csv, to TreeGrid XML or JSON. Return the converted string or null to ignore the event.
new 6.0 API event string

OnDataGet

(TGrid grid, object source, string data, object IO)
Called when received successful server response with correct data in AJAX communication.
This event is called after the <IO> tag is parsed, but before the downloaded data are added to grid, changes accepted or body is reloaded (<IO Reload='1'/>).
source is the data source that is accessed, for example grid.Source.Layout. The source.Name contains the name of source, e.g. "Layout".
For Page data source the source.Row contains the row or page the data are loaded for.
data is XML or JSON in string received from server as the server response.
IO is parsed <IO> tag with the server response header.

In this event handler you can read and change all IO attributes, including custom attributes sent from server in <IO> tag.
You can also modify the received data and return the modified data from this handler (in string).
chg 6.0 API event void

OnDataReceive

(TGrid grid, object source)
Called when received successful server response with correct data in AJAX communication.
This event is called after all the received data have been added to grid, but before changes are accepted or body is reloaded (<IO Reload='1'/>).
source is the data source that is accessed, for example grid.Source.Layout. The source.Name contains the name of source, e.g. "Layout".
For Page data source the source.Row contains the row or page the data are loaded for.

In this event handler you can update the grid after it received the data from server.
chg 6.0 API event void

OnDataError

(TGrid grid, object source, int result, string message, string data)
Called when communication with server failed and got server HTTP error response.
It is called also if the server returned success, but its response does not contain TreeGrid XML data (tag <Grid>) – it probably contains some error message from server.
source is the data source that is accessed, for example grid.Source.Layout. The source.Name contains the name of source, e.g. "Layout".
For Page data source the source.Row contains the row or page the data are loaded for.
result is TreeGrid error code if exception raised or bad data downloaded:
-1 empty URL, -2 bad URL, -3 URL not found, -4 bad document format (no tag <Grid>), -5 empty response, -6 Timeout
result is HTTP response error code (e.g 404 as not found) if AJAX communication failed.
message is HTTP response error message (statusText) or JavaScript exception message when HTTP communication failed.
data is a response got from server. It can be HTTP error page or the response HTML received from server for successful AJAX, with invalid format.
For timeout (result = -6) the handler can change the source.Repeat and RepeatText to change repeating behavior on the timeout.
new 6.0 upd 15.0 global func. string

AjaxCall

(string Url, string Data, function Func)
Universal function to do synchronous or asynchronous AJAX call to send data to and / or receive data from server.
Url is server URL to communicate with. It can be absolute or relative, or even static local file.
Url can be also JavaScript object as the TreeGrid data source like grid.Source.Layout with its parameters like Url, Method, Param, etc. set.
Data is the data to send to server in parameter named Data.
If the Func is not set, the function does synchronous AJAX call and returns the received response in string.
If the Func is set, the function does asynchronous AJAX call and after finish it calls Func: function (int result, string response, string Url). Url is set since 15.0 as the AjaxCall input Url parameter.
new 6.0 API method string

AjaxCall

(object Source, string Data, function Func)
This method does synchronous or asynchronous AJAX call to given TreeGrid data source and adds the server response to grid.
This method is related to TreeGrid, to do custom AjaxCall, use global AjaxCall function.
source is the data source that is accessed, for example grid.Source.Layout.
Data is the data to send to server.
Func is called after the communication is finished, Func: function (int result).
API method void

AddDataFromServer

(string Data)
Adds the XML or JSON Data ("<Grid>...<Changes> ... </Changes> ... </Grid>") into grid like it was sent from server.
Accepts all changes and does not send anything to server.
Use it to modify data by <Changes> tag with rows Added/Changed/Deleted/Moved.
new 6.0 API variable string

xxx.Name

[0] Postfix to data source (e.g. grid.Source.Data.Name)
The name of the data source, e.g "Defaults" or "Layout". To distinguish the data source in API events.
new 6.0 API variable string

Page.Row

Data source Page attribute (grid.Source.Page.Row)
When downloading page or child page, the grid.Source.Page.Row contains the page that is downloading.
new 6.0 API variable string

Upload.Row

Data source Upload attribute (grid.Source.Upload.Row)
When uploading change of only one row in AutoUpdate, the grid.Source.Upload.Row contains the row.
new 6.0 API variable string

Cell.Row

Data source Cell attribute (grid.Source.Cell.Row)
When requesting changes for some cell, the grid.Source.Cell.Row contains the cell row.
new 6.0 API variable string

Cell.Col

Data source Cell attribute (grid.Source.Cell.Col)
When requesting changes for some cell, the grid.Source.Cell.Col contains the cell column.
new 6.0 API variable string

Cell.Value

Data source Cell attribute (grid.Source.Cell.Value)
When requesting Suggest list for some cell, the grid.Source.Cell.Value contains the actually entered value.