Data Formats

TreeGrid XML data format

TreeGrid v3.4

Updates

3.4

Added <IO Session> attribute

3.3.3

Updates <Header> section, multi rows header support

3.3

Added <Img> description

Deleted <Cfg> attributes CacheImages and ImgPath

Added <Cfg> attributes DebugCalc, DateStrings

3.2

Added Defaults description

Added attributes LeftVal, MidVal, RightVal. Cell attributes Button, ButtonText.

Basics

TreeGrid uses XML structure to describe data rows and cols. The root tag is always <Grid>.

Immediate children of <Grid> tag are main tags and describe the parts of the grid: Communication (<IO>), Configuration (<Cfg>), Defaults (<Def>), Left panel (<Panel>), Columns (<LeftCols>, <Cols>,<RightCols>), Header (<Header>), Rows (<Head>, <Body>,<Foot>), Toolbar (<Toolbar>), Configuration menu (<MenuCfg>), Pager (<Pager>), Language settings (<Lang>).

Order of main tags is optional. Not all main tags must be present, most of their attributes are pre-defined in required files Defaults.xml and Text.xml.

Required main tags are <Cols> and <Body>, these tags must contain at least one children (TreeGrid must contain at least one variable column and one page).

If tags are defined in more files, their attributes and children are merged. Existing attributes are overwritten by new value. Defaults (<D>) and columns (<C>) tags are merged by Name attribute. Fixed rows () are merged by id. Other tags are single and are merged by tag name.

Pages () and variable rows () are not merged, just added, even if they are the same id – this will cause an error. It is due performance reason.

Data are loaded in this order: Text.xml + Bonus, Defaults.xml + Bonus, Layout + Bonus, Data + Bonus.

Formats

TreeGrid accepts data in XML format. The XML format can use one of four sub-formats: DTD, Internal, Short, Extra short. These formats differ in speed of processing, data length and DTD standard compatibility. The format structure differs in storing cell values and cell and row attributes. This affects tags <D>, and <Header> only.

This XML format is not compatible with XML format from TreeGrid v2.x. The CSS format from TreeGrid v1.x and v2.x has been abandoned.

Preferred format is Internal.

DTD format It is largest and has slowest processing. Use it for short data that need to be generated and processed on server side by standard XML parser with DTD validation and using getElementById (or similar) method to find row by id.

DTD format contains each cell data and settings in separate tag . This tag has attribute N with column name and can have attribute V with cell value and other attributes named as cell parameters.

This is recommended format for small grids.

Example:

</Body></Grid>

Internal format This format uses TreeGrid as internal format to store data. Thus if you use JavaScript API to browse TreeGrid data on client, the data is in internal format. The format is fast to process and is shorter then DTD format. It can be generated and processed on server side by standard XML parser but without DTD validation and cannot use standard function to locate rows by their ids. You cannot use predefined DTD, but you can define you own DTD for your data.

Internal format stores cell values as row attributes named as column name. And cell attributes stores in row attributes named as column name joined with attribute name.

This format is also used in sample ASP.NET service and in ASP.NET supports objects.

Example:

</Body></Grid>

Short format It is shorter then internal or DTD format and is fast to process. It can be generated and processed on server side by standard parser with DTD validation and using getElementById (or similar) method to find row by id, same as DTD format. But cell values and attributes are stored as text node and needs another parsing on server side.

Short format stores cell values and row and cell attributes except id attribute in text node in row according to predefined Par tag. Attribute names in text use Internal format naming.

Text node has this format: “|par|attr1|attr2|...|attrN”, where “|” is chosen character that is not present in any attribute value. par is name of tag. And next are separated values of attributes in . Count of attributes must be the same as count of attributes in List. If any attribute value is missing, just leave the space empty, but separator must be present.

This is recommended format for large grids.

Example:

<Grid>

<Par>

</Par>

<Body>

|N||1|xx

|D|0|0||xx-aa|1|10|

|D||||xx-bb||20|

|N|1|2|yy

|D|1||10|yy-aa|||c1*2

</Body></Grid>

Extra short format It is shortest and is fast to process. It can be generated and processed on server side by standard XML parser with DTD validation, but without access rows by their id attribute. But cell values, row and cell attributes and immediate leaf children row’s attributes and cells are stored as text node, therefore it needs another parsing on the server side.

Extra short format stores row’s attributes, cell values and attributes and attributes of all immediate children data rows (rows without children) in text node. Attribute names in text use Internal format naming.

If the main row has no attributes and first part is empty, just let it empty, like “||par|count|...” – two starting separators.

Example:

<Grid>

<Par>

</Par>

<Body>

