Global settings

TreeGrid documentation

Status messages

Which TreeGrid status messages will be suppressed.

1	Messages during loading and updating grid on start and on reload
2	1 + Informational messages shown when longer task is run
3	2 + Message inside loading or rendering page
4	3 + Error message if TreeGrid cannot show

Minimal width of TreeGrid status messages, in pixels.
To place centered message to the same position and to not change the width according to message text.
If set to 1 it centers all the grid messages in the whole page. Useful for small grids.
If set to 2 it also disables the whole page while showing the message.
If set to 1 it all the grid modal messages can be moved by mouse dragging.
TreeGrid core must be compiled with LibMouse module, that is not included by default.
Called when any grid status message is displayed. message is the tag showing the text.
It is called after the tag is shown, but with display="none".
Called before grid is disabled (and optional status message is shown).
Called after grid is enabled (and any status message is hidden)
Displays modal message centered inside main tag
It hides previously displayed message. When message is displayed, grid is disabled.
Shows only messages with importance > SuppressMessage.
(Since 13.0) If set type = 1, it disables the grid visually, usually as 50% transparent. type = 3 = 1 + 2.
(Since 13.0) If set type = 2, it animates the showing and hiding the message. Message is animated only if no JavaScript is running during the animation time.
Displays modal message centered inside main tag with given buttons.
The message is shown in 10ms timeout, so it can be used within handlers that hide message after their finish.
If set time, the message is hidden in next timeout after the time milliseconds elapsed.
If time is 0, the message is shown forever, if in this case the buttons are not set, shows OK button to hide it.
If func is set, it is called after the message is hidden or button is clicked. It has format: function func (result); The result is 0 - timeout, 1 - the first button, 2 - the second button, 3 - ..., -1 Enter, -2 Esc
The buttons is array of button names shown in the message. They can be direct button captions, or values from <Lang><MenuButtons/></Lang> tag, see Text.xml.
Shows only messages with importance > SuppressMessage.
For example: grid.ShowMessageTime("Do you want to do this action?",2000,function(result){ if(result==1) alert("Clicked yes"); },["Yes","No"]);
Hides grid modal message and enables grid. If no message is shown, does nothing.
Disables grid, the grid is grayed and does not respond to user actions.
(Since 13.0) If set hard = true, it disables the grid visually, usually as 50% transparent. Enables disabled grid.
Replacement for standard JavaScript window.prompt function. It is asynchronous.
text is message text (can be HTML), default is default input value, width is optional width in pixels of the message box.
function func (val) is called after a user enters the value. The val is entered text or null when user clicked to Cancel button.
Shows modal progress message with caption and text texts.
If set cancel, shows cancel button with the cancel caption. If clicked to this button, the message is hidden and the grid has set property CancelProgress = 1.
pos is actual progress completed from all cnt units.
Call the ShowProgress method whenver the progress changes with different pos
Set it before JavaScript modal dialog like alert, confirm or prompt to 1 and after call set it back to 0.
For example: Grids.Alert=1; alert("Error"); Grids.Alert=0;
It ensures that grid will not loose focus because of the alert dialog.

Configuration menus

TreeGrid contains four predefined configuration menus:
Settings menu in <MenuCfg>, Columns menu in <MenuColumns>, Print / PDF menu in <MenuPrint> and Export menu in <MenuExport.
A list of items to display in the configuration menu. It sets also their order.
See available items in particular menus above.
To show separator, place item named "-".
The individual items can be hidden also by setting its name to 0.
Since 9.3 it is possible to disable individual option for the Enum item if set its text to empty string. Defined in Text.xml.
Default value depends on the menu, defined in Defaults.xml.
Full JSON menu definition used instead of Items.
If set, splits the menu rows and columns items to given number of columns.
If set to 0, splits the menu if it has more than 25 visible items.
If set, splits the menu configuration and options items to given number of columns.
If set to 0, it is set to Columns/0.66.
If set to 1, sorts all columns according to alphabet and not by their sections and merges to them also side pagers, if present Pagers item.
If set to 2, sorts all rows according to alphabet and not by their sections.
If set to 3, sorts both columns and rows.
For 0 never hides items that cannot be changed, just shows them disabled.
For 1 hides all items that cannot be changed and will not be processed, but shows disabled items that cannot be changed, but will be processed (for Print and Export).
For 2 hides all items that cannot be changed.
Which row and column attribute will be tested to display them in menu.
For MenuCfg and MenuColumns it is "CanHide", for MenuPrint "CanPrint and for MenuExport "CanExport".
Html string displayed in Cols menu part for this column. If not set, the column caption is displayed.
Html string displayed in Rows / Head / Foot / Space menu part for this row. If not set, the row Name or value in NameCol cell or row id is displayed.
Shows given configuration menu.
source is the grid tag that contains the menu definition, it can be grid.MenuCfg, grid.MenuColumns, grid.MenuPrint or grid.MenuExport.
If the user clicks to OK, it calls function func (TMenu Menu), where Menu is the TMenu object.
options named array of groups of custom menu items to replace items in source, it is possible to read the options changes in the Menu parameter in function func.
Returns the created menu or null for error.
Called before the configuration menu is created.
Menu is not initialized menu, it is possible to change or define its Items or other attributes.
source is menu object definition, it can be: grid.MenuCfg, grid.MenuColumns, grid.MenuPrint or grid.MenuExport.
options named array of groups of custom menu items to replace items in source, e.g. Print or Export options.
Return true to not show the menu.
Called before configuration menu is displayed, Menu is initialized TreeGrid menu with all items to display.
It is possible to use the event to add custom items to the menu.
Return true to not show the menu. For parameters see OnCreateMenu.
Called after the configuration menu button OK is clicked, before the changes are saved.
Return true to not save the changes. For parameters see OnCreateMenu.
Called after the configuration menu is closed. saved is true if the changes were saved. For parameters see OnCreateMenu.

TreeGrid settings menu

Shows and changes grid and Gantt options. Can also choose visibility of columns and rows.
Defined in <MenuCfg /> tag, texts defined in <Lang><MenuCfg /></Lang>.
Shown by action ShowCfg attached to click to Cfg toolbar button.

Available items

Column groups: ColsCaption, Cols (all columns with CanHide>0), PagersCaption, Pagers (all side pagers with CanHide>0),
Row groups: SpaceCaption, Space (all solid space rows with CanHide>0), RowsCaption, Head (all head rows with CanHide>0), Foot (all foot rows with CanHide>0), Rows (all variable rows with CanHide>0),
Configuration groups: GanttCaption, GanttCfg (all Gant configuration items), CfgCaption, Cfg (all grid configuration items).
Individual Cfg items: ShowDeleted (show deleted rows), ReversedTree (child items above parents), AutoSort (auto sort rows after change), SortClick (sorting behavior on click to header), AutoUpdate (auto update changes to server), CheckUpdates (periodically download changes from server), Scrollbars (scrollbars on tablet), Scroll (scrolling behavior on tablets) , MouseHover (hover objects under mouse), ShowDrag (show dragged object below mouse cursor), ShowPanel (show left row panel column), ShowPager (show first side pager), ShowAllPages (show all pages or one page), ShowButtons (icons or text on toolbar buttons).
Individual GanttCfg items: GanttCheckDependencies (restrict circular dependencies), GanttCheckExclude (starting tasks on holidays), GanttCheck (incorrect manual inputs), GanttCorrectDependencies (auto schedule tasks), GanttDirection (schedule from start or finish), GanttStrict (schedule tasks method), GanttCorrectDependenciesFixed (auto schedule also the changed task), GanttFixComplete (schedule also already started tasks), GanttCorrectOutsideBounds (schedule tasks outside project bounds), GanttBaseProof (move objects before project start), GanttFinishProof (move objects after project finish), GanttBasePreferred (project start is preferred to constraints), GanttFinishPreferred (project finish is preferred to constraints), GanttMinSlack (minimal slack for critical task), GanttErrSlack (minimal slack bound for error task), GanttSeparateSlack (calculate critical path individually), GanttHideExclude (show holidays in chart).
Shows configuration menu defined in <MenuCfg />.
All settings loaded from <MenuCfg> tags.
Called before the default configuration is loaded, when clicked to Defaults button in the options menu. Return true to not load it.
Replaced by OnCreateMenu Replaced by OnShowMenu Replaced by OnSaveMenu

Columns visibility menu

Can change visibility of columns and since 12.1 also rows. Since 12.1 it can also show and change grid and Gantt options.
Defined in <MenuColumns/> tag, texts defined in <Lang><MenuColumns/></Lang>.
Shown by action ShowColumns attached to click to Columns toolbar button.

Available items

The same as in TreeGrid settings menu.
In fact it can show the same items as TreeGrid options menu, the only difference is that Reset/Defaults button is replaced by Clear/Show all button and different API events are called.
Shows the column visibility menu.
All settings loaded from <MenuColumns> tags.
Replaced by ShowCfg, note it has different parameters!
Replaced by <MenuCfg Columns/>.
Replaced by <MenuCfg Sort/>.
Replaced by OnShowMenu.
Replaced by OnSaveMenu.
Deprecated, use OnSaveMenu instead.
Called when user presses OK button on columns menu. Before any updates in data or display.
cols is array of changed columns, with string index as column name and value as its new visibility.
Return true to suppress changes.
Replaced by OnCloseMenu.

