EJS TreeGrid documentation
Events and actions
TreeGrid contains fully customizable Key and Mouse schema, all key and mouse actions (JavaScript callbacks, event handlers) are set in Defaults.xml in <Actions> tag and can be changed by a user.
a) TreeGrid mouse events
Every part (row, cell, button, etc.) in grid has its own name and you can attach an action for it:
click, double click, right click, mouse down, mouse up, mouse over, mouse out, mouse move, start drag, drag over (over when dragging).
To the action name is attached key prefix when some control key is held down: “Shift”, “Ctrl”, “Alt” and their combinations.
The actions can be defined in global <Actions> tag, attached in global Grids array by JavaScript, defined for specific <C>, <I> or cell.
The JavaScript action has always this definition: function (TGrid Grid, TRow Row, TCol Col, TEvent Event).
b) TreeGrid key events
There are three different key actions called when a user presses key in Focused grid: regular, edit, edit multiline.
The action name is the key name defined in <Actions> tag.
To the action name is attached key prefix when some control key is held down: “Shift”, “Ctrl”, “Alt” and their combinations.
The actions can be defined in global <Actions> tag, attached in global Grids array by JavaScript, defined for specific <C>, <I> or cell.
The JavaScript action has always this definition: function (TGrid Grid, TEvent Event).
c) TreeGrid API events
TreeGrid provides many JavaScript callbacks for many actions done in grid, like OnSelect, OnRenderFinish, OnClick and so on.
The actions are attached to global Grids array by JavaScript.
The JavaScript actions have various definitions.
d) TreeGrid calculations and formulas
Every row or cell attribute can be calculated, so it can have attached JavaScript formula to calculate the value. Basically the formulas are used to calculate cell values, but also other attributes can be calculated.
e) Standard JavaScript events
You can attach any JavaScript event handler like onclick to any tag on HTML page and provide some action with TreeGrid using its API. The grid is accessible by global Grids array.
You can attach JavaScript events also to HTML code inside grid cells, but if there are many such cells, it can remarkably slow down the grid, so you should reconsider it and use another event option.
The event name consists from: On + key_prefix + event_name + target.
For example OnMouseOverTree, OnShiftClickRow, OnCtrlShiftRightClickCell
OnClick – when the target is clicked (any mouse button is pressed and released). Called after OnMouseUp. Called only if mouse did not move between button press and release.
OnDblClick – when the target is double clicked (left mouse button is pressed, released, pressed and released). Called after OnMouseUp. Called only if mouse did not move between button press and release.
OnRightClick – when the target is clicked by right mouse button, similar to OnClick. Since 7.0 it is just OnClick event with “Right” mouse button prefix.
OnMouseDown - when any mouse button is pressed on the target
OnMouseUp - when any mouse button is released on the target
OnMouseOver – when mouse is moved to the target. For every target is the event run only once (opposite to standard JavaScript onmouseover event). See also OnDragOver.
OnMouseOut – when mouse leaves the target. For every target is the event run only once (opposite to standard JavaScript onmouseout event).
OnMouseMove – whenever mouse moves above the target. It is called many times, so the handler should be very simple and fast.
OnDrag – when dragging should be started on the target – when user holds down any mouse button and slightly moves mouse
OnDrop – (new 7.0) when dragging successfully finished on the target. Called only if the dragging successfully started and OnDrag returned true.
OnDragOver – called instead of OnMouseOver when dragging is active
Shift, Ctrl, Alt, ShiftCtrl, ShiftAlt, CtrlAlt, ShiftCtrlAlt
(since 7.0) Right, ShiftRight, CtrlRight, AltRight, ShiftCtrlRight, ShiftAltRight, CtrlAltRight, ShiftCtrlAltRight. The Right prefix cannot be used for DblClick event.
(since 7.0) Middle, ShiftMiddle, CtrlMiddle, AltMiddle, ShiftCtrlMiddle, ShiftAltMiddle, CtrlAltMiddle, ShiftCtrlAltMiddle. The Middle prefix cannot be used for Click and DblClick events.
Remember, not all key prefixes are possible in all browsers. Some browsers use some prefixes for built-in functions.
If there is no action defined for the actual key prefix, it is called an action without prefix, if it exists.
For example there is called OnCtrlShiftRightClick event, if there is no action defined for this event, it is called OnClick.
Touch event names (for iPAD) (new 7.0)
There are available events for one or more fingers touching down the pad.
If defined more handlers for the same event with different fingers, it is called only one (even if it returns false) for the specified count of fingers.
For example if defined Click, Click1 and Click3 events, for 1 finger is called Click1, for 2 fingers also Click1, for 3 or more fingers is called Click3. The Click is never called if defined Click1.
All the affected fingers must be on the grid, not outside on the pad!
No key or button prefixes for the touch events available!
OnClick – when the target is clicked (touch down and up, without move), it is the same as standard mouse click and is shared with mouse events
OnClick1 – when the target is clicked by one finger
OnClick2 – when the target is clicked by two fingers (called when two fingers are down on touch pad and one of them releases the pad). For the other finger release or move is not called any other touch event.
OnClick3 – when the target is clicked by three fingers (called when three fingers are down on touch pad and one of them releases the pad). For the other two fingers release or move is not called any other touch event.
OnMouseDown - when the target is touched down by some finger, called for every finger, it is the same as standard mouse down and is shared with mouse events
OnMouseDown1– when the target is touched down by some finger, called for every finger.
OnMouseDown2– when the target is touched down by some finger and there is already another finger on the pad, called for every finger, except the first one.
OnMouseDown3– when the target is touched down by some finger and there are already other two fingers on the pad, called for every finger, except the first two.
OnMouseUp - when the target is released by some finger, called for every finger, it is the same as standard mouse down and is shared with mouse events
OnMouseUp1 - when the target is released by some finger, called for every finger
OnMouseUp2– when the target is released by some finger and there is still another finger on the pad, called for every finger, except the last one.
OnMouseUp3– when the target is released by some finger and there are still other two fingers on the pad, called for every finger, except the last two.
OnDrag – when dragging should be started on the target – when user touches down the pad and slightly moves the finger, it is the same as standard mouse drag and is shared with mouse events.
OnDrag1 – when the target is dragged by one finger
OnDrag2 – when the target is dragged by one finger while there is down another finger on the pad. The dragging is done only by one finger, moving of the other finger is ignored.
Moving is done by the finger that first moved enough to start dragging.
OnDrag3 – when the target is dragged by one finger while there are down other two fingers on the pad. The dragging is done only by one finger, moving of the other fingers is ignored.
OnDrop – when dragging successfully finished on the target. Called only if the dragging successfully started and OnDrag returned true. It is the same as standard mouse drop and is shared with mouse events.
OnDrop1 – when dragging by one finger successfully finished on the target.
OnDrop2 – when dragging by two fingers successfully finished on the target, the finger count is got in time of start dragging, by the OnDrag.
OnDrop3 – when dragging by three fingers successfully finished on the target, the finger count is got in time of start dragging, by the OnDrag.
OnDragOver – called during dragging for every target the moving fingers visit. It is the same as standard mouse drag over and is shared with mouse events.
OnDragOver1 – called during dragging for every target when dragging by one finger.
OnDragOver2 – called during dragging for every target when dragging by two fingers, the finger count is got in time of start dragging, by the OnDrag.
OnDragOver3 – called during dragging for every target when dragging by three fingers, the finger count is got in time of start dragging, by the OnDrag.
Every point in grid belongs to one or more targets. For one point in grid can be run more events, for different targets.
The targets are classified into 12 groups, every point in grid can have only one target per group.
To see what targets are assigned to grid points, set <treegrid>/<bdo> Debug attribute to “event” and hover the grid.
The assigned action are called in the order 0 – 11, if any of the actions succeeds, the next actions are not called.
0) Edge – the edge of the cell, now implemented only for header cells
Inside / Resize (bottom right edge in grid, for resize grid) / HeaderLeft / HeaderRight / PagerHeaderLeft / PagerHeaderRight
HScrollLeft (edge between left and middle scrollbar) / HScrollRight (edge between middle and right scrollbar)
1) Special
Sort / SortUp / SortDown (sorting icon or the whole header cell depending on <Cfg SortIcons/> setting)
Radio1 / Radio2 / Radio... (individual Radio type buttons)
DropCol1 / DropCol2 / DropCol... (individual columns in DropCols type, the empty space is the last DropCol)
PagerPage1 / PagerPage2 / PagerPager... (individual pages in right side pager, without empty space)
Left / Mid / Right (horizontal scrollbar)
2) PartType
Edit + cell Type (e.g EditText, EditInt, ..., only editable cells, for Bool and Radio is returned for the icon only, otherwise returns Nothing)
/ DropCol / DropEmpty (cell Type="DropCols", DropEmpty is the empty space without columns)
/ Link (cell Type="Img","Link", only the link or image, otherwise Nothing)
/ Gantt (cell Type="Gantt") / GanttHeader (header of Gantt type column)
/ Expand (expand or collapse button in tree)
/ ButtonSave / ButtonAdd / ... / ButtonXXX (all standard and custom toolbar buttons - cell Type="Button", XXX is column name)
/ PanelFiltered / PanelGrouped / PanelSorted / SpaceOff / Space... (all custom panel buttons in Space row, Type=”Panel”)
/ PanelDelete / PanelSelect / PanelMove / PanelCopy / PanelOff / Panel... (all custom panel buttons in standard row, Type=”Panel”)
/ HeaderDelete / HeaderSelect / HeaderMove / HeaderCopy / HeaderOff / Header... (all custom panel buttons in Header row, Type=”Panel”)
/ SideSort / SideDate / SideDefaults / SideFilter
/ SideButton (custom right side Button)
/ SideIcon (custom left / right side Icon)
/ Nothing (other types when CanEdit='0'; Bool and Radio also outside the icon, Bool,Radio,Enum also in ReadOnly mode)
3) Part
Content (standard cell content) / Caption (header cell content) / Side (right/left cell button) / Tree (tree button or lines) / Panel (cell Type=”Panel”) / Button (cell Type=”Button”)
4) CellState
Edited (focused cell in edit mode) / Viewed (focused cell in read only edit mode) / Focused (focused cell) / Regular (not focused cell)
5) CellEdit
Editable / ReadOnly (CanEdit=’0’) / NoFocus (CanFocus=’0’)
6) CellKind
Kind + row Kind attribute (KindData, KindHeader, KindSpace, KindFilter, KindGroup, KindSearch, KindToolbar, KindPager, ...)
/ KindUser (standard row without cells, specified by xxxHtml attribute)
7) CellSection
Header (Kind=”Header”) / Body (body row) / Fixed (head and foot row except header) / Space (space row )
/ PagerHeader (right side pager header) / PagerBody (right side pager except header, including empty space)
8) Cell
Cell (any cell) / PagerPage (right side page, no empty space) / Empty (any other place without cells)
9) Section
Left / Mid / Right / All (space row)
10) RowKind
HeaderRow / BodyRow / FixedRow / SpaceRow / NoRow
11) RowSection
Row (any row) / Pager (right side pager) / VScroll (vertical scrollbar) / HScroll (horizontal scrollbar) / Other
12) Grid
Grid (anything inside grid) / Outside (anything outside the grid, including other grids)
Assigning event actions/callbacks
The event actions can be assigned in TreeGrid XML or by JavaScript in global Grids array.
In XML the event can be assigned to cell, whole row, whole column or whole grid in <Actions> tag.
For example: <I Col1OnCellClick=’Focus’/> (cell), <I OnCellClick=’Focus/> (row), <C OnCellClick=’Focus’/> (column), <Actions OnCellClick=’Focus’/> (grid).
If more events are assigned for one cell, they are called in this order: 1) Grids array, 2) one from cell or row or column, 3) <Actions>. If any action returns true, the next are not called.
Dynamical assignment by JavaScript
Every action can be replaced dynamically by JavaScript, by simple assignment, for example:
Grids.OnCellClick = function(Grid,Event) { ... }
row[col+”OnCellClick”] = “alert(‘click’)”;
row.OnCellClick = “...”
grid.Cols[col].OnCellClick = “...”
grid.Actions.OnCellClick = “...”
The action code assigned to XML can be exact JavaScript code or simplified notation. The action in global Grids array must be JavaScript function.
Simplified notation for assigning actions in XML
- One action is assigned just by name
[A] <Actions OnClickCell=’Focus’/> - do Focus
- Constant action. 1 or 0, useful with other operators to return 0 or 1 independently on result of actions
[1] or [0] <Actions OnUp=’GoUp,1’/> - do GoUp and always return success to suppress default behavior for OnUp key event
- Two action are always executed. Separate by plus. The return value is true if at least one action succeeded.
[A + B] <Actions OnClickCell=’Focus+ShowDetail/> - do Focus and next ShowDetail
- The second action is executed only if the first action succeeds. The return value is true if both actions succeeded. Separate by AND or &&. Attention, when you use only “&” instead of “&&”, both action are always called!
[A && B] or [A AND B] <Action OnClickCell=’Focus AND StartEdit’/> - do Focus and if succeeds, do StartEdit
- The second action is executed only if the first action fails. The return value is true if at least one action succeeded. Separate by OR or ||. Attention, when you use only “|” instead of “||”, both action are always called!
[A || B] or [A OR B] < Action OnClickSort=’SortAsc OR SortDesc’/> - do SortAsc or, if not possible, do SortDesc
- Action B is executed only when Action A succeeded, Action C is executed only when Action A failed. The colon must not be missing.
[A ? B : C] <Actions OnClickCell=’Focus ? StartEdit : ShowDetail’/> - do Focus and if succeeds do StartEdit otherwise do ShowDetail
- Both actions are always executed. The return value is the result of the second action and the first action result is ignored
[A , B] <Action OnMouseOverBody=’ColorHover,HoverRowCell’/> - do ColorHover and next HowerRowCell, return value of HoverRowCell.
The operators can be combined together, the operator priority is according to they are listed here, the plus has the highest priority. You can use parenthesis ( ) to change the priority.
<Actions OnClickCell="Focus AND StartEdit+ShowDetail"/> - do Focus and, if it succeeds, do both StartEdit and ShowDetail
Exact JavaScript notation for assigning actions in XML
You can use any JavaScript code here, for long code is better to define custom JavaScript function and call it here
Example: <Actions OnClickCell="alert('clicked ['+this.ARow.id+','+Event.Col+']');"/>
Assigning function to global Grids array
You can assign the JavaScript function in script in HTML page or in external script. The assignment must be placed after including TreeGrid script GridE.js.
Example: Grids.OnClickCell = function(Grid,Row,Col,Event){ alert('clicked ['+Row.id+','+Col+']'); }
Event action (function callback) parameters
The event handler is called with parameters TGrid Grid, TRow Row, string Col, TEvent Event.
These parameters can be accessible from the event handler code, for example: OnClickRow = “Grid.SelectRow(Row)”.
The Row and Col parameters can be null if there is click outside cells.
The event assigned to global Grids array is called as global function with these parameters – function (Grid, Row, Col, Event).
The event code should return 1 or true for success, 0, false or null for failure.
TEvent properties (the cell properties are related always to mouse position!)
string Name Name of event without On, for example MouseMove or Click.
TRow Row, string Col Cell under mouse cursor
string Type Type of the cell, like Int or Text
bool CanEdit, CanFocus Permissions of the cell
int X, Y Position of mouse click relative to the cell
int Width, Height Size of the cell
int ClientX, ClientY Absolute position of mouse click, the event.clientX, event.clientY
int AbsX, AbsY Absolute position of mouse click. It is not the same as event.clientX, event.clientY. It is position where will be placed tag with position:absolute.
string Level Target group (0-11), for example PartType or CellSection
string Target Target name from the group, for example ButtonSave or PagerBody
string Prefix Key prefix, for example Shift or CtrlAlt
int Button Button pressed in OnMouseDown, 1 left, 2 middle, 3 right
...and many other internal properties that must not be changed ...
Calling predefined actions from JavaScript
Every action can be also called from JavaScript by grid[“Action”+name], for example grid.ActionSave( );
To use ...F (focused) version of action, you need to call it with the first parameter as 1, for example grid.ActionSelectRow(1); => There is no method named ActionSelectRowF.
Some actions are related to focused row or cell. The focused cell can be changed by Focus method.
Some actions are related to actual row or cell. This cannot be changed, it is always cell under mouse cursor.
Calling actions from JavaScript is intended just to extend the global mouse or key schema. To provide specific actions for individual cells, use standard API methods like SelectRow or AddRow.
Predefined actions are done usually for focused or actual cell or row. It is not the same.
Actual cell or row is under mouse cursor and focused cell or row is with TreeGrid cursor (blue by default).
Also focused row or cell is not the same as selected row or cell. There can be more selected cells and rows and is possible to delete, move or copy them, whereas focused cell is only one and it is a grid cursor.
When action says that works with actual or focused row / column / cell, it exists in two versions, one without postfix works with actual and the second with postfix F works with focused.
For example DeleteRow ...F has DeleteRow for actual row and DeleteRowF for focused row.
The event name consists from: On + key_prefix + key_name [+ target].
For example OnUp, OnShiftTab, OnUpEdit
The key actions are called in JavaScript onkeydown event and are called only for focused grid. There can be only one focused grid at a time. The focused grid is set by Grids.Focused property automatically when some cell in grid is focused.
The build-in TreeGrid action should be used with ...F suffix when assigned to key events, to handle focused cell and not active (under mouse) cell.
Key names for all possible keys on keyboard.
Key names are defined by KeyNames... attributes for key scan codes. The KeyNames should not be changed, if there is not real reason to do it.
A - Z D0 - D9 (keys 0 to 9) Space Tab Backspace Enter Esc
Maxthon browser has disabled Esc key for JavaScript
F1 – F12 Ins Del Home End PageUp PageDown Up Down Left Right Pause
In IE have function keys F1 – F12 predefined action that cannot be suppressed (for example F5 always reloads page)
Some function keys F1 – F12 are reserved for system use and cannot be handled by browser on some systems
Safari and Konqueror have disabled Ins key for JavaScript
Tilde ‘~’ Minus ‘-‘ Equal ‘=’ LeftBracket ‘[‘ RightBracket ‘]’ Backslash ‘\’ Semicolon ‘;’ Apostrophe ‘’’ Comma ‘,’ Point ‘.’ Slash ‘/’
Firefox returns for Minus the code for NumMinus and for Equal unknown code 61
Opera has completely different codes for these keys and often conflicts with control keys, for example Apostrophe returns code for Right arrow.
Num0 – Num9 NumDivide NumStar NumMinus NumPlus NumPoint
Num0 – Num9 keys are identified only when NumLock is ON, otherwise the return code as control key.
The numeric Enter is always the same as Enter, so there is no NumEnter.
Firefox returns NumMinus also for Minus key
Konqueror has problems with identification of NumDivide, NumStar, NumMinus, NumPlus, NumPoint
CapsLock NumLock ScrollLock
ScrollLock on some systems does not work
Character keys
Key – the OnKey event is called for all character keys.
By default has key event no target that is used for standard controlling when EditMode is off – no cell is being edited.
If the EditMode is on, there are called events for target Edit. If the edited cell is multiline, there is called two actions for targets EditMultiline and Edit – if the EditMultiline action returns true, the Edit action is not called.
Assigning actions for events and function parameters are the same as for mouse events.
By default are API event handlers defined as methods of global Grids object like:
Grids.EventName = function(grid, param1, param2, ...) { ... }
For example:
Grids.OnClick = function(grid,row,col,x,y) { alert("clicked cell "+(row?row.id:null)+ ","+col+" at "+x+","+y); }
This global event is called for all grids on page, with different first parameter grid.
Or you can set one event handler per grid by SetEvent.
Or you can set more event handlers per event and grid by AddEvent and remove by DelEvent.
global func. void SetEvent (string name, string id, function func) .
Sets TreeGrid event handler for grid with given id.
Use it, if you have more grids and want to call for every grid different function.
It is possible to have only one handler per event and grid, to have more event handlers use AddEvent / DelEvent functions.
name event name like “OnClick”.
id id of the grid. If it is null, the function will be called for all other grids than for those having attached the event handler by SetEvent.
func any JavaScript function to be called for event raised.
Example:
Standard way: Grids.OnClick = function(G){ if(G.id=="G1") alert("G1 clicked"); if(G.id=="G2") alert("G2 clicked"); }
SetEvent way: SetEvent("OnClick","G1",function(){ alert("G1 clicked");} );
SetEvent("OnClick","G2",function(){ alert("G2 clicked");} );
Do not use both ways together, if you set Grids.OnClick, you cannot set it also by SetEvent and vice versa. Also don’t use with AddEvent / DelEvent.
SetEvent is useful also when using automatic merging web pages like by Java portal - JSR-000168 Portlet.
! For events that return by default another value than false or null (OnRowFilter, OnGetClass) you have to define default event handler for all grids by calling it with null id.
global func. void AddEvent (string name, string id, function func) .
Adds TreeGrid event handler for grid with given id. If id is missing, adds it for all grids.
With this function you can have more handlers for one event and one grid and you can add and delete them dynamically
Must not be used with SetEvent function. Must not be used with standard event assignment by Grids[name]
Calling order of attached events is expected to be random.
The return value for event is the first non null return value from some handler.
This function slightly slows event execution.
! For events that return by default another value than false or null (OnRowFilter, OnGetClass) you have to define default event handler for all grids by calling it with null id.
global func. void DelEvent (string name, string id, function func) .
Removes TreeGrid event handler added by AddEvent function.
It removes only the event added by AddEvent with all three parameters the same as when calling DelEvent.