Using
TreeGrid on HTML page
TreeGrid
v3.4
Updates
3.4
Added <treegrid> attribute Session
3.3
Rewritten TreeGrid files section.
3.2
Added <treegrid> attributes Timeout, Repeat.
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
The Main tag can have
absolute or static position.
Into the grid
TreeGrid is created when document is loaded. It uses event body.onload. If you set event handler for <body onload=...> in html
or by any script on page (window.onload)
you must call from this handler
function TreeGridStart(
) to create TreeGrids on page from tags <treegrid>.
If you have problems with communication with server, set Debug parameter to 3 to see server responses.
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 Data_Url="../data/TreeGridSample.xml"> </treegrid>
</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
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"
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"
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"
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"
Destination
for upload changed data from grid. Uploaded can be only changed rows. If not
set, data cannot be uploaded.
<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 without form submit
and TreeGrid Auto update option can
be set.
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 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.
“Soap” – data are uploaded in SOAP XML envelope. This is usual for
communication with web services
“Form” – data are uploaded like form
submit in format application/x-www-form-urlencoded.
“Get” – for download only, parameters
are sent by HTTP GET method, in url string.
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 are data encoded to string (&
and <,> are replaced). The web service’s parameter is type of string.
For
1 data are uploaded as XML, the web
service’s parameter is type of XmlDocument (or similar type).
Used only when Url set and Method is “Soap” or Tag is set. Default is 0.
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.
For example:
Data_Param_Test=”
Used
only when Url is set.
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
<treegrid
Layout_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 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.
Data are sent as “application/x-www-form-urlencoded;
charset=UTF-
This method is supported by most servers or XML web services.
Usually you need to set Upload.Data
string to parameter name
Soap – SOAP envelope.
Data are sent as “text/xml; charset=UTF-
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.
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.
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.