Events that fire on a page with a Webix-based application fall into three groups:
The main part of the article below concerns the inner events of Webix components, while the details of the other two groups can be checked by the related links in the list above.
Common inner events for all UI components are mouse events (onItemClick, onBeforeContextMenu, onMouseMoving, onMouseOut, etc.) since all the components can be clicked (and right-clicked) and respond to a mouse pointer.
Other inner events depend on the component functionality and are provided in API references for each component.
A handler can be attached to a component in different ways:
1. The most common way is to use any event of the component (check its API reference) within:
2. Depending on the component nature, you can attach a handler to some specific events defined by component properties:
Now let's study each possibility in detail.
The attachEvent() method takes the name of the component's inner event and the function it fires (handler) as parameters. The syntax is:
$$("element_id").attachEvent("onSomeEvent", some_function(){/* ... */});
Event names are case-insensitive.
A button to collapse the all tree nodes
var myEvent = $$("button_id").attachEvent("onItemClick", function(){
$$("dtree").closeAll();
});
Later on, you can easily detach this event from the component with the help of the opposite method:
$$("button_id").detachEvent(myEvent);
You can also define event handlers right in the component constructor within either of the following properties:
webix.ui({
rows:[
{
view:"button",
click:function(){ }
},
{
view:"list",
data:[ ],
ready:function(){ }
}
]
});
Related sample: Attaching Functions in the Constructor
When attaching an event you can specify only the name of a function to attach and declare it outside the webix.ui() constructor with the help of the on property:
function select_first(){
$$("list").select($$("list").getFirstId();)
};
webix.ui({
view:"button",
on:{
"onItemClick": select_first
}
});
Related sample: Creating a Custom Table
For buttons you can make it more compact by using the click property:
function close_tree(){/* ... */};
{view:"button", id:"sample_button", value:"Close", width:100, click:close_tree }
While data components inherit methods from DataStore and TreeStore, events aren't inherited. That's why they should be attached through the data object:
view.data.attachEvent("onParse", function(driver, data){
// some code
});
There are also two alternative ways of attaching such events:
datatable.attachEvent("data->onParse", function(driver, data){
// some code
});
view:"datatable",
on:{
"data->onParse", function(){
// some code
}
}
Data scheme allows changing the default pattern of data handling within the component.
For instance, the function specified in its $init key will run each time when data are loaded/reloaded to the component and when the add method is called.
webix.ui({
view:"list",
scheme:{
$init:function(obj){/* ... */},
$update:function(obj){/* ... */}
}
});
Related sample: Horizontal List
More possibilities of the data scheme are described separately.
Such properties come in pairs and include:
All these properties allow attaching the corresponding behavior (clicking, double-clicking, etc.) for the items of a component with a specified CSS class, thus redefining the default behavior.
Let's have a look at the examples that show how the onClick and on_click handlers can be used.
1. With on_click, redefining can be done only after the component initialization.
The on_click handler:
grid = webix.ui({
view:"datatable",
columns:[
{ id:"", template:"<input type='button' class='delbtn' value='Delete'>"},
{ id:"title", /* ... */}
],
on:{
"onItemClick":function(){/* ... */} // the default click behavior
},
select:true
});
grid.on_click.delbtn = function(e, id, trg){
webix.message("Delete row: "+id);
return false; // blocks the default onclick event
};
Related sample: Datatable: Custom Handler
One of the columns features an HTML template with a button styled with the 'delbtn' CSS class. All cells including the one with this button will react on the default click behavior. When you click the button itself rather than on its cell area, the default behavior will be overridden with the function attached to the the 'delbtn' CSS class.
2. The onClick handler allows redefining the current click behavior right in the component constructor.
webix.ui({
view:"list",
template:"#votes# <span class='info'>Details</span>",
select:"multiselect",
onClick:{
info:function(e, id){
webix.message(this.item(id).title);
return false; // blocks the default onclick event
}
},
});
When you click list item styled with info CSS class, the item won't be selected and a custom message will appear.
Note that returning false from the onClick handler blocks all further click-related events: onBeforeSelect, onAfterSelect, onSelectChange, onItemClick. To check the full stack of the blocked events, you should enable the debug version of the Webix library.
Related sample: List: Event Handlers
The same pattern is true for other pairs of properties.
Event Mapping helps to get rid of repetitions in code when one and the same event should be attached to different components. If you have already attached an event to the component and described the function that this event triggers, you can route this event to another component in your app.
For these needs, use the mapEvent method and pass a map into it, where the map is an event-object correspondence:
webix.ui({
rows:[
{ view:"list", id:"list1", data:list_data, on:{
onItemClick:getItemValue
}},
{ view:"list", id:"list2", data:list_data}
]
});
// here event name should be in the lower case
$$("list2").mapEvent({onitemclick:$$("list1")});
As a result, when the second list is clicked, the function that was initially attached only to the first one, will be executed for it as well:
function getItemValue(id){
var obj = this.$eventSource || this;
var value = obj.getItem(id).value;
webix.message("List: "+obj.config.id+", clicked: "+id);
}
Note that if you need to access the object for which the handler is called at the moment, you can do it via the $eventSource property while this will always point to the object for which the handler is attached initially.
Inner events make it possible to work with component items provided that the ID of an item you click, select, etc. is passed to the attached function.
For instance, you need an event that fires each time you click an item in the list and performs an action that manipulates its data.
$$("mylist").attachEvent("onAfterSelect",function(id){
alert(this.item(id).title);
});
Related sample: Sizing and Events
Events can be divided into two groups:
The function returns false, selection is blocked
$$("my_list").attachEvent("onBeforeSelect", function(){ return false; })
You can also temporarily block all events associated with the component by using the blockEvent() method. To re-enable event triggering use the unblockEvent() method.
$$("component_id").blockEvent();
$$("component_id").unblockEvent();
The default value for response to events is 500 ms. With such events as onMouseMove and onMouseOut, you can delay the server response for as much time (in milliseconds) as you need:
webix.ui({
view:"menu",
mouseEventDelay:100
});
Components that are in focus at the moment automatically receive the ability to respond to keyboard actions and can take keyboard events, namely
Look how the onTimedKeyPress event works with a text field to filter data in view list:
$$("list_input").attachEvent("onTimedKeyPress",function(){
var value = this.getValue().toLowerCase();
$$("list").filter(function(obj){
return obj.title.toLowerCase().indexOf(value)==0;
});
});
// "list_input" id the ID of the dedicated "text" input control
Related sample: List: Filtering
More information about key codes and hot keys is to be found in the UI Manager article.
Webix global events are not connected with any specific component and can be used to control general application issues (clicks, touch movements, server-side requests, etc). Some of them repeat native DOM events.
All such events are attached to the webix object:
webix.attachEvent("onRotate", function(mode){
// logic
});
The details on Touch Events are given in the related part of API reference.
Note that these events will fire only for Ajax requests issued by Webix. It can be a custom request created with Webix Ajax interface or an automatic one (issued by a data component during data loading or saving);
Native DOM events can be handled with the help of the Webix event() and eventRemove() functions that are called from the webix object:
var eventId = webix.event("divId", "click", function(e){
do_something();
});
webix.eventRemove(eventId);
Comments: