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 <I> attributes LeftVal, MidVal, RightVal. Cell attributes Button, ButtonText.
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 (<I>) are merged by id. Other tags are single and are merged by
tag name.
Pages (<B>) and variable rows (<I>) 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.
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>, <I> 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 <U>. 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:
<Grid><Body><B>
<I id='r1' CanDelete='0'><U N='c1' V='1'/><U N='c2' V='xx'/>
<I id='r11' CanEdit='0'><U N='c2' V='xx-aa' CanEdit='1'/><U N='c3' V='10'/></I>
<I id='r12'><U N='c2' V='xx-bb'/><U N='c3' V='20'/></I>
</I>
<I id='r2'><U N='c1' V='2'/><U N='c2' V='yy'/>
<I id='r21' Calculated='1'><U N='c1' V='10'/><U N='c2' V='yy-aa'/><U N='c3' Formula='c1*2'/></I>
</I>
</B></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:
<Grid><Body><B>
<I id='r1' c1='1' c2='xx' CanDelete='0'>
<I id='r11' c2='xx-aa' c3='10' CanEdit='0' c2CanEdit='1'/>
<I id='r12' c2='xx-bb' c3='20'/>
</I>
<I id='r2' c1='2' c2='yy'>
<I id='r21' c1='10' c2='yy-aa' Calculated='1' c3Formula='c1*2' />
</I>
</B></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 <P Name=> tag.
And next are separated values of attributes in <P List=>. 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>
<P Name='N' List='CanDelete,c1,c2'/>
<P Name='D' List='Calculated,CanEdit,c1,c2,c2CanEdit,c3,c3Formula'/>
</Par>
<Body><B>
<I id='r1'>|N||1|xx
<I id='r11'>|D|0|0||xx-aa|1|10|</I>
<I id='r12'>|D||||xx-bb||20|</I>
</I>
<I id='r2'>|N|1|2|yy
<I id='r21'>|D|1||10|yy-aa|||c1*2</I>
</I>
</B></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 rows attributes and cells are
stored as text node, therefore it needs another parsing on
the server side.
Extra short format stores rows 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.
The text node has this format: |par|attr1|attr2|...|attrN|par|count|attr1-1|...|attr1-N|attr2-1|...|attr2-N|... ...|attrM-1|...|attrM-N, where the first part is the same as in Short format, but next is par name of <P Name=> for
immediate children without any their children, count is count of the children and next is two-dimensional table of
attribute values, where N is from 1 to length of List and M is from 1 to count.
Parameters can now include even id parameter.
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>
<P Name='N' List='id,CanDelete,c1,c2'/>
<P Name='D' List='id,Calculated,CanEdit,c1,c2,c2CanEdit,c3,c3Formula'/>
</Par>
<Body><B>
<I>|N|r1||1|xx|D|2||r11|0|0||xx-aa|1|10||r12||||xx-bb||20|</I>
<I>|N|r2|1|2|yy|D|1||r21|1||10|yy-aa|||c1*2</I>
</B></Body></Grid>
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 rows cells. Under this name are rows 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 rows 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.
Every row <I> has
predefined attribute values in its default row <D>. The values from <D> are used when the row <I>
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 <I> that references to its <D> that references to another
<D>, that ...
If you dont set Def
attribute for any <D> or <I> 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 <I> 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 rows 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 dont 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 dont 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 dont need to edit this file for every new grid.
<Grid> (Root tag, can accept any count
of introduced child tags in any order)
<IO ... attributes with server response ...
/>
<Img ... attributes with images setting ... />
<Cfg ... attributes with grid settings ... />
<Def> ( list of default
settings (tags <D>) for rows)
<D Name='name of default' ... row attributes ... ... cell attributes and values in Internal format ...
>
<U N=column name ... cell attributes and value in DTD format ...
/>
... more tags
<U> for other cells, in DTD format ...
</
D>
... More tags <D> ...
</
Def>
<Par> (list of prepared parameters for short formats)
<P
Name="list name" List="parameter names, comma
separated"/>
</ Par>
<Panel ... Attributes for left row panels settings
... />
<LeftCols> ( Columns fixed to left
side, still visible, can be empty)
<C Name='column name' ... Attributes with column settings ... />
... more tags <C> for other columns ...
</
LeftCols >
<Cols> (Variable
columns, required, must contain at least one column)
<C Name='column name' ... Attributes with column settings ... />
... more tags <C> for other columns ...
</
Cols>
<RightCols
> (Columns
fixed to right side, still visible, can be empty)
<C Name='column name' ... Attributes with column settings ... />
... more tags <C> for other columns ...
</
RightCols >
<Header ... Attributes
with column titles (named as column names) and header row settings in Internal format ...
>
<U N='column name' V='column title' ... attributes
with header row settings in DTD format ... />
... more tags
<U> for other columns, in DTD format ...
</
Header>
<Head> (List of
top fixed rows, always visible, can be empty, rows cannot contain children
rows)
<I ... row attributes ... ... cell
attributes and values in Internal format ... >
<U N=column name ... cell attributes and value in DTD format ...
/>
... more tags
<U> for other cells, in DTD format ...
</
I>
... More tags <I>
...
</
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))
<B> (One page
with rows, if pages are created automatically, can be only one with all rows)
<I ... row attributes ... ... cell
attributes and values in Internal format ... >
<I ... row attributes ... ... cell attributes and values in Internal format ...
>
<U N=column
name ...
cell attributes and value in DTD format ... />
... more
tags <U> for other cells, in DTD format ...
... More tags <I>, with
possible children tags I with possible children and so on unlimited levels of
tree ...
</ I>
... More tags <I> ...
<U N=column
name ...
cell attributes and value in DTD format ... />
... more tags
<U> for other cells, in DTD format ...
</
I>
... More tags <I>
...
</
B>
... More tags <B> 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)
<I ... row attributes ... ... cell
attributes and values in Internal format ... >
<U N=column name ... cell attributes and value in DTD format ...
/>
... more tags
<U> for other cells, in DTD format ...
</
I>
... More tags <I>
...
</
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>
<Grid> (Root tag, can accept any count
of introduced child tags in any order)
<Changes> (list of changed rows)
<I ... row attributes ... ... cell attributes and values in Internal format ...
>
<U N=column name ... cell attributes and value in DTD format ...
/>
... more tags
<U> for other cells, in DTD format ...
</
I>
<Changes/>
</Grid>
<Grid> (Root tag, can accept any count of
introduced child tags in any order)
<IO ... attributes with request settings...
/>
<Cfg ... attributes with grid settings read from cfg
... />
<Filters> (list of filters read from cfg)
<I ... row attributes ... ... cell attributes and values in Internal format ...
>
<U N=column name ... cell attributes and value in DTD format ...
/>
... more tags
<U> for other cells, in DTD format ...
</
I>
<Filters/>
<Body> (List of
all requested pages
or rows)
<B ... attributes identifying page (by Pos) or
row (by id) ... />
... More tags <B>
...
</
Body>
</Grid>
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. Dont use zeroes, if they are
not required, instead of
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
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
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
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] Rows 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
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
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 rows 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 <I>
or <C> tag, depends for what it
is default. Except id attribute.
<Panel> Rows 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
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 <I>.
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
string LeftRC
[] Cell value for other
rows then
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
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.
<B> 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 <B Asum=123.50>,
where A is column name ...
<I> 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>, <B>.
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 <P Name=> 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 targets 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
rows cell value has been changed. Which cell is specified by the cells
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 <I>
only !
string [] CalcOrder [] If row is calculated, there is comma
separated list of column names. In this order are rows 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 <I>
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 cells 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 <I>, <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: <I
id=r1 CanEdit=0><U N=c1 V=xxx/><U
N=c2 V=yyy CanEdit=1/></I>
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: <I
id=r1 CanEdit=0 c1=xxx c2=yyy
c2CanEdit=1/>
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
columns type
string Format [] Overridden
columns format string
string
EditFormat [] Overridden columns format string
for editing
string [] Enum [] Overridden columns list of
values for enum
type. Due performance needs, this can be
used only in <D> and fixed <I> only !
string Formula [] Formula to
compute cells 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 <I>
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 rows Recalc
parameter.
1 Row, 2
Calculated parents, 4 All parents,
8 Immediate children, 16 All children, 256 All table
string sum, count, ... Only
in <B> 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.
<P> 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 rows attribute names. Attribute names always use Internal format
!
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 <B> tags with attributes
but without any child <I> tags.
When any not loaded page is displayed, TreeGrid
downloads data for this page by sending appropriate request. The request for
page (<B> 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><I
id=MyFilter C=10 CFilter=1
E=A AFilter=10/></Filters>
</Grid>
Example of resulted body (grid has also one foot row: <I AFormula=sum() CFormula=sum(D)/2+A/>)
<Grid>
<Body>
<B Count=20 Asum=123 Dsum=312 />
<B Count=20 Asum=453 Dsum=6.5 />
<B Count=20 Asum=1297 Dsum=-
<B Count=12 Asum=145 Dsum=349.7 />
</Body>
</Grid>
Example of request for second page (grid has columns named A,B,C,D,E):
<Grid>
<Cfg SortCols=C,A
SortTypes=0,1/>
<Filters><I id=MyFilter C=10 CFilter=1 E=A AFilter=10/></Filters>
<Body><B Pos=1/></Body>
</Grid>
Example of resulted second page
<Grid>
<Body>
<B Pos=1>
<I id=xa A=10 B=20 C=10.3 D=-
... 18 rows ...
<I id=xu A=3 B=12 C=4.6 D=-
</B>
</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 <B> tag with rows attribute id.
(For example: <Grid>...<Body><B
id=r123/></Body></Grid>). And server returns the <B> tag
with the same id and with content of the rows 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>
<Cfg
SortCols=C,A SortTypes=0,1/>
<Filters><I id=MyFilter C=10 CFilter=1
E=A AFilter=10/></Filters>
<Body><B id=xy/></Body>
</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 cells 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>
<I id=xy Changed=1 A=12/>
<I id=xa Moved=1 Parent=aa Next=xc/>
<I id=xz Added=1 Parent=1 Next= A=3 B=7 C=5.4 D=-
<I id=xg Deleted=1/>
</Changes>
</Grid>