Download data

TreeGrid documentation

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

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

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

Source

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

Text_

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

Text_Start

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

Text_StartErr

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

Defaults_

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

Base_

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

Layout_

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

Data_

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

Page_

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

BasePath

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

OnReadData

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

ReadData

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

Loading

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

OnLoaded

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

OnLoadError

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

OnUpdated

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

OnReady

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

CacheTimeout

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

Prepared

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

Layout XML structure

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

</Grid>

Data XML structure

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

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

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

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