|N|r1||1|xx|D|2||r11|0|0||xx-aa|1|10||r12||||xx-bb||20|

|N|r2|1|2|yy|D|1||r21|1||10|yy-aa|||c1*2

</Body></Grid>

Names and IDs

Rows are identified by attribute id (both characters lowercase!). If this attribute is not set, row cannot be identified and its changes cannot be updated to server. Therefore every editable row needs to have set its id. All rows ids must be unique among all row ids inside one grid. The id is not used in JavaScript API to access rows.

Columns are identified by attribute Name. Every column must have set this attribute. The Name identifies column and row’s cells. Under this name are row’s cells in this column set and accessed. All column names must be unique among all column names inside one grid. Under this name saves column its configuration to the cookies. If you change any column name, you need to increment Grid attribute Version to clear old configuration. In JavaScript API, cell is accessed by column name.

! Attention ! Column names must not interfere with row’s attribute names, like Def, Kind or Deleted !

The best way is to name columns as letter ‘A’, ‘B’ or ‘a’, ‘b’. There is no interference and data length is short.

Defs (default rows or columns) are identified by attribute Name. Every def must have set this attribute. The rows that use values from this default points to the default row by its attribute Def, with value of def Name. The default column must have Name=”C”. The default row for all rows and defs has Name=”R”. If fixed (head or foot) row has not set Def attribute, it uses def with Name=”Fixed”. The def can also point to another def by Def attribute.

All ids and names are case sensitive and can contain lower and uppercase letters (a-z, A-Z) and character “_”. Cannot start with digit but can contain digits (0-9). Any other characters are forbidden.

Defaults

Every row has predefined attribute values in its default row <D>. The values from <D> are used when the row has some attribute not set. If row has attribute set to empty value, the default value is not used.

Using defaults helps you to reduce data size and also to control adding and moving rows. But using defaults is not required.

Using defaults is good especially for trees with different levels, at least to differentiate tree nodes and data rows.

Defaults <D> are identified by their attribute Name. By this Name string are referenced from rows or other defaults by attributes Def or CDef. See Names and ids.

Def attribute specifies default for the row itself.

You can use Def attribute even in <D> tag to reference another <D>. This means that you define that references to its <D> that references to another <D>, that ...

If you don’t set Def attribute for any <D> or tag the default is always <D Name=”R”>. Only for fixed rows is predefined <D Name=”Fixed”> that, of course, references “R” default too. This means that any attribute value not set in branch of and <D> tags is at last read from “R” default.

Pay attention to cross-references among <D> tags.

CDef attribute specifies default for all immediate children rows, but only if they have not set their own Def attribute.

When dragging rows to children of the row, the parent row can accept only children rows with the same default as the parent row’s CDef.

When adding rows to children of the row, the new row will implicitly have default the same as parent rows’ CDef.

You can use CDef attribute even in <D> tag to predefine CDef attribute for all rows that use this default (the CDef attribute does not concern <D> tag itself, unlike Def attribute).

The CDef attribute can be also set in tag <Header>, this specifies default for all root rows. In this case (but in this case only), <Header> acts as parent for all variable root rows, including adding and dragging rows to root.

You can specify to row which default to use by many ways, all can be done in every case, but some are better for some cases and some for other cases.

Using Def attribute only is more simple but by CDef attribute you can control more. Remember, CDef attribute you can set even in <D> and <Header> tags too.

If you don’t use any Def or CDef attributes, all variable rows will have default <D Name=“R”> and fixed rows <D Name=”Fixed”>. These <D> are defined in basic file Defaults.xml. It means, if you don’t need to use defaults, you need not do it. You can change attributes of “R” or “Fixed” if you use <D> tag with this name in your data. New attributes you specify are merged or overwrite attributes specified in Defaults.xml => you don’t need to edit this file for every new grid.

XML structure – download

<Grid> (Root tag, can accept any count of introduced child tags in any order)

<Img ... attributes with images setting ... />

<Cfg ... attributes with grid settings ... />

<Def> ( list of default settings (tags <D>) for rows)

... more tags for other cells, in DTD format ...

</ D>

... More tags <D> ...

</ Def>

<Par> (list of prepared parameters for short formats)

</ Par>

<Panel ... Attributes for left row panels settings ... />

<LeftCols> ( Columns fixed to left side, still visible, can be empty)

... more tags <C> for other columns ...

</ LeftCols >

<Cols> (Variable columns, required, must contain at least one column)

... more tags <C> for other columns ...

</ Cols>

<RightCols > (Columns fixed to right side, still visible, can be empty)

... more tags <C> for other columns ...

</ RightCols >

<Header ... Attributes with column titles (named as column names) and header row settings in Internal format ... >

... more tags for other columns, in DTD format ...

</ Header>

<Head> (List of top fixed rows, always visible, can be empty, rows cannot contain children rows)

... more tags for other cells, in DTD format ...

... More tags ...

</ Head>

<Body> (List of all variable rows in pages, required, must contain at least one page, must not contain rows in root (only in pages))

(One page with rows, if pages are created automatically, can be only one with all rows)

... more tags for other cells, in DTD format ...

... More tags , with possible children tags I with possible children and so on – unlimited levels of tree ...

... More tags ...

... more tags for other cells, in DTD format ...

... More tags ...

... More tags if data of pages are loaded on demand ...

</ Body>

<Foot> (List of bottom fixed rows, always visible, can be empty, rows cannot contain children rows)

... more tags for other cells, in DTD format ...

... More tags ...

</ Foot>

<Toolbar ... Attributes with settings for bottom toolbar ... />

<MenuCfg ... Attributes with settings for dialog displayed for configuration ... />

<Pager ... Attributes with pager settings ... />

<Lang> (All language depended texts and formats)

<Alert ... Attributes with plain text for alert dialogs .../>

<Text ... Attributes with html text for messages and other use ... />

<Toolbar ... Attributes with tool tips texts for toolbar buttons .../>

<MenuCfg ... Attributes with menu item names and values ... />

<Format ... Attributes with format texts and regional settings ... />

</ Lang>

</Grid>

XML structure – upload

<Grid> (Root tag, can accept any count of introduced child tags in any order)

<Changes> (list of changed rows)

... more tags for other cells, in DTD format ...

<Changes/>

</Grid>

XML structure – request

<Grid> (Root tag, can accept any count of introduced child tags in any order)

<Cfg ... attributes with grid settings read from cfg ... />

<Filters> (list of filters read from cfg)

... more tags for other cells, in DTD format ...

<Filters/>

<Body> (List of all requested pages or rows)

... More tags ...

</ Body>

</Grid>

Attributes of XML Tags

Description of all attributes in all tags. This notation uses C syntax, but of course in XML are all values strings.

string is value from any visible characters. int is integer number. bool is boolean value 0 or 1 (not false and true !). Array is list of comma separated values.

In [ ] is default value from file Defaults.xml.

Floating point numbers use ‘.’ as decimal separator and no thousands separator. Don’t use zeroes, if they are not required, instead of “020.00” use “20”.

Date and time values are in English notation (mm/dd/yyyy hh:mm:ss).

Date and time values can be also set as number of milliseconds from 1/1/1970 00:00:00.000 (standard JavaScript Date.getTime()). This format is preferred for large grids. Set also Cfg.Prepared = 1 to speed up loading.

You can set any other custom attributes or even tags and use their values in formulas or in your own JavaScript functions and event handlers.

<IO> Request or server response. If error occurred, this is usually the only tag returned. If there were no error or warning, this tag is usually missing.

int Result General result of server response, 0 means OK, >0 OK with warning, <0 Error, sent data were not accepted.

string Message Server response message, if set, this text is alerted to user, independently of Result value.

string Session Sent to server from client, was read from <treegrid> tag. It identifies server session.

Remember, the IO is not sent to server if method <treegrid ???_Method=’Get’> is used

<Img> Images settings, image files and sizes. Change them only if you want to use another or custom image set. See changing images.

string Grid [“Grid.gif”] Image file with all grid icons except toolbar icons

int Height [17] Height of all icons in grid except toolbar icons, in pixels

int Line [21] Width of all tree straight line icons

int Tree [26] Width of all tree ending icons

int Panel [13] Width of all left panel icons

int Sort [14] Width of all sorting images in header

int Filter [17] Width of all filter images

int Row [17] Width of all row content images (checkbox, calendar)

string Toolbar [“Toolbar.gif”] Image file with all toolbar icons

int ToolbarHeight [16] Height of all toolbar icons

int ToolbarWidth [25] Width of all toolbar icons

string DragOne [“DragOne.cur”] Cursor file. This mouse cursor is displayed when dragging one row or column

string DragMore [“DragMore.cur”] Cursor file. This mouse cursor is displayed when dragging more rows.

<Cfg> Grid settings

Main settings

string id [...] Unique ID of created TreeGrid on the page, under this name will be stored configuration to cookies.

By this name can be TreeGrid accessed from JavaScript code, as Grids[id].

It is also ID of <TABLE> tag where grid is rendered. This tag replaces <TreeGrid> tag.

Default value is “TableX”, where X is grid index, from 0, in order grids are created

int Version [0] Version of data. Grid loads cfg from cookies only if version is the same as saved.

