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).
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> 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:
For example Data_Url='..\Source\Body*Sort0.xml' Page_Url='..\Source\Page*Pos.xml'
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 (/).
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>.
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>)

GET	For 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 '?'.
POST	For 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
SOAP	For download or upload. Uses HTTP method POST and uploads data in SOAP XML envelope. See AJAX SOAP.

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.
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)
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.
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.
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).
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".
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 method SOAP: It contains XML nodes in format <ParamName>ParamValue</ParamName><ParamName2>ParamValue2</ParamName2> 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".
Caching setting for individual data source. See Cache attribute.

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.
Set the Method to "SOAP" for SOAP communication.
Name of SOAP function. This function will be called in the web service.
Name of SOAP namespace. The namespace the Function belongs to.
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>
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.

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

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.
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!
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.
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.
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.
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.
This attribute should not be set in data xml, only in layout.
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)

General result of the server response.
TreeGrid distinguishes only two values:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Sets synchronous download of page or child page in server paging.
The grid is disabled during load and waits for server response.
Sets synchronous upload for AJAX communication.
The grid is disabled during upload and waits for server response.
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.
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.
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.
Version for caching when Cache=2. When the value is increased, the files are forced to download.

API (AJAX)

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.
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".
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);

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; }
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".
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.
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".
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).
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".

In this event handler you can update the grid after it received the data from server.
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".
result is TreeGrid error code if exception raised or bad data downloaded:
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.
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.
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).
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.
The name of the data source, e.g "Defaults" or "Layout". To distinguish the data source in API events.
When downloading page or child page, the grid.Source.Page.Row contains the page that is downloading.
When uploading change of only one row in AutoUpdate, the grid.Source.Upload.Row contains the row.
When requesting changes for some cell, the grid.Source.Cell.Row contains the cell row.
When requesting changes for some cell, the grid.Source.Cell.Col contains the cell column.
When requesting Suggest list for some cell, the grid.Source.Cell.Value contains the actually entered value.