TreeGrid XML
Configuration
TreeGrid v5.1
TreeGrid settings and configuration for whole grid is set by <Cfg> tag.
A user can control some settings from TreeGrid configuration menu, which setting will be available you can set by <MenuCfg> tag.
A user can control TreeGrid functions from TreeGrid toolbar, you can set it by <Toolbar> tag.
If paging is permitted, the pager settings can be set in <Pager> tag.
Persistent configuration - cookies
Many TreeGrid settings are automatically saved in client browser and are persistent between sessions. So the server does need to care about it.
The saved settings override the settings in xml, so the settings in xml are used only for the first visit, when no settings are saved in cookies.
When the grid layout is changed, you should increase Version attribute to delete old configuration from cookies and use the new setting from xml.
You can suppress saving configuration completely by SuppressCfg=3 or you can suppress only some setting by appropriate Lap attribute (for example SortColsLap=1 suppresses only sorting).
Configuration is saved under grid id name. Grids with the same id will share their saved settings, but only if cookie or persistent storage is shared between those pages.
You can control cookie setting also by API properties Grids.CookieExpires and Grids.CookieParam.
The settings are saved to cookies by default. Because of cookies size limit (4096 B) you can save it to browser persistent storage instead. The persistent storage is supported only by IE 5.0+ and Firefox 2.0+. See PersistentCfg attribute.
To cookies (or persistent storage) is saved by default:
For grids with more columns to decrease cookie size of saved data, you should name columns as short as possible, the best to up to three characters.
To cookies (or persistent storage) you can also save:
Take care about the length of saved data, especially if you are saving to cookies and not to persistent storage. You can usually permit saving of these setting only for small grids.
<Cfg>
Configuration and settings for whole grid.
Root tag placed in <Grid> ... <Cfg/> ... </Grid>. Permitted only one per one XML data source. Cannot contain child tags, but only attributes.
string id [...] (both letters lowercase!) Unique ID of created TreeGrid on the page
Under this name will be stored configuration to cookies or persistent storage.
By this name can be TreeGrid accessed from JavaScript code, as Grids[id].
It is also ID of <TABLE> tag where grid is rendered. This tag replaces <TreeGrid> tag.
Default value is TableX, where X is grid index, from 0, in order grids are created
int Version [0] Version of data. Grid loads cfg from cookies only if version is the same as saved.
Change this number whenever data structure (especially number of columns, column names and types) changes to delete old configuration saved to cookies.
string MainCol [] Name of main column with tree. Let it empty for pure grid without tree.
In this column will be displayed the tree with expand / collapse icons. Only one main column is possible to be in grid.
If set, the column must exist (must exist the tag with this name <C Name= />)
You can page root rows in grid, the pages can be displayed in large vertical pager or in simple horizontal pager.
For other possibilities of paging see paging tutorial.
See also examples in downloadable trial, for your server side script. For server paging see Ajax table with server paging and export example.
For paging child rows in tree, see paging in tree.
int Paging [0] Method of paging used. This paging is done only for root rows, it is the 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 0 - None but with pager enabled.
For AllPages = 0 is the same as 2 - 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 at least 500ms (see PageTime).
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, filtering, grouping and searching.
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 needed to be online.
See server communication for server paging.
For server application you can use TreeGrid.dll/so.
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.
int PageLength [20] Average count of rows in page. For client paging there are all pages created to contain this number of rows (except the last).
For server paging it determines height of page it is default value of <B> Count attribute.
Exact count of rows in pages can differ due to adding or deleting rows or in last incomplete page.
This value is returned as part of result of count ( ) function in formulas.
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.
In TreeGrid server is this parameter used to set count of rows in page.
int PageLengthDiv [1] Page length divider for very large tables (>250 000 root rows) with AllPages==1 and FastPages>0.
This divides PageLength to display smaller non rendered pages.
Set this attribute to your rows count / 200 000. For 1 000 000 set it to 5. In this case set PageLength to be enough, for example to 100.
This attribute is used due problems in some browsers with too high tags (in IE there are problems with tags higher then 5M pixels).
int RootCount [] Count of all rows in root. Used to compute Count parameter of last page when server paging used and pages have not Count attribute set.
bool NoPager [0] If set to 1, grid does not render pager. The pager cannot be shown by user. Also does not pre-calculate page names.
TreeGrid server does not generate page names and does not send page names to client.
int FastPages [0] For large tables (> 50 000 root rows). Set it to default value of 100 to speed up rendering of large tables.
Bigger value speeds up initial rendering, but can slow down TreeGrid usage and vice versa.
int PageTime [500] How long (in ms) must be page visible (by scrollbars) before it loads data or renders (for AllPages=1).
int OnePage [0] If set, sorts, filters or groups rows only in actual page. Only when AllPages = 1 (one page visible at a time).
Bit array: 1. bit (&1) sorting, 2. bit (&2) filtering, 3. bit (&4) grouping. Set to 7 for all actions done at one page only.
Use this attribute only for server paging (Paging=3) if you are not able to do sorting, filtering or grouping on server.
There are few advices how to use TreeGrid for grids with more then about 10 000 root rows. It is not related to huge trees, the tree can handle unlimited count of rows.
All these advices are used only to speed up rendering and using TreeGrid, they do not concern about handling of such amount of rows, TreeGrid can handle unlimited rows count.
For grids with more then 10 000 rows always use server paging (<Cfg Paging=3/>). Your server script must provide data for grids pages. You can use TreeGrid server component to help you with this task. The TreeGrid server can do nearly all functions required in server paging as creating pages according to sorting and filter settings. Also pre-calculates aggregate functions. Saves changes returned from client. And more.
For grids with more then 50 000 rows use Extra short format to send list of pages. The TreeGrid server does it automatically.
If possible, use all page of the same width and dont return rows count for every page, but set <Cfg PageLength and RootCount /> attributes. The TreeGrid server does it automatically.
Also increase <Cfg PageLength/> attribute according to count of columns in your grid. For 1 5 columns use 100, for 5-10 use 50 and for more columns use 30.
Also use <Cfg FastPages/> attribute. Set it to value about 100. Higher value speeds up initial rendering but can slow down work with the grid and vice versa.
For grids with more then 250 000 rows and all pages visible (<Cfg AllPages=1 />) use <Cfg PageLengthDiv/> attribute to reduce page size and all grid scroll height because some browsers have problems with too high scroll height. IE has problems with editing in tag with scroll height higher 5M pixels (about 277 000 rows of standard height). Mozilla has scrolling problems from about the same height.
Set PageLengthDiv to your rows count / 200 000. For 1 000 000 set it to 5.
For grids with more then 2 000 000 rows display only one page at once by using <Cfg AllPages=0 />. If you use configuration menu, set <MenuCfg AllPages=0/>. Also to suppress loading defaults for AllPages use AllPagesLap=1.
If you use TreeGrid server, remember that for such amount of rows it allocates about 400 MB memory. Of course, it does concern client browser memory consumption; it is independent on row count.
In tree you can render or download children on background when their parent is being expanded at first time.
The parent row must be collapsed to be paged. You have to set its Expanded attribute to 0.
To send all rows collapsed you can set for default row named R: <Def><D Name=R Expanded=0/></Def>
The maximum of children in row is limited, because all the children are rendered at once. By default there can be 300 children. If the count of children overruns this limit, the children are divided to newly created rows. See rows attribute MaxChildren.
In tree you can of course use also standard paging for root rows.
int ChildPaging [2] Method of paging of children rows in tree. How will be rendered or downloaded children rows after parent is expanded for the first time.
0 None. All rows, including all children are rendered on start. This means slow start and fast use.
2 Auto (Client). 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 (Server). Children of collapsed row are downloaded at first expand. Server must be able to send the children of the row.
Remember, if you send parent rows expanded (what is default state), the paging will not be applied.
See server communication for server child paging.
For server application you can use TreeGrid.dll/so.
bool EmptyChildPages [0] Used when the count of children exceeds MaxChildren value and in row are created children pages.
If the child page row shows all values of its parent [0] or shows only value in main cell [1].
Creating and generating row id
For possibilities of row identification on server, see id tutorials.
string [] IdNames [id] Comma separated list of attributes fully identifies the row, these attributes are like unique primary key in database table.
The list can contain column names, attributes like Def or any user defined row attribute.
The last attribute in list is specific, because its value is generated automatically for new rows from IdChars, IdPrefix and IdPostfix.
The row id attribute is automatically created from the attribute values from the list, separated by $.
If any value contains $, it is replaced by _.
If the list item is editable column and its value is changed there is possibility that the id will not be unique.
In this case the last attribute value is re-generated (before changes are sent to server).
After changes are sent to server, the row id is updated according to changed attribute (column) values.
When new row is added, the last attribute value is generated to ensure the id to be unique.
Remember, if the list contains more items the last attribute must not be id, because the row id attribute gets the result.
bool FullId [0] If set to 1, row id contains its parent id as prefix, separated by $.
For example if parent id is A$3, the row id can be A$3$B$7.
When row is moved to another parent, the last attribute from IdNames can be regenerated to ensure id to be unique.
bool AppendId [0] If set to 1, the generated id (the last attribute in IdNames) is appended to existing value.
When new row is added, the cell gets default value for cell and if it is not unique, new id is appended to value.
When user changes the id cell (the last from IdNames), to the end of new value is appended id if the value is not unique.
string LastId [] Last (maximal) id when used server paging, because TreeGrid cannot generate new ids if does not know all row ids.
Can be used only when IdNames contains only one item!
New generated id (of new added row) will get next 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 new id. In this order.
Example: if the last id was ab the next id is ac, for az is ba for zzz is ____
int NumberId [0] Set it to 1 for generating number ids. And set IdChars=0123456789.
This attribute says, that id cannot start with count of NumberId characters from start of IdChars.
string IdPrefix [] This string is inserted before generated new id (before the last part).
string IdPostfix [] This string is appended at the end of generated new id.
int IdCompare [0] How to compare ids if they are unique. Bit array, 3.bit (&4) case insensitive compare. Other bits reserved.
Remember if used case insensitive ids, the IdChars cannot contain both type letters (A, a).
int Editing [1] How values of grid can be edited, 0 never, 1 yes, according to other settings, 2 preview (read only) mode
int Selecting [7] How rows and/or cells can be selected, bit array
1. bit (&1) if selecting is permitted
2. bit (&2) - row can be selected by Ctrl + click,
3. bit (&4) rows / cells range can be selected by Shift + click. The range is between focused cell and clicked cell.
If focused row / cell is selected, the whole range is unselected, otherwise is the whole range selected
4. bit (&8) individual cells can be selected, if set, grid supports selecting cells instead of whole rows
Row with selected only some cells has Selected=2 and selected cells have its attribute Selected=1
5. bit (&16) rows / cells range can be selected by Ctrl + mouse dragging. The range is between focused cell and actual cell.
If focused row / cell is selected, the whole range is unselected, otherwise is the whole range selected
6. bit (&32) if set, whole selection is cleared after focus change
bool Deleting [1] Rows can be deleted
bool Adding [1] Rows can be added
bool Sorting [1] Rows can be sorted
bool Dragging [1] Rows can be moved by mouse
bool DragCopy [0] If set to 1 in source grid when dragging rows between two grids, rows are copied instead of moved.
bool DropFixed [0] If set to 1, the grids head section accepts dragged rows as the first row and foot section accepts rows as the last row.
bool Copying [1] Rows can be copied by toolbar button (+).
int Pasting [3] How cells are pasted from clipboard (from TreeGrid, MS Excel and so on), bit array.
Data being pasted are expected in format: Rows are separated by CRLF or CR or LF. Cells are separated by tabulator.
1. bit (&1) - if set, data are pasted to selected rows, if any
2. bit (&2) if set, data are pasted to actually focused row, if any.
If both 1. and 2. bit are set, the data are pasted to selected rows and if no row is selected, to actually focused row.
3., 4. bit (&12) how are data pasted to focused row.
0 To focused row only, if the pasted range contains more rows, an alert is displayed
4 To focused row and to next rows (if in tree, in the same parent only).
8 To focused and next rows are added after the focused row
12 Inserts new rows in front of the focused row.
5. bit (&16) If set, always pastes cells from cursor position (applies to columns, not rows)
6. bit (&32) If set, always pastes from the first column.
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)
int ResizingMain [0] If set, main tag can be resized by user by dragging by bottom right edge of toolbar.
= 1 resizes vertically (height), 2 resizes horizontally (width), 3 resizes both sides
Extents of main tag are saved to cookies, to suppress it set ResizingMainLap=1.
bool SuppressMessage [0] Grid is silent, does not display messages
bool Silent [0] If set to 1, the grid produce no sounds
string [] SortCols [] Array of column names (comma separated), according to them are rows sorted, in this order. Max 3 columns.
If the first column(s) in this array have set Visible=0 and CanHide=0, an user cannot change sorting for these columns
and they will stay the first forever use this case to predefine some sorting behavior.
int [] SortTypes [] Array of sort types (comma separated) for every column in SortCols, bit array: bit 1 (&1) 0 DESC, 1 ASC, other bits reserved
bool SortLap [0] When set to 1 does not load sorting settings (SortCols and SortTypes) from cookies and always uses the attributes above.
bool Sorted [0] Sorting is enabled by user (to not load from cookies set SortedLap=1)
bool AutoSort [0] Row is sorted if value is changed after edit (to not load from cookies set AutoSortLap=1)
string [] GroupCols [] Array of column names (comma separated), according to them are rows grouped, in this order.
Remember, to control grouping you should place to fixed or solid rows one row with Kind=Group.
int [] GroupTypes [] Array of grouping flags (comma separated) for every column in GroupCols, bit array:
bit 2 (&2) - case insensitive localized comparing, see also CharCodes property
bit 3 (&4) 1 = case insensitive comparing
bit 4 (&8) 1 = ignore white chars given by WhiteChars attribute.
bit 5 (&16) do not create grouping row for empty values
bit 6 (&32) do not create grouping row for single values.
bit 7 (&64) do not create grouping row for zero values.
other bits reserved
string GroupMain [] Column where to show tree when rows are grouped. Used only for plain tables; for grids is used always MainCol.
See also GroupMain in <D> row.
bool GroupLap [0] When set to 1 does not load grouping setting from cookies and always uses the attributes above.
int GroupFlags [0] Various settings for grouping, bit array. It is not saved to cookies.
1. bit (&1) If set to 1 refreshes Toolbar after grouping or ungrouping to show another set of buttons related to tree or given grouping. Useful for plain tables with grouping enabled.
2. bit (&2) If set to 1 restores sorting state after grouping that was before grouping
3. bit (&4) If set to 1 when grouping always sorts according to main column ascending
4. bit (&8) If set to 1 when grouping always sorts according to main column descending
string UngroupAction [] Action run when grid is ungrouped to change some settings. See also <D Group=1 Action=/>.
The action has access to Grid property. For example Grid.Editing=1 permits editing when grid is ungrouped. This attribute is not saved to cookies.
Searching and advanced filtering
string SearchExpression [] Expression to search or advanced filter expression.
The expression syntax depends on SearchMethod used. By default is the method chosen automatically according to expression syntax, see SearchMethod.
1- Search like Google expression has similar syntax to searching at www.google.com.
word word words separated by space - finds all cells or rows containing all the words
Phrase with spaces in double quotes quoted words are searched together as whole phrase.
-word word or phrase with hyphen prefix - finds all cells or rows without this word or sentence
word OR word words or phrases joined by OR (uppercase only) - finds all cells or rows containing at least one of them
# finds all empty cells
Example: London Paris OR Nice above sea level
2 - Search by expression expression has similar syntax to TreeGrid formulas and JavaScript code, but it is not in TCalc content, so it cannot use TreeGrid calculation functions like sum().
The expression has the JavaScript syntax, operators (==, !=, <, <=, >, >=, &&,||, !, parenthesis, function calls), if fact it can contain nearly every JavaScript code.
Cell values from the row are referenced by column captions (not names!);
these names can be predefined by column SearchNames attribute, especially if the column caption contains spaces.
The column captions are referenced case insensitive.
String constants can be in double or single quotes or can be without quotes at all.
Not quoted strings must not interfere with column captions and other reserved words
For comparing equality can be used both == and = operators. For comparing inequality can be used both operators != and <>
For operators &&, || and ! can be used word (case insensitive) equivalents, defined in Text.xml, in <Lang><Text And= Or= Not=/></Lang>
By default can be used instead of && => and, || => or, ! => not
Remember, the operator && / and have higher priority then || / or
Here can be used special string operators to check if one string contains another string, starts with the string, ends with the string.
The operator names are defined in Text.xml, in <Lang><Text Starts= Ends= Contains=/></Lang>
By default is Contains="contains,has" Starts="starts,starts with,starts by,begins,begins with,begins by" Ends="ends,ends by, ends with"
Example: (Name starts James or Name = John) and Age >20 and Age <40
string SearchAction [] Name of search action currently applied in grid, can be one of Filter, Select, Mark, Find or empty
Filter Hides all rows that dont match the SearchExpression in method and other search options set.
The filter works in the same way as filter by <I Kind=Filter ... />
You can control the filter also by <Cfg> attributes FilterEmpty and StandardFilter and rows CanFilter.
If row cannot be searched through or filtered by its settings, it is not hidden.
Select Selects all rows that match the SearchExpression in method and other search options set.
Selects only whole rows, cannot select only cells.
If row cannot be searched through it is not selected.
Mark Colors all rows or cells (see 1.bit of SearchType) that match the SearchExpression in method and other search options set.
The rows or cells are colored by the Found colors.
After change some search setting like SearchExpression and do Mark action again, new color for coloring is used (Found1->Found2->...)
The color is restored to Found1 after any other search action is done (Filter,Select,Find,Clear)
If row or cell cannot be searched through it is not colored.
Find Focuses the first row or cell that match the SearchExpression in method and other search options set.
By default searches from the next / cell from actually focused (like Find next), for other possibilities see SearchType.
If row or cell cannot be searched through it is not focused.
int SearchType [176 (16+32+128)] Various flags for searching, bit array
1. bit (&1) Now used only for SearchMethod = 1 (Search like Google)
for 0 searches in rows, thus all the cells in one row together must fulfill the SearchExpression.
For example if you search London AND 1000 at least one cell in row must contain London and other (or the same) the 1000.
For Filter or Select action the row is filtered (visible) or selected if it fulfills the SearchExpression.
For Mark action the whole row is colored.
For Find action the whole found row is focused (does not change focused column), for next match it continues in next row.
for 1 searches in cells, thus every cell to find must fulfill the SearchExpression.
For example if you search London AND 1000 the found cell must contain both London and 1000.
For Filter or Select action the row is filtered (visible) or selected if at least one cell is found.
For Mark action only the found cell is colored.
For Find action focuses the first cell found, for next match continues in the same row in next cell.
2. bit (&2) Now used only for SearchMethod = 1 (Search like Google). For 1 and any action it searches also in hidden columns.
3. bit (&4) For 1 does case sensitive search and comparing
4. bit (&8) For 1 and action Select or Mark it expands parents of the found row to be visible in tree.
5. bit (&16) For 1 and action Find after it reaches the end of grid starts from beginning and continues to focused cell, see also 6. bit (&32).
6. bit (&32) For 1 and action Find after it reaches the end it asks if to continue from beginning, only if set 5.bit (&16).
7. bit (&64) For 1 and action Find searches always from beginning, for 0 searches from focused cell.
8. bit (&128) For 1 and action Find alerts message Not found if no result is found.
int SearchMethod [0] Method of search
0 Automatic method selection automatically chooses 1 or 2 method according to used expression
2 (expression search) is chosen if the expression contains one of these characters ( ) = ! < >
or if the expression contains at least two column names or one column name and one keyword of these: contains, ends, starts
otherwise is chosen 1 (Search like Google)
1 - Search like Google
2 Search by expression
string [] SearchDefs [] Comma separated list of default row names. Only row with the Def attribute that is listed will be searched through.
The row with not listed Def will be: a) for Filter action never hidden, b) for other actions never found / colored / selected
If SearchDefs is empty, all rows will be searched through.
string [] SearchCols [] Columns names (not captions!). Only cells in given columns will be searched through. Used only for SearchMethod = 1 (Search like Google)
If SearchCols is empty, all cells will be searched through.
Result depends also on SearchType, 2. bit. If column has CanSearch=0, it cannot be searched through at all.
bool SearchLap [0] When set to 1 does not load searching setting from cookies and always uses the attributes above.
string SearchDateFormat [] Format to convert strings to date when used in advanced filtering (SearchMethod=2). It is not saved to cookies.
This configuration can be controlled by user in configuration menu or toolbar
What attributes to permit to change by user see <MenuCfg>.
To not load the attribute value from cookies, set its appropriate ...Lap attribute to 1, for example AutoUpdateLap=1 or HoverLap=1
bool Calculated [1] Calculating is enabled by user. If disabled, formula cells are not re-calculated after change
bool AutoUpdate [0] If true, after any change, sends changed data to server like user clicked to Save button on toolbar.
Can be used only for AJAX communication, when Upload_Url is set.
bool ShowDeleted [1] Shows deleted rows (in red).
If set to 1, deleted rows are still visible and can be undeleted. When deleting, no confirm message is displayed.
If set to 0, deleted rows are hidden and cannot be undeleted by user. When deleting row, a confirm message is displayed.
int Hover [2] What blinks under mouse cursor. 0 nothing, 1 border (caption, panel, ...), 2 border and cells
The value of 2 can slow down large grids on slow computers.
int SortIcons [1] How sorts and shows icons. 0 hides icons and sorts ascent by click to cell, descent by double click, 1 shows icons and sorts ascent by click to cell, descent by double click,
2 sorts by click to icon only, bottom icon ascent, upper icon descent, 3 shorts by click to cell, bottom part ascent, upper part descent.
To change direction meaning set ReversedSortIcons attribute.
bool ShowDrag [1] Shows dragged object under mouse cursor. The dragged row(s) or moved column(s).
bool HidePanel [0] Rows left panel (with select and delete buttons) 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.
Set those attributes to not load the setting value from cookies and use the predefined in xml data.
bool ColsLap [0] Overrides saved configuration for column positions and widths, if set, the mentioned settings from cookies is ignored.
bool ColsPosLap [0] Overrides saved configuration for column positions, if set, the mentioned setting from cookies is ignored.
bool FilterLap [0] Overrides saved configuration for filters, if set, the mentioned setting from cookies is ignored.
bool PagerWidthLap [0] Overrides saved configuration for pager width, if , the mentioned setting from cookies is ignored.
bool CheckUpdatesLap [0] Overrides saved configuration for Interval for checking updates.
Attributes for controlling what, how and where will be saved
int SuppressCfg [0] Does not use any client settings in cookies (0 uses, 1 does not load, 2 does not save, 3 nothing)
If set to 4 does not load or save configuration from cookies, but still accepts and returns configuration in Cookie attribute.
int PersistentCfg [0] If set to 1 or 2 uses persistent browser cache instead of cookies for saving configuration.
The persistent cache can store much more data, at least one megabyte (shared among all pages).
This persistent cache is only in IE (userData behavior) and Firefox 2.0+ (globalStorage property).
Due bug in Firefox 2.0, the persistent cache is not used when running locally on protocol file://.
0 use cookies, 1 use persistent cache if available otherwise use cookies, 2 use only persistent cache, if available.
int SaveExpanded [0] If set to 1, saves expanding / collapsing state of all rows to cookies. All rows must have set id attribute.
If set to 2, saves the state of only rows that differs from their default rows Expanded state.
Remember, cookies are limited to 4096 bytes for the whole page, so use this setting only for very small tables or use PersistentCfg.
and also use the smallest ids as possible (the amount of space is used: id+1 bytes per row)
bool SaveSelected [0] If set to 1, saves Selected attribute of all rows to cookies. See restrictions at SaveExpanded.
bool SaveValues [0] If set to 1, saves all changed values of all rows to cookies.
Remember, cookies are limited to 4096 bytes for the whole page, so use this setting only for very small static tables or use PersistentCfg.
and also use the smallest ids and column names as possible (the amount of space is used: (name+1)+id+value+2 bytes per row).
Also use it only for number tables or restrict strings by edit mask.
string[] SaveAttrs [] Comma separated array of pairs row_id, attribute_name. Saves all these attribute/cell values to cookies. To save cell value, just specify its column name (as even value).
If row_id (the odd item) is empty, saves attribute of Cfg. You can also save any your custom row or grid/Cfg attribute.
For example R1,Col1,R6,Col7CanEdit,,Adding = saves values R1.Col1 and R6.Col7CanEdit and Cfg.Adding
! Remember, the configuration from cookies is loaded after layout xml (if present) is loaded, so to save attributes from rows loaded in data xml is impossible !
bool SaveAttrsTrim [50] By default are all values saved by SaveAttrs trimmed to 50 characters, because the size of cookie is small, you can change the predefined length here
string SaveSession [] If set to id of hidden input, it stores Session attribute value to this input to be persistent for page reloading.
Only some browsers preserve input values for page reloading.
The hidden input must be placed to page in HTML and not by JavaScript. Also dont place it into TreeGrid main tag.
If set to 1, saves Session attribute value to cookies. It saves Session regardless of values of SuppressCfg and Version.
This attribute should not be set in data xml, only in layout.
string Cookie [] Whole configuration in string as it was saved to cookie. Use this attribute to get or return configuration saved on server by Upload_Type=4096.
If this attribute is set, the configuration is loaded from it instead of cookies.
Loading configuration is still affected by SuppressCfg (see also its value 4), Version and other such settings.
Remember, this setting must not be modified, it must be completely the same as the setting returned by grid when saving.
To send configuration to server by API you can use such code (if you used AJAX for uploading):
grid.Communicate2 (grid.Data.Upload, grid.GetXmlData(4096));
int MaxHeight [0] If set, updates height of main tag to fill the whole window. It does not modify grid height, see ConstHeight.
If the main tag is placed inside another tag with overflow or absolute position, it resizes it only to fill its parent tag.
It cannot be used when ResizingMain is set to 1 or 3.
Is possible to have more grids on page (vertically) with MaxHeight set, in this case their height is computed as ratio of their MaxHeight value.
For pages with too complex layout is this attribute ineffective or can cause unwanted grid shrinking,
in this case you have to define your own JavaScript code called on page resize that resizes main tag to fill requested area.
bool ConstHeight [0] If set to 1, updates height of grid to fill whole main tag. It does not modify main tag height, see MaxHeight.
In fact it adds to grid new special row <Space RelHeight=1 Space=2/>. This row is positioned between body and foot section.
To better control this space, you can add this <Space> row by yourself instead of using ConstHeight attribute.
If grid already contains some row with RelHeight attribute set, the ConstHeight attribute is ignored.
! If you use ConstHeight, do not set height of main tag in percent !
bool MaxWidth [0] If set to 1, updates width of main tag to fill the whole parent tag or body. It does not modify grid width, see ConstWidth.
It cannot be used when ResizingMain is set to 2 or 3.
Use it to fill parent tag width if there are more tags with float style attribute, otherwise use standard CSS style width:100% instead of this attribute.
bool ConstWidth [0] If set 1, updates width of grid to fill whole main tag. It does not modify main tag height, see MaxWidth.
In fact it adds to grid new column <RightCols><C Name=_ConstWidth RelWidth=1/></RightCols>. It is positioned as the first right fixed column.
To better control the grid width, use RelWidth attribute of existing columns instead of using ConstWidth attribute.
If grid already contains some column with RelWidth attribute set, the ConstWidth attribute is ignored.
Those attributes are only to help developers and should not set in released applications
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 AlertWidths [0] If set to 1, alerts all column widths after grid render. Use to find out actually set widths to set predefined widths in data.
Helping setting for grids in master / detail relationship. The main attribute to relate grids is rows attribute Detail.
bool Detail [0] Detail grid attribute. Set it to true for grid used as detail grid.
To show master rows children in detail grid you need to set its Detail attribute.
int DetailOn [0] Master grid attribute. When to show data in detail grid.
1. 3. bit (&7) 0 disabled, 1 on focus to row, 2 on click to row, 3 on double click to row
4. bit (&8) if set, does not refresh detail grid if already displays actual (focused / clicked) row.
int DetailExpand [0] Master grid attribute. What to when expanding row marked as detail.
0 show it in detail grid only, 1 expand it only,
2 show it in detail grid and also expand it the children will be on two places in two copies and changes will be done to both.
Handling empty numbers and dates
string EmptyNumber [] A value displayed and returned if cell type Int or Float contains empty value.
By default this attribute is not set at all it means that all empty values are displayed and formatted as 0
and TreeGrid does not differ between empty values and zeroes.
If this attribute is set to any value, even to , this value is displayed for all empty values
and TreeGrid differs between empty values and zeroes except these few cases:
when sorting; when filtering with operator >=, >, <, <=;
! Remember, when you are using calculations, you can get this string as input value to formula, so you need to adapt your formulas for this case.
string EmptyDate [] A value displayed and returned if cell type Date contains empty value.
By default this attribute is not set at all it means that all empty values and zeroes (GMT 1/1/1970 00:00:00) are displayed as empty.
and TreeGrid does not differ between empty values and zeroes takes them as zeroes.
If this attribute is set to any value, even to , this value is displayed for all empty values and zeroes are displayed as standard date
and TreeGrid differs between empty values and zeroes (GMT 1/1/1970 00:00:00) except these few cases:
when sorting; when filtering with operator >=, >, <, <=;
string EmptyEnum [] A value displayed and returned if cell type Enum contains empty value.
By default this attribute is not set at all it means that all empty values are displayed as the first item from list.
If this attribute is set to any value, even to , this value is displayed for all empty values.
bool StaticCursor [0] If set to 1, grid does not hide cursor when looses focus after click outside grid
bool ShowVScrollbar [0] If set to 1, the vertical scrollbar is still visible.
Set it to 1 if there are many columns with RelWidth and showing / hiding vertical scrollbar slows down the grid, especially for tree.
bool NoScroll [0] If set to 1, does not use TreeGrids scrollbars. In this case are used scrollbars of main tag or browser window.
If set to 1, you can control scrollbars by setting style overflow of main tag, set it to visible to resize main tag to show whole grid
or set it to auto or scroll (and set height and width of the main tag) to use scrollbars of main tag.
bool NoHScroll [0] If set to 1, the TreeGrid always resizes horizontally the main tag to show the entire grid.
bool NoVScroll [0] If set to 1, the TreeGrid always resizes vertically the main tag to show the entire grid.
bool HideRootTree [0] Hides the first line in tree (root items are without any line)
bool NoTreeLines [0] If set to 1, it does not show connecting lines in tree, just expand / collapse buttons
bool ReversedSortIcons [0] If set to 1, the sort icons for ascending and descending sorting are swapped
int MaxSortColumns [0] Maximum columns according to can be grid sorted (1-3). It affects only sorting icons.
string PrintPrefix [] HTML code added in front of TreeGrid when printing
string PrintPostfix [] HTML code added behind TreeGrid when printing
string PrintCSS [] Url of CSS style sheet for printing used instead of default CSS style sheet
string ExportPrefix [] HTML code added in front of exported TreeGrid data when it is exported by simple export
string ExportPostfix [] HTML code added behind exported TreeGrid data when it is exported by simple export
string [][!] Top [] Section displayed above the grid, can be used for example for rounded corners. Two dimensional array.
For every item displays one <DIV> tag with settings set the item every item is comma separated array of settings.
One item has this layout: [margin-left, border-left width, border-left color, background, height, border-right width, border-right color, margin-right]
Size values are in pixels but without suffix px, color values are in #RRGGBB.
Example of rounded corners with five pixels height and one pixel border:
Top='|5,0,,1,#E0E0E0,0,,5|3,2,#E0E0E0,1,#F0F0E0,2,#E0E0E0,3|2,1,#E0E0E0,1,#F0F0F0,1,#E0E0E0,2|1,1,#E0E0E0,2,#F0F0E0,1,#E0E0E0,1'
string [][!] Bottom [] Section displayed bellow the grid, the same structure as Top attribute.
Example of rounded corners with five pixels height and one pixel border:
Bottom='|1,1,#E0E0E0,2,#F0F0E0,1,#E0E0E0,1|2,1,#E0E0E0,1,#F0F0F0,1,#E0E0E0,2|3,2,#E0E0E0,1,#F0F0E0,2,#E0E0E0,3|5,0,,1,#E0E0E0,0,,5'
int OverflowDialog [4] How to overflow dialogs and messages and where to display them, if they cannot get into the main tag. Bit array.
! Attention, to preserve compatibility with TreeGrid version < 4.7, the default value for this attribute should be 7.
1.bit (&1) - for 1 it overflows configuration menu and columns menu to main tag extents. It also affects ShowMessage function.
2.bit (&2) for 1 it overflows rows dialog and menu to main tag extents. It also affects ShowDialog function.
3.bit (&4) for 1 it moves rows dialog and menu to better position inside main tag. It also affects ShowDialog function.
int MaxMenuHeight [0] Maximal height in pixels of all pop-up menu dialogs, higher menus will be overflowed with vertical scrollbar.
int ZIndex [255] z-index style setting for all absolutely positioned grid objects like dialogs, menus and drag objects.
Set it to higher value if grid is placed to html tag with higher z-index value and these objects are not visible.
bool Prepared [0] You can prepare input xml data for grid to speed up loading grid. If input xml data are prepared, set in them Prepared to 1.
In prepared xml data:
date-time must be values set as count of milliseconds from 1/1/1970 00:00:00.000
float values must be set in standard English format, without leading zero, but with leading zero for values between -1 and 1.
must not be used Enum type in cell in variable row, only for whole column or for fixed row or for default row
string Focused [ ] Id of focused row. When used server paging, it can be id or position of page with focused row and FocusedPos is used too.
Use it to automatically focus some cell after data are initially loaded.
This attribute is also sent to server in request for data.
int FocusedPos [0] Position of focused row at page when used server paging.
string FocusedCol [] Name of focused column
bool IgnoreFocused [0] Ignores attribute Focused sent from server. Has sense especially when used TreeGrid server library.
int DateStrings [0] If set to 0 (default), Date values are uploaded as numbers (milliseconds from 1/1/1970),
If set to 1, Date values are uploaded as strings in English format (M/d/yyyy HH:mm:ss).
If set to 2, Date values are uploaded as strings in JAVA format (yyyy-MM-dd HH:mm:ss).
int EnumKeys [0] Set it to 1 to use columns EnumKeys attribute for converting enum values.
If set to 2 and columns EnumKeys attribute does not exist, uploads enum text value (from Enum array) instead of its index.
Use value 2 especially for related enums where columns EnumKeys cannot be used.
bool ReSort [0] Output attribute only. This attribute is filled in Request XML as request for re-sorting grid after sorting has been permitted by user.
bool ReCalc [0] Output attribute only. It is filled in Request XML as request for re-calculating grid after calculations have been permitted by user.
bool VarHeight [0] If set to 1, the rows can have different height. This height is automatically computed according to highest cell in the row.
Set it to 1, when you want to use multi line textarea (cell type Lines) or you include to cells various HTML code.
Variable rows height is not recommended to use with Paging (Child paging is mostly ok).
Setting to 1 can slow down grid rendering and also grid images may not fit in rows.
int RowHeight [18] Average height of row if VarHeight is 1. This value is used to pre-compute page height and some other settings.
bool NoFormatEscape [0] If set to 1, you can use HTML tags in columns Format string, in prefix and postfix for text and anywhere for numbers.
bool InEditMode [1] If set to 1, the edit mode is run when user clicks any editable cell
If set to 0, the edit mode is run only when user clicks to focused editable cell or double clicks some editable cell.
bool AcceptEnters [0] If set to 1, pressing Enter key textarea inserts new row as usual in HTML. To finish editing is possible by Alt+Enter or Ctrl+Enter.
Enter always inserts LF only (
).
bool FilterEmpty [0] If set to 1 when filtering, hides all not filtered rows with CanFilter=2 (or 3) that have all children filtered/hidden.
If you expect opposed behavior, to show already filtered rows that have some children visible you can do it by this way:
1) set <Cfg StandardFilter=1/> to filter children before parent, let all rows to have CanFilter=1
2) define event: Grids.OnRowFilter = function(G,row,show){ return show || G.HasChildren(row); }
bool StandardFilter [0] By default is filter applied to parents before to children to speed up filtering.
If set to 1, applies filter to children before filtering parent. Use it if parent is filtered according to visibility its children,
when uses aggregate functions. It can be much slower.
string [] CalcOrder [] Global calculation order for fixed rows if you have more fixed rows and want calculate cells in fixed rows at random
If set it is used instead of CalcOrder attribute in fixed rows.
In this array you can point to individual cells by id$col,
for example F1$A,F2$C,* calculates cell [F1,A], next [F2,C] and next all variable rows.
bool SortSpan [0] If set to 1, grid supports SortSpan attribute in <I> for number columns.
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 NoScrollAfterExpand [0] If set to 1, does not scroll into view the rows children the icon stays under mouse cursor
string BaseUrl [0] String added before urls in types Img and Link, if their format specifies it.
string HelpFile["Help.html"] Path and filename of TreeGrid help.
int MaxGroupLength [300] Maximal count of immediate children in grouped row. If the count is higher, the grouping row is divided to more rows.
int ExportType [2] The way of simple export (or server export via TreeGrid.dll/so) to Excel, binary array
1.bit (&1) export also filtered rows, 2.bit (&2) exports all rows expanded,
3.bit (&4) store strings in file twice to preserve their type a spaces, set it if you want to export all strings as strings and not chosen by Excel.
int ExportRows [0] For how many rows will be displayed and updated progress bar. Displaying progress bar suppresses also message about slow script. 0 never shows progress bar.
But in IE7 and some servers a user can be asked for permission to download the file.
Too small value can slow down the export, reasonable value is about 100.
int PrintType [496] The way of printing, binary array 1.bit (&1) reserved, 2.bit (&2) prints all rows expanded, 3.bit (&4) reserved, 4.bit(&8) - reserved
5.bit (&16) - includes header, 6.bit (&32) includes head, 7.bit (&64) includes foot, 8.bit (&128) includes body, 9.bit (&256) includes spaces
The default values is set bits 5,6,7,8,9.
int PrintRows [10] For how many rows will be displayed and updated progress bar. Displaying progress bar suppresses also message about slow script. 0 never shows progress bar.
Too small value can slow down the printing.
int Keys[0] Controls various keys, bit array.
1.bit (&1) if set, gray (numeric) + and writes character to input instead of accepting / canceling input.
int ExpandAllType [1] Which rows ExpandAll action expands, bit array. Bit 1 (&1) if set, expands only already loaded rows (for server child paging).
int AddChildType [0] Where to add, move or copy row(s) to children for action AddChild, bit array. Bit 1 (&1) = 0 to beginning of children, 1 to end of children.
int ReloadChanged [5] If permits reloading grid if not uploaded changes are pending.
0 no (does not allow neither reloading nor server side sorting/filtering/searching/grouping)
1 yes, save them (only when reloading as request for server side filtering/sorting/searching/grouping, for reload by Reload button always discards changes),
2 yes, discard changes (should be used only when changes are not saved to server at all and server paging is used)
3 show confirmation message to user
&4 test also selected rows (values 4,5,6,7 are related to 0,1,2,3)
bool ClearVariableAttrs [0] Set it to 1 if you set any of these attributes directly in some variable row (and not in default) Enum, Formula, CalcOrder, Action
You should set it to 1 to avoid memory leaks in IE the Clear function will check all variable rows and clear these attribute when unloading
For many variable rows it can slightly slow down the unloading so you should reconsider move these attributes to default rows.
bool StoreOriginalValues [1] If set to 1 it stores original cell values before are changed by a user and if user sets the cell value back to original value the cell is marked as unchanged.
<Pager>
Settings of main vertical pager, positioned on the grid right side.
Root tag placed in <Grid> ... <Cfg/> ... </Grid>. Permitted only one per one XML data source. Cannot contain child tags, but only attributes.
bool Visible [1] If pager is visible. Pager can be visible only if Cfg.Paging > 0 and Cfg.NoPager = 0. A user can select pager visibility from configuration menu and it 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. If set to 1, pager can also be resized if there is no room for it, to preserver displaying Too small extents message.
bool CanHide [0] If pager is displayed in columns menu and can be hidden or displayed by user from this menu.
If set to 1, the pager can be also hidden automatically if there is no room for it, to preserve displaying Too small extents message.
This attribute does not affect displaying and hiding pager from configuration menu.
<Toolbar>
Settings of bottom toolbar. This tag can be placed in main <Grid> section.
From version 5.0 / 4.7 is defined as solid space row and is described in rows.
<MenuCfg>
Settings of configuration dialog.
Root tag placed in <Grid> ... <Cfg/> ... </Grid>. Permitted only one per one XML data source. Cannot contain child tags, but only attributes.
bool ShowDeleted, AutoSort, AutoUpdate, CheckUpdates, Separator1 [1]
bool MouseHover, ShowDrag, ShowPanel, ShowIcons, ShowPager, ShowAllPages [1]
If this menu option is visible. Default is 1 for all.
Updates
3.3
Deleted <Cfg> attributes CacheImages and ImgPath
Added <Cfg> attributes DebugCalc, DateStrings
3.4
Added <IO Session> attribute
3.5
Added <Cfg> attribute NoFormatEscape
3.6
Excluded from file TreeGridDataFormats.htm to TreeGridDataFormatReference.htm
Added <Cfg> attributes AcceptEnters and VarHeight
3.7
Added <Cfg> attribute Focused, FocusedPos and FocusedCol
3.8
Added <Cfg> attributes PageLengthDiv, FastPages, RootCount, NoPager, PageTime
Added <Cfg> attributes NoScroll, NoHScroll, NoVScroll
Added <Cfg> attribute Copying. Added <I> attribute Copy
4.0
Updated attribute <Cfg> attribute Editing
Added <Cfg> attribute RowHeight.
Added <Cfg> attribute Silent
Added <Cfg> attribute HideRootTree
Added <Cfg> attribute FilterEmpty and updated <I> attribute CanFilter
Added <Cfg> attributes MaxHeight and MaxWidth
Added <Cfg> attributes NoTreeLines, SaveExpanded, SaveSelected, SaveValues, NoScrollAfterExpand
4.0.3
Added <Cfg> attribute BaseUrl
Added <Cfg> attribute SortSpan
4.2
Added <Cfg> AlertWidth attribute
Updated <Cfg> attribute MaxWidth
Added <Cfg> attribute ResizingMain
Added <Cfg> attribute ReversedSortIcons
Added <Cfg> attribute MaxSortColumns
Added <Cfg> attributes PrintPrefix and PrintPostfix
Added <Cfg> attributes IdNames, FullId and NumberId
Updated <Cfg> attribute DateStrings
Added <IO> Reload attribute
4.3
Updated <Cfg> attribute Selecting
Added <Cfg> attribute InEditMode
4.4
Updated <Cfg> attribute Selecting and <I> attribute Selected and added cell attribute Selected.
Added <Cfg> CalcOrder and updated <I> CalcOrder attributes
Added <Cfg> Detail, DetailOn, DetailExpand attributes and <I> Detail attribute
Added <Cfg> SaveSession attribute and updates <IO> Session attribute.
Added <IO> ReloadMessage and UpdateMessage attributes
4.5
Added <Cfg> attributes GroupCols, GroupTypes, GroupMain
Added <Cfg> attribute MaxGroupLength
Added <Cfg> attributes ReCalc and ReSort
Added <Cfg> attribute EmptyChildPages
Updated <Cfg> attribute ResizingMain
Added <Toolbar> attributes Formula, FormulaCol
Added <Cfg> attribute ExportType
Added <Cfg> attribute PrintCSS
Added <Cfg> attribute PersistentCfg
4.5.2
Added <Toolbar> AddChildType
4.5.4
Added <Cfg> attribute OnePage
4.5.9
Added <Cfg> attributes EmptyNumber, EmptyDate
Added <Cfg> attribute Keys
4.5.11
Added <Cfg> attribute ColsPosLap
4.6
Updated <Cfg> MaxHeight attribute
Added <Cfg> attribute EnumKeys
Added <Cfg> attribute StaticCursor
5.0
Excluded from file TreeGridDataFormatReference.htm to TreeGridXmlCfg.htm
Updated <Cfg> SaveExpanded attribute.
Added <Toolbar> Cells attribute and remove button visibility attributes
Added <Cfg> attribute DragCopy
Added <Cfg> attributes Top and Bottom
Added <Cfg> attribute ShowVScrollbar
Added section Custom Toolbar buttons to tag <Toolbar>
Updated <Cfg> attribute EnumKeys
Added <Cfg> attribute OverflowDialog
Added <Cfg> attributes SearchAction, SearchListAction, SearchExpression, SearchType, SearchRow
Added <Cfg> attributes ConstHeight and ConstWidth
Added <Cfg> attribute ZIndex
Updated <Cfg> attribute ExportType, added 3.bit
Moved attributes ExpandAllType and AddChildType from <Toolbar> to <Cfg>
Added <Cfg> attribute SaveAttrs and SaveAttrsTrim
<Toolbar> moved to TreeGridXmlRows.htm
Added <Cfg> attribute DropFixed
Added <Cfg> attribute ReloadChanged
5.0.6
Added <Cfg> attribute PrintType
Added <Cfg> attributes ExportRows and PrintRows
5.0.10
Added <Cfg> attribute MaxMenuHeight
5.0.11
Added <Cfg> attributes ExportPrefix and ExportPostfix
Added <Cfg> attribute Cookie
5.0.15
Updated <Cfg> attribute SuppressCfg, added value 4
5.1
Updated <Cfg> SortIcons
Update <Cfg> GroupTypes
Added <Cfg> attribute GroupFlags
Added <Cfg> attribute Pasting
Added <Cfg> ClearVariableAttrs
Updated <Cfg> attribute GroupTypes, bits 5 and 7
Added <Cfg> attribute IgnoreFocused
Added <Cfg> attribute UngroupAction
Added <Cfg> attribute EmptyEnum
5.1.4
Added <Cfg> attribute StoreOriginalValues
Updated <Cfg> DetailOn attribute