TreeGrid Basics
TreeGrid v5.9
· TreeGrid is client JavaScript component and runs in client browser.
· TreeGrid loads XML data from server and displays them in table, tree or grid with tree. TreeGrid lets user to view, control or modify these data. TreeGrid provides complete user interface for the data manipulation.
· TreeGrid uploads changes in XML to server back.
· You don't need to write any own JavaScript code to use TreeGrid on your page. But you can write JavaScript functions like event handlers to better control TreeGrid look and behavior.
· All the TreeGrid required files are in folder /Grid/ in distribution. These files must be accessible by browser.
· The only thing you need to know to use TreeGrid is to understand its input / output XML format. The best way to learn the XML format is to look at tutorials. The tutorials are from basic empty grid to expert functions. You can try to modify them to see what changes. And try examples in static html files (folder /Html/). And after you will know XML format, you can generate it and process it by your server script.
When you are programming with TreeGrid you have to do these actions:
a) Prepare HTML page with TreeGrid
This page can be static html page or can be generated by server script engine from files such .asp,.aspx.,.jsp,.php or other.
This page must include main JavaScript code (GridE.js).
Particular TreeGrid tables are placed by <treegrid> or <bdo> tags into parent div tag (called Main tag). The <treegrid> must contain all settings needed for loading and uploading TreeGrid data. The main tag must have set its width and height. You can place the main tag everywhere on your page body.
TreeGrid tables can also be created dynamically by JavaScript function TreeGrid( ).
TreeGrid can be included to any web page and also count and positions of grids is not limited.
Remember, you must always use enclosing tags </script>, </treegrid> or </bdo>. Otherwise some browsers will ignore these tags or will load them more times.
Documentation
Placing TreeGrid to web page by <treegrid> tag: TreeGridHTML.htm#TagTreeGrid
Creating TreeGrid dynamically by JavaScript: TreeGridHTML.htm#JavaScript
The simplest page with empty TreeGrid
<html> <head><script src="../Grid/GridE.js"> </script>
</head> <body> <div style="width:100%;height:98%;"> <treegrid Data_Data="<Grid><Cols><C Name='Col1'/></Cols><Body><B/></Body></Grid>"> </treegrid>
</div> </body></html>
These XML data can be static XML files or can be generated by server script by files such .asp, .aspx, .asmx, .jsp, .php. But result of server generated file must be always valid formatted XML. Also for other language coding than English is good to set content type and charset to “text/xml” and “utf-8”. For some scripts there is also good to set code-page to 65001.
The input XML data are usually divided to Layout and Data.
Layout is usually static XML file with defined TreeGrid structure like columns and defaults. But also can be generated dynamically by server script
Data is usually generated dynamically, usually from database and contain row and cell data.
For synchronous (submit, non-ajax) communication can be both Layout and Data included in HTML page from point a), or just Data.
For asynchronous (ajax) communication are Layout and Data generated by separate script(s) or are static files.
Documentation
TreeGrid XML format description: TreeGridXmlBasics.htm#Basics
TreeGrid XML format structure: TreeGridXmlBasics.htm#XMLDownload
Ajax versus submit: Server communication
c) Prepare server script to process uploaded changes in XML (optional)
This point is required only if you want to update changes back to server.
You need by your server script parse XML data uploaded by TreeGrid and store the changes to storage you want.
For synchronous (submit, non-ajax) communication returns the script new data and is almost always the same as in point b)
For asynchronous (ajax) communication the script just return success or error information. The script can be the same as in point b) or independent.
Documentation
TreeGrid XML format structure of upload: TreeGridXmlBasicsn.htm#XMLUpload
Uploading information: TreeGridXmlBasics.htm#Upload
<treegrid> attributes for upload settings: TreeGridXmlBasics.htm#Url
Ajax versus submit: Server communication
d) Write your own JavaScript functions and events (optional)
This point is required only if you want to extend TreeGrid user interface, behavior or look.
If you need to provide your own client interface, you can use TreeGrid JavaScript API.
This API lets you control nearly all TreeGrid behavior. It contains many properties, functions and events.
You can also use your JavaScript function from TreeGrid formulas.
Remember, the most of the API is included in Extended API that must be purchased apart.
Documentation
TreeGrid API reference: TreeGridAPI.htm
Server communication - AJAX versus Submit
TreeGrid can communicate by two ways, synchronously (Submit) or asynchronously (AJAX).
Submit – synchronous communication, data are included directly in html, usually in hidden input or directly in <treegrid> attributes.
Your server script must prepare all data at once and include it in html page.
The changes are written back to hidden input and the page (respectively its form) is send back to server with all changes. And page is reloaded back from server with new data.
This method does not support automatic updates. An user must always click to Save button (or any other submit button you included on page) to save changes to server.
This method also does not support server paging.
<treegrid> attributes used for this method are: Layout_Data or Layout_Tag, Data_Tag and Upload_Tag.
See documentation: Data sources and data source attributes.
AJAX (Asynchronous JavaScript And XML) – data are downloaded from independent urls.
Data are uploaded or reloaded without reloading the page, just asynchronous request is sent to server.
You can set url for layout (Layout_Url) and data (Data_Url).
For uploading you can set url by Upload_Url. For uploading you can choose two methods Form and Soap. For other parameters see documentation.
For large grids with more then 5,000 rows you can use server paging and set url for downloading pages Pages_Url.
All urls can be the same and you can identify request according to user parameters (*_Param_*).
See documentation: Data sources and data source attributes.
You can also set auto update feature, to update all changes done by user immediate to server. See <Cfg> AutoUpdate attribute.
Server side library - TreeGrid.dll
For very large grids you can use prepared TreeGrid.dll/so to help you to generate and update data on server side. The DLL supports server paging, updating, sorting, filtering and pre-calculations. The DLL works upon given XML data or file.
This library is expected to be used with large grids with more then 5000 rows. For small grids you can use client functions without any sophistical server code.
This is DLL / SO and now is available for Windows and Linux systems. The library is written in pure C++ and is much faster and much less memory consuming than any code you can write in managed languages as C#, Visual Basic or Java. The DLL can be used in any server script languages that can use DLL on Windows or SO on Linux systems (ASP.NET, Java servlets / JSP, PHP, ...). In downloadable evaluation version are examples of using TreeGrid server in ASP.NET (C#, VB), JSP (Java) and PHP.
See documentation: TreeGridServer.htm.
This DLL is just helper object, you don't need to use this DLL, you can use your own server script to generate and update data.
TreeGrid supports two base paging types: client and server.
In the client paging the pages are created and handled by TreeGrid itself. The input data are still downloaded all. The paging is used only for rendering, because it is the slowest part of creating grid.
You don’t need to do anything else then to set TreeGrid to use this paging type.
This paging type is limited to about 20,000 rows.
In the server paging the pages must be created by server script. TreeGrid downloads only data of pages that will be displayed.
The server must be able to send XML data for requested page. If your grid uses sorting, filtering or aggregate calculations, the server must be able to provide these functions. The server also must generate page names if you want to use pager.
For this paging type you can also use the support library TreeGrid.dll/so.
There also two ways of showing pages: all pages visible and one page visible. These options can be switched also by user from configuration menu.
In all pages visible type are all pages still present in grid, there is long vertical scrollbar and user can scroll to page he requests. The data for page are rendered (in client paging) or downloaded and rendered (in server paging) only when the page is displayed (by scrollbar) for about 500ms. Switching to page is also possible by clicking to pager if it is visible.
In one page visible type is only one page visible at once. The pages can be switched only by clicking pager or by keys PageUp PageDown. This type is usually faster.
In tree there is also possibility to use delayed rendering or downloading of child nodes of parents. In TreeGrid this is called child paging. Child paging can be also client type or server type as mentioned above. All children of one parent are always in one page. For child paging there is no pager to use. Child paging can be used for rows on any level(s) in tree.
The child page is rendered (client paging) or downloaded and rendered (server paging) when user expands parent row.
If you want to use client paging, the parent row must be collapsed by default, because expanded rows must be downloaded immediately.
Paging you can set by <Cfg ... Paging=’’ ... /> (2 for client, 3 for server)
Child paging you can set by <Cfg ... ChildPaging=’’ .../> (2 for client, 3 for server)
To choose All pages / one page visible you can by <Cfg ... AllPages=’’ .../> (0 for one page, 1 for all pages).
Limits - How many rows TreeGrid can handle
TreeGrid can handle unlimited count of rows and unlimited levels of tree. The row's count is limited by duration of rendering and data downloading. The real counts vary according to paging type used. For pure grids can be used none, client or server paging, for tree, in addition, none, client or server child paging.
Without paging
All rows are displayed at start and are still rendered, therefore all
operations are fast.
Depending on column count, TreeGrid can handle about 300 – 1,000
rows without paging.
Client paging
All data are downloaded at start and all operations (sorting, filtering,
calculations) are done offline without need of server support. But not all rows
are still visible and after some operations (sorting, filtering) must be
re-rendered. Pages are rendered on demand.
Depending on complication of operations and data length, TreeGrid can handle up
to 20,000 rows with client paging.
Server paging
Data are downloaded and rendered only on demand. Server must be able to sort,
filter and pre-calculate rows.
Limitation depends on speed of server script and operations requested. With TreeGrid.dll you can have about million rows. If you
use some SQL database, limits will growth to couple of millions of rows,
depending on efficiency of your SQL procedures. For too many pages, it is
better to set the option AllPages
to 0 (One page visible at once). Also if TreeGrid has too many pages (tens
thousands of pages), there can problem with aggregate calculations of all rows
and with page names on pager.
Tree (child paging)
The paging and limits listed above are related to pure grids and root nodes of
the tree. If you send to client nodes collapsed you can use child paging to
grow the limits, especially for server paging.
In tree you can handle unlimited count of rows in unlimited depth.
For tree there is one limitation, one node can display only limited count of
immediate children. If the count of immediate children of node exceeds this
limit, these children are automatically grouped to sub nodes, but only if some
paging is used. By default is this limit 300 child nodes, but you can
change it and also specify it for every row individually.
If you have huge tree, you need to send to client the most of nodes collapsed,
because expanded rows must be rendered at once and above limitation is used for
all expanded children, not only immediate.
Updates
Rewritten from web
Updated section Limits - Tree.
Removed including CSS style to HTML page