Change this number whenever data structure (especially number of columns, column names and types) changes.

int MainCol [0] Main column with tree, empty for pure grid without tree

Paging

int Paging [0] Method of paging used. This paging is only for root rows, best for pure grids or trees with many root nodes.

0 – None. All rows are in one page, pager cannot be visible. All rows are rendered on start. This means slow start and fast use.

It is good for small grids, up to about 500 rows in root.

1 – Show all. Pages are automatically created but all are rendered on start. For AllPages = 1 is the same as None but with pager enabled.

For AllPages=0 is the same as Auto. It is good for medium grids, 250 – 1000 rows in root.

2 – Auto (Client) Pages are automatically created.

For AllPages = 1 is page rendered only when is visible in window by scrolling for 500ms.

For AllPages=0 is page rendered immediately but is visible only one page at a time and after switch to another is re-rendered.

It is good for large grids up to 10 000 rows. All functions still works offline, include sorting, filtering and calculations.

3 – Load (Server) Pages are created by server and TreeGrid downloads only page being displayed.

The server is responsible for sending data for requested page and also for sorting and filtering.

Calculations are still possible offline on client, but must be prepared on server.

It is good for very large grids, with more then 10 000 or for grids with special relations or grids need be online.

For server application you can use TreeGrid.dll.

int ChildPaging [2] Method of paging of children rows in tree.

0 – None. All rows, including all children are rendered on start. This means slow start and fast use.

2 – Auto. Rendered on start are only children of expanded rows. Children of collapsed parent are rendered on first access.

This means faster start for collapsed tree, but slower first expanding of collapsed node.

3 – Load. Children of collapsed row are downloaded at first expand. Server must be able to send the children of the row.

For server application you can use TreeGrid.dll.

int PageLength [20] Average count of rows in page when Paging is auto and automatically creates pages.

Exact count of rows in pages can differ due to adding or deleting rows or in last incomplete page.

Every page must contain at least one row or is deleted. Exception is when grid does not contain any row, but must contain one page.

Generating id (when adding new rows)

string LastId [“”] Last (maximal) id. New generated id (of new added row) will get next id. If empty, on first adding grid must find the last id.

If IdPrefix and / or IdPostfix are used, this attribute must start with IdPrefix and end with IdPostfix

string IdChars ["_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"] Accepted characters when generating id. In this order.

Example: if LastId is “ab” the next id is “ac”, for “az” is “ba” for “zzz” is “____”

Remember, id cannot start with digit, if you want to use digits, use also IdPrefix.

string IdPrefix [“”] This string is inserted before generated new id.

string IdPostfix [“”] This string is appended at the end of generated new id.

Grid capabilities

bool Editing [1] Values of grid can be edited

bool Deleting [1] Rows can be deleted

bool Selecting [1] Rows can be selected

bool Adding [1] Rows can be added

bool Sorting [1] Rows can be sorted

bool Dragging [1] Rows can be moved by mouse

bool ColResizing [1] Columns can be resized. Remember, column resizing is slow.

bool ColMoving [1] Columns can be moved by mouse dragging. Inside its section only (LeftCols, Cols, RightCols)

bool SuppressMessage [0] Grid is silent, does not display messages

bool SuppressCfg [0] Does not use client settings in cookies (0 – uses, 1 – does not load, 2 – does not save, 3 – both)

Grid configuration, used only at first time or when Version changes or when SuppressCfg=1or when ...Lap = 1

If you need to overlap saved cfg for any parameter, set attribute ...Lap to 1 (for example for ShortCols set SortColsLap = ‘1’)

bool Sorted [0] Sorting is enabled by user

bool AutoSort [0] Row is sorted if value is changed after edit

string [] SortCols [] Array of column names (comma separated), according to them are rows sorted, in this order. Max 3 columns.

int [] SortTypes [] Array of sort types (comma separated) for every column in SortCols

type value is integer as bit array: bit 1 – 0 DESC, 1 ASC,

bit 2 - 4 (&14) string sorting, bit 2 (&2) – 1 = localization sorting, bit 3 (&4) – 1 = case insensitive, bit 4 (&8) = ignore white space

bool Calculated [1] Calculating is enabled by user

bool AutoUpdate [0] If true, after any change, sends changed data to server

bool ShowDeleted [1] Shows deleted rows (in red). For true are deleted still visible and can be undeleted.

int Hover [1] What blinks under mouse cursor. 0 – nothing, 1 – border (caption, panel, ...), 2 – border and cells

int SortIcons [1] How sorts and shows icons. 0 – hides icons and sorts by click to cell, 1 – shows icons and sorts by click to cell, 2 – sorts by click to icon

bool ShowDrag [1] Shows dragged object under mouse cursor

bool HidePanel [0] Row’s left panel is hidden by user

bool AllPages [1] When paging enabled, shows all pages at once and renders page on demand, when displayed by scrolling.

For false shows one page at a time and switches to pages only by pager click.

bool ColsLap [0] Overrides saved configuration for column positions and widths, if set this settings from cookies is ignored.

bool FilterLap [0] Overrides saved configuration for filters, if set this settings from cookies is ignored.

bool PagerWidthLap [0] Overrides saved configuration for pager width, if set this settings from cookies is ignored.

Other settings

string HelpFile["Help.html"] Path and filename of TreeGrid help.

int RowHeight [0] Minimal height of one row, it must be set if not all rows have the same height (have different images for example).

bool Prepared [0] Prepare grid to speed up loading grid. If prepared, date-time values are set as count of milliseconds from 1/1/1970 00:00:00.000.

Set Prepared to 1 for large grid also if grid does not contain date-time values.

int CacheTimeout [5] How long TreeGrid waits for all images complete loaded, in seconds.

If the timeout expires, TreeGrid alerts warning and continues rendering.

bool DebugCalc [0] Set it to 1 to see all errors in calculations. Set it only when debugging not in release data.

Many errors are caused by syntax errors in formulas or when any input value is null or by missing CalcOrder.

bool DateStrings [0] If set to 0 (default) Date values are uploaded as numbers (milliseconds from 1/1/1970),

if set to 1, Date values are uploaded as strings in English format (M/d/yyyy HH:mm:ss).

<D> Default row or column. From this row are filled all attributes in pointed row or column that are not explicitly set. This tag can only be in <Def> tag.

string Name Name of the default. Required. To this name points row’s Def attribute to use this default.

See also chapter Names and IDs. Predefined names (in Defaults.xml) are:

“C” – default column for all columns, column cannot have the Def attribute. You cannot mix the “C” with other rows defaults.

“R” – default row for all rows and defaults without Def attribute and for all attributes not set in row and even in its default (s).

“Fixed” – default row for all fixed (head and foot) rows without Def attribute.

string Def The default can also point to another default by specifying its name in Def attribute.

From this parent default reads all attribute values not explicitly set.

Other attributes are the same as in or <C> tag, depends for what it is default. Except id attribute.

<Panel> Row’s left panel settings. This tag can only be in <Grid>.

bool Visible [1] If the panel is visible. The panel can be hidden also by Cfg.HidePanel attribute.

bool Select [1] If the button Select is visible. This button is hidden also if Cfg.Selecting attribute is 0.

bool Delete [1] If the button Delete is visible. This button is hidden also if Cfg.Deleting attribute is 0.

<C> One column settings. Values of not set attributes are read from default <D Name=”C”>. This tag can be in tags <LeftCols>, <Cols>, <RightCols>.

Column position grid is according to its position in parent tag. This is used only for first display on client or when Cfg.Version changes, otherwise is column position read from cookies. Column caption is set in tag <Header>.

string Name [“”] Column name. Required. By this name are accessed cells in this column. See also chapter Names and IDs.

string Type [text] Column type:

Bool boolean value 1 and 0 – in HTML is displayed as checkbox

Int integer number – in HTML is displayed as formatted text according to Format string.

when editing, this is displayed in <INPUT type=”text”> and is formatted according to EditFormat string

when editing, only valid keys are accepted, the other are ignored.

Float floating point number, other is same as in int type.

Enum enumeration – index to array Enum. In HTML is displayed string from Enum array on position given by this value.

when editing, displays <SELECT> with items from Enum array with this value as selected index.

the enumeration can be used for special sorting, when you need to have non standard order.

Date date and/or time. In input data is this value number of milliseconds from 1.1.1970.

the value is displayed as formatted text according to Format string.

when editing, this is displayed in <INPUT type=”text”> and is formatted according to EditFormat string

when editing, there is displayed button on the right in the cell to show date picker to select date from calendar

Text string – if Rows=1 is displayed as text and when editing in <INPUT type=”text”>

if Rows > 1 is displayed in <TEXTARREA> with given number of rows.

Pass password, it is displayed as “***”, when editing is displayed in <INPUT type=”password”>

for now passwords are sent not coded

string Format [‘’] Format string for int, float and date types. Format string is the same as in function ToString ( ) in Microsoft .NET.

string EditFormat [‘’] Format string for editing, if is empty, Format is used

string [] Enum [‘’] List of values for enum type. This is array in string. The first character is the separator and this separator is used to separate items of array.

The item cannot contain the separator. For example “,one, two,three” or “|1,1|2,3”.

