Creating TreeGrid
TreeGrid documentation
Basics
The simplest page with TreeGrid:
<html>
<
head>
<script src="GridE.js"> </script> <!-- including TreeGrid script -->
</
head>
<
body>
<
div style="width:100%;height:500px;">
<!-- TreeGrid main div tag -->
<treegrid Data_Url="Data.xml"> </treegrid> <!-- TreeGrid data source definition -->
</
div>
</
body>
To fully create and render TreeGrid during page loading you can use such HTML code:
<
div id="Main"
style="width:100%;height:500px;">
<!-- TreeGrid main div tag with id -->
<script> TreeGrid('<treegrid Sync="1" Data_Url="Data.xml"> </treegrid>',"Main"); </script>
</
div>
TreeGrid is created after click to button Create:
<
div id="Main"
style="width:100%;height:500px;"> </
div>
<!-- TreeGrid main div tag with id -->
<
button onclick='Create()'>Create</
button>
<
script>
function Create(){ TreeGrid( { Data:{ Url:"Data.xml" } },"Main" ); }
</
script>
When you are upgrading to new version or registered license or newly compiled script you can add some version info as query string to GridE.js to ensure using the new one and suppress caching the old one, for example:
<script src="../Grid/GridE.js?Version=6.0.24"> </script>
Basic information
TreeGrid can be
placed to HTML page by tag <
treegrid> or <
bdo> or can be
created dynamically by API function
TreeGrid.
The <treegrid> or <bdo> tags must always have enclosing tag (<treegrid> </treegrid> or <bdo> </bdo>).
In <
treegrid / <
bdo> tag or
TreeGrid function you define data sources to download XML data from and upload data to.
TreeGrid can download data from remote server, local server, local files or from XML placed directly in the source HTML page.
TreeGrid can upload data to remote or local server or include the data to HTML page and submit it.
TreeGrid can be fully
deleted from page by calling
Dispose method.
TreeGrid can be
reloaded by calling
Reload method. Or you can reload only body rows by calling
ReloadBody.
TreeGrid can is
accessible by API by
Grids array.
By default is the communication
asynchronous, you can set
<treegrid Sync='1'/> to use
synchronous communication.
The synchronous communication is faster, but disables the whole page usage during loading.
Encoding strings in XML. If you want to store any string to xml, you need to encode these characters:
<,
& and
" or
' depending on quotations used in your xml attribute.
And if you want to store this xml data to html page in any attribute
as string you have to make the same encoding once more (
you again stores string in xml/html). The only exception is that HTML accepts
< character in attribute values, but if you encode it, it will be better.
Creating
<HTML tag>
<treegrid>
Basic TreeGrid definition on page
Places one grid to HTML page and defines base grid attributes, the data sources to download XML data from and upload to.
The <treegrid> tag is placed to parent
div tag that is called
Main tag. The
Main tag can be also any server control to control this tag from server script, but it always needs to be a block (not inline) tag.
All content of the
Main tag will be overridden by TreeGrid content after the grid is created.
The
Main tag is partially controlled by TreeGrid, especially its
size and overflow (depending on
size and scroll settings), but all other properties can be set as to standard HTML tag.
When the page is loaded (in body onload event), all <treegrid> tags on page are processed and replaced by appropriate grid.
To process the <treegrid> tags later, call
StartTreeGrid method.
To create grid dynamically by API call
TreeGrid method.
All the attributes are accessible by API by grid.
Source attribute.
The <treegrid>tag must always have enclosing tag (<treegrid> </treegrid> not <treegrid/> ).
<HTML tag>
<bdo>
An alternative to <treegrid> tag
You can use <bdo> tag instead of <treegrid> to support some old browsers like Safari 3.x that don't accept non HTML tags.
<bdo> is a standard HTML tag to setting text direction, but without its
dir attribute has no sense and can be used as TreeGrid definition.
The <bdo>tag must always have enclosing tag (<bdo> </bdo> not <bdo /> ).
upd 6.0 global func. TGrid
TreeGrid
(object Source, string tag = "", string id = "")
Creates and renders new grid by API according to settings in
Source.
Source can be:
a) string with <treegrid> or <bdo> tag with all settings like it is included directly to HTML
Example: TreeGrid("<treegrid Data_Url='Grid2.xml'></treegrid>","Main");
b) string with XML to create the grid from. The grid will have only Data_Data source defined.
Example: TreeGrid("<Grid><Cols><C Name='A'/></Cols><Body><B><I A='xxx'/></B></Body></Grid>","Main");
c) object with parsed <treegrid> / <bdo> tag.
All multilevel attributes (data sources) containing '_' must be set as nested objects, split by the '_',
for example Data_Param_Test is accessed as Source.Data.Param.Test and set as {Data:{Param:{Test:'val'}}}
Eample:
TreeGrid({Layout:{Url:"Grid2Def.xml"},Data:{Url:"Grid2.xml"}},"Main");
is the
main div tag to render grid into. The
tag can be an id of the tag or the HTMLElement itself. The htm tag must exist in time of calling the function.
If the parameter is missing, the id of the tag must be set in input XML by attribute
<Cfg Tag/>. See <
treegrid> tag description.
is the unique id of the grid, used to identify it, especially in saving configuration to the cookies.
If the parameter is missing, the id of the grid can be set in input XML by attribute <Cfg id/>
The function returns created
TGrid object as main TreeGrid object. Remember, loading and rendering is asynchronous by default, so at the moment of function return, the grid is
not fully loaded and rendered yet. You can change it by setting
Sync to 1.
It returns null for fatal error. It fails if the
Source is null or cannot be used as one of the three options.
After finish will be fired
OnRenderFinish and
OnRenderPageFinish or
OnLoadError event.
The
Source is accessible by API by grid.
Source attribute.
global func. void
StartTreeGrid
( )
Creates all grids on page from all HTML tags <treegrid> / <bdo>.
The grid creating is asynchronous procedure by default, so in time of function return the grids are not fully created yet.
By default it is called from window.onload event.
Call this function after you place new <treegrid> / <bdo> tag to your page.
This function creates grid in place of <treegrid> / <bdo> tag and destroys it, so it can be called as many times as you want.
Deleting
upd 6.0 API method void
Dispose
( )
Completely removes the grid from page.
It frees memory allocation for the TreeGrid by calling
Clear() and removes the Grid from
Grids array.
The disposed grid must not be used.
The indexes of disposed grids are not used again, except if was called
DisposeGrids function.
new 6.0 global func. void
DisposeGrids
( )
Completely removes all grid from page. Calls for all grids
Dispose().
Sets also
Grids.length to 0 to start indexing new grids from 0.
upd 6.0 API method void
Clear
( )
Frees memory allocation for the TreeGrid. If you delete grid from JavaScript, call this function to free browser's memory.
It is used especially to avoid memory leaks in IE.
TreeGrid calls this function automatically when reloading or when window is closing.
The cleared can be only reloaded (called grid.Reload()).
Reloading
upd 13.0 API method TGrid
Reload
(object Source = null, string id = null, int type = 1, string message = null)
Reloads and re-renders the whole grid.
Returns newly created grid or null for error or cannot reload.
The actual grid object is cleared and must not be used after reload! It can be only again reloaded if the Reload function failed.
By default it is asynchronous and returns before the loading starts (like
TreeGrid function). You can set
Sync=1 in
Source to reload synchronously.
After finish will be fired
OnRenderFinish and
OnRenderPageFinish or
OnLoadError event.
The
Source is data source settings for grid, the same as in
TreeGrid function. If the source is null, it is used original grid data source
Source.
This function can be called to reload data from the same source to get the newest one or to reload another data from another source.
The
id is new
id to change the grid id, under this id will be now the grid accessible in
Grids array.
(Since 7.0) To preserve old grid id, set it to null, to load id from new data, set it to empty string.
If there are some pending changes in grid, it confirms reloading by a user. The user can cancel reloading and the method returns false.
type is a bit array of flags to control the reloading.
type,
1. bit &
1 =
0, it never asks a user about reloading.
type,
2. bit &
2 =
2,
(new 13.0) it preserves grid configuration like style or print settings.
type,
3. bit &
4 =
4,
(new 13.0) it preserves data configuration like filter settings or column widths.
(Since 13.0) If set
message (either to empty string) and
SuppressMessage >= 1, it shows the
message and does not clear the grid html and does not show other messages during loading.
API event bool
OnReload
(TGrid grid)
Called from
Reload method or when user clicks to reload icon on toolbar.
Return true to suppress reloading.
chg 11.0 API event bool
OnCanReload
(TGrid grid, int changed, bool cancel)
Called when
reload is requested - called from
Reload method and when changed
server side sorting/filtering/grouping/searching/export.
Called
instead of confirming message to a user.
Return
false to cancel action. Return
true to confirm reloading.
(since 11.0) Return
null to ignore the event and show the confirm message to user if changed.
changed = bit array, &
1 - grid contains changed rows, &
2 - grid contains selected rows.
cancel is
true if changes should be canceled (called from
Reload method),
false if changes should be saved (server side request).
To save changes call
Save function from this event.
<Actions>
Reload
Attached to event OnClickButtonReload
Reloads the grid, cancels changes, see
Reload method.
new 13.0 <Actions>
ReloadCfg
Not attached any to event
Reloads the grid, cancels changes, but preserves the grid configuration.
new 13.0 <Actions>
ReloadSettings
Not attached any to event
Reloads the grid, cancels changes, but preserves the grid and data configuration.
API method void
ReloadBody
(function Func)
Reloads whole body (from source grid.
Source.
Data), all variable rows.
By default it is asynchronous and returns before the reloading finishes. You can set
Sync=1 in Source.Data to reload body synchronously.
After finish, it calls function
Func. function
Func (
int code).
The grid.Source.Data source can contain only variable rows (<Grid><Body>... </Body></Grid>), all other definitions like columns, fixed rows and so on must be defined in Source.Layout.
new 11.0 API method void
ClearBody
( )
Removes all body rows in the grid. The rows are removed permanently, not only deleted.
Rendering
new 6.4 <treegrid,bdo> bool
Hidden
[0]
If set to
1 the grid is never rendered and can be used as invisible data source for other grids or other page components.
The hidden grid has
not set
MainTag and cannot be shown at all.
API event bool
OnRenderStart
(TGrid grid)
Called before rendering or re-rendering of whole grid started.
It is called on create grid, from Render method, but also in various other situations where the grid is re-rendered.
Return true to cancel rendering.
API event void
OnRenderFinish
(TGrid grid)
Called when rendering or re-rendering of grid is finished and grid is ready to work. Use if you need to do some post-render actions.
When used (client or server)
paging (
<Cfg Paging>1), the body rows are
not rendered yet in time of this handler call.
When used
child parts (
<Cfg ChildParts='1'), not all rows in tree are rendered yet in time of this handler call.
API event void
OnRenderPageStart
(TGrid grid, TRow row)
Called before rendering of the root page or child page started rendering.
When used child paging (
<Cfg ChildPaging>), this event is fired before start of rendering children when a parent row is being expanded.
API event void
OnRenderPageFinish
(TGrid grid, TRow row)
Called after the root page or child page is fully rendered and ready.
When used child paging (
<Cfg ChildPaging>), this event is fired after children are rendered when a parent row is being expanded.
new 6.0 API event void
OnRenderChildPartStart
(TGrid grid, TRow row, int index)
Called before rendering of a part of children is started rendering.
The
index is an index of the part from 0.
new 6.0 API event void
OnRenderChildPartFinish
(TGrid grid, TRow row, int index)
Called after the part of children is rendered and ready.
The
index is an index of the part from 0.
new 7.0 API event void
OnRenderColPageStart
(TGrid grid, int sec)
Called before rendering of the column page.
The sec is the section index to
ColNames.
new 7.0 API event void
OnRenderColPageFinish
(TGrid grid, int sec)
Called the column page is fully rendered and ready.
The sec is the section index to
ColNames.
API variable bool
Rendering
It is set during render or other function that updates grid HTML.
It is set to not update grid layout by
Update method during such function.
Set it if you manipulate more rows or columns to not to update grid layout to speed up the action. After that you must call the
Update() method.
new 6.0 upd 13.1 API method void
Rerender
(bool scroll, bool sync)
Asynchronously renders the whole grid into main tag's innerHTML. Or it renders synchronously if set
<treegrid Sync='1'/>.
Calls
Render asynchronously or synchronously.
Since 13.1 if set
scroll, it preserves actual scroll position.
Since 13.1 if set
sync to 0 or 1, it renders synchronously or asynchronously regardless on Sync attribute value.
API method void
Render
( )
Synchronously renders whole grid into main tag's innerHTML.
The previous grid HTML is cleared, it takes care about memory leaks.
This function may be slow, if many rows are present.
If used paging, the pages are rendered asynchronously.
Call it if you want to do many changes in grid to speed up the action - do not show the changes and after finish render the grid.
renamed 6.0 API method void
RenderBody
( )
Re-renders the whole body.
In paging, call it to clear all already rendered pages and render them again.
Call it if you want to do many changes in body rows to speed up the action - do not show the changes and after finish render the body.
Accessing by API
global variable TGrid[ ]
Grids
read only
This is global array of all created grids on page.
The individual grid can be accessed by Grids["id"] where the
id is an <treegrid id> or <Cfg id> attribute.
The individual grid can be also accessed by Grids[Index], where the Index is grid index that got assigned in creating process.
Accessing individual grids by index is not recommended if more grids are on page.
To iterate all grids on page use such loop:
for(var i=0;i<Grids.length;i++) { var G = Grids[i]; if(G){ ... } }, remember some indexes can be missing.
The grids are added to the array by creating grids on start or by function
TreeGrid ( ) or
StartTreeGrid ( ).
Existing grid can be removed by
Dispose ( ).
new 6.0 global func. TGrid[ ]
GetGrids
( )
Returns all grids on page.
<treegrid,bdo> string
id
An
id of the grid. By this id the grid can be accessed from JavaScript as
Grids[id]. This parameter can be also set in data, in <Cfg
id /> attribute.
If the
id is set neither in <treegrid
id> nor in <Cfg
id />, it is created default as "Table"+grid_index.
If the
id is set in both <treegrid
id> and <Cfg
id />, the <treegrid
id /> is used.
By this
id the grid saves configuration to cookies, if two grids have the same
id, they share their configuration in cookies.
<Cfg> string
id
An id of the grid, see the <
treegrid id> attribute description.
API variable string
id
read only
An id of the grid set by <
treegrid id> or <
Cfg id> or created as "Table"+
Index.
API variable int
Index
read only
Unique index of the grid in global array
Grids. Newly created grid gets the first available index (from 0).
By this index you can access the grid, but you should rather use its
id.
The indexes of disposed grids are not used again, except if was called
DisposeGrids function.
renamed 6.0 API variable object
Source
The actual data sources settings. It is the parsed <
treegrid> attribute or the source set in TreeGrid function.
You can change the individual settings to download or upload data from different location.
For example:
grid.Source.Data.Url = "new.xml"; grid.ReloadBody();
For example:
grid.Source.Upload.Sync = 1; grid.Source.Upload.Url = "save.jsp"; grid.Save();
API variable object
MainTag
read only
The main tag where the grid is rendered inside.
It is set during creating. It is the HTMLElement object itself.