Print / PDF menu

Can choose printed columns and rows and set print options.
Defined in <MenuPrint/> tag, texts defined in <Lang><MenuPrint/></Lang>.
Shown by action Print attached to click to Print toolbar button, only if set PrintCols attribute.
Shown by action ExportPDF attached to click to ExportPDF toolbar button, only if set PrintPDFCols attribute.

Available items

Column groups: ColsCaption, Cols (all columns with CanPrint=1,2),
Row groups: SpaceCaption, Space (all solid space rows with CanPrint=1,2,5,6), RowsCaption, Head (all head rows with CanPrint=1,2,5,6), Foot (all foot rows with CanPrint=1,2,5,6), Rows (all variable rows with CanPrint=1,2),
Print groups: OptionsCaption, Options (all base print options), SizeCaption, Size (print page size options).
Individual Options items: PrintRows (maximum rows per page), PrintPageRoot (start page always by root row), PrintExpanded (print all rows expanded), PrintFiltered (print all rows (unfiltered)), PrintSelected (print selected rows only), PrintVisible (print visible Gantt only).
Individual Options items for PDF only: PDFName (file name), PDFFormat (actually not used), PDFText (actually not used)
Individual Size items: PrintPageSize (paper size), PrintPageOrientation (portrait/landscape), PrintMarginWidth (page margin width (mm)), PrintMarginHeight (page margin height (mm)), PDFFitPage (fit to one page), PrintDPI (DPI (PPI) ratio), PrintWidth (page width (px)), PrintHeight (Page height (px)), PrintResults (calculates printed pages count).
The Options and Size individual items cannot be used in the Items / Menu, they can be used only as attribute to hide the item by setting the attribute value to 0!
All settings loaded from <MenuPrint> tags.

Export menu

Can choose exported columns and rows and set export options.
Defined in <MenuExport/> tag, texts defined in <Lang><MenuExport/></Lang>.

Available items

Column groups: ColsCaption, Cols (all columns with CanExport=1),
Row groups: RowsCaption, Head (all head rows with CanExport=1), Foot (all foot rows with CanExport=1), Rows (all variable rows with CanExport=1),
Export groups: OptionsCaption, Options (all export options).
Individual Options items: ExportName (file name), ExportFormat (file extension), ExportExpanded (export all rows expanded), ExportFiltered (export also filtered rows), ExportOutline (create Excel outline), ExportIndent (indent tree levels)
Individual Options items for XLSX only: ExportSelectedRows (export only selected rows), ExportSelectedCols (export only selected columns), ExportSelectedCells (export only selected cells), ExportFixedRows (freeze head rows), ExportFixedCols (freeze left columns), ExportEmpty (export also empty cells)
All settings loaded from <MenuPrint> tags.

Default Toolbar

Toolbar is standard Space row and has all Space row and cell attributes.
Default TreeGrid toolbar is defined by root <Toolbar> tag in Defaults.xml.

Buttons visibility

The default toolbar buttons are defined in file Defaults.xml, in <Toolbar> section.
Here is defined also their xxxVisibleFormula that specifies when the button is shown.
To hide any default toolbar button set its name to 0, for example <Toolbar Add='0'/>.

Buttons actions

The default toolbar button actions are defined in <Actions> tag as OnClickButtonXXX, where XXX is the button name, for example <Actions OnClickButtonAdd="AddRowEnd"/>.
The default toolbar button actions are defined in Defaults.xml.

Adding custom buttons to toolbar