int Rows [1] Count of rows in input cell for type text. 1 – input type text, >1 – textarrea.

bool CanEdit [1] Column values can be edited

bool CanFocus [1] Column cells can be focused

bool CanResize [1] Column can be resized

bool CanMove [1] Column can be moved

bool CanFilter [1] Rows can be filtered by this column

bool CanSort [3] If and how can rows be sorted by this column, 1.bit (&1) – can sort rows by this column, for other bits see Grid-SortType

bool ToolTip [0] Cell values are displayed as tool tip on mouse hover

string Formula [‘’] Formula for calculated column. If set, column is calculated. See document Cell Formulas.

Remember, set CalcOrder for every row if you use in some formula result of another formula on the same row.

Remember, all cell values you use in formula must be set in all rows. Value not set is not 0 but “undefined” and cannot be calculated.

Best way is to set all values from formula to 0 in some Def, usually in Def “R”.

text Button [] Type of button on the right in the cell. None (no button), Button (user <BUTTON>), Img (user <IMG>), Date (date picker for date type)

When empty it is None for all types except date for that is Date.

int WidthPad [0] Width of button/img tag. If Button = Button or Img, then is required value

string ButtonText [''] Button text or img src for Button = Button or Img.

int Width [] Column width in pixels, if empty is computed before the grid is first displayed

int Size [] Max characters in tag input / textarrea

bool Visible [1] Column is visible

<Header> Top header with column captions. This tag can only be in <Grid>. In cell values are titles (captions) for individual columns

It contains also settings of root node.

string CDef [“R”] The name of default for child rows in root. See CDef in tag .

int Rows [1] Count of rows in header, 1 is minimum, use for multi-caption headers

If there are more rows than 1, one row is main row with column captions and functions for sorting, resizing and moving columns

and other rows are section rows with no user input, but can be spanned to more columns and also can contain html code.

If you set Rows>1 you must set all apropriate LeftXX, MidXX and RightXX attributes too !

If you set Rows>1 you usually need to disable column moving ability <Cfg ColMoving=”0”>.

int Main [0] Index of main row with column captions and response to user activity, if Rows are greater then 1.

string LeftRC [“”] Cell value for other rows then Main if Rows is greater then 1 for left columns section.

RC are wild-cars, attribute name is for example Left00 or Left312 (R is always one digit, C can be larger).

R is row index, cannot be the same as Main. You have to use all row indexes from 0 to Rows-1 except Main.

C is cell index from 0. No one index can be skipped.

Value can be a HTML code.

int LeftRCSpan [1] How many columns this cell spans. You have to span all columns in section. This is for left columns section.

Sum of ...Span must be the same as count of all columns in section (except row panel).

string RightRC [“”] Cell value for right columns section, see LeftRC.

int RightRCSpan [1] Span for right columns section, see LeftRCSpan.

string MidRC [“”] Cell value for variable columns section, see LeftRC.

int MidRCSpan [1] Span for variable columns section, see LeftRCSpan.

One page with variable rows. If Grid.Paging is not 3 (Load) this is usually only one with all rows inside and without any attribute.

This tag can only be in tag <Body>, it is required tag. Attributes are used only when Grid.Paging = 3 (Load).

string id [] Unique ID of the page. By this ID is page identified when downloading data for this page. Used only if Rows are not set.

string Rows [] User string. If set, the page is identified by this string when downloading data for this page. It usually contain list of rows page contains.

int Pos [] Page position, identifies page, used only in request.

string Name [] Name of page, displayed in pager. Can contain HTML code (coded).

string Title [] Tilte of page, displayed in pager as tool tip. Pure text.

string Count [] Count of rows page contains. It specifies height of the page when does not show rows yet.

... cells with result of specific aggregate function on children rows in the column, for example , where A is column name ...

One row settings and data. Values of not set attributes are read from default specified by Def attribute or if not set, from <D Name=”R”>.

This tag can be in tags <Head>, <Foot>, .

Main setting

string id [] Unique ID of the row. If this attribute is not set, row cannot be identified and its changes cannot be updated to server.

Therefore every editable row needs to have set its id. All rows ids must be unique among all row ids inside one grid.

The id is not used in JavaScript API to access rows.

string Def [“R”] The name of default (<D Name=””>). From this default are read all attributes, cell values and attributes not explicitly set in this row.

string CDef [“R”] The name of default for child rows. This value is used as Def attribute value for children, if they have not set its own.

This value is also used as value of Def attribute for new child rows added to this parent.

When dragging, the row can only accept children with their Def attribute with the same value as this CDef value.

If the CDef is set to empty string, the row cannot accept any children (by adding or by dragging).

string Kind [“Data”] A kind of the row. This can be:

