TreeGrid v6.0

Global settings

TreeGrid documentation index

 

 

Status messages

 

<Cfg> <treegrid / bdo> int SuppressMessage        [0]                                                                                         chg 6.0.

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

 

<Cfg>                int          MessageWidth                        [140]                                                                                                   .

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.

 

API event          void       OnShowMessage (TGrid grid, HTMLElement message)                                                           .

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”.

 

API event          void       OnDisable          (TGrid grid)                                                                                                                 ,

Called before grid is disabled (and optional status message is shown).

 

API event          void       OnEnable            (TGrid grid)                                                                                                                  .

Called after grid is enabled (and any status message is hidden)

 

API method      void       ShowMessage            (string message, int importance = 2)                                                            .

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.

 

API method      void       ShowMessageTime           (string message, int time = 0, function func = null, string[] buttons = null, int importance = 4)   new 7.0 .

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. Their can be direct button captions, or values from <Lang><MenuButtons/></Lang> tag, see Text.xml.

Shows only messages with importance > SuppressMessage.

 

API method      void       HideMessage ( )                                                                                                                                  .

Hides grid modal message and enables grid. If no message is shown, does nothing.

 

API method      void       Disable     ( )                                                                                                                                               .

Disables grid, the grid is grayed and does not respond to user actions.

 

API method      void       Enable       ( )                                                                                                                                               .

Enables disabled grid.

 

API method      void       Prompt      (string text, string default, function func, int width)                                                                .

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.

 

global variable bool       Grids.Alert                                                                                                                                new 6.1 .

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 menu

 

This menu shows and let a user change various TreeGrid configuration settings.

All these settings are saved to cookies are persistent between page loads.

This menu is by default shown on click to Toolbar cell Cfg.

 

The individual menu items can be shown / hidden by attributes in root tag <MenuCfg>.

The menu item text are set in Text.xml, in tag <Lang><MenuCfg/></Lang>

 

<MenuCfg>      string    Items                                     [...]                                                                                                                   .

A list of items to display in the configuration menu. It sets also their order.

Default value of Items is:             ShowDeleted,AutoSort,SortClick,AutoUpdate,CheckUpdates,Separator1,MouseHover,ShowDrag,ShowPanel,ShowPager,ShowAllPages

The individual items can be hidden also by setting its name to 0, see next attributes.

 

<MenuCfg>      bool       ShowDeleted               [1]                                                                                                                    .

Displays option Show deleted rows (in red).

It can be shown only when set <Cfg Deleting=’1’/>

 

<MenuCfg>      bool       AutoSort                           [1]                                                                                                                    .

Display option Auto sort rows after change.

It can be shown only when set <Cfg Sorting=’1’/> and is not possible to server paging.

 

<MenuCfg>      bool       SortClick                           [1]                                                                                                                    .

Display option Sorting click.

It can be shown only when set <Cfg Sorting=’1’/>.

 

<MenuCfg>      bool       AutoUpdate                  [1]                                                                                                                    .

Display option Auto update changes to server.

It can be shown only when set <treegrid/bdo Upload_Url/>. It cannot be displayed in detail grid.

 

<MenuCfg>      bool       CheckUpdates           [1]                                                                                                                    .

Display option Check for updates on server every ...

It can be shown only when set <treegrid/bdo Check_Url/>. It cannot be displayed in detail grid.

 

<MenuCfg>      bool       Separator1                      [1]                                                                                                                    .

Display horizontal line as separator between two sections.

 

<MenuCfg>      bool       MouseHover                 [1]                                                                                                                    .

Display option Mouse hover.

Shown always

 

<MenuCfg>      bool       ShowDrag                       [1]                                                                                                                    .

Display option Show dragged object.

It can be shown only when set <Cfg Dragging=’1’/> or <Cfg ColMoving=’1’/>

 

<MenuCfg>      bool       ShowPanel                     [1]                                                                                                                    .

Display option Show row's left panel.

Shown always

 

<MenuCfg>      bool       ShowPager                    [1]                                                                                                                    .

