Bitsmist Frameworks
Docs » EventOrganizer

EventOrganizer

Inherit:Organizer

Overview

EventOrganizer handles the management of events such as installing event handlers and triggering events. It loads settings from the “events” section and sets event handlers to the component and elements inside.

Organizing

EventOrganizer loads settings from the “events” section and sets event handlers. At the “beforeStart” timing, only the component events are set since elements inside the component are not loaded yet. After an HTML file is attached to the component and afterAppend event is triggered, it sets the event handlers for elements inside the component.

Sections

  • events

Timings

  • beforeStart
  • afterAppend

Settings

Event settings are placed in the “events” section.

Syntax:

{
    "events": {
        <elementName>: { or [{
            "rootNode": <rootNode>,
            "handlers": {
                <eventName>: {
                    "handler": <handler>,
                    "listerOptions": <listnerOptions>,
                    "options": <options>,
                    "order": <order>,
                }
            }
        } or }]
    },
}

Syntax (Shorthand):

{
    "events": {
        <elementName>: {
            "rootNode": <rootNode>,
            "handlers": {
                <eventName>: <handler> or [<handler>]
            }
        }
    },
}

elementName

Type:String

An element name. If the ”rootNode“ is not specified, this value is treated as the element's id. If the value is “this”, it refers to the component itself. If the “rootNode” setting is specified, this value is nothing meaningful, just make sure it's a unique string.

rootNode

Type:String

A selector string that points to target nodes to which the event handlers are attached. This value is passed to the querySelectorAll(). The same event handler is set to all the elements returned by querySelectorAll().

eventName

Type:String

An event name. Valid events are BitsmistJS events or Javascript native events. A value for this eventName can be an array of objects also.

handler

Type:String/Function

An event handler. Can be a string or a function object. If a string is specified it is treated as the name of the event handler function. A method that has this name in the component is used as the event handler. The event handler will be bound to the component (unless specified in addEventHandler() parameter), so “this” points to the component itself.

options

Type:Object

An object that passed to event handlers via the “ex” parameter of event handlers.

order

Type:Number Default:0

A priority of an event handler. This value controls the order event handlers are executed when one element has several event handlers on one event. The greater the number, the higher the priority.

listenerOptions

Type:Object

Options passed to Javascript native API addEventListener().

Settings Examples

Specifying elements

In this section, we explain how to specify target elements. It can be divided into whether it is a component itself or elements inside the component.

Targetting a component itself

"events": {
    "this": {
        "handlers": {
            "doRefresh": this.onDoRefresh
        }
    }
}

Since <elementName> is ”this”, the event handler is set to the component itself.

"events": {
    "bar-header": {
        "handlers": {
            "doRefresh": this.onDoRefresh
        }
    }
}

Assuming this component's tag name is “bar-header”, you can set “bar-header” instead of “this”.

They can be placed in “rootNode”, also. In this case, the elementName “myself” is just a meaningless (to the library) string but should be a unique one.

"events": {
    "myself": {
        "rootNode": "bar-header" or ”this”
        "handlers": {
            "doRefresh": this.onDoRefresh
        }
    }
}

Elements inside a component

If an element has an id, you can specify it in <elementName>

"events": {
    "btn-menu": {
        "handlers": {
            "click": this.onBtnMenu_Click
        }
    }
}

In the above example, the event handler is set to an element that has id “btn-menu”.

You can use a selector string in “rootNode”.

"events": {
    "btn-menu": {
        "rootNode": ".buttons"
        "handlers": {
            "click": this.onBtnMenu_Click
        }
    }
}

It is no problem resulting in more than one element. Each event handler is set to all the elements matched.

Specifying event handlers

We will show you how to specify an event handler.

"events": {
    "this": {
        "handlers": {
            "doRefresh": this.onDoRefresh
        }
    }
}

In the above example, a function object is specified as the event handler for the “doRefresh” event.

"events": {
    "this": {
        "handlers": {
            "doRefresh": "onDoRefresh"
        }
    }
}

In this example, a string is set as the event handler. In this case, the method that has the name “onDoRefresh” is searched from the components method, that is, this.onDoRefresh method.

If a function object is set, the function needs to exist at the time of specifying it in the settings, while it needs to exist at the time of adding the event handler if a string is set.

"events": {
    "this": {
        "handlers": {
            "doRefresh": ["onDoRefresh1", this.onDoRefresh2]
        }
    }
}

In the above example, two event handlers are specified to one event. You can mix function objects and strings.

