EJS TreeGrid documentation
Cell editing and changing values
<Cfg> int Editing [1] .
If and how values of grid can be edited. It does not affect rows of Kind = Filter, Group, Search.
0 – read only
Cells cannot be edited, cannot be switched to edit mode.
Bool and Radio types cannot be clicked. Enum type and Defaults list cannot be expanded.
The Date button is not displayed for Date type by default.
1 – editable
Cells can be edited. Default mode. The individual cell editability can be changed by their CanEdit attribute to 0 (read only) or 2 (preview).
Cells can be switched to edit mode and changed by user. Bool and Radio type can be changed by click.
Enum type and Default list can be expanded and value selected.
The Date button is displayed for Date type by default (can be hidden by setting the Button=””).
2 – preview
Cells cannot be changed, but they can be displayed in read only edit mode.
The cell cannot be previewed if it has set CanEdit=’0’ (read only). The CanEdit=’1’ does not change to editable!
Bool and Radio types cannot be clicked. Enum type and Defaults list cannot be expanded.
The Date button is displayed for Date type by default, but the calendar dialog displayed on click is in read only mode.
The preview mode is intended especially for multiline types (Lines) to let user to display the whole text and also select it and copy to clipboard.
The default mode is 1 (editable), you can switch all editable cells to 0 - read only or 2 - preview mode by setting the Editing attribute.
<C> <I> <cell> int CanEdit [0/1] .
If and how values in cells can be edited.
0 – read only, 1 – editable, 2 – preview. See Editing attribute.
The routine to find out the cell editability checks these points in this order:
1) If editing is suppressed (<Cfg Editing=’0’/>) returns 0, except the Row Kind is Filter, Group, Search
2) If the cell is not focusable (CanFocus=’0’) returns 0, except the cell Type is Bool or Radio.
3) Checks cell CanEdit, if it set, returns it
4) Checks row CanEdit, if it set, returns it
5) For Filter row returns 0 for Pass type and for columns with CanFilter=’0’ otherwise returns 1
6) For calculated cell returns 0
7) Checks column CanEdit, if it set, returns it
8) Returns 0 or 1 according to the cell Type, default editable types are: Text, Lines, Int, Float, Date, Enum, Bool, Radio, Pass
If point 3 – 8 returns 1 and set <Cfg Editing=’2’/> returns 2.
After points 3 – 8 it calls OnCanEdit event to change the result dynamically.
API event int OnCanEdit (TGrid grid, TRow row, string col, int mode) ,
Called to check editability of the cell dynamically.
It is called in various situations, during rendering, before start edit, on mouse hover and so on.
This handler should be very fast and short.
The mode is preset editability, 0 – readonly, 1 – editable, 2 – preview.
Return new editability or the mode.
API method int CanEdit (TRow row, string col) .
Checks if the cell can be edited, return 0 – read only, 1 – editable, 2 – preview.
A list of predefined values for the cell to let a user to choose one or more of them.
Displayed on click to button or by API.
This list can be used also for non editable cells of any Type, it does not depend on CanEdit settings.
Since 9.2 it is possible to simulate Enum value/key pairs by Html type and its Format attribute.
<C> <cell> string Button Button = “Defaults” chg 6.0.
To show right side button with Defaults list set Button=”Defaults”.
It can be shown also by Icon="Defaults"
<C> <cell> string [*] Defaults chg 6.0; upd 9.2.
A first character separated list of values to select to the cell. A user can choose one value from combo or even more values if Range is set.
Or it can be in standard TreeGrid menu format as complex menu with sub levels, sub menus, columns and so on.
It is used when set Button=”Defaults” or Icon = “Defaults” or Type=”Select”. It can be used for cell of any Type.
To show a list of predefined values while editing use Suggest list instead.
Separator can be shown as item named ‘-‘.
Since 9.2 the Defaults can be used with name/key pairs using new Format and EditFormat attributes structure for Text, Lines and Html types.
For example <C Name="A" Button="Defaults" Defaults="|one|two|three" Format="{1:'one',2:'two',3:'three'}" EditFormat="{1:'one',2:'two',3:'three'}"/> will show/edit strings one, two, three, but cell values will be 1,2,3
The list can contain special items starting with ‘*’:
*Date After click on menu item it shows calendar to select date
*Button After click on menu item it calls OnButtonClick user event for the cell
*Default Item contains default value for the cell (value from Def row).
*FilterOff Switches off the filter operator, only for filter row
*All Chooses all items for range
*None Selects empty range
*Rows... There will added more items containing values from other rows in this column according other settings:
...Variable... from variable rows (used also if no Fixed / All / Sibling is present)
...Fixed... from fixed rows
...All... from fixed and variable rows
...Sibling... from sibling rows
...Def... only from rows that have the same default (Def attribute) as the row
...DefXXX*... (since 7.0) only from rows that have its default (Def attribute) named XXX
...Visible... only visible rows
...CanFilter... (for Filter row) only rows that can be filtered according to this column
...n... maximally n most frequent values
...ColXXX*... values from another column, XXX is column name, from left must have prefix ‘Col’ and from right postfix ‘*’.
...Alphabet... (new 6.1) the menu items will be divided to submenus according to the first letter. Useful for long menus. See also DefaultsAlphabetWhite.
The menu item name is defined by <Lang><Text DefaultsAlphabet=’%d ...’/>, the %d will be replaced by the character
For example: “*RowsDef20” returns maximally 20 variable rows with the same default row.
<C> <cell> bool DefaultsServer [0] .
If set to 1, TreeGrid dynamically downloads the Defaults list from server side by <treegrid> Cell_Url settings before it displays it (after the button was clicked).
Example: Let’s have row MyRow with cell MyCol with Defaults button:
<I id='MyRow' MyColButton='Defaults' MyColDefaultsServer='1' ...
Set in your TreeGrid definition:
<treegrid Cell_Url='myscript.jsp' Cell_Data='MyData' ...
And the myscript.jsp (or .aspx, .php) will get such XML in MyData property:
<Grid> ... <Body> <B id='MyRow' Col='MyCol'/> </Body> </Grid>
And the myscript should return XML to update the Defaults list in the appropriate row cell:
<Grid> <Changes> <I id='MyRow' MyColDefaults='the prepared list'/> </Changes> </Grid>
<Cfg> string DefaultsAlphabetWhite [“!"#$%&'()*+,-./:;<=>?@[\]^_{|}”] new 6.1.
Characters ignored when grouping items by *Alphabet keyword in Defaults.
<C> <cell> int DefaultsAlphabetMin [0] new 7.0.
Minimal count of the items starting by the same character to group them, by *Alphabet keyword in Defaults.
For example if set to 2, there will not be created sub menus with one item only.
API event string OnGetDefaults (TGrid grid, TRow row, string col, string defaults) .
Called before displaying menu Defaults to get the list dynamically.
Returns original or modified defaults list.
API event void OnShowDefaults (TGrid grid, TRow row, string col, TMenu Menu, TPosition Pos) new 6.3.
Called before displaying menu Defaults to update the menu dynamically.
It can be used to do any modification in Menu, for example to sort or change position in Menu.Items array. See Menu documentation
<Actions> ShowDefaults ...F .
Displays dialog Defaults for the actual or focused cell.
API method int GetDefaultsIndex (TRow row, string col, string val = null) new 6.0.
Returns index (from 0) of actual cell value inside its Defaults array.
Returns null if the value is not in the Defaults array or the Defaults array does not exits.
If set val, compares this value instead of the cell one.
Works only for simple defaults as first character separated array, without special items (*) and not as TreeGrid Menu.
API method string GetDefaultsValue (TRow row, string col, int index) new 6.0.
Returns an item from Defaults array in the given position index (from 0).
Returns null if the index is outside defaults boundary or the Defaults array does not exits.
Works only for simple defaults as first character separated array, without special items (*) and not as TreeGrid Menu.
A list of predefined values for the cell and actual input to let a user to choose one of them.
Displayed while editing and updated whenever the input text changes. .
<C> <cell> string[*] Suggest new 6.0; upd 9.2.
A list o values to suggest them to user while editing.
It contains all items that can be suggested for the cell.
The user will see only items that contain already entered part of the value in input. The searching is case insensitive.
The Suggest can contain also the special items starting by * like Defaults menu.
Since 9.2 the Suggest can be used with name/key pairs using new Format and EditFormat attributes structure for Text and Lines types.
For example <C Name="A" Suggest="|one|two|three" Format="{1:'one',2:'two',3:'three'}" EditFormat="{1:'one',2:'two',3:'three'}"/> will show/edit strings one, two, three, but cell values will be 1,2,3
Due internal implementation the no key can be equal to value, e.g. {a:'b',b:'c'}, the b cannot be both key and value.
<C> <cell> string [] SuggestType new 6.0; upd 6.5.
Various settings for Suggest menu. Comma separated list of keywords, case insensitive
Replace – if set, replaces the actual edit input while changing selected item in the suggest menu by cursor keys.
Start – if set, shows the suggest menu also on start editing for current value
Empty – if set, shows the full suggest menu also for empty input value
All – if set, shows the full suggest menu always – it does not search the current input value
Case – (new 6.2) if set, preserves case sensitivity, shows only items that contains the text in the same case
Complete – (new 6.2) auto completes the input value if there is only one value to suggest.
Existing – (new 6.2) accepts only values existing in the actual suggest menu
Begin – (new 6.2) the suggested items must start with the value (otherwise the item is suggested if any its word starts with the value)
Separator – (new 6.4) after selecting suggested item for the last value, adds also SuggestSeparator to the end. Used only if set SuggestSeparator.
Esc – (new 6.5) escape hides the suggestion menu instead of cancelling editing.
Arrows – (new 6.5) in multiline edit the up/down arrows will be used in suggest menu. If not set, Ctrl + arrows control the suggest menu
<C> <cell> int SuggestDelay new 6.2.
Delay before the suggest menu is shown. If next key is pressed within this time, the menu is not shown for the previous text.
<C> <cell> int SuggestMin new 6.2.
Minimal count of characters in text to show the suggest menu for the text.
<C> <cell> string SuggestSeparator new 6.4.
Set for range values separated by this separator.
If set, suggest is shown separately for the individual parts of the value. After choose suggest item, it replaces the part by the item and does not end editing.
To add the separator also to the end after item is selected like in MS Outlook, set SuggestType, value Separator.
Default value is empty for normal cells, and ValueSeparator (semicolon by default) for Range cells.
It can be set also to “
” for enter as separator in multiline cells
API event string OnSuggest (TGrid grid, TRow row, string col, string val, TMenu suggest) new 6.0.
It is called whenever the value is changed by user while editing to get the appropriate defaults for the value.
The val is actual value, the suggest is the proposed suggest menu.
Return new suggest string or the suggest. The returned suggest is not searched for the val again and is displayed always the whole.
The OnSuggest is not called when set SuggestServer=’1’
<C> <cell> bool SuggestServer new 6.0.
For dynamic loading the suggest menu list from server.
If set to 1, TreeGrid downloads the Suggest attribute setting from server side <treegrid> Cell_Url settings whenever a user changes the input value while editing.
The returned suggest is not searched for the val again and is displayed always the whole.
For example you can return for cell [row id=’R1’ col=’Col1’] such XML to change the Suggest menu:
<Grid><Changes><I id=’R1’ Col1Suggest=’|One|Two|Three’/></Changes></Grid>
If you change from server also Format / EditFormat, you should set <Changed Update='32'> to not refresh the edited cell.
API event string OnGetSuggest (TGrid grid, TRow row, string col, string suggest) new 6.2.
Called to get the complete Suggest attribute once on start editing.
<I> bool Changed [0] Uploaded to server, supports Undo .
It is set to 1 when any cell value in the row has been changed. Which cell is specified by the cell’s attribute Changed.
If the changed cell value is set back to its original value, the cell and row looses the Changed flag, except is set <Cfg StoreOriginalValues=’0’/>.
After uploading changes to server or calling AcceptChanges the changed row just looses its state and becomes normal row.
<cell> bool Changed [0] Uploaded to server, supports Undo .
It is set to 1 when the cell value has been changed.
API event type OnValueChanged (TGrid grid, TRow row, string col, type val) .
Called before cell value is changed by a user input. It is called even if a user entered the same value.
This event is called when a user edited cell, selected item from Defaults or Enum list, selected date from calendar, clicked and changed Bool or Radio cell, dragged column to DropCols cells.
Use this event to change or update the entered value. To do some action after finish edit call OnEndEdit.
Return new value or the entered value val.
API event void OnAfterValueChanged (TGrid grid, TRow row, string col, type val) upd 6.0.
Called after cell value is changed by user edit, only if the value was changed to another.
Called before the changed value is shown in the cell.
Use this event to run code after cell value is modified.
<C> <cell> bool CaseSensitiveValues [1] new 6.0.
If strings are stored case sensitive.
If set to 0, the input value is always converted to lower case.
<Cfg> bool StoreOriginalValues [1] .
If all the cell values are stored before they are changed. If the values are stored and the cell value is set back to the original value, the row is marked back as not Changed.
Set it to 0 just to save memory, if you don’t need this behavior.
<Cfg> bool SaveValues [0] .
If set to 1, saves all changed cell values of all rows to cookies.
It can be used only for very small grids their changes are not uploaded to server. Usually for grids that controls something on client side.
Remember, cookies are limited to 4096 bytes for the whole page, so use this setting only for very small static tables or use PersistentCfg.
Use the smallest row ids and column names as possible (the amount of space is used: (name+1)+id+value+2 bytes per row).
Also use it only for number tables or restrict input strings length by edit mask.
API method void SetValue (TRow row, string col, type val, bool refresh = 0) .
Sets the cell value.
The val should be already type of the cell, the Date type must be set as count of milliseconds and Int and Float type should be set as JavaScript Number.
Set refresh to true to display changes in grid or call RefreshCell method.
This method updates all things around the setting value like calculations, master / detail, CopyTo, id, AutoUpdate and so on.
It does not call OnValueChanged / OnAfterValueChanged events.
For synchronized Gantt cells (like Start/End/Duration or Descendants/Ancestors) call CheckGantt before SetValue to update also the other Gantt cells.
API method void SetString (TRow row, string col, string val, bool refresh = 0) .
Sets cell values as string in data xml format, the format affects especially Date type.
Set refresh to true to display changes in grid or call RefreshCell method.
This method converts the string to value and calls SetValue.
<XML event> void OnChange (TGrid Grid, TRow Row, string Col, TEvent Event) .
Called as <Actions> or cell event when cell value is changed.
Attach the action or any JavaScript code to the cell to be run on cell value change, like <I ... Col1OnChange=’alert(“changed!”)’ ... />
The new value can be got by Get(Row,Col).
<Cfg> int InEditMode [2] chg 6.0.
If the edit mode is started on click, on double click or on character key press.
It presets actions OnDblClickCell, OnKey and OnBackspace. You can modify these actions by yourself to get more options.
It is tested also in FocusEdit action attached to OnClickCell by default.
The default actions settings corresponds to InEditMode=’2’, but without modifications of the event actions.
0 the edit mode is run only when user clicks to already focused editable cell or double clicks some editable cell or presses Enter or F2.
1 the edit mode is run when user clicks to any cell or presses character key or Enter, F2 or Backspace.
2 the edit mode is run when user clicks to already focused editable cell or double clicks some editable cell or presses character key or Enter, F2 or Backspace.
<Cfg> int EnterMode [0] new 6.0.
The Enter key behavior, if and how it moves edit cursor.
It presets actions OnEnter and OnEnterEdit. You can modify these actions by yourself to get more options.
0 Standard mode, Enter accepts value and do nothing else, no modification to OnEnter and OnEnterEdit.
1 Enter starts editing cell below, it sets <Action OnEnterEdit='AcceptEdit AND GoDownEdit,1' OnEnter='GoDownEdit'/>
2 Enter starts editing cell below and on the last row adds new row and moves to it, it sets <Action OnEnterEdit='AcceptEdit AND GoDownEditAdd,1' OnEnter='GoDownEditAdd'/>
3 Enter starts editing cell right, it sets <Actions OnEnterEdit='AcceptEdit AND TabRightEdit,1' OnEnter='TabRightEdit'/>
4 Enter starts editing cell right and on the last row and cell adds new row and move to it, it sets <Actions OnEnterEdit='AcceptEdit AND TabRightEditAdd,1' OnEnter='TabRightEditAdd'/>
To support also other cell types than the <input> ones, e.g. Enum type, don't define the EnterMode, but implement it by API event OnEndEdit like:
Grids.OnEndEdit = function(G,row,col,save,val){ if(save) setTimeout(function(){
if(row!=G.FRow||col!=G.FCol) return; G.ActionTabRightEdit(); if(G.GetType(G.FRow,G.FCol)=="Enum") G.StartEdit(); },10); }
<Cfg><C><cell> bool AcceptEnters [0] .
For Lines type cell to let input CR/LF character into cell.
For 0 the Enter key accepts changes and finishes editing like in single line text.
For 1 the Enter key inputs LF character (
). To finish editing is possible by Alt+Enter or Ctrl+Enter or click outside the cell.
<C><cell> bool CancelUnchanged [0] new 6.7.
If set to 1, it does not save the value, if the entered string was not changed by a user.
It is intended to be used when the value is changed just by entering end leaving edit mode in the cell due EditFormat or DefaultDate settings.
API variable bool EditMode read only .
If focused cell is being edited now.
It is set if the <input> or <textarea> is shown in grid or the Enum list is expanded.
It is set also if grid is in preview mode (the <input> or <textarea> is shown as read only)
<C> <cell> bool EditServer upd 6.0.
For dynamic loading cell settings and content for editing the value.
If set to 1, TreeGrid downloads the cell settings from server side by <treegrid> Cell_Url settings before it starts cell editing.
After the edit finishes, all the cell settings (but only this cell settings) are restored to original values before the new value is accepted or rejected.
The server response should contain the <Changes> with attributes to change, only the actual cell settings should be changed.
For example you can return for cell [row id=’R1’ col=’Col1’] such XML to change the type for editing:
<Grid><Changes><I id=’R1’ Col1Type=’Enum’ Col1Enum=’|One|Two|Three’/></Changes></Grid>
It will change cell type to Enum and download Enum list from server side and let a user to select the value from it.
API event bool OnStartEdit (TGrid grid, TRow row, string col) .
Called before started editing of textual cell (in <input> or <textarea>) or before Enum list is expanded.
Return true to suppress editing.
API event bool OnEndEdit (TGrid grid, TRow row, string col, bool save, string val, string raw) chg 6.0; upd 8.1.
Called before editing is finished in textual cell (in <input> or <textarea>) or before Enum list is closed.
The save is 1 if a user accepted entered value, 0 if canceled editing. The val is entered or chosen value if save = 1. For save=0 is val null.
Return true to continue editing, only if save is 1. For save = 0 the finish cannot be suppressed.
To change edited value you should rather use event OnValueChanged. Also see OnAfterValueChanged event.
(Since 8.1) The raw value is exact not converted string entered by a user
API event type OnCustomStartEdit (TGrid grid, TRow row, string col, string val, HTMLElement cell, int width) .
Use this event to create and manage your own editing control.
Called before starting editing to display the custom editing control.
val is formatted string to be displayed in edit control, cell is cell object that should be used as parent of the custom editing control, width is inner width of the cell.
If displayed custom editing control, return any nonull value – this value will be passed to OnCustomEndEdit event to let you to delete the custom edit control.
For example to use ExtJS basic TextField editing component use such framework:
Grids.OnCustomStartEdit = function(G,row,col,val,cell,width){ var I = new Ext.form.TextField({ value: val }); I.render(cell); I.focus(); I.selectText(); return I; }
Grids.OnCustomEndEdit = function(G,row,col,save,I){ var val = I.getValue(); I.destroy(); return val; }
API event string OnCustomEndEdit (TGrid grid, TRow row, string col, bool save, type custom) .
Use this event to delete your own editing control and save its value.
Called to finish editing by custom edit control returned by OnCustomStartEdit.
save is 1 when value will be changed (user accepted editing), otherwise it will be ignored. custom is the object returned by OnCustomStartEdit.
Return new value to save or null to not save even if save parameter is 1.
API event string OnGetInputValue (TGrid grid, TRow row, string col, string val) chg 6.0.
Called to convert or update cell value to string for input.
Called before the value is set to <input> or <textarea> on start edit.
Return converted or original value val.
API event string OnSetInputValue (TGrid grid, TRow row, string col, string val) .
Called to convert or update input string back to cell value.
Called before OnValueChanged, but only for cells edited by <input> or <textarea>
Return converted or original value val.
API method void StartEdit ( ) upd 6.0.
Starts editing in the focused cell. The focused cell can be set grid.Focus ( ) and read by grid.FRow, grid.FCol
Starts editing only in textual cell by <input> or <textarea> or shows Enum list.
API method int EndEdit (bool save) upd 6.0.
Finishes / cancels editing in the edited focused cell.
If save is true, saves changed value, if save is 0, discards changes and restores original value.
Returns 1 if value has changed, 0 if value has not changed, -1 to continue editing (editing cannot be finished, only for save = 1), null for error (not in edit mode)
<Actions> StartEdit Attached to many events .
Starts editing focused cell.
It fails if cell cannot be edited or there is no focused cell or some cell is already being edited.
By default it is attached to events OnClickCell, OnClickEnum, OnDblClickCell, OnKey, OnBackSpace, OnEnter, OnF2,
OnTabEdit, OnShiftTabEdit, OnTabEnum, OnShiftTabEnum, OnUpEdit, OnDownEdit. See also InEditMode settings.
<Actions> AcceptEdit Attached to events OnEnterEdit, OnCtrlEnterEdit, OnAltEnterEdit .
Ends editing, saves changed value, returns true when editing was finished, even if value was not saved.
Changes are automatically accepted also by any change of focus by navigation actions – if you want to discard changes, call CancelEdit first.
It fails if the grid is not in edit mode or editing was not finished.
<Actions> CancelEdit Attached to event OnEscEdit .
Cancels editing, discards changes, returns true when editing was finished.
It fails if the grid is not in edit mode or editing was not finished.
<C> <cell> string Edit new 9.0.
JSON settings for inline editing. It contains JSON definition of TEdit object.
TEdit event void OnStartEdit ( ) new 9.0.
Called when the TEdit object is created.
The TEdit object is accessible by this, the <input> tag by this.Tag.
The grid is accessible by this.Grid, the actual cell by this.Grid.Row and this.Grid.Col.
Example: <C Name="A" Edit=" { OnStartEdit: function() { this.Tag.className='MyInput'; } } "/>
TEdit event void OnChange (string Value, string Old) new 9.0.
Called after every change done while editing. Called for every key up or suggest select.
The Value is already shown in the input. Old is old value before change.
The TEdit object is accessible by this, the <input> tag by this.Tag.
The grid is accessible by this.Grid, the actual cell by this.Grid.Row and this.Grid.Col.
Example: <C Name="A" Edit=" { OnChange: function(V) { alert('Value '+V+' in column '+this.Grid.FCol); this.Tag.focus(); } } "/>
TEdit event void OnKeyDown (string key, Event event, bool handled) new 9.0.
Called after holding key down while editing.
It is called after functional keys like enter or esc are processed.
key is keyCode / charCode, event is standard JavaScript MouseEvent.
handled is true, if the event will be cancelled and the key will not be used in the input.
The TEdit object is accessible by this, the <input> tag by this.Tag.
The grid is accessible by this.Grid, the actual cell by this.Grid.Row and this.Grid.Col.
Example: <C Name="A" Edit=" { OnKeyDown: function(key,event) { if(key==65) CancelEvent(event); } } "/> (restricts entering 'a' key)
Editing masks can be used for any column type.
For column types Int, Float and Date are predefined default editing masks. These masks can be also changed using following attributes.
<C> <cell> int Size .
Maximal count of characters permitted to enter in <input> tag, not used for <textarea> (Lines type).
It sets <input maxLength/> attribute.
<C> <cell> string EditMask .
Mask for editing. It can be any regular expression (JavaScript RegExp string).
This is mask is checked during editing. If a user presses a key, the resulted text is checked with the mask. If the new text does not pass the mask, the cell blinks and the previous text is restored.
The mask is checked by JavaScript text.search(EditMask)>=0.
Examples of editing masks: without spaces: "^\S*$", only digits: "^\d*$", only alphanum chars: "^\w*$", max 10 digits: "^\d{0,10}$"
Remember, some validation should be done rather by ResultMask to not complicate editing – you should for example permit empty string in EditMask even if the input is required – it can be rejected by ResultMask. Or structure validations like URL, email or telephone number should be fully tested by ResultMask and by EditMask just test only applicable characters.
By EditMask you can also define some exact text structure and let user to change only some parts of it.
For example EditMask=”^Src:.*\r?\nw\:\d{0,3},h\:\d{0,3};\sx\:\d{0,4},y\:\d{0,4}$”
displays (in textarea, always on two rows):
Src:[text]
w:[int],h:[int]; x:[int],y:[int]
where [...] are the only editable sections, [text] can contain any characters, [int] can contain only digits, max 3 or 4.
Remember, default cell value must always pass the EditMask, otherwise a user will not be possible to edit it.
<C> <cell> string MaskColor [‘red’] .
The edit field blinks by this color, when user tried to write character conflicting with EditMask.
It can be color name or any other CSS color setting.
<Cfg> bool Silent [1] .
If set to 0, the grid beeps on error.
It is not supported on all browsers and also on some browsers it can required a plugin to download.
<C> <cell> string ResultMask .
Validation mask applied after finish editing or when validate cells on save. Syntax is the same as in EditMask.
When input value collides with ResultMask, the ResultText alert message is displayed and editing continues.
Examples of result masks:
number range 0 – 255: "^([01]?[0-9]?[0-9]|2[0-4][0-9]|25[0-5])$"
floating point number: "^[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?$"
email address: "^[\w\.\+%-]+@[A-Za-z0-9\.-]+\.[A-Za-z]{2,6}$"
credit card VISA: “^4[0-9]{12}(?:[0-9]{3})?$”
credit card MasterCard: “^5[1-5][0-9]{14}$”
<C> <cell> string ResultText .
Alert message displayed when value collides with ResultMask.
If not set (default), the alert message is not displayed and editing just continues without accepting the input.
<C> <cell> string ResultMessage new 7.0.
HTML message displayed as modal TreeGrid message when value collides with ResultMask.
If not set (default), the message is not displayed and editing just continues without accepting the input.
The message can be automatically hidden after ResultMessageTime milliseconds
<C> <cell> int ResultMessageTime new 7.0.
How long will be the ResultMessage shown, in milliseconds.
If not set or set to 0, the message is shown forever with OK button to hide it.
If set to negative number, the message is shown for the (positive) time, but also with OK button to hide it.
API event int OnResultMask (TGrid grid, TRow row, string col, string val) .
Called when entered value collides with ResultMask.
Return 0 – alert ResultText message and continue editing
1 – don’t alert the ResultText message and continue editing,
2 – don’t save value and finish edit,
3 – save value and finish edit
<Cfg> string[] Validate chg 6.0; upd 9.1.
If and how will be validated all result masks (ResultMask) before changes are uploaded to server on save. Comma separated list of keywords.
For custom validation you can use also OnValidate API event.
Added Validates only added new rows, to ensure that all new added rows are filled correctly
Changed (Since 9.1) Validates also changed rows, to ensure that all modified rows are filled correctly
All Validates all rows in grid, to ensure that all required inputs are filled correctly – it can be slow for large grids.
Confirm On error displays confirm message and let a user to continue or not, otherwise it displays alert and cancels saving
Focus On error focuses the first invalid cell
Edit On error starts editing the first invalid cell
Text On error inserts ResultText before ValidateText in alert or confirm message
NoColor Does not set Error attribute and color for invalid cells
There must be set keyword All or Added to do the validation.
On error calls OnValidateError event and displays alert or confirm message with ValidateText and colors invalid cells.
Not used for AutoUpdate.
<Cfg> string ValidateText .
Alert or confirm message displayed for error in validation on save.
<Cfg> string ValidateMessage new 7.0.
Alert or confirm HTML message displayed by TreeGrid message for error in validation on save.
The message can be automatically hidden after ValidateMessageTime milliseconds
If Validate contains Confirm keyword, this message is shown in standard confirm dialog.
<Cfg> int ValidateMessageTime new 7.0.
How long will be the ValidateMessage shown, in milliseconds.
If not set or set to 0, the message is shown forever with OK button to hide it.
If set to negative number, the message is shown for the (positive) time, but also with OK button to hide it.
<cell> string Error .
If set it means that the cell contains invalid value.
The cell is colored red and as tool tip is displayed the Error string.
The Error attribute is set by Validate on save and it is cleared after cell value changed.
It can be returned also from server in on server validation. In this case the server must also clear it after successful upload in next response.
API event bool OnValidate (TGrid grid, TRow row, string col, bool err) .
It is called for every cell to validate its value on saving, only if set Validate attribute.
The err is error result of ResultMask validation, if any, otherwise 0.
Return 0 ok, 1 error.
API event int OnValidateError (TGrid grid, TRow[] rows, string[] cols) .
Called on validation error when saving. When set Validate attribute.
Return 0 - alert or confirm message and cancel or continue saving, depending on user confirmed the saving or not
1 - cancel saving, no alert shown
2 - continue saving, no alert shown
rows and cols are invalid cells that do not match their ResultMask.
<Actions> Validate Attached to event OnClickButtonSave .
Validates data according to settings in Validate.
Checkbox displayed usually in tree in main column between tree and cell text.
It has two direct states 0 unchecked and 1 checked.
Parent row shows state of its children. It shows 1 checked if all children are checked, 0 unchecked if all children are unchecked and 2 unknown if there are both the checked and unchecked children.
On click to parent checkbox it changes all child values to 1 checked or 0 unchecked.
If the cell is not editable, the icon is checked / unchecked by click to any part of the cell. To check / uncheck the icon still only by clicking to icon itself, set:
<Actions OnClickSideCheck="" OnDblClickSideCheck=""/> (to disable the original actions called for the whole cell click)
and to your column or cell add the actions like: <C ... OnClickSide="Focus,SetChecked" OnDblClickSide="SetChecked" ... />
<C> <cell> string Icon Icon = “Check” new 9.3.
To show left side checkbox set Icon="Check"
It can be set also as right side button by Button=”Check”.
<cell> int Checked [0] new 9.3 .
Value for Icon="Check".
0 - unchecked, 1 - checked, 2 - unknown
To upload this value to server define new column <C Name="XXXChecked" Visible="0" CanHide="0"/>, where XXX is name of the column with the Icon="Check"
<Actions> SetChecked ...F Attached to event OnClickSideCheck new 9.3 .
Called on click to the Check icon, changes the Checked attribute / icon state to 0 / 1. It updates also all related parent and child Checked states.
API method void SetChecked (TRow row, string col, int value) new 9.3 .
Changes the state of given Check icon / Checked attribute. It updates also all related parent and child Checked states.
If row is null, it changes all checkboxes in the column to the value. In this case value can be 0 or 1.
col is the column with the Check icon / Checked attribute.
value can be 0 or 1 to set this value. If value is null, it changes the Checked state from 2 or 1 to 0 and from 0 to 1. value should not be 2.
API method void ResetChecked (TRow row, string col) new 9.3 .
Updates this checkbox value according to its children. Updates also the children in the deep levels.
Call it in OnLoaded like Grids.OnLoaded = function(G){ G.ResetChecked(); } if you want to specify only leaf rows' Checked value to '1' to calculate all the parent values.