XML - Basics

TreeGrid XML

Description

TreeGrid v5.9

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>

<Cfg ... attributes with grid settings read from cookies (SortCols, SortTypes, GroupCols, GroupTypes, ReSort, ReCalc) ... />

<Filters> (list of filters read from cookies, filter row have cell value attribute and Filter attribute set)

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

</Filters>

<LeftCols> (used in server export request)

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

</LeftCols>

<Cols> (used in server export request)

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

</Cols>

<RightCols> (used in server export request)

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

</RightCols>

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

... More tags ...

</Body>

</Grid>

<IO>

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

On client is this tag cleared between request and response, so this tag contains only those parameters sent by response and none old.

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 on Result value.

int Reload Some data needs to be reloaded. 0 – No reload needed,

1 – reloads body (useful to regenerate pages for server paging when pages was changed on 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.

string ReloadMessage If set in server response, shows confirm dialog before reloading, to confirm this action by user

string UpdateMessage If set in server response, shows confirm dialog before updates changes received from server to grid, to confirm this action by user

It can be used especially when used checking for updates function.

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

It can be sent from server to client to change this parameter.

Remember, the IO is not sent to server if method <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 SaveSession attribute.

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 (Server), 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 (Server) 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 was 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.

If you are not able to do sorting, filtering or grouping on server and you still want to use these features, you can set OnePage attribute (and AllPages=0) to do them partially in actual page.

The data of returned page can contain also defaults (<D> tags). These defaults are added to grid layout, but should be used only for data in the page they were loaded with.

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

The parent row must have set the Count attribute to at least 1. It is better if Count is set to real count of immediate children the row contains. And Expanded must be set “0”, because only not expanded rows can be downloaded asynchronously.

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 server can modify any row(s) and send changes back to grid in the same format.

The uploaded rows can have set these attributes:

id – this attribute is always set to identify uploaded row. There are many ways to set this attribute, see Row’s identification tutorial.

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

Updates

3.2

Added Defaults description

3.6

Excluded from file TreeGridDataFormats.htm

3.8

Updated Extra short format

Added Very large tables section

4.2

Added section Identifying uploaded rows

4.3

Updated XML structure – request

4.4

Added section XML structure – download changes done on server

4.5

Updated XML structure – request

5.0

Renamed file TreeGridDataFormatDescription.htm to TreeGridXmlBasics.htm

Moved tag <IO> from TreeGridDataFormatReference.htm

Removed sections Defaults, Names and ids, Very large tables

Rewritten section Basics

Updated XML structure sections

Added section Layout and data

Added row attribute Color to <Changes>

5.0.6

Added Update attribute to <Changes> tag for data added from server

5.0.7

Updated list of cell attributes accepted as <Changes> from server

Updated XML structure - request