Display option Show pages.

It can be shown only when used Paging and set <Pager CanHide=’1’/>

 

<MenuCfg>      bool       ShowAllPages            [1]                                                                                                                    .

Display option Show all pages.

It can be shown only when used paging.

 

<Actions>                      ShowCfg                           Attached to event OnClickButtonCfg                                                                       .

Shows configuration menu

 

API event          bool       OnCreateCfg   (TGrid grid)                                                                                                   new 6.0 .

Called after user clicked to show cfg button, before the configuration menu is created and shown.

You can show / hide the menu items by setting them grid.MenuCfg.

Return true to not show the menu.

 

API event          void       OnShowCfg     (TGrid grid, TMenu Menu)                                                                            chg 6.0 .

Called before configuration menu is displayed, Menu is TreeGrid menu with all items to display.

 

API event          void       OnCfgChanged         (TGrid grid)                                                                                                    .

Called when user presses OK button on configuration menu, after all changes have been set in data, but before saving to cookies and before any updates in display. Fired even if the user did not make changes.

 

API variable      object    MenuCfg                                                                                                                                                   .

All settings loaded from <MenuCfg> tags.

 

Default Toolbar

Default TreeGrid toolbar is defined by root <Toolbar> tag in Defaults.xml.

Toolbar is standard Space row and has all Space row and cell attributes.

 

<Toolbar>        bool       Visible       [1]                                                                                                                                               .

If the default toolbar is visible

In trial version this attribute is ignored.

 

<Toolbar>        int          Space         [4]                                                                                                                                               .

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.

 

<Toolbar>        string    Kind             [“Toolbar”]                                                                                                                    new 7.0 .

The Kind can be Toolbar, Toolbar1, Toolbar2, Topbar, Topbar1, Topbar2.

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.

 

<Toolbar>        string    Tag                                                                                                                                                                  .

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.

 

<Toolbar>        string[]  Cells            [...]                                                                                                                                             .

Comma separated list of cells on Toolbar.

You can list some or all of the standard cells defined in <Defaults.xml> and / or custom cells that you defined later. You specify also their order here.

Default value of the Cells is:              “Save,Reload,Repaint,Print,Export,Add,AddChild,Sort,Calc,ExpandAll,CollapseAll,Columns,Cfg,Help,Debug,

StyleTitle,StyleStandard,StyleLight,StyleOffice,StyleModern,StyleBorders,StyleRobust,StylePlain,Empty,Formula,Resize”

The individual cells can be hidden also by setting its name to 0, see next attributes.

Empty cell is for alignment.

 

<Toolbar>        bool       Save             [ ]                                                                                                                                                .

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/>.

 

<Toolbar>        bool       Reload       [ ]                                                                                                                                                .

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.

 

<Toolbar>        bool       Repaint     [ ]                                                                                                                                                .

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.

 

<Toolbar>        bool       Print             [ ]                                                                                                                                                .

Button for creating printable version and printing it. Set it 0 to hide the button.

Shown always

 

<Toolbar>        bool       Export        [ ]                                                                                                                                                .

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/>.

 

<Toolbar>        bool       Add               [ ]                                                                                                                                                .

Button for adding or copying rows. Set it 0 to hide the button.

It can be shown only when permitted Adding.

 

<Toolbar>        bool       AddChild             [ ]                                                                                                                                  .

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.

 

<Toolbar>        bool       Sort              [ ]                                                                                                                                                .

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.

 

<Toolbar>        bool       Calc              [ ]                                                                                                                                                .

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.

 

<Toolbar>        bool       ExpandAll          [ ]                                                                                                                                  .

Button for expanding all rows. Set it 0 to hide the button.

It can be shown only when set MainCol.

 

<Toolbar>        bool       CollapseAll       [ ]                                                                                                                                  .

Button for collapsing all rows. Set it 0 to hide the button.

It can be shown only when set MainCol.

 

<Toolbar>        bool       Columns              [ ]                                                                                                                                  .

