03.Controller

• Overview
• What is "controllization"?
• How to write an event handler
  • Basic syntax
    • Event handler
    • Controllization
  • Event handler argument
    • Argument 1: event context
    • Argument 2: event target element
  • Event handler processing scope
• Controllization life cycle
• Reference

Overview

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
  etc.

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).

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

• • 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:

This may make it easier to understand:

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

apart from existing names like click or submit.

Controllization

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); 

selector

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

controller

• Specifies controller definition object.

param

• Specifies initialization parameter passed to controller.

Returns

• 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:

event

• jQueryEvent object.

controller

• Reference of the controller.

rootElement

• An element that controller is bound to.

evArg

• A parameter passed by using trigger method.

Argument 2: event target element

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.

Example:

例：

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）。

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.

Example:

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:

HTML：

JavaScript：

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:

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.

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.

__construct

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

__init

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

__ready

• 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

Reference

• Self-study/Selector notations
• Reference/Configuring event handler for special objects (window, document etc.)
• Reference/Configuring event handler for special events (non-bubbling events)
• Reference/Usable methods after controllization
• Reference/Life cyle of a controller
• Reference/Controller meta definition
• Reference/Controller initialization flow
• Reference/Passing initialization parameters when controllizing.