“Data” – Standard data row with cell values. Can be fixed or variable. Can be source for calculations. Can be sorted, filtered, ...

“Filter” – Row with filter settings for filtering data rows. It is usually fixed row.

“User” – User row without columns. Cannot be edited by standard grid functions. Can contain any html code. It is usually fixed row.

Row is divided to sections. For every section displays HTML code from attribute LeftVal, MidVal or RightVal.

string Par [“”] For short format only. The name of the with list of attribute names set in the row text.

string Class [“”] Name of CSS style class to use for whole row

Row capabilites

bool CanEdit [1] Row values can be edited.

bool CanFocus [1] Row can be focused

bool CanDelete [1] Row can be deleted

bool CanSelect [1] Row can be selected

bool CanDrag [1] Row can be moved by mouse dragging. To where can be row moved is specified by drop target’s CDef attribute.

bool CanFilter [1] Row can be filtered (hidden) by any filter

Row state, usually set in uploaded data only

bool Deleted [0] Row has been deleted and will be deleted from data when updating.

bool Added [0] Row has been added and will be added to data when updating.

bool Changed [0] Any row’s cell value has been changed. Which cell is specified by the cell’s attribute Changed.

int Moved [0] If and how row has been moved. 0 – no, 1 – to another position in the same parent, 2 – to another parent.

string Parent [] When moved, this is id of the new parent row or “” if the row is the root row.

string Next [] When moved, this is id of row before row have been added or “” if the row is the last in its parent.

Other settings

bool Visible [1] Row is visible.

bool Selected [0] Row is selected

bool Expanded [1] Row is expanded, displays its children

bool Calculated [1] Row is calculated, at least one of its cells contain Formula attribute. You must set the Calculated attribute, if the condition is fulfilled.

Due performance needs, this can be used only in <D> and fixed  only !

string [] CalcOrder [] If row is calculated, there is comma separated list of column names. In this order are row’s cells calculated.

Set it, if some cells formulas are depended on another calculated cells from the row. If not set, alphabetical order is used.

Due performance needs, this can be used only in <D> and fixed  only !

int Recalc [3] What to recalculate, if any value changed or row moves / is deleted / added. Binary mask.

1 – Row, 2 – Calculated parents, 4 – All parents, 8 – Immediate children, 16 – All children, 256 – All table

It must contain at least all bits as in cell’s Recalc parameters to ensure appropriate recalculations.

string LeftVal [] Left section value for User row

string MidVal [] Variable section value for User row

string RightVal [] Right section value for User row

Cells Cell value and settings can be set by two ways according to format used.

Cells can be in tags , <D>, <Header>

1) DTD Format – each cell settings is in separate child tag <U N=’column_name’ ... /> with attributes named without prefix.

Cell value is in attribute V.

Example:

2) Internal and shorts formats – all cells settings are in row attributes. The attributes are named as column_name + attribute_name.

Cell values are in attributes named only column_name.

Example:

string Value Cell value in string.

Floating point numbers use ‘.’ as decimal separator and no thousands separator.

Date and time values are in number of milliseconds from 1.1.1970 00:00:00.000 (standard JavaScript Date.getTime()).

bool CanEdit Cell value can be edited. Order testing if cell can be edited is: cell (+default), row (+default), column(+default). The first value set is returned.

bool CanFocus Cell can be focused. Order of testing is the same as in CanEdit.

string Type Overridden column’s type

string Format [] Overridden column’s format string

string EditFormat [] Overridden column’s format string for editing

string [] Enum [] Overridden column’s list of values for enum type. Due performance needs, this can be used only in <D> and fixed  only !

string Formula [] Formula to compute cell’s value. If formula of any cell in the row is set, the Calculated attribute must be set too.

Due performance needs, this can be used only in <D> and fixed  only !

string Error [] If set it means that cell contain invalid value. The cell is colored red and as tool tip is displayed the Error string.

text Button [] Type of button on the right in the cell. None (no button), Button (user <BUTTON>), Img (user <IMG>), Date (date picker for date type)

string ButtonText [''] Button text or img src for Button = Button or Img.

int Recalc [] What to recalculate, if value changed. Binary mask. Overrides row’s Recalc parameter.

1 – Row, 2 – Calculated parents, 4 – All parents, 8 – Immediate children, 16 – All children, 256 – All table

string sum, count, ... Only in tag, result of aggregate function on children rows in the column, used when Cfg.Paging = 3

<Pager> Settings of pager

bool Visible If pager is visible. Pager can be visible only if Grid.Paging > 0. Pager visibility user can select from configuration menu and is saved to cookies.

string Caption Pager caption