It is possible to add new buttons to toolbar like to any other Space row into Cells array. Because Toolbar already defines many cells, it is better to define custom CellsXXX attribute and control the placement by the XXX as index, for example:
<Toolbar Cells05Custom="Custom1" Cells65Custom="Custom2"
Custom1Type="Button" Custom1Button="Button" Custom1="Custom 1" Custom1OnClick="alert('Custom 1 clicked')"
Custom2Type="Button" Custom2Icon="Test.gif" Custom2OnClick="alert('Custom 2 clicked')" />
For more button types see Button type. It is also possible to show any other cell types (like Text, Int, Select,...) on Toolbar.
If the default toolbar is visible.
In trial version this attribute is ignored.
Toolbar position in table.
-1 - above table, 0 - above Head, 1 - between Head and Body, 2 - between Body and Foot, 3 - between Foot and vertical scrollbar, 4 - under vertical scrollbar, 5 - under table
-1, 0, 4, 5 are spanned for whole grid, including vertical scrollbar and pager,
1, 2, 3 are spanned only for columns - the vertical scrollbar and pager are placed right side.
The Kind can be Toolbar, Toolbar1, Toolbar2, Toolba3, Topbar, Topbar1, Topbar2, Topbar3.
It specifies just style of the toolbar. Set to Topbar when placing on top. Set it Toolbar1 or 2 when there are two bottom toolbars.
To place Toolbar outside the grid to any HTML tag on page. If set, the Space attribute is ignored.
It is the id of HTML tag where to render the row.
The width of the external space row is still preserved to be the same as the actual main table width.
In trial version this attribute is ignored.
Since 12.0 the Toolbar does not define the Cells, but more CellsXXX.
If you define the Cells, it removes all default Toolbar buttons and uses only the cells defined in the Cells.
Groups of Toolbar cells. Every group contains comma separated list of cells.
The final order of the cells on Toolbar is done by sorting the CellXXX groups by the names, always as strings.
To add new button to Toolbar, define new CellXXX group with the new cells. Choose the XXX to place the new cells to desired place.
The individual Toolbar cells can be hidden also by setting its name to 0, see next attributes.
Empty cell is for alignment.
By default Toolbar defines these CellXXX groups in Defaults.xml:
Cells10Gantt = "Correct"
Cells20Data="Import,Save,Reload,Repaint,Print,ExportPDF,Export"
Cells30Manipulate="Undo,Redo,Add,AddChild,AddCol,Join,Split,Outdent,Indent,ExpandAll,CollapseAll"
Cells40Sheet="Left,Center,Right,Top,Middle,Bottom,Bold,Italic,Underline,Strike,RotateLeft,RotateRight,WrapText,Size,ColorText,ColorShadow,ColorBackground,Border,Format"
Cells50GanttZoom="ZoomIn,ZoomOut,ZoomFit"
Cells60Cfg="Sort,Calc,Columns,Cfg,Help,Debug"
Cells70Styles="Styles,GanttStyles,Sizes,Scales"
Cells80Right = "Empty,Formula,Resize"
Button for uploading pending changes to server. Set it 0 to hide the button.
It can be shown only when set <treegrid/bdo Upload_Url or Upload_Tag/>.
Button for reloading data from server. All the pending changes are lost. Set it 0 to hide the button.
Cannot be shown in Detail grid.
Button for repainting all pages. Useful when too many pages are rendered and grid becomes slow. Set it 0 to hide the button.
It can be shown only when set Paging and AllPages.
Button for creating printable version and printing it. Set it 0 to hide the button.
Shown always
Button for exporting grid data to Excel or CSV. Set it 0 to hide the button.
It can be shown only when set <treegrid/bdo Export_Url/>.
Button for adding or copying rows. Set it 0 to hide the button.
It can be shown only when permitted Adding.
Button for adding or copying rows into row's children. Set it 0 to hide the button.
It can be shown only when permitted Adding and MainCol is set.
Button for enabling / disabling sorting. It is a switch button and has value of Sorted attribute. Set it 0 to hide the button.
It can be shown only when permitted Sorting.
Button for enabling / disabling calculating grid. It is a switch button and has value of Calculated attribute. Set it 0 to hide the button.
It can be shown only when permitted Calculating.
Button for expanding all rows. Set it 0 to hide the button.
It can be shown only when set MainCol.
Button for collapsing all rows. Set it 0 to hide the button.
It can be shown only when set MainCol.
Button for showing columns menu to choose visible columns. Set it 0 to hide the button.
Shown always.
Button for showing configuration menu (MenuCfg) to set various grid configuration. Set it 0 to hide the button.
Shown always.
Button for displaying TreeGrid user help page (Help.html). Set it 0 to hide the button.
Shown always.
Button for showing debug window. Set it 0 to hide the button.
It can be shown only when set <treegrid/bdo Debug/>.
Controls visibility of all Style... buttons for choosing TreeGrid CSS style.
0 - no style buttons, 1 - style radio buttons, 2 - (new 7.0) styles combo
Formula on toolbar, just to simplify showing some calculation result on toolbar.
You can add also any other custom cells and set their Formula attribute and have more calculated cells on toolbar.
Set the Formula to the formula to calculate, like <Toolbar Formula='count()+" rows"'/>
Special button for resize grid. Set it 0 to hide the button.
The special icon for resizing is displayed if set <Cfg ResizingMain/> regardless on setting this Resize button.
This button just indents the Toolbar buttons from right to not overflow the resizing icon.
All settings loaded from <Toolbar> tags.