Button for showing columns menu to choose visible columns. Set it 0 to hide the button.

Shown always.

 

<Toolbar>        bool       Cfg                [ ]                                                                                                                                                .

Button for showing configuration menu  (MenuCfg) to set various grid configuration. Set it 0 to hide the button.

Shown always.

 

<Toolbar>        bool       Help              [ ]                                                                                                                                               .

Button for displaying TreeGrid user help page (Help.html). Set it 0 to hide the button.

Shown always.

 

<Toolbar>        bool       Debug        [ ]                                                                                                                                                .

Button for showing debug window. Set it 0 to hide the button.

It can be shown only when set <treegrid/bdo Debug/>.

 

<Toolbar>        int          Styles         [1]                                                                                                                                 upd 7.0 .

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

 

<Toolbar>        string    Formula                                                                                                                                                      .

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/>

 

<Toolbar>        bool       Resize        [ ]                                                                                                                                                .

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

 

API variable      object    Toolbar                                                                                                                                                       .

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>

 

<Lang>                          <Alert>                   XML tag                                                                                                                       .

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 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.

 

<Lang>                          <Text>                     XML tag                                                                                                                       .

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 strings in the message.

What message can contain variable information you can see from its text in Text.xml.

 

<Lang>                          <Gantt>                 XML tag                                                                                                         new 6.0 .

Gantt chart texts, the same syntax as <Text>.

 

<Lang>                          <MenuButtons>       XML tag                                                                                           new 6.0 .

Popup dialog buttons, for menu and calendar. Pure texts.

 

<Lang>                          <MenuCopy>  XML tag                                                                                                         new 6.0 .

All possible items in popup Copy / Add menu.

 

<Lang>                          <MenuCfg>       XML tag                                                                                                                       .

All item names in configuration menu.

 

<Lang>                          <MenuFilter>  XML tag                                                                                                                       .

All operator names in Filter operator menu.

 

<Lang>                          <Format>             XML tag                                                                                                                       .

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.

 

<Toolbar cell> string    Tip                                                                                                                                                     new 6.0 .                                      

Tooltip texts for all standard Toolbar buttons

 

<Panel>            string    PanelxxxTip                               xxx is name of Panel button like Select                             new 6.0 .                                      

Tooltip texts for all standard Panel buttons

 

<Header>          string    PanelHeaderxxxTip           xxx is name of Panel button like Select                              new 6.0 .                                      

Tooltip texts for all standard Panel buttons in header

 

API variable      object    Lang                                                                                                                                                              .

Actual language settings loaded from <Lang> tags.

 

 

Useful API functions

 

global func.      int[2]      GetWindowSize        ( )                                                                                                                    .

Returns size of browser’s window (not the whole body), client area without scrollbars, returns [width, height]

 

global func.      int[2]      GetWindowScroll   ( )                                                                                                                    .

Returns scroll of body, returns [left,top]

 

global func.      int[2]      EventXYToElement            (Event event, object elem )                                                              .

Converts event.clientX, event.clientY to coordinates relative to elem, returns [left,top]

 

global func.      int[2]      ElemToParent             (object elem, object parent)                                                                          .

Returns relative position of element in its parent, returns [left,top]

 

global func.      void       CancelEvent    (Event event, int type = 0)                                                                                          .

Cancels propagation and/or prevents default of event.

type = 0 – both, 1 - cancels propagation only, 2 - prevents default only.

 

global func.      Style     GetStyle (object Elem)                                                                                                                            .

Returns computed style of the element.

 

global func.      object    CreateXML         (string str)                                                                                                                    .

Creates internal XML document from string. This document can be iterated by DOM functions.

This document does not provide attributes childNodes and xml.

 

API method      string    Escape      (string str)                                                                                                                                 .

Escapes the string to show it in HTML code. Replaces the & < ‘ “ characters by entities

 

Help file

 

<Cfg>                string    HelpFile   ["Help.html"]                                                                                                                              .

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.

 

<Actions>                      ShowHelp                                                                                                                                                .

Show TreeGrid user help page