Using TreeGrid on HTML page
TreeGrid v4.3
Creating TreeGrid by <treegrid> HTML tag
You need to include main treegrid script GridE.js and predefined styles to the page in <HEAD> section. If these files have another url, you must use the other.
<head> <link id=GridCSS href="../Grid/Grid.css" title="GridStyle" type="text/css" rel="stylesheet"><script src="../Grid/GridE.js"> </script>
</head>Due compatibility issues, don’t use the !DOCTYPE tag with URL to switch IE to compliant mode. As this mode works only in IE 6.0+, it is not supported by the TreeGrid. See http://msdn.microsoft.com/library/default.asp?url=/workshop/author/dhtml/reference/objects/doctype.asp for more information.
Now include on the place where you would display a TreeGrid component the <div> or any other block tag. This tag is called TreeGrid Main tag. You can set style of this tag (background, border, etc.), but you must set width and height (in style) of this tag to any other value than "auto" to display TreeGrid properly. The Main tag can be also any server control to control this tag from server script, but always it needs to be a block (not inline) tag. You can also have more TreeGrids and Main tags on one page. All content of the Main tag will be overridden by TreeGrid content after document loads.
The Main tag can have absolute or static position.
Into the grid Main tag place <treegrid> tag, with attributes and children nodes specifying TreeGrid data source and other settings.
If you want compatibility with some minor browsers like KHTML (Koqueror / Safari) you need to use <bdo> tag instead of <treegrid>. Also don’t forget to enclose all attribute values to quotes.
TreeGrid is created when document is loaded. It uses event body.onload.
If you have problems with communication with server, set Debug parameter to 3 to see server responses.
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.
All treegrid attribute names are case insensitive, but attribute values are case sensitive!
There is simple page with a TreeGrid:
<html> <head> <link id=GridCSS href="../Grid/Grid.css" title="GridStyle" type="text/css" rel="stylesheet"><script src="../Grid/GridE.js"> </script>
</head> <body> <div style="width:100%;height:100%;"> <treegrid Layout_Url="../Data/CalcDef.xml" Data_Url="../Data/CalcData.xml"> </div> </body></html>
string Id [""] Id of the grid. By this id grid can be accessed from JavaScript as Grids[id]. This parameter can be also set in data.
If the Id is set neither there nor in data, it is created default as “Table”+grid_index.
By this name the grid saves configuration to cookies, if two grids have the same Id, they share their configuration in cookies.
string Session [“”] Parameter identifies server session, this is not used on client, it is only sent to server in data in <IO Session=””> attribute
int Debug [0] For debugging purposes,
0 no debug information.
1 adds some formatting to the sent data as enters and tabs and shows error messages sent from server in new window.
3 adds formatting as in 1 and shows all data sent to and received from server in new window
int SuppressMessage[“”] Suppresses all no critical messages, similar to SuppressMessage in data xml, but suppresses even messages during initialization.
Every data source has its own prefix before its attribute name (for example Data_Url, Data_ is prefix and Url is attribute name)
Data sources are loaded in this order:
Text_ Default: Url="Text.xml" Start="Loading data ..." StartErr="Fatal error !<BR>TreeGrid cannot load"
Data source for all texts and language settings. This is loaded as first. This is required source, but you can keep the default value.
string Start Message displayed when data are loading
string StartErr Message displayed if texts have not been loaded
string ErrXMLFormat Alert displayed if text file is not found
Defaults_ Default: Url="Defaults.xml"
Data source for predefined values of all parameters in TreeGrid. This is required source, but you can keep the default value.
Layout_ Default: Method="Get" Required attribute to set is Url or Tag or Data.
Data source for grid structure, definitions and columns and usually fixed rows. If not set, you must include grid structure to Data_.
Data_ Default: Method="Get" Required attribute to set is Url or Tag or Data.
Data source for all grid data, usually variable rows. This is required source, you must set at least this source.
Page_ Default: Method="Form" Xml="0" Required attributes to set are Url and Data.
Data source for individual pages, when Cfg.Paging = 3 or Cfg.ChildPaging = 3.
Data_ in this case must return only fixed rows and page list without rows.
Upload_ Default: Method="Form" Format="DTD" Xml="0" Type="1" Required attributes to set are Url and Data or Tag only.
Destination for upload changed data from grid. What can be uploaded see Upload_Type. If not set, data cannot be uploaded.
Export_ Default: Method="Form" Xml="0" Type="0" Required attributes to set are Url and Data.
Destination for page that generates data to export to Excel or another spreadsheet program.
This communication is not done by AJAX, but by always by hidden form, so can be used even if no ActiveX is supported.
Export cannot use Soap or Get communication.
For other information see also Export_Type.
Check_ Default: Method="Get" Interval="60" Required attribute to set is Url.
This source can be used to repeatedly check updates on server and, if there are some, to download them and add them to grid.
Set Interval attribute to number of seconds of interval.
<treegrid> data source attributes
These attributes can be used in tags <Text>, <Defaults>, <Layout>, <Data>, <Upload>
string Url Url to connect to. From this url are data downloaded or to this url are data uploaded.
This url can url of static file to download or any web page or web service.
For download it can contain parameters for GET method (beyond the ‘?’). For upload it cannot, because the POST method used.
If set for upload, data are uploaded by AJAX (without form submit) and TreeGrid Auto update option can be set.
This attribute can contain wildcards to change it according to grid or page settings.
All these strings will be replaced by appropriate runtime value:
*SortCols0, *SortCols1, *SortCols2 Column name according to is grid sorted.
*SortTypes0, *SortTypes1, *SortTypes2 Sorting type for sorting column (0 = desc, 1 = asc).
If grid is not sorted or SortCount is less then 3, the not used wildcards are removed.
*id Row or page id (only for Page_Url)
*Pos Page position (only for Page_Url)
*Rows Page’s attribute Rows (only for Page_Url), this attribute can be set to anything, for example to generate whole url.
string Tag ID of tag (usually hidden input). From its attribute value are read data. When data are read, the value is cleared.
Or for upload to this value are changes written when submitting form.
This is alternative to Url and cannot be set both. For upload this must be id of <input> tag.
If set for upload, data are uploaded by form submit and TreeGrid Auto update option cannot be used.
When uploading, don’t forget to place this hidden input on HTML form with specified Action attribute as usual,
when uploading forms to sever.
When user clicks Save button, the input’s value is filled by changed data and form to which the input belongs is submitted to server.
When the form to which the input belongs is submitted by any other way, before submit, the input value is filled by changed data.
By default are data html encoded (&,<,> to entities) because of security validation in server scripts, you can change it by Xml attribute.
string Data String with direct data for TreeGrid. It is alternative to Url and Tag and can be set only one from them. For download only.
string Data Name of parameter where to store uploaded data or data of request. Used only when Url is set.
string Format Format of uploaded data: “DTD”, “Internal”. See TreeGrid data formats. No short versions possible. Default is DTD.
Used for upload or for request.
string Bonus String with direct data for TreeGrid. This data is read after main data in Url/Tag/Data are read to change some default behavior.
For download sources only.
int Timeout Timeout in seconds. How long grid will wait for server response. Default value is 60 seconds.
int Repeat Behavior when Timeout expires. 0 – alert, 1 – no alert, 2 – repeat with confirmation alert, 3 – auto repeat. Default is 0.
string Method Method of upload or for download method of upload of parameters if data are downloaded from web service or page with parameters.
“Get” – for download only, parameters are sent by HTTP GET method, in url string. Default for downloading.
“Form” – data are uploaded like form submit in format application/x-www-form-urlencoded. Default for uploading.
“Soap” – data are uploaded in SOAP XML envelope. This is usual for communication with web services.
Used only when Url is set. Default is Get for download and Form for upload.
string Function Name of SOAP function. Used (and required) only when Url set and Method is “Soap”.
string Namespace Name of SOAP namespace. Used only when Url set and Method is “Soap”.
bool Xml For 0 (default) are data encoded to string (& and <,> are replaced). The web service’s parameter is type of string.
The 0 is required value when submitting form due security validation in some server script like ASP.NET.
For 1 data are uploaded as XML, the web service’s parameter is type of XmlDocument (or similar type).
Param_ This is second prefix for other parameters to function, for soap or form parameter.
The value in this attribute is filled to function’s parameter named as third part of name.
The case sensitivity of function name is unsure, the name is always converted to format “First letter upper, other letters lower” !
For example: Data_Param_Test=”12” => to function parameter named “Test” is put value 12.
Used only when Url is set. Remember, default method for downloading data is “Get”,
if you want to use Param, you need to use “Form” or “Soap” Method.
int Type (Upload_) Upload type, binary array, what will be sent to server, default is 1 – only changed rows.
&7 – rows - 0 – none, 1 – changed only (Added, Deleted, Changed, Moved + values), 2 – selected only (Selected attribute)
3 – changed + selected (same as 1+2)
4 – changed + selected with all or given attributes, 5 – All fixed rows, 6 – All variable rows, 7 – All rows.
For 4-7 sends all attributes or attributes in Attrs list. Uses Internal format only.
Setting this attribute to 6 or 7 can significantly slow data communication for larger grids.
If variable rows are in tree, for 6, 7 are in output also in tree.
&8 – configuration (sends sort settings in <Cfg>, filter setting in <Filters> and columns’ widths and positions
in <LeftCols>, <Cols>, <RightCols>). Cannot be set with &16 or &64.
&16 - <Cfg> tag, sends all attributes from this tag, including some runtime internal settings.
&32 -<Def>,<D> tags, sends all defaults with all attributes in Internal format only, including some runtime internal attributes.
&64 - <LeftCols>,<Cols>, <RightCols>, <C> tags, sends all columns’ settings, including some runtime internal attributes.
&128 - <Header> tag, sends all attributes in Internal format only, including some runtime internal attributes.
&256 - <Panel>, <Toolbar>,<MenuCfg>, <Pager> tags, sends all attributes of these tags.
&512 - <Img> tag, sends all attributes of this tag.
&1024 - <Lang> tag, sends all texts and format settings.
&0x10000 – Does not include <Grid> tag, if you need to append some other tags to XML. XML is not valid in this case.
&0x20000 – Does not include <IO> tag.
Setting Type=65535 returns whole grid data with all settings.
string Attrs (Upload_) Comma separated list of attribute row’s names, that are uploaded. The names must be in Internal format.
It concerns about variable rows only. Used only when Upload_Type&7 = 4,5,6,7.
If this attribute is omitted, fills all rows’ attributes. For large grids it can be significantly slower.
The row has always set id and Def attributes, do no include them to Attrs list.
int Type (Export_) Export type
0 – simple export, to server is sent whole prepared report that can just be returned by this page back to Excel.
Can be used only for small grids, because to server are send all data back.
Cannot be used with server paging or server child paging.
The server script just returns the data from Data attribute back to client with changed content type.
For MS Excel use ContentType="application/vnd.ms-excel" and charset: utf-8.
1 – server export, to server is sent just configuration – sorting, filters and column width, positions and visibility.
The configuration is sent as standard TreeGrid XML in Data attribute.
Server must generate the report from data on server by itself and return report to client.
Use this way for larger grid and/or for grids with server paging or server child paging.
Use it also if you want to generate different then standard report or
you want to generate report for another program then MS Excel.
int Interval (Check_) How often checks for updates, in seconds.
This value can be modified by user from menu and is saved to cookies.
Saving value to cookies can be suppressed by <Cfg ... CheckUpdatesLap=’1’ ... />
TreeGrid with all data and structure downloaded from static file, without upload
<treegrid Data_Url="../data/TreeGridSample.xml"> </treegrid>
TreeGrid with structure read direct from string, data downloaded from static file, uploaded by form submit in hidden input GridData.
<input type=“hidden“ name=“grid“ id=“GridData“><div style="width:100%;height:100%;"> <treegrid Layout_Data="<Grid><Cols><C Name=‘C1‘/></Cols></Grid>" Data_Url="../data/TreeGridSample.xml"
Upload_Tag="GridData">
</treegrid> </div>
TreeGrid with structure downloaded from static file. Data is downloaded from soap webservice, method string Load (string Grid), with parameter Grid = “Grid1”.
Data is uploaded to soap web service, method string Save (XmlDocument Data, string Grid, int Test), with parameters Data=”changed data in XML”, Grid=”Grid1”, Test=12
<treegridLayout_Url="../data/TreeGridSampleDef.xml"
Data_Url="../aspx4/TreeGridSample.asmx" Data_Method=“Soap“ Data_Function=“Load“
Data_Namespace=“www.treegrid.com“ Data_Param_Grid=“Grid1“
Upload_Url="../aspx4/TreeGridSample.asmx" Upload_Method=“Soap“ Upload_Function=“Save“
Upload_Namespace=“www.treegrid.com“ Upload_Format=“Internal“ Upload_Data=“Data“ Upload_XML=“1“
Upload_Param_Grid=“Grid1“ Upload_Param_Test=“12“
</treegrid>
Recognized input data formats and methods
Remember, if you use XML web service function to generate data, this function must return data in return value and as string or XmlDocument.
Static XML file with root tag (or any other but only one) named <Grid>
This is usual response of standard web page generated XML data.
This is standard response of any XML web service (independent on post method - HTML form or SOAP) if function returned data as XmlDocument.
XML SOAP envelope, with TIOData.Function. Data are in the tag <FunctionResult> as string.
This is the standard output of the XML web service, if function returns string and data were sent as SOAP XML envelope.
XML file with one root node with text. The text contains encoded data in string. Data to the text node is encoded by any XML parser.
Example: <?xml version="1.0" encoding="utf-8" ?><string><Grid><Body>...</Body></Grid></string>
This is the standard output of the XML web service, if function returns string and data were sent as HTML form.
Possible output formats and methods
Data are uploaded when are changed and are sent to server or when specific data are requested from server, especially when Cfg.Paging=3.
Form – A standard submit as HTML form.
Default method of uploading
Data are sent as “application/x-www-form-urlencoded; charset=UTF-8”.
This method is supported by most servers or XML web services.
Usually you need to set Upload_Data string to parameter name where to store uploaded XML data.
By default are characters ‘<’ and ‘>’ coded to XML entities ‘<’ and ‘>’ due security reasons. You can change this behavior in Upload_Xml attribute.
By default are only changed rows sent to server, you can choose what will be sent server by Upload_Type attribute.
Soap – SOAP envelope.
Data are sent as “text/xml; charset=UTF-8”.
This method is supported by SOAP XML web services.
You need to set Upload_Function to called function name and Upload_Data to function parameter which gets the data.
If you used namespace for your function, you need to set Upload_Namespace. Default namespace is often “http://tempuri.org”.
You can set attributes of Upload.Param to other parameter names and values to send with the data to web service function.
You can set Upload_XML to true, if function data parameter is type of XmlDocument, or to false (default), if it is type of string.
This is default format due backward compatibility, but now is preferred the Internal format.
Use it if your data is in this format and you want to use easiest way of data updating. See DTD format and XML Upload.
Internal – Shorter and faster format
Use it if your data is in Internal or in any short format to use easiest way of data updating. See Internal format and XML Upload.
There is no possibility to send data in short format.
This format is used in sample ASP.NET service and in ASP.NET support objects.
Creating TreeGrid from JavaScript
The first points are the same as in creating TreeGrid from <treegrid> tag:
To your page you need to include main treegrid script GridE.js and predefined styles to the page in <HEAD> section. If these files have another url, you must use the other.
<head> <link id=GridCSS href="../Grid/Grid.css" title="GridStyle" type="text/css" rel="stylesheet"><script src="../Grid/GridE.js"> </script>
</head>Due compatibility issues, don’t use the !DOCTYPE tag with URL to switch IE to compliant mode. As this mode works only in IE 6.0+, it is not supported by the TreeGrid. See http://msdn.microsoft.com/library/default.asp?url=/workshop/author/dhtml/reference/objects/doctype.asp for more information.
Now include on the place where you would display a TreeGrid component the <div> or any other block tag. Or you can create this tag also dynamically by JavaScript. This tag is called TreeGrid Main tag. You can set style of this tag (background, border, etc.), but you must set width and height (in style) of this tag to any other value than "auto" to display TreeGrid properly. The Main tag can be also any server control to control this tag from server script, but always it needs to be a block (not inline) tag. You can also have more TreeGrids and Main tags on one page. All content of the Main tag will be overridden by TreeGrid when it is created.
The Main tag can have absolute or static position.
TreeGrid object you can create from JavaScript by global TreeGrid ( ) function. The function description (from API documentation):
TGrid TreeGrid (TDataIO D, string tag = “”, string id = “”) Creates and renders the grid. Connects the grid to the given data D.
D is object with data settings, it corresponds to <treegrid> tag attributes. TDataIO has the same properties as <treegrid> tag, see attributes section.
If the <treegrid> attributes contain “_”, this means new sub-objects in TDataIO,
for example “Data_Url” means D.Data.Url or Upload_Param_F1 means D.Upload.Param.F1.
You can create it as new TDataIO object with predefined default settings.
D can be also of string type. In this case it contains full XML source for TreeGrid to create from. And TreeGrid cannot upload data.
tag is an id attribute of main tag or main tag object itself (usually <div>) to render grid to, this is required attribute.
id is the unique id of the grid, used to identify it, especially in saving configuration to the cookies. It can be undefined if set in downloaded data.
This function also sets the grid identity.
Function returns created TGrid object. Remember, creating and rendering is asynchronous, thus at the moment of function return, the grid is not fully prepared yet.
After finish will be fired OnRenderFinish and OnRenderPageFinish or OnLoadError event.
This function is available in all versions of TreeGrid.
For creating TreeGrid dynamically you can also use the next method. You can dynamically by JavaScript fill to main tag the <treegrid> tag with attributes you want and call StartTreeGrid ( ) function. This functions calls for all <treegrid> tags it finds in document the TreeGrid ( ) function. Remember, this functions destroys all <treegrid> tags and replaces them by TreeGrid objects. This function is available in all versions of TreeGrid.
For using TreeGrid from JavaScript is the best way to use Extended JavaScript API. In Extended API version are revealed and documented all TreeGrid properties, functions, methods and events and you can control nearly any procedure done by TreeGrid.
All required files are in one directory. In default distribution is this directory “Grid\”. All files can be moved or renamed, but these changes must be registered. For every file is noted, where you have to do changes.
By default you must preset location for main script file GridE.js and style sheet file .css. All other files are by default searched in the same directory as .css style sheet.
All listed files are required, except cursor files.
All files can be changed or renamed except GridE.js.
GridE.js Main JavaScript code. You must include reference to this file in <head> section on HTML page.
(<SCRIPT src="../Grid/GridE.js"> </SCRIPT>). Don’t change this file!
Grid.css Cascade style sheet for TreeGrid look. You can change this file to change TreeGrid look.
How to change styles is described in TreeGridStyles.htm.
Remember, all other required files are searched by default in the same directory as this .css file.
You must include link to this file in <head> section on HTML page.
If you link more style sheets to your page, you must set TreeGrid style sheet’s title attribute to value “GridStyle”.
(<link href="../Grid/Grid.css" type="text/css" title="GridStyle" rel="stylesheet">).
Actual TreeGrid distribution contains four different style sheets: Grid.css, GridLight.css, GridBigger.css, GridGame.css.
Only one style sheet from them can be use at a time.
Grid.gif All images used in grid except toolbar images. Path and name you can change in input XML data, in attribute <Img Grid=””>.
Image extents are described in other attributes of tag <Img> in input XML data.
You can change these images to change grid’s look, but remember, if you resize images, you must change their extents in input XML data, tag <Img>,
also all images must have the same height and many images must have the same width.
Actual TreeGrid distribution contains three different image sets: Grid.gif (for Grid.css and GridLight.css), GridBigger.gif. GridGame.gif.
Toolbar.gif All images on grid toolbar. Path and name you can change in input XML data, in attribute <Img Toolbar=””>.
DragOne.cur Mouse cursor displayed when dragging one row or column. Path and name you can change in input XML data, in attribute <Img DragOne=””>.
DragMore.cur Mouse cursor displayed when dragging more rows. Path and name you can change in input XML data, in attribute <Img DragMore=””>.
Help.html User help for the TreeGrid. It is displayed after user clicks on ? button at control panel.
Path and name you can change in input XML data, in attribute <Cfg HelpFile=””>.
Remember, this file uses image files Grid.gif and Toolbar.gif in the same directory, therefore if you move this file, you must update hrefs in included styles.
Text.xml Data source file with all TreeGrid texts and messages and language dependent constants for formatting numbers and dates.
Path and name or place you can change in input HTML tag attributes <treegrid Text_???=””>
This file can be loaded as static file or can be generated by web page or service or can be included in HTML page.
This file is for English language.
You can translate this file to any other languages and also return appropriate language file according to client browser settings.
Defaults.xml Data source file with predefined values of all TreeGrid parameters.
Path and name and or place you can change in input HTML tag attributes <treegrid Defaults_???=””>
This file can be loaded as static file or can be generated by web page or service or can be included in HTML page.
Updates
3.2
Added <treegrid> attributes Timeout, Repeat.
3.3
Rewritten TreeGrid files section.
3.4
Added <treegrid> attribute Session
3.7
Added <treegrid> attributes Upload_Type and Upload_Attrs
3.8
Updated _Url attribute, added wildcards
4.1
Added information about <bdo> tag
4.2
Added section Creating TreeGrid from JavaScript
Updated Upload_Type and Upload_Attrs
4.3
Added Export and Export_Type
4.4
Added Check and Check_Interval