int Width Starting width of pager in pixels.

bool CanResize If pager can be resized by user

<Toolbar> Settings of bottom toolbar

string Tag [“”] If set, the id of tag where to render the toolbar, if there is need to show toolbar outside the grid. In trial version this attribute is ignored.

bool Visible [1] If toolbar is visible. In trial version this attribute is ignored.

bool Save, Reload, Repaint, Add, AddChild, Sort, Calc, ExpandAll, CollapseAll, Cfg, Help [1] If this button is visible. Default is 1 for all.

<MenuCfg> Settings of configuration dialog

bool ShowDeleted, AutoSort, AutoUpdate, Separator1, MouseHover, ShowDrag, ShowPanel, ShowIcons, ShowPager, ShowAllPages [1]

If this option is visible. Default is 1 for all.

For short formats only. Predefined list of attribute names for row pointed by Par attribute. This tag can only be in tag <Par>.

string Name Name of parameter. To this names points row by the Par attribute.

string List Comma separated list of row’s attribute names. Attribute names always use Internal format !

Communication with the server

1) Download of structure

On start TreeGrid downloads data from data source Text, Defaults and Layout. Does not send any request, just downloads data.

When server returns HTTP error or IO.Result < 0 the TreeGrid stops loading and shows fatal error.

2) Download of data

Next TreeGrid downloads data from data source Data. If Paging is not set to 3 (Load), does not send any request, just downloads all data.

When server returns HTTP error or IO.Result < 0 the TreeGrid stops loading and shows fatal error.

2a) Paging

If Paging is set to 3 (Load) it loads configuration from cookies and inserts it to the request (See XML request) and sends it to server and downloads prepared pages without data. This request contain filter and sorting settings.

Server prepares pages – calculates, sorts and filters rows and distributes rows to pages. And sets page names and results of aggregate functions for page and column.

Returned <Body> tag contains only tags with attributes but without any child tags.

When any not loaded page is displayed, TreeGrid downloads data for this page by sending appropriate request. The request for page ( tag) contains Rows attribute of page (if was set) or id attribute (if was set) and (always) Pos attribute as page index (position from 0).

The request also contains filter and sorting settings, the same as when pages body were downloaded.

When user changes sorting or filtering, TreeGrid reloads all data from data source Data with new configuration in request. And repeats loading of pages.

Re-calculations after cell change are still done on client. Calculated cells are not sent to server. Therefore server must also recalculate appropriate cells if changed values are saved to server.

Example of request for body (grid has columns named A,B,C,D,E):

<Grid>

<Cfg SortCols=’C,A’ SortTypes=’0,1’/>

<Filters></Filters>

</Grid>

Example of resulted body (grid has also one foot row: )

<Grid>

<Body>

</Body>

</Grid>

Example of request for second page (grid has columns named A,B,C,D,E):

<Grid>

</Grid>

Example of resulted second page

<Grid>

<Body>

... 18 rows ...

</Body>

</Grid>

2b) Child paging

If ChildPaging is set to 3 (Load) it loads the server not send content of collapsed rows when downloading data or page.

When user expands collapsed not yet loaded row, TreeGrid sends the same request as for downloading page. The requested row is set as  tag with row’s attribute id. (For example: <Grid>...<Body></Body></Grid>). And server returns the tag with the same id and with content of the row’s children. Server must return all immediate children and children of all expanded rows.

ChildPaging can be set to 3 independently of Paging value.

Example of request for children of row ‘xy’ (grid has columns named A,B,C,D,E):

<Grid>

</Grid>

3) Upload of changed data

When automatic updates are set and user changes any data in the grid or when user clicks Save button on control panel, changed data are sent to the server. See XML upload.

The uploaded rows can have set these attributes:

id – this attribute is always set to identify uploaded row.

Deleted – The row have been deleted by user. No other attribute is set.

Changed – Any cell’s value of the row have been changed. The row contain values of all changed cell. The row can also contain the Moved attribute.

Moved – The row has been moved to new position. The Parent and Next attributes specify new position. The row can also contain Changed attribute.

Added – The row is new row. The row contain new generated id. The Parent and Next attributes specify new position. The Def attribute specifies default values.

The row also contain all cell values, that are not the same as default values and are not calculated.

Parent attribute (Added, Moved) can be string for row id or number for page position, Next is string for row id.

When server returns HTTP error or IO.Result < 0, the TreeGrid shows message if provided and does not accept changes. The changes can be send again.

If server return HTTP OK and IO.Result is not set or is >= 0, the TreeGrid accepts all changes – deleted rows are physically deleted and other flags are cleared.

Example of changed data sent to server:

<Grid>

</Changes>

</Grid>