Language and regional settings (Text.xml)

All TreeGrid texts, messages, alerts and language dependent settings are stored in Text.xml.
You can translate this file to all languages you need and provide to visitors appropriate file according to their language settings.
Url to Text.xml is set by <treegrid/bdo Text_Url/>
In Text.xml are the attributes marked according to TreeGrid version in which were added.

The most of language settings is set in <Lang> tag, the rest in <Toolbar>, <Panel> and <Header>.

You can define or redefine any particular or even all settings outside the Text.xml in any other input XML, in appropriate tags.
For example to change text for deleting row set <Lang><Alert DelRow='Do you want to delete the row %d ?'/></Lang>
All pure text settings. Used for standard alert and confirm dialogs.
If the particular text is set to empty string, the message is not shown and the confirm dialog returns true or false according to particular logic.
The message can contain some variable information like row or column name, count of rows and so on. This information replaces the %d or %1, %2, etc. string in the message.
If there are more variable information, they replace one by one the %d strings in the message.
What message can contain variable information you can see from its text in Text.xml.
All HTML texts in grid. Usually text of status messages displayed in grid.
If the particular text is set to empty string, the message is not shown.
The message can contain some variable information like row or column name, count of rows and so on. This information replaces the %d string in the message.
If there are more variable information, they replace one by one the %d or %1, %2, etc. strings in the message.
What message can contain variable information you can see from its text in Text.xml.
Gantt chart texts, the same syntax as <Text>.
All action texts in cell popup menu.
If the particular text is set to empty string, the item is not shown.
The message can contain some variable information like row or column name, count of rows and so on. This information replaces the %d string in the message.
If there are more variable information, they replace one by one the %d or %1, %2, etc. strings in the message.
What message can contain variable information you can see from its text in Text.xml.
Popup dialog buttons, for menu and calendar. Pure texts.
All possible items in popup Copy / Add menu.
Replaced by <MenuCell> All item names in options menu.
All item names in columns menu.
All item names in print menu.
All item names in export menu.
All operator names in Filter operator menu.
All language settings for formatting date, time and numbers.
Contains predefined formats and item names (like day or month names).
Predefined formats are global for whole page, for all grids on one page.
For attribute description see Number localization and Date localization.
Tooltip texts for all standard Toolbar buttons
Tooltip texts for all standard Panel buttons
Tooltip texts for all standard Panel buttons in header.
Since 12.0 it was renamed from PanelHeaderxxxTip.
Actual language settings loaded from <Lang> tags.

Useful API functions

Returns size of browser's window (not the whole body), client area without scrollbars, returns [width, height]
Returns scroll of body, returns [left,top]
Converts event.clientX, event.clientY to coordinates relative to elem, returns [left,top]
Returns relative position of element in its parent, returns [left,top]
Cancels propagation and/or prevents default of event.
type = 0 - both, 1 - cancels propagation only, 2 - prevents default only.
Returns computed style of the element.
Creates internal XML document from string. This document can be iterated by DOM functions.
This document does not provide attributes childNodes and xml.
Escapes the string to show it in HTML code. Replaces the & < ' " characters by entities.
It is set to 1 if TreeGrid is run on touch screen.
Calls given code in timeout, similarly to standard JavaScript setTimeout, but with extended behavior.
The code will not be called if the grid is cleared or reloaded during the timeout time.

code	is JavaScript code as string or JavaScript function to be called.
time	is the delay in milliseconds, after this time will be the code called. Note, it is not exact value, the code can be called later if the browser is busy. The browser must be idle (no running JavaScript) to call the delayed codes.
ident	is unique string to identify this timeout. It is required parameter. It can be null, if the code is string, in this case it will have the code value.
	If the SetTimeout is called with the same ident again before the timeout expired, it calls only one code, the new or the old depending on the flags setting.
flags	bit array of settings.
	1. bit (&1). If set, it calls the code immediately from the SetTimeout, if there was no call with the same ident for at least time milliseconds.
	2. bit (&2). If set, it does not replace the old not yet run code with the same ident. It also does not reset the timeout.
	If not set, it replaces the not yet run code with the same ident by the new code and resets the timeout to time.
data	is custom JavaScript object passed to code. If the code is string, it is accessible in parameter named data. If the code is function, the function is called with the data as its first parameter.

Returns true if the code was already called (due type&1), false if the code will be called, or null if it did not replace the previous code due type&2.

Help file

Path and filename of TreeGrid help file. It is shown when a user clicks to Help button on toolbar.
It is relative to actual page URL.
Show TreeGrid user help page