behavior

A behavior is an object that defines event handlers.

A behavior may also define additional properties and helper methods.

Events

Registering event handlers

Event handlers are methods of a behavior.

Event handlers are registered when you create a behavior.

var mybehavior = jsb.behavior.extend({
  onclick: function(element, event) {
    // this is the click event handler
  },

  onkeydown: function(element) {
    // this is the keydown event handler
  }
});

Event order

jsb uses base2.dom to manage events. base2 fires missing events on some platforms:

The event object

The event object passed to jsb event handlers is a modified event object. The modifed object has normalised event properties. The following properties and methods are normalised:

Event signature

An event handler is passed two arguments:

function(element, event){}

The first argument, element, is always the attached element no matter the value of event.target.

Mouse and keyboard events have an extended signature (see below). These extended signatures are for convenience only and reflect the underlying properties of the event object.

Mouse events

For convenience, mouse events have an extended event signature:

onclick
ondblclick
onmousedown
onmouseenter
onmouseleave
onmousemove
onmouseout
onmouseover
onmouseup
function(element, event, offsetX, offsetY, screenX, screenY){}

The values offsetX and offsetY are always relative to element no matter the value of event.target (event.offsetX and event.offsetY are always relative to the event.target).

If the jsbExtendedMouse property is set then the event signature for onclick, ondblclick, onmousedown and onmouseup is:

function(element, event, button, offsetX, offsetY, screenX, screenY){}
onmousewheel
function(element, event, wheelDelta){}

You are not required to declare all of the arguments in an event handler.

Keyboard events

For convenience, keyboard events have an extended event signature:

onkeydown
onkeypress
onkeyup
function(element, event, keyCode, shiftKey, ctrlKey, altKey, metaKey){}

You are not required to declare all of the arguments in an event handler.

JSB events

jsb fires these additional events:

onattach

Fires immediately an element is attached to a behavior.

oncontentready

Fires when the attached element’s children have been loaded and parsed. If the element does not allow child elements then the event is fired immediately.

ondocumentready

Fires after the DOMContentLoaded event and after all behaviors have been attached.

Take care when using the onattach/oncontentready events. Because jsb attaches behaviors while the document is loading you want to avoid causing a reflow. So try to avoid doing the following:

You can still do all of the above things. But if you do them too often you may slow down the rendering of the page. You should use CSS to style elements and avoid styling from onattach/oncontentready.

jsb events (onattach, oncontentready and ondocumentready) do not bubble and are not cancelable.

Custom events

Custom events can be dispatched using the dispatchEvent() method.

To listen to a custom event you just need to declare the handler:

var mybehavior = jsb.behavior.extend({
  oncustomevent: function(element, event) {
    alert("Custom event detected!");
  },
  
  onsomeotherevent: function(element, event) {
    alert("Some other event detected!");
  }
});

Properties

A behavior has the following built-in properties:

Behaviors are essentially stateless. If you want to store state associated with an element then it is suggested that you use an element’s attributes. jsb provides get(), set() and modify() methods to maintain the state of an element through its attributes.

Methods

A behavior has the following built-in methods:

You may create as many additional methods as you need.