FAQ
TreeGrid v5.9
TreeGrid is client component and runs in web browser. Therefore it can be used on any web server with any server script environment. TreeGrid can be even used on local file system, for example in on CD HTML presentations.
You need to include TreeGrid script and css styles to your page.
You need to include <treegrid> tag into your page.
You need to generate input XML data to create TreeGrid from.
Optionally you can process uploaded XML data on server.
Optionally you can write your JavaScript functions and event handlers to extend TreeGrid capabilites.
See Four point to use TreeGrid on web page.
You don’t need to write any JavaScript code to use TreeGrid.
You just need to generate and optionally process TreeGrid XML input / output data.
You can create TreeGrid from JavaScript by API TreeGrid () function.
Or you can generate by JavaScript the <treegrid> tag and call API StartTreeGrid () function.
You need to set few <treegrid> attributes.
If you use AJAX communication, you need to set Upload_Url attribute to url where to upload changes. And you need to set Upload_Data to parameter name, where the uploaded data will be stored.
If you use Submit communication, you need to set Upload_Tag to id of hidden input where to store uploaded data. This input must be placed on some form, because the form will be submitted when user clicks Save button.
If you want to use Internal format, you need to set Upload_Format=”Internal”, because default upload format is DTD.
See other <treegrid> data source attributes.
Yes, you can use feature AutoUpdate. You can set in input XML by <Cfg ... AutoUpdate=’1’ .../>. An user can set auto update from configuration menu. Remember, setting from configuration menu has higher priority then AutoUpdate attribute.
You can set many options what to upload by <treegrid ... Upload_Type ...>
When using AJAX communication, you can set <treegrid ... Upload_Param_MyParam1=’MyVal’ ...>. In uploaded data there will be parameter MyParam1 with value MyVal.
You can also send your custom data when downloading data or layout, set <treegrid Data_Param_MyParam1=’MyVal’>.
When using submit communication, you can your custom data to other (hidden) inputs on the same form as hidden input that will get TreeGrid data.
You can reload grid by API functions TGrid.Reload or TGrid.ReloadBody.
Use ReloadBody to reload only data, not layout or defaults. Before call, you can change downloading parameters in TGrid.Data.Data property.
Use Reload to reload all TreeGrid data from current or new location.
Of course, you can still use standard page reloading, but for AJAX communication is better to use functions mentioned above.
TreeGrid.dll/so is support library to manage XML data for very large grids when using server paging. It is not required, but helper library.
See description of server paging, see description of TreeGrid.dll/so.
The uploaded row is fully identified by its id attribute.
See Row’s identification tutorial.
The row’s id attribute <I ... id=’’ .../> must be set if you want to update changes to server. You can set it on server or you can let TreeGrid to generate it from other row’s attributes.
By its id is row identified on server. This is the only information to identify row, so you need to prepare the id to uniquely identify the row and to provide all information about row to server to know which data will be updated.
There are many options to generate and use ids in TreeGrid, see Row’s identification tutorial.
The grid’s id attribute <Cfg ... id=’’ .../> must be set, if you want to save configuration to cookies. By this id can be grid identified also in JavaScript API.
When new row is added, its id is generated as unique primary key (set by <Cfg IdNames>). New id uses characters from <Cfg IdChars=’’/> attribute. New id is created as the first id after the <Cfg LastId=’’/> attribute. See also <Cfg IdPrefix IdPostfix/>.
To know parent row of child rows, you can set <Cfg FullId=’1’/> and to new ids is also added id of their parent.
See all ways to generate ids in Row’s identification tutorial.
You need to set in input XML data attribute <Cfg MainCol=’’/> to column name where tree will be displayed.
Child row tags in XML data are included to parent row tags: <I id=’Parent’> <I id=’Child1’/> <I id=’Child2’/> </I>
You need to write two JavaScript routines with using TreeGrid API.
a) Create TreeGrid from your data
1) Download your data from server in your format
2) Convert downloaded data to TreeGrid XML input format
3) Create TreeGrid by TreeGrid API function (or create <treegrid> tag and use StartTreeGrid API function).
b) Upload changes to server
Write event handler OnSave. In this handler you can get changes in XML by API function TGrid.GetChanges or TGrid.GetXmlData.
Or if you don’t want to parse XML in JavaScript, you can get changes by iterating all TreeGrid rows by GetFirst, GetNext methods and checking Changed/Added/Deleted/Moved attributes.
Convert changes to your format and send them to server. For AJAX communication you use TGrid.Communicate API function.
If you use AJAX communication, you need to accept changes by TGrid.AcceptChanges API function.
And return true from the handler.
See this paragraph.
See this paragraph.
AJAX is asynchronous background communication, Submit is standard upload by page form submit.
In most cases is AJAX better communication, because sends data in background, without changing other page content. In AJAX you can also upload changes immediately after edit, without clicking Save button.
Many developers still use old Submit communication, because they have prepared code for this communication and also server side developing environments still prefer the old communication. But switching to AJAX is very easy.
See description of both methods.
The preferred format for all data is Internal format, but as input format TreeGrid accepts all four formats.
Due backward compatibility is default output format the DTD format. To use internal format for upload, you need to set <treegrid ... Upload_Format=”Internal” ...>
If your XML data are very long and download is slow, you can reconsider to use some short format.
If you want to use DTD schema when processing your XML, you can use the DTD format.
Layout source is set by <treegrid ... Layout_ ...>, data source are set by <treegrid ... Data_ ...>.
TreeGrid does not differ between layout and data when loading. Layout is loading first. The only difference is in API function ReloadBody, this functions reloads only data, not layout.
You can use the only one data source or both. But recommended using is this:
Layout XML contains information about table/tree structure, like configuration, columns or defaults. Layout XML is often static file, because it is independent on data in database.
Data XML contains all data from database. In XML it usually contains only rows. It is usually generated from database and contains all data (rows) that are editable and can be uploaded back to server.
For changing background colors see next question.
a) Globally, for all cells you can modify file Grid.css, sections “Cells” and “Cell contents”. See TreeGrid styles.
b) To change style for individual cell, you can use cell attributes ClassOuter, ClassInner and ClassEdit.
The class name must exists, you can define your own classes in Grid.css or you can modify and use predefined classes GTextB, GNumberB, GTextM, GNumberB that are not use by TreeGrid are prepared for custom use.
To change cell class for whole column, set these attributes in default row.
c) You can also add HTML code before and after the value. This HTML code can contain style settings. Use cell attributes HtmlPrefix and HtmlPostfix.
Example: <I Col1HtmlPrefix=’<b style="color:red; text-align:left;">’ Col1HtmlPostfix=’|</b>’/>
d) To change style dynamically by JavaScript you can use API event OnGetClass. In this event handler you can return class name for individual cell, event dynamically.
In OnGetClass event always test the input class and don’t replace classes from different sections. Always remember you must preserve cell extents, always test your settings, because not all settings are possible.
Example:
Grids.OnGetClass = function (G,row,col,cls){
if(col=="A" && cls=="GNumber") return "GNumberB";
return cls;
}
e) In rare situations, when you want to use different HTML code for individual parts in number or data format, you can also include HTML tags in column or cell Format attribute. In this case you have to set <Cfg NoFormatEscape=’1’/>
Example:
<Cfg NoFormatEscape=’1’/> ...
<C Name='X' Type='Float' Format='
#0.00;"<span style='color:red;'>"-#####0.00"</span>"
'/> // Negative numbers in red
<C Name='Y' Type='Date' Format='
"<span style='color:blue;'>"ddd"</span>" m/d/yyyy
'/> // week day in blue
Cell background color is specific, because background colors are used by TreeGrid to show row’s or cell’s state.
So background colors cannot be changed by CSS style classes.
a) Globally you can change predefined state background colors in input XML (or in Defaults.xml) in tag <Colors>.
b) You can define alternate colors for odd rows to improve table lucidity. The alternate colors are ideal in pure table. But the alternate colors can slow down sorting and filtering in table. Set Alternate attribute in <Colors> tag. You can also set AlternateRepeat attribute to change spaces between alternate colored rows.
c) You can define specific color for row or cell by row Color or cell Color attribute. This color is used instead of Default color and is modified by state color modifiers.
d) You can change background color dynamically by JavaScript API events OnGetColor and OnGetDefaultColor. Pay attention to the two events differnce.
Example:
Grids.OnGetColor = function (G,row,col,r,g,b){
if(col=="A") return "rgb("+r+","+(g-30)+","+b+")";
}
Alignment is set in Grid.css file, in “cell content” section. It is different according to column type. By default are numbers right aligned (GNumber) other types are left aligned. You can use cell attribute ClassInner to set another class for cell.
For individual data or even cell, you can change alignment in column or cell HtmlPrefix and HtmlPostfix attributes. See changing styles, point c).
You can also change it for individual cell by OnGetClass API event, see changing styles, point d).
You can set type for individual cell by <I ... ColumnNameType=’...’ .../>, where ColumnName is column name where the cell resides. This is internal format notation, see also DTD format.
You can also set many other setting for individual cells, see documentation.
In your formulas you can use any JavaScript expression. There are many predefined function, but if you want to calculate something special you can write your custom function in JavaScript and call it from your formula.
See Custom functions.
TreeGrid has export function to XLS file by button on toolbar.
For small tables you can use predefined simple export. In this way TreeGrid generates whole report by itself and sends this report to your server script defined in <treegrid Export_Url>. And your server script must just return these data back to client. There are predefined server scripts for ASP, ASP.NET, JSP and PHP, look at Export.xxx file in the Examples directory, server script subdirectory.
For large tables and / or tables with server side paging or child paging you can generate the report by your server script. Set Export_Type=”1”. In this way the grid sends to server just information about sorting, filters and columns. There are examples for server scripts in example Ajax Table with server paging.
TreeGrid also supports copying content to and from clipboard. The format is compatible with Microsoft Excel and also with many other programs.
Therefore you can select some or all rows in TreeGrid, copy them to clipboard by Ctrl+C and paste them to Excel. Or you can select some rows in Excel, copy them to clipboard and paste them to TreeGrid by Ctrl+V.
As developer you can control the copying by cell attribute CopyValue, column attribute CanCopy and API events OnGetCopyValue.
TreeGrid has print function accessible by button on toolbar. This function opens new window with printer friendly content of grid and shows Print dialog.
As developer you can control printing by <Cfg> attributes PrintPrefix and PrintPostfix and API event OnPrint.
You cannot set key value for Enum type. The Enum type is always integer index to array, zero based. To server is always sent only the index, not any string.
TreeGrid supports some features for resizing:
<C RelWidth/> You can set relative width for column, the column(s) fill the whole width of main tag.
<I RelHeight/> You can set relative height for user fixed row, the row(s) fill the whole height of main tag.
<Cfg MaxHeight MaxWidth /> You can maximize extents of main tag. Main tag fills the rest of page.
<Cfg ResizingMain /> You can permit user to resize main tag
<Cfg NoScroll /> TreeGrid does not use its own scroll, but uses standard scrolling in the main tag.
<Cfg NoHScroll NoVScroll/> TreeGrid resizes main tag to show all the content without scrolling
You can prohibit editing for individual cell, whole row, whole column or even for whole grid. You can use CanEdit attribute (for whole grid the Editing attribute). For example <I ... ColNameCanEdit=’0’ ... />, where ColName is column name where the cell resides.
You can also change editing dynamically by JavaScript in event OnCanEdit.
All TreeGrid features can be disabled. It can be done usually in <Cfg> tag, for example <Cfg Editing=’0’ Deleting=’0’ Adding=’0’ Selecting=’0’ Sorting=’0’ Dragging=’0’ Copying=’0’ ColResizing=’0’ ColMoving=’0’/>
TreeGrid is not by default accessible by tab key. To permit this, you need to write some JavaScript code:
1) Write TreeGrid event handler OnTabOutside. In this event focus previous or next control in tab order.
2) Write HTML event handler onkeydown for previous and next control in tab order and in the code call TreeGrid function TabInside.
TreeGrid supports variable row height to use for example higher text areas. You can set it by <Cfg ... VarHeight=’1’ ... />.
Remember, setting VarHeight to 1 can slow down TreeGrid rendering, because the height of all rows must be computed.
For fixed rows there is not displayed any tree icon.
For variable root rows you can hide the icon by setting <Cfg ... HideRootTree=’1’ ... />
You can also hide tree lines and show only expand/collapse buttons by <Cfg ... NoTreeLines=’1’ ... />.
You can prohibit expanding/collapsing of some rows and hide their expand/collapse button by <I ... CanExpand=’0’ ... />
You can span cells in one row together (horizontal span), but you cannot span rows together (vertical span).
For spanning cells see <I ... Spanned ... > and cell’s Span and Merge attributes. See also the spanning tutorial.
Defaults are predefined values and settings for rows. See their description.
You can use column/cell type “Html”. It displays in cell any html code. The cell is always read only.
You can also use user row <I Kind=’User’/>. This row displays any html for all cell together. The row is always read only.
If you want only extend display of your (editable) values, you can use <C Format=’’/> with html code, see formatting values.
All the TreeGrid texts are in file Text.xml. You can translate or change any text in this file.
You can iterate all variable rows in grid by GetFirst / GetFirstVisible and GetNext / GetNextVisible. You can get all fixed rows by GetFixedRows. You can get all selected rows by GetSelRows. You can get row by its id attribute by GetRowById.
You can get cell value from the row by GetValue or GetString methods.
You can set cell value by SetValue or SetString methods. To display changes in grid, you need to refresh cell by RefreshCell.
Don’t confuse selected rows and focused rows/cells. Selected rows are rows marked yellow and there can be more selected rows in table. Focused row/cell is only one with cursor.
The focused cell is set by FRow and FCol properties. You can write event handler OnFocus, that is fired when cursor is moved to another cell.
All selected rows you can get by API function GetSelRows. You can write event handler OnSelect, that is fired when user changes selection of some row. If individual row is selected you can see by row.Selected attribute.
Don’t confuse selected rows and focused rows/cells. Selected rows are rows marked yellow and there can be more selected rows in table. Focused row/cell is only one with cursor.
You can move cursor to new location by API function Focus.
You can mark selected rows in input XML data by <I ... Selected=’1’ ... /> attribute. You can select row by API function SelectRow or all rows by SelectAllRows.
By TreeGrid API you can show hidden row by ShowRow or Focus, hide row by HideRow, add new row by AddRow, mark row deleted by DeleteRow and delete row by DelRow.
You can get row by its id by GetRowById (or you can get row by another method).
You can show hidden row by ShowRow. Or you can show it and move cursor to it by Focus.
To just scroll to some row, you can use ScrollIntoView or access some page by GoToPage.
By TreeGrid API you can show hidden column by ShowCol, hide column by HideCol, add new column by AddCol and delete column by DelCol.
You can use AddPage methods.
To display another page, you can use GoToPage, GoToNextPage, GoToPrevPage.
You can also use methods for showing rows like ShowRow, Focus or ScrollIntoView.
You can write TreeGrid event handler OnClick or OnDblClick or even OnRightClick.
You can also catch standard HTML events for main tag and there you can use helper functions like GetClick to see what was clicked.
There are many TreeGrid events you can catch. For editing there are OnStartEdit, OnEndEdit, OnValueChanged, OnAfterValueChanged.
For adding and deleting there are OnCanRowAdd, OnRowAdd, OnCanRowDelete, OnRowDelete.
You can use event OnRenderFinish that is fired when TreeGrid layout is rendered.
Or you can use event OnRenderPageFinish that is fired when any page was rendered. When there is not use paging, it is fired only once when TreeGrid is fully rendered.
There is no default menu for the cell. You can use JavaScript and catch right click in TreeGrid event OnRightClick and create and show popup menu by function ShowMenu. You can also use simpler function ShowDialog if you want to generate your own HTML for menu.
Yes, you can provide your own filtering in event handler OnCanFilter and return false.
Or you can use the default filtering and control which row will be filtered in event handler OnRowFilter.
You can use TGrid.GetCell to return given cell. Remember, never modify TreeGrid HTML representation manually, always use API functions to modify data.
Yes, you can run any function from toolbar by TGrid.ControlPanel.Click method.
You forgot to include main TreeGrid script “GridE.js” into your page header or this file is missing or not accessible by browser.
Or you forgot to include any <treegrid> or <bdo> tag into your page, into main tag.
These files are required files for TreeGrid, see list of all required files.
By default these files are searched in the same directory as CSS file.
You forgot to include TreeGrid style sheet “Grid.css” into your page header or its url is wrong or you forgot its rel=”stylesheet” attribute.
Or files Defaults.xml or Text.xml are missing or moved elsewhere or not accessible by browser.
If these files are located elsewhere then in directory with Grid.css you can set their location by <treegrid> attributes Defaults_Url and Text_Url. You can even include them to your page directly to attribute Defaults_Data and Text_Data (if you don’t use ActiveX objects in IE).
Every grid must contain at least one named variable column and one (even empty) page.
The minimal layout in XML is <Grid><Cols><C Name=’...’/></Cols><Body><B/></Body></Grid>.
The error means, that in all your input data there are missing variable columns or page(s).
Remember, XML is case sensitive and TreeGrid ignores all unknown tags (and all their content) and attributes in data. Therefore if you use <Grid><body><B></body></Grid>, the XML is well formed but there is missing <Body> tag, because <body> is different (and ignored) tag. And TreeGrid displays error message.
If you don’t know, what is sent to TreeGrid from server, you can show this by using Debug attribute <treegrid ... Debug=’3’ ... >
You forgot to set data source attribute in <treegrid> tag. TreeGrid does not know where to load data from. You have to set at least one data source attribute from Data_Url, Data_Tag, Data_Data, Layout_Url, Layout_Tag, Layout_Data. Usually you need to set the only one Data_xxx source or one Data_xxx and one Layout_xxx data source. See description of data sources.
You set bad url in <treegrid> data source, in Data_Url, Layout_Url or Page_Url. Or this url is not accessible by browser.
All TreeGrid inputs XML must be well formed. To test if your XML is well formed, just open your XML in your browser directly.
This situation occurs also when your server script in AJAX communication returns its error message instead of XML data.
The often bug is also that your server script in AJAX communication returns HTML page instead of XML data.
If you don’t know, what is sent to TreeGrid from server, you can show this by using Debug attribute <treegrid ... Debug=’3’ ... >
This is known bug in Internet Explorer. It cannot be solved exactly.
But you can set <treegrid> attribute Upload_Param_SSL=”True”. It works on SSL2 (but not on SSL3). But why, nobody knows.
You can set <Cfg ... DebugCalc=’1’ .../>. It alerts all formulas that raise exception or return NaN, with values of input parameters.
The calculations are described in documentation.
The common problems are:
You forgot to set Calculated attribute for calculated row
The CalcOrder list attribute does not contain the column name for the calculated cell.
Formulas use standard JavaScript syntax, the formula must be valid in JavaScript (operators, strings, function calls, ...)
In input XML values you used bad number format like “0.0”. It must be “0”, because “0.0” is used as string.
You used bad parameter name. Remember, all parameters like column names and row ids are case sensitive and cannot start with number, see Column names.
Some settings like column width, visibility and position and configuration settings are stored to cookies on client. And loading stored settings has higher priority then settings in input XML.
To suppress loading settings from cookies you can these ways:
Set <Cfg ... SuppressCfg=’1’ .../> It suppresses all loading from cookies
Set <Cfg ... Version=’X’ .../> Set Version to higher value. It suppresses loading for one time, to delete old configuration, when you changed layout.
Set <Cfg ... xxxLap=’1’ .../> It suppresses loading for the xxx attribute, like SortColsLap.
Also don’t forget, all attribute names are case sensitive.
By default TreeGrid uploads date and time values as number of millisecond since 1/1/1970. This is standard result of function JavaScript function getTime().
By default are these integers treated as local time, you can set <Lang><Format GMT=’1’/></Lang> to change it to GMT.
If you want to send date and time values as strings, you need to set <Cfg ... DateString=’1’ ... />. The date and time will be uploaded in English format “mm/dd/yyyy hh:mm:ss” (hh=0-23).
If your browser has cache setting to not check newer page versions, you should control HTTP cache on server side when you are generating XML for AJAX (or may be also HTML for submit).
You need to append to HTTP response header this or similar setting:
Response.AppendHeader("Cache-Control","max-age=1, must-revalidate");
It is syntax for ASP.NET C#, for other languages is similar.
TreeGrid does not contain any security issue.
TreeGrid never uses any problematic or forbidden objects like FileSystem.
TreeGrid never access other pages then those you filled in input XML.
TreeGrid never shows any links to other pages than you filled in input XML. The only exception is link to www.treegrid.com on bottom toolbar, but this link can be hidden in purchased version.
Of course, you cannot use in JavaScript any authorization or password validation. These inputs can be filled to and sent by TreeGrid, but always must be validated on server.
All TreeGrid code is written by our company, therefore we guarantee, that it does not contain any problematic code.
Remember, JavaScript code can be dangerous only if you use some unnamed code from unofficial web sites. The JavaScript code can present security risk only if it is written with intention to do this. And TreeGrid as official commercial product never does such things.
In Internet Explorer 5.0, 5.5 and 6.0 is AJAX communication done by ActiveX object XmlHttpRequest. This object is marked as safe.
But if your visitor has forbidden using all ActiveX objects, you cannot use AJAX. But you can always use standard synchronous communication by page submit. But AJAX is now standard communication on internet. See also NoTryActiveX property.
The XmlHttpRequest is the only ActiveX object the TreeGrid uses (and only for AJAX).
There are few questions for you to answer:
It will be used on one server only. - You can use BASIC license (at up to 10 pages).
I want to use it any my application and I am a single developer. – You can use PERSONAL license. (licensed to your name).
We want to use it only in one our application. – You can use STANDARD license (for up to four developers).
We want to use it in any our application. – You can use GRAND license (for up to eight developers).
If you want to write some JavaScript code to extend TreeGrid or control its functions, you will probably need to purchase also Extended API together with license. See API documentation, if you expect to use any function or property available in Extended API only.
I want to use TreeGrid only for small tables, with maximally 33 rows. – You can use free FreeGrid component (no Extended API available for this component).
I want only basic table functions, without tree functionality, filtering, calculations, dragging or paging. – You can purchase PureGrid component.
I want only tree functionality with maximally three columns. – You can purchase PureTree component.
I want to have component without any restrictions in functionality. – You need to purchase original TreeGrid component.
If you need source codes for learning purposes or you want to modify sources, you have to purchase them.
If you just need a warranty, that you will get sources if TreeGrid project and support will be stopped, you can choose Extended support or Source code escrow. See next question.
If you purchase Extended support, you will also get source code if CoqSoft will be bankrupt.
The difference is in warranties. Source code escrow is guaranteed by U.S. company Lincoln-parry SoftEscrow (called escrow agent). In this case, you will get TreeGrid sources in case of described event from the escrow agent independently on CoqSoft.
On other hand, Source code escrow is just escrow, but Extended support also contains free upgrades and priority in requests.
Therefore the two options cannot be substituted and you can purchase even both, if you need warranties and free upgrades.
You can always upgrade from lower license to higher (from Personal only to Grand), or you can purchase Extended API or source code to your license (source code only for Standard and Grand).
All these upgrades are done for 125% from difference between prices.
Upgrades to higher version are done for free for minor versions and for 40% for major versions. When you purchase Extended support, all these upgrades are for free.
The TreeGrid is commercial product and must be purchased before using it. This sentence means that you pay only for server or developer license and never for using TreeGrid by your customers or visitors.