Using
TreeGrid on HTML page
TreeGrid v3.7
Updates
3.7
Added <treegrid> attributes Upload_Type and Upload_Attrs
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 Layout_Url="../Data/CalcDef.xml" Data_Url="../Data/CalcData.xml">
</div>
</body></html>
<treegrid> attributes
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
<treegrid> data sources
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. What can be uploaded see Upload_Type.
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 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.
“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.
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=”
Used
only when Url is set.
int Type 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)
5 – All fixed rows, 6 – All variable rows, 7 – All rows. For 5-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, these 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 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 = 5,6,7.
If this attribute
is omitted, fills all rows’ attributes. For large grids it can be significantly
slower.
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.