"events": {
    "this": {
        "handlers": {
            "doRefresh": {
                "handler": this.onDoRefresh,
                "options": {"value":"1"}
             }
        }
    }
}

In the next example, both an event handler and options are set at the same time. The options can be accessed from “ex” parameter of the event handler.

onDoRefresh(sender, e, ex)
{
    console.log("value =", ex.value); // console displays "value = 1"
}

In the next example, two handlers with each option are specified.

"events": {
    "this": {
        "handlers": {
            "doRefresh": [
                {
                    "handler": this.onDoRefresh1,
                    "options": {"value":"1"}
                 },
                {
                    "handler": "onDoRefresh2",
                    "options": {"value":"2"}
                 },
             ]
        }
    }
}

Extended Methods

addEventHandler(eventName, handlerInfo, element, bindTo)

Type:undefined Inject:Component

Sets event handlers to elements.

Parameters

ParameterTypeDescription
eventName
Required
StringAn event name.
handlerInfo
Required
ObjectAn hander info. Refer to Settings#handlerInfo for details.
element
Default:(see desc)
HTMLElementAn element to set event handlers. Default is the component itself.
bindTo
Default:(see desc)
ObjectBinds event handlers to this object. This value becomes “this” in the event handlers. Default is the component itself.

Return value

undefined

getEventHandler(handlerInfo)

Type:Function Inject:Component

Returns an event handler function object from the handlerInfo.

Parameters

ParameterTypeDescription
handlerInfo
Required
ObjectAn object that holds handler info. Refer to Settings#handlerInfo for details.

Return value

A Function object or undefined if a handler does not exist.

initEvents(elementName, handlerInfo, rootNode)

Type:undefined Inject:Component

Installs event handlers to elements as specified in handler info passed.

Parameters

ParameterTypeDescription
elementName
Required
ObjectAn element name. Refer to Settings#elementName.
handlerInfo
Required
ObjectAn object that contains handler info which is explained in Settings#handlerInfo. If not specified, the object will be retrieved from the “events” section using the value passed to the elementName parameter as the key.
rootNode
Default:(see desc)
StringA root node for searching for target elements. Default is the component itself.

Return value

undefined

removeEventHandler(eventName, handlerInfo, element)

Type:undefined Inject:Component

Removes event handlers from elements.

Parameters

ParameterTypeDescription
eventName
Required
StringAn event name.
handlerInfo
Required
ObjectAn hander info. Refer to Settings#handlerInfo for details.
element
Default:(see desc)
HTMLElementAn element from which remove event handlers. Default is the component itself.

Return Value

undefined

trigger(eventName, options, element)

Type:undefined Asynchronous Inject:Component

Triggers an event on an element. If the element has several event handlers on the event, functions are called one by one, waiting for the previous handler to finish and the next.

An event handler can wait for the previous handler only if the previous event handler returns a promise and resolve/reject at appropriate timing.

Parameters

ParameterTypeDescription
eventName
Required
StringAn event name to trigger.
optionsObjectOptions. Can be accessed from the event handlers.
element
Default:(see desc)
HTMLElementAn element on which event triggers. Default is the component.

Return value

undefined

triggerAsync(eventName, options, element)

Type:undefined Asynchronous Inject:Component

Triggers an event. The difference between trigger() method is the triggerAsync() doesn't wait for the previous event handler to finish. Refer to trigger() for other details.

Previous Next

© 2019-2023 Masaki Yasutake

Bitsmist Frameworks

Table of Contents

Table of Contents

  • EventOrganizer
    • Overview
    • Organizing
    • Settings
      • elementName
      • rootNode
      • eventName
      • handler
      • options
      • order
      • listenerOptions
    • Settings Examples
      • Specifying elements
      • Specifying event handlers
    • Extended Methods
      • addEventHandler(eventName, handlerInfo, element, bindTo)
      • getEventHandler(handlerInfo)
      • initEvents(elementName, handlerInfo, rootNode)
      • removeEventHandler(eventName, handlerInfo, element)
      • trigger(eventName, options, element)
      • triggerAsync(eventName, options, element)

GENERAL

  • Overview
  • Installation
  • Create a sample component

COMPONENT

  • Loading
  • Settings
  • Events
  • Extending with organizers

REFERENCE - COMPONENT

  • Component

REFERENCE - ORGANIZER

  • EventOrganizer
  • LoaderOrganizer
  • OrganizerOrganizer
  • SettingOrganizer
  • StateOrganizer
  • TemplateOrganizer

REFERENCE - STORE

  • Store
  • ChainableStore

REFERENCE - UTILITY

  • AjaxUtil
  • ClassUtil
  • Util