TreeGrid data formats

TreeGrid documentation

TreeGrid uses XML structure to describe all input and output data.
Instead of XML there can be used also JSON data format, the tag names are the same as in the XML
The root XML tag is always <Grid>.
Immediate children of <Grid> tag are root tags and describe the parts of the grid:

Tag Description	Tag name	Possible children tags
Communication with server	<IO>
Configuration of the entire grid	<Cfg>
Key and mouse action schema	<Actions>
Default rows	<Def>	<D>
Default columns	<DefCols>	<D>
First left fixed panel column	<Panel>	<C>
Left fixed columns	<LeftCols>	<C>
Variable columns	<Cols>	<C>
Right fixed columns	<RightCols>	<C>
Main Header row with column captions	<Header>
Special solid rows	<Solid>	<Space> (or <I>), <Group>, <Search>, <Toolbar>, <Tabber>
Top fixed rows	<Head>	<I>, <Filter>, <Header>
Variable rows in pages	<Body>	<B> (<B> can contain <I> tags that can contain nested <I> tags and so on, unlimited levels of nesting)
Bottom fixed rows	<Foot>	<I>, <Filter>, <Header>
Toolbar	<Toolbar>
Configuration menu	<MenuCfg>
Columns menu	<MenuColumns>
Print menu	<MenuPrint>
Export menu	<MenuExport>
First vertical Pager	<Pager>
Vertical pagers	<Pagers>	<P>
Gantt zoom	<Zoom>	<Z>
Gantt resources	<Resources>	<R>
Language settings	<Lang>	<Alert>, <Text>, <Gantt>, <MenuButtons>, <MenuCopy>, <MenuCfg>, <MenuFilter>, <Format>
Short format setting	<Par>	<P>
Uploading or downloading changes	<Changes>	<I>
Uploading spanned cells	<Spanned>	<I>
Actual filters in request for data	<Filters>	<I> (instead of <Filter>, for backward compatibility)

The parent tags (Def, LeftCols, Cols, RightCols, Solid, Head, Body, Foot, Pagers, Changes, Filters, Par) can have no attributes.

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

If tags are defined in more files, their attributes and children are merged. Existing attributes are overwritten by new value.
Defaults (<D>), columns (<C>) and resources (<R>) tags are merged by Name attribute.
Fixed and Space 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. To change existing variable rows or add new rows from server use <Changes> tag.

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

Formats

TreeGrid accepts data in XML format. The XML format can use one of four sub-formats: Internal, Short, Extra short, DTD. 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.

The preferred format for standard use Internal format.
For large grids you can use Short or Extra short format.

Internal XML format

Preferred format for standard use

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.
This format is also used in all samples and in TreeGrid server.

This format uses TreeGrid as internal format to store data. So if you use JavaScript API to browse TreeGrid data on client, the data is in internal format.

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.

Internal format example

<Grid<Body> </Body></Grid>

Short XML format

Use for large grids

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.
Cell attribute names in text use Internal format naming (column name + cell attribute name).
For short format you need to define  tag, with list of attributes to use in the short format part. The tag must be defined in XML before it is used!
It is possible to mix short format and internal format, even in one node - some attribute define in node text (short format) and other in node attributes (internal format).

Text node has this format: @par@attr1@attr2@...@attrN
@ is chosen character that is not present in any attribute value (attr1-attrN). You can choose any character you want, but take care to not have it in any attribute value.
par is name of  tag.
attr1, attr2, ..., attrN are separated values of attributes in . Count of attributes (the N) 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.
Don't append any empty characters to node texts. Always append enclosing tag or first child's tag immediately after the text.

 string

Name

Name of parameter. The row points to this name by the first item in its text node list.

 string

List

Comma separated list of row attribute names listed in text node, in this order.
Attribute names always use Internal format (column name + cell attribute name)
For example:  ... @PP@b@c is the same as 

Short format example

<Grid> <Par> </Par> <Body> @P1@@1@xx@P2@0@0@@xx-aa@1@10@ @P2@@@@xx-bb@@20@ @P1@1@2@yy@P2@1@@10@yy-aa@@@c1*2 </Body></Grid>

Extra short XML format

Use for very large grids or for long page list in server paging

It is the shortest and is the fastest 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 attributes, cell values and attributes and attributes of all immediate leaf child rows (rows without children) in text node.
Cell attribute names in text use Internal format naming (column name + cell attribute name).

The text node has this format: @par@attr1@attr2@...@attrN@parchild@childcount@attr1-1@...@attr1-N@attr2-1@...@attr2-N@... ... @attrChildCount-1@...@attrChildCount-N
@ is chosen character that is not present in any attribute value (attr1 to attrChildCount-N). You can choose any character you want, but take care to not have it in any attribute value.
par is name of  tag for the parent node attributes.
attr1, attr2, ..., attrN are separated values of attributes in . Count of attributes (the N) 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.
parchild is name of  tag for all the children and their attributes.
childcount is count of children listed here.
attr1-1, ... attr1-N are attribute values of the first child row, their names are listed it .
attr2-1, ... attrChildCount-N are attribute values for next children.

If the main row has no attributes and first part is empty, just let it empty, like "@@parchild@childcount@..." - two starting separators.

If there are too many children (>1000), it is possible to use another separator to divide children to sections. This speeds up data parsing in IE.
You can use "#@par@attr1@attr2@...@attrN@parchild@childcount@#attr1-1#...#attr1-N# ... #attr100-1#...#attr100-N@#attr101-1#...#attr101-N# ... #attrChildCount-1#...#attrChildCount-N".
The @ is second separator, it is usually added for every 100 children.

Don't append any empty characters to node texts. Always append enclosing tag or first child's tag immediately after the text.

 string

Name

Name of parameter. The row points to this name by the first item in its text node list.

 string

List

Comma separated list of row attribute names listed in text node, in this order.
Attribute names always use Internal format (column name + cell attribute name).
For example:  ... @PP@b@c is the same as 

Extra short format 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>

Extra short format example 2

Use for very large grids or for long page list in server paging

<Grid> <Par> </Par> <Body>#@@B@10000@#P1#43#P2#76#P3#45# ... #P99#65@#P100#23#P101#56# ... #P199#34@#P200#89# ... #P9999#123</Body> </Grid>

DTD XML format

Use only when needed DTD validation

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.

DTD format example

<Grid><Body> </Body></Grid>

JSON format

Use if you are more familiar with JavaScript than with XML

It is shorter than Internal format, but longer than Short formats. It can be slower than other formats for long data, especially in IE7 and below.
It does not require to replace characters < and & by XML entities, it simplifies including HTML code into the data.
In strings must be replaced '\' by '\\' and if required " by \".

JSON format used standard JavaScript Object Notation. The strings must be quoted, the number value need not. The bool values must be set as number 0 or 1.

The root <Grid> tag is defined as not named object { }.
Before and after the root object can be any characters except < and {, for example var MyData = { /* grid data here */ }
The definition can contains standard JavaScript comments - block /*...*/ and line //

The simple root tags <Cfg>, <IO>, <Panel>, <Header>, <Toolbar>, <MenuCfg>, <Pager>, <Filter>, are defined as object named as the tag,

for example <Cfg MainCol='A'/> is defined as Cfg:{MainCol:'A'}

The list root tags <Cols>, <LeftCols>, <RightCols>, <Def>, <DefCols>, <Head>, <Foot>, <Body>, <Solid>, <Pagers>, <Resources>, <Zoom>, <Filters> and <Changes> tags are arrays in [ ],

for example <Body> ... </Body> is defined as Body:[ ... ]

The tags <Cols>, <LeftCols>, <RightCols>, <Def> and <DefCols> are arrays since version 7.0, in previous versions were objects with named children.
The <D> and <C> tags are defined in array as unnamed objects with id or Name attribute and other attributes,

for example: <Cols><C Name='A' Type='Int'/></Cols> is defined as Cols:[{Name:'A',Type:'Int'} ]

Nested  tags (in , or <D>) are defined in array named Items,

for example  is defined as {id:'R1',Items:[{id:'R1-1'}]}

tag without attributes can be defined as array of row objects, with attributes normally with Items tag, for example is defined as [{},{}]
It is not possible to define two objects with the same name! For example you cannot define { Cfg:{id:"grid"}, Cfg:{MainCol:"A"} }
It is not possible to use tag names (except root tags) Header, Filter, Group, Search, Toolbar and Tabber, they must be defined by Kind attribute like <Group ... /> is defined as { Kind:"Group" ... }
The <Lang> tag is defined as object with nested named objects,

for example <Lang><Format ValueSeparator=','/></Lang> is defined as Lang: { Format: { ValueSeparator:':' } }

JSON format example

var Test = { Cfg: { id:"Json", MainCol:"A", Paging:3 }, Cols: [ { Name:"A" }, { Name:"B", Type:"Int", Formula:"1+1" }, { Name:"C", Format:"d.M.yyyy" } ], RightCols: [ { Name:"D", Type:"Date", Format:"hh:mm" } ], Def: [ { Name:"R", CType:"Date" } ], Header: { A:"AAA" }, Head: [ { Kind:"Header", A:"H1" }, { A:"H2" }, { Kind:"Filter", B:3, BFilter:3 } ], Foot: [ { A:"F1" } ], Body: [ [ { A:"R1", id:"R1", Deleted:1, C:'1/1/2000' }, { A:"R2", id:"R2", Added:1, Items: [ { A:"R2-1", Changed:1, AChanged:1 }, { A:"R2-2", Items: [ { A:"R2-2-1", Selected:1 } ]} ]} ], { id:'B2',Count:1 } ] }