Tutorial (basic learning) » 03.Controller


Last modified by kashi on 2015/01/30, 12:48


Controller is the core of interaction process with the user.
Specifically, it performs:

  • Event handling
  • Logic, View (template) declaration
  • Life-cycle event definition
  • DOM manipulation

This chapter will describe how to write a controller via the following sections.

What is "controllization"?

Before proceeding to detailed description about controller, we need to understand what the word "controllization" means.

As described in chapter 02.HelloWorld, you can put the controller into actual operation by calling
h5.core.controller() method and bind controller definition object to an element.

But before binding the controller to an element, you need to:

create an instance based on controller definition object (clone).
include default necessary functions into the instance.
configure event handler
And this is called "controllization".

Controllization in this section is 

    • calling the h5.core.controller() method for the controller to be able to operate. 

How to write an event handler

Event handler is a function that is called when an event occurs.
Normally, an event corresponds to user manipulation such as mouse click, keyboard input, etc.

The most basic process that the controller executes is event processing (event handling).
In hifive, if you assign a property with special notation to a controller, it will automatically be recognized as
event handler, will be called whenever an event occurs (for example a button is clicked).

Basic syntax

In this section we will learn how to create a controller that handle the event when an element that has  id  =  btn  is pressed ( click  event occurs).

var sampleController = {  
  __name: 'SampleController',  
 '#btn click': function(context, $el) {  
    alert('Button is clicked ');

__name property in row 2 indicates name of the controller (__name is a mandatory property , without this error should occur).

In actual development, declare
__name property as full name of the package.
(例) com.htmlhifive.tutorial.step03.SampleController
    • Apart from __name property, you can also declare Logic/View template/Child controller as property (described later).。

Event handler

Row 4 shows the event handler definition. The event handler is written as per below syntax:

'(selector) (event name)': function(context, $el) {  
  // process  

This may make it easier to understand:

'(When an element matches this selector's condition) (this event occurs)': funciton(){}//(Execute this function)

You can specify your own custom event name, apart from existing names like click or submit.

apart from existing names like click or submit.


When you finish defining the controller, bind it to an element. Call the  h5.core.controller()  method to bind the controller.
h5.core.controller(selector, controller, param); 


  • Specifies the element to bind the controller. Its value should be a selector or an element.


  • Specifies controller definition object.


  • Specifies initialization parameter passed to controller.


  • Returns controller object.

Event handler argument

Argument 1: event context

An event context object is passed to argument 1 of the event handler.
You can specify any desired name to the argument, however, unless there's a specific reason, you should unify it to "context".

Properties of event context object are as below:


  • jQueryEvent object.


  • Reference of the controller.


  • An element that controller is bound to.


  • A parameter passed by using trigger method.

Argument 2: event target element

Argument 2 is added in ver.1.1.4.
It is not passed in older versions.

An element  that processes current event  will be passed to Argument 2.
You can specify any desired name to the argument, however, unless there's a specific reason, you should unify it to "$el" ("el" is the abbreviation of element).

This argument is same as $(context.event.currentTarget), with context is argument 1 of the handler.
It means that,  after parsing the element specified by the selector of the event handler, a jQuery object is returned. 
If you directly set an event handler to an element, when the handler is called, "this" will indicate the element itself.



<ul class="list">
 <li class="listItem">a list item</li>  <!-- Click this element -->
var listController = {
  __name: 'ListController',

 '.listItem click': function(context, $el) {
     //$el points to li element
h5.core.controller('.list', listController);

By default, a jQuery object is passed to $el, however, you can configure to pass
reference of native element instead of jQuery object.
If you want to pass the native element, write the following code line after importing h5.js(see:listenerElementType)。

h5.settings.listenerElementType = 0;

Note: if the event is bubbling

As described above, $el points to the element (specified by selector) that processes the current event.
Therefore, if the element of the selector has child element and event occurs in the child element,
"the element where event occurs"and $el are not the same.


<div id="container">  <!-- この要素にコントローラをバインド -->
   <div class="parent">
       <a class="target" href="#">LINK</a>  <!-- この要素をクリック -->
var sampleController = {
  __name: 'SampleController',

 '.parent click': function(context, $el) {
    //When you clicked <a> tag, since the one that is specified by selector is div parent element
    //$el refers to div element (which is a parent class).
    //If you wish to know the element where the event occurs, use $(

 '.target click': function(context, $el) {
    //In this handler the selector refers to <a> tag,
    //certainly $el will point to <a> tag.
h5.core.controller('#container', sampleController);

Event handler processing scope

In principle, the event handler defined by the controller will only operate if an event occurs in child element
of the element that controller is bound to.
As result, you will also have to clarify the processing scope of the controller.
For example if the selector condition is wide, you need to prevent the handler from unexpectedly processing an event that occurs in the element that is out of processing scope of the controller.

For example:


 <div id="container">  
   <input type="button" name="click1" value="click1" />  
   <input type="button" name="click2" value="click2" />  


var selectorController = {  
  __name: 'SelectorController',  
 'input[type=button] click': function(context, $el) {  
h5.core.controller('#container', selectorController);  

In the above example, selectorController is bound to <div id="container"> element, thus if 

    • click1  button is pressed (click1 is <div id="container"> child element), an alert message will appear
      and if 
      click2  button is pressed, it will trigger nothing.

However, exceptionally, element that is out of controller processing scope can also be processed.
If you want all the elements (elements external to the controller or peer elements) in this example to be processed,
simply put the selector between braces

Therefore, if a controller is defined as below:

var selectorController = {  
  __name: 'SelectorController',  
 '{input[type=button]} click': function(context, $el) {  //Surround the selector with {}  

an alert message will appear whichever button is pressed.
Also, the selector cannot point to "the element that controller is being bound to".
If you want to configure the handler for the event that occurs in the binding element,
use {rootElement} as the selector.

var selectorController = {  
  __name: 'SelectorController',  
 '{rootElement} click': function(context, $el) {  //If the selector is {rootElement}, the element that controller is bound to can be pointed to  

Controllization life cycle

There are several steps (lifecycle) to perform before binding a controller to an element for it to actually operate.
The controllization lifecycle is as below:


If you want to execute processing at a specific step of the lifecycle, set a function for a specific key name, so that it will be called at execution time.

var lifecycleSampleController = {  
  __name: 'LifecycleSampleController',  
  __construct: function(context) {  
  __init: function(context) {  
  __ready: function(context) {  


  • Executes at the end of controllization. Resource import (view template) is not completed.


  • Executes when binding to View is completed and resources required for controllization and its operation is imported. Event handler is yet not bound


  • Executes when binding event handler to View and importing resources required for controllization and its operation is completed.
    In most cases if you want to execute further processing after "the controller is ready to operate", use ready event.

Understanding definition and role of the controller,

you will easily recognize when and which event happens in a clear scope.

Next chapter will describe screen (view) manipulation.

Next chapter ⇒ 04.View


Copyright (C) 2012-2017 NS Solutions Corporation, All Rights Reserved.