XML - Basics

TreeGrid XML

Description

TreeGrid v5.5

Individual sections are described in references:

Configuration reference (<Cfg>, <MenuCfg>, <Toolbar>, <Pager>)

Columns reference (<Cols>, <LeftCols>,<RightCols>, <C>, <Panel>, <Header> )

Rows reference (<Def>, <D>, <Root>, <Head>, <Foot>, <Body>, , , <Solid>, <Space>, <User>, <Filter>, <Group>, <Search>, <SimplePager>)

Styles reference (<Img>, <Colors>, <Lang>)

TreeGrid uses XML structure to describe all input and output data.

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>
Styles and images settings	<Img>
Background state colors	<Colors>
Configuration of the entire grid	<Cfg>
Default rows and column	<Def>	<D>
Left fixed panel	<Panel>
Left fixed columns	<LeftCols>	<C>
Variable columns	<Cols>	<C>
Right fixed columns	<RightCols>	<C>
Header with column captions	<Header>
Special solid rows	<Solid>	<I> (= <Space>), <Search>, <Group>, <SimplePager>
Top fixed rows	<Head>	<I>, <Filter>, <User>
Variable rows in pages	<Body>	<B> (<B> can contain <I> tags that can contain also <I> tags and so on)
Bottom fixed rows	<Foot>	<I>, <Filter>, <User>
Toolbar	<Toolbar>
Configuration menu	<MenuCfg>
Vertical Pager	<Pager>
Language settings	<Lang>	<Alert>, <Text>, <Toolbar>, <MenuCfg>, <MenuFilter>, <Format>
Short format setting	<Par>
Uploading or downloading changes	<Changes>	<I>
Actual filters in request for data	<Filters>	<I> (instead of Filter, for backward compatibility)

The tags with no link (Def, LeftCols, Cols, RightCols, Solid, Head, Body, Foot, Changes, Filters) can have no attributes. Other tags are described on their links.

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.

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

Layout and data

Input XML data are usually divided to two sources, layout (set by <treegrid> attribute Layout) and data (set by <treegrid> attribute Data). It is not required (all input can be in data and layout empty), but it is good to separate layout and data.

Layout data source should contain structure description of the grid. It is usually static and can be in static XML file.

Usual structure of layout xml is:

<Grid>

<Cfg id=’GridId’.../> Attributes with grid configuration

<Cols> Variable column definition

<C Name=’Col1’ .../> One column with its settings

... Next columns

</Cols>

<Header Col1=’Column 1’/> Columns captions

</Grid>

Data data source should contain only rows and cells. Usually contain only variable rows, but if some fixed rows are editable and their values are uploaded, should be set here too.

Usual structure of data xml is:

<Grid>

<Body>

Row list, in tree rows can be included as children of their parent rows

</Body>

</Grid>

Formats

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

Internal format Preferred 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 all samples and in TreeGrid server.

Example:

</Body></Grid>

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>

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.

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

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 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’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. It can be used also for list of pages when server paging used.

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

Don’t append any empty characters to node texts with this format. Always append enclosing tag immediately after the text.

This is recommended format for list of pages for very large grids with more then 500 pages.

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>

Example for list of pages when server paging used:

<Grid>

<Par>

</Par>

</Grid>

XML structure – download

Basic structure of input XML data. Data sent from server to grid. Used when downloading data for empty grid or reloading all data for the grid or for body.

The input xml should be divided to layout source and data source.

To layout should belong all sections except <Body>.

To data should belong the <Body> tag and optionally <Head> and <Foot> tags.

Gray texts are variants for different formats (internal, DTD, short).

<Grid> (Root tag, can accept any count of introduced child tags in any order, but every tag can be present only once)

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

<Colors ... attributes with cell background color setting ... />

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

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

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

<Solid> (List of special solid rows, these rows can be positioned in more locations in table)

<Group ... group attributes ... /> (one special row with user interface for grouping)

<Search ... group attributes ... /> (one special row with user interface for search and advanced filter)

<SimplePager ... group attributes ... /> (one special row with simple horizontal pager)

<Space ... group attributes ... /> (special row with no special interface, just to display custom html code)

... More tags <Space> ...

</Solid>

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

<Filter ... row attributes ... ... cell attributes and values in Internal format ... > (special row with user interface for filtering rows by column(s))

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

</Filter>

<User ... group attributes ... /> (special row with no special interface, just to display custom html code)

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

... More tags , <Filter>,<User> ...

</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 for other cells, in DTD format ...

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

... More tags ...

... More tags ...

... More tags if data of pages are loaded on demand in server paging ...

</Body>

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

<Filter ... row attributes ... ... cell attributes and values in Internal format ... > (special row with user interface for filtering rows by column(s))

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

</Filter>

<User ... group attributes ... /> (special row with no special interface, just to display custom html code)

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

Data sent from grid to server. Used when uploading changes to server. This format is generated by grid.

Here is described default structure used for <treegrid Upload_Type=’1’/>. For other values can the uploaded XML contain other requested tags.

<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 – download changes done on server

Data sent from server to grid. Used when downloading changes done on server after uploading or checking for updates.

Only these row attributes are supported:

Deleted, Added, Moved, Changed, Parent, Next, Prev

Color

CanEdit, CanFocus, CanDelete, CanSelect, CanExpand

Selected, Expanded

Only these cell attributes are supported:

Value

CanEdit, CanFocus

ClassInner, ClassOuter, ClassEdit, HtmlPrefix, HtmlPostfix, Color, Visible

Type, Format, EditFormat, EditMask, ResultMask

Button, ButtonText, Defaults, Enum, EditEnum, EnumKeys, IntFormat,

Tooltip, Error, Selected

To change id attribute of existing row, return it in NewId attribute.

<Changes> tag can contain Update attribute (default values is 1) that controls what to update after rows are changed/added/deleted/moved. Binary array.

1.bit (&1) – accepts changes, for 1 is row displayed as unchanged, 2.bit (&2) – (re) calculate row, 3.bit (&4) – filter row, 4.bit (&8) – search row (only Select or Mark actions).

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

<Changes Update=’1’ > (list of changed rows)

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

</Changes>

</Grid>

XML structure – request

Data sent from grid to server. It is generated by grid.

Used in request for:

a) body when used server paging (tags IO, Cfg, Filters)

b) specific page when used server paging (tags IO, Cfg, Filters, Body)

c) row’s children when used server child paging (tags IO, Cfg, Filters, Body)

d) server export to Excel (Export_Type=’1’) (tags IO, Cfg, Filters, LeftCols, Cols, RightCols)

e) cell when editing or displaying defaults list (tags IO, Cfg, Filters, Body with attributes id and Col)

<Grid>