TreeGrid v6.0

Data communication with server

TreeGrid documentation index

 

This document contains basic information about TreeGrid data communication.

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

TreeGrid can upload data to remote or local server or include the data to HTML page and submit it.

 

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

 

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.

 

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

If you want to load data from another domain, you need to do some bridge (place on this domain some server script that will load data from another domain).

If this URL  is relative, it is relative to the actual page URL.

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, *Sort2   Column 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.

*id        Row or page id (only for Page_Url)

*Pos      Page position (only for Page_Url)

*Rows  Page’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’

 

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

 

<treegrid,bdo> string   xxx_Method     [“GET”/”POST”]              Postfix to data source (e.g. Data_Method)             chg 6.0 .

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.

 

<treegrid,bdo> string   xxx_Format      [“Internal”]          Postfix to data source (e.g. Data_Format)             chg 6.0;upd 6.6  .

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

Used for uploading data or for request, input data format is always automatically recognized.

 

<treegrid,bdo> string   xxx_Bonus                    Postfix to data source (e.g. Data_Bonus)                                        .

A string with direct XML 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 send 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>

 

<treegrid,bdo> int         xxx_Cache         [0]         Postfix to data source (e.g. Data_Cache)                                                      .           

Caching setting for individual data source. See Cache attribute.

 

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> int         xxx_Static           [???]     Postfix to data source (e.g. Data_Cache)                                       new 7.0 .           

Caches static data under this name to not load the data from source.

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:

 

<treegrid,bdo> string   xxx_Method     [“GET”/”POST”]              Postfix to data source (e.g. Data_Method)             chg 6.0 .

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/">”

 

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 &lt;Grid&gt; in text node

 

 

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.

 

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

 

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="&lt;Grid>&lt;Cols>&lt;C Name=‘C1‘/>&lt;/Cols>&lt;/Grid>" 
    Data_Url="../data/TreeGridSample.xml" 
    Upload_Tag="GridData">
</treegrid> 
</div>

 

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. See example Examples/Html/SubmitNoActiveX.html.

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 directly to html page can be combined with other communication types, especially for upload.

 

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

 

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> 

 

<treegrid,bdo> string   xxx_Script          Postfix to data source (e.g. Data_Script)                                         new 6.6 .

JavaScript global variable name that contains string with data XML or JSON or JavaScript object with the same structure as JSON format.

It is alternative to Url and Tag and can be set only one from them.

For download only.

 

Example

Simple TreeGrid with data directly included in JavaScript

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

 

 

 

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)

 

<IO>                  int          Result                                                                                                                                            chg 7.0 .

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.

 

<IO>                  string    HtmlMessage                                                                                                                        new 7.0 .

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.

 

<IO>                  int          HtmlMessageTime                                                                                                          new 7.0 .

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

 

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

 

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.

 

<treegrid,bdo> bool       Sync                                                                                                                                                 chg 6.0 .

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

 

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

 

<treegrid,bdo> int         Cache         [0]                                                                                                                                 chg 6.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, 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)

 

API event          type      OnDataSend    (TGrid grid, object source, string data, function Func)                              upd 6.0 .

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 data string to sent and return string with the modified XML.

Do your own communication and return true to not continue. You must call the Func after the custom communication finishes.

 

API event          string    OnDataGet        (TGrid grid, object source, string data, object IO)                                      new 6.0 .

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

 

API event          void       OnDataReceive         (TGrid grid, object source)                                                             chg 6.0 .

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.

 

API event          void       OnDataError    (TGrid grid, object source, int result, string message, string data)     chg 6.0 .

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.

 

global func.      string     AjaxCall (string Url, string Data, function Func)                                                                      new 6.0 .

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

 

API method      string     AjaxCall (object Source, string Data, function Func)                                                              new 6.0 .

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

 

API variable      string   xxx.Name            [0]         Postfix to data source (e.g. grid.Source.Data.Name)                      new 6.0 .           

The name of the data source, e.g “Defaults” or “Layout”. To distinguish the data source in API events.

 

API variable      string   Page.Row                        Data source Page attribute (grid.Source.Page.Row)                      new 6.0 .           

When downloading page or child page, the grid.Source.Page.Row contains the page that is downloading.

 

API variable      string   Upload.Row                  Data source Upload attribute (grid.Source.Upload.Row)                new 6.0 .           

When uploading change of only one row in AutoUpdate, the grid.Source.Upload.Row contains the row.

 

API variable      string   Cell.Row                                         Data source Cell attribute (grid.Source.Cell.Row)              new 6.0 .           

When requesting changes for some cell, the grid.Source.Cell.Row contains the cell row.

 

API variable      string   Cell.Col                              Data source Cell attribute (grid.Source.Cell.Col)                             new 6.0 .           

When requesting changes for some cell, the grid.Source.Cell.Col contains the cell column.

 

API variable      string   Cell.Value                        Data source Cell attribute (grid.Source.Cell.Value)                         new 6.0 .           

When requesting Suggest list for some cell, the grid.Source.Cell.Value contains the actually entered value.