Behave3d.Controller

Introduction

Behave3d.Controller is the central class in the behave3d library, representing the main unit of functionality - the controller. There are different types of controllers and each type is defined by a class that inherits Behave3d.Controller.

Every controller performs some piece of functionality on the element it is assigned to or to its children. It has parameters that are supplied upon its instantiation and which can be modified in the course of its functioning. It receives messages (i.e. commands) from scripts, other controllers or internally. And it fires events (not the same as DOM events) that can be listened for by user-defined listener functions or by message-on-event user-defined triggers.

Some controllers are not merely waiting for messages to react to, but also add DOM event listeners to the elements they are assigned to, realizing some automated behavior of the element.

The controllers assigned to an HTML element are contained within and managed by an instance of class Behave3d.Element, which itself is attached to the HTML element as a property with name behave3d. For more information about Behave3d.Element, visit the Behave3d.Element Documentation page.

For a more streamlined description of the basic use of a controller, read the Workflow Documentation page.

Instantiation and Removal

There are two ways that controllers can be attached to HTML elements:

  • The static way, through the behave3d="..." attribute on the HTML tags:

     ...and after all elements:
  • The dynamic way, entirely through javascript:

In both ways the syntax of the controllers-definitions strings is the same - see the Syntax of Controller Param Line section below for details on it. You can set not only parameters in these strings, but also triggering conditions (message-upon-event) and initial messages.

You can remove a single controller or the whole behave3d functionality from an HTML element:

You can also automate the removal of a controller or whole element when they are no longer needed:

Syntax of Controller Param Line

The behave3d library is meant to be easy and quick to use, and a most essential contribution to this is made by the ability to define a controller with not only parameters, but also instructions for behavior (though simple at this early stage of development), right on a single line.

Strings defining parameters, messages to send immediately, and message-on-event triggers are all accepted in a list of comma-separated parameters, in any order, both at the initialization, and later, during the functioning of the controller by all methods that accept parameters.

  • Parameters: <param name>: <param value>
  • Messages: <message to send immediately>
  • Triggers: <message to send> on: <event definition>

Note that the parts of the param line are not executed (parameters set, messages sent, triggers set) in the order they are supplied. The process is divided into 3 steps:

  1. All parameters are set, where repeated assignment of the same parameter throws no errors but overwrites the previous assignments.
  2. All triggers are set in the order they are supplied. Repeated supplying of the same trigger will lead to several callings of the callback function (or repeated sending of message).
  3. All messages are sent in the order they are supplied.

When the DOM tree is scanned with Behave3d.updatePool(), these three steps will be common for all newly-created controllers, i.e. first, all controllers will be created and their parameters set, after which their triggers will be set, and then messages to each controller will be send.

This allows controllers to address other controllers situated bellow them on the page when triggers are created (on step 2), as all controllers have been created and IDs set on step 1. Also, this process makes sure that all event handlers have been set on step 2 before the controllers start executing and firing events on step 3.

When controllers are added via javascript with Behave3d(element).add("controller(params) | controller..") the controllers defined within a single call to the method will also have the 3 steps of initialization shared.

Syntax of Triggers

A trigger allows to define a condition, which, each time when met, will cause the sending of a specified message to the controller.

General syntax of a trigger:

<message type> on: [<milliseconds> after ][[<element id>] <controller id>] <event type>

Variants of the trigger condition:

  • <milliseconds>
    The message is sent once, after the supplied number of milliseconds.
  • <event type>
    The message is sent every time this controller fires this event.
  • <controller id> <event type>
    The message is sent every time another controller on the same element fires this event.
  • <element id> <controller id> <event type>
    The message is sent every time a controller attached to another element fires this event.
  • <milliseconds> after <element id> <controller id> <event type>
    The message is sent with a delay of the supplied number of milliseconds every time the controller attached to another element fires this event.

Note that when addressing controllers assigned to this element's parent element, instead of supplying the parent element's ID, you can supply "@parent". You can, as well, supply "@ancestor" which will reference the closest element in this element's parent chain which has behave3d functionality, i.e. has an Behave3d.Element attached.

Examples:

Parameters

Every controller has parameters that tune the way it works. With a few exceptions (like parameters that supply links to other elements/controllers), all parameters have default values and might be omitted when defining the controller.

Parameters are usually of primitive type - a boolean, a number or a simple string (usually an element's or controller's ID). Controllers don't receive texts as parameters, these are taken from the DOM structure (either from text nodes or element attributes).

Note that when supplying string values in the controller's param line, the strings must have no quotes surrounding them. Quotes in such cases will be treated as parts of the supplied strings.

Some parameters supply a reference to a function. Instead of a reference, the function name as a string will also be accepted. If the function is in a different namespace than window, supply the namespace chain in the string. For example,
window.namesp.namesp2.function_name

Note that while internally a controller's parameters are stored as properties on its object and so can be modified directly, using the controller's .set() method is recommended for setting them, as this way the controller 'knows' about the modification and can fire a notification event, update other working variables, etc. Javascript setters and getters are not implemented for performance reasons.

While changing some parameters' values takes effect immediately, the values of other parameters are used by their controller only when it recalculates its internal variables upon receiving a message.

Coordinate Parameters

The behave3d library works only with pixels and rem units. All coordinates and lengths supplied as numbers, without a "rem" string at the end, are treated as numbers of pixels.

Since CSS transforms (and so, every controller) work in a coordinate system with origin at the element's position in the layout, all supplied coordinates are relative to the element's initial position in the layout (without any transforms applied).

Apart from simple numbers, parameters representing layout coordinates or lengths can receive values with a special syntax, allowing the supplying of coordinates relative to different points of origin, and the supplying of lengths as percentige of different lengths (not only the element's own width or height).

Syntax:

  • <number>
    Number without dimensions is a value in pixels. If it's a coordinate, the supplied position will not be an absolute screen/document position, but a position relative to the element's own position in the layout.
  • <number>o
    (From 'own') Same as above.
  • <number>p
    (From 'parent') Coordinate relative to parent element's origin.
  • <number>d
    (From 'document') Coordinate relative to document's origin.
  • <number>v
    (From 'viewport') Coordinate relative to viewport's origin.
  • <number>rem
    Value in CSS rem units.
  • <number>%
    Percentage of parent's width/height, or percentige of scene's perspective property (i.e. the distance between the camera and the layout plane z=0) when evaluating a Z-axis parameter.
  • <number>%p
    (From 'parent') Percentage of parent's width/height.
  • <number>%o
    (From 'own') Percentage of own width/height.
  • <number>%d
    (From 'document') Percentage of document's width/height.
  • <number>%v
    (From 'viewport') Percentage of viewport's width/height.
  • <number>%Z
    Forces returning of percentige of scene's perspective property (the camera's altitude).
  • <number><any of above>X
    An 'X' in the end of the string forces returning of horizontal value (X position or width).
  • <number><any of above>Y
    An 'Y' in the end of the string forces returning of vertical value (Y position or height).

Transition Easing & Inertia

All controllers that have to animate some variable by interpolating it between two values have the following parameters controlling the easing of the interpolation:

  • ease_type
    What kind of easing to be applied on the movement.
    Currently supported values:
    • "linear" - constant speed in all trnasition parts (i.e. no easing),
    • "ease" - slower start and end of trnasition, elliptical shape,
    • "ease_in" - slower start, fast and sudden end,
    • "ease_out" - fast and sudden start, slow end.
    In all controllers and cases, the default easing type is "ease", which makes the smoothest transitions.
  • ease_amount
    Strength of easing to be applied on the movement.
    Values in the range (0 - 1] make sense, though values greater than 1 (up to 2-3) can also be of use.
  • ease_mirror
    Tells if the easing applied on 'backwards' movement is the same as the forward easing, or mirrored. If this parameter is set to true and parameter ease_type is "ease_in", then upon a backwards movement, "ease_out" easing will be applied.

Apart from easing, all controllers that animate a variable between two values have the following parameters, which modify how the (already eased) trajectory is followed:

  • half_step
    If set (to less than 1), each frame the current position will step closer to the required position, where step = half_step * distance_to_required_position. This lag can be used to smooth changes in movement direction.
    Values in the range (0 - 1) make sense.
  • spring_acc
    If set bigger than 0, the variable will behave as if attached to a spring. Bigger values result in stronger pulling of the "spring" and faster movement (i.e. shorter spring period). Note that setting too high of a value will cause a self-amplifying spring movement. What is the highest value before the positive feedback kicks in depends on the value of spring_vdamp, but values up to 2 are always safe.
  • spring_vdamp
    When spring motion is enabled via parameter spring_acc, every frame the current speed of the spring is multiplied by this parameter, effectively slowing the transition. Values between 0 and 1 are reasonable, where smaller values result in faster dying of the movement and a value of 1 means absolute elasticity of the spring.

Common Parameters

Apart from the specific parameters related to its function, every controller type has the following common parameters, handled by the base class Behave3d.Controller

  • id
    An alpha-numerical ID distinguishing the controller among the controllers attached to the same HTML element. A controller needs its id set only if going to be addressed by other controllers and their triggers or by user scripts.
  • paused
    A boolean flag for pausing the animations performed by the controller. While the controller is paused, its logics will not update and it will continue to apply the same transforms as on the last frame before being paused.
    When a controller's paused parameter is modified, the controller will fire a notifying event paused or unpaused.
  • disabled
    A boolean flag for disabling the controller. While the controller is disabled, its .update() method will not be called, so its logics will not update and it will stop applying any transforms. Note that this means that the transforms that have been applied on the last frame before the controller was disabled will disappear, as the engine expects controllers to request their transforms on every frame.
    When a controller's disabled parameter is modified, the controller will fire a notifying event disabled or enabled.

Messages

Controllers receive commands and notifications from the outside world as messages.

A message is a string, optionally accompanied by an object containing message parameters as its named properties. Messages are sent to a controller via its .message() method, or by defining message-on-event triggers in the controller definition or via the .set() method:

Common Messages

Apart from the specific messages related to its function, every controller type accepts the following common messages, handled by the base class Behave3d.Controller

  • pause, unpause
    Pause or un-pause the controller, setting its paused parameter. The controller will fire a notifying event paused or unpaused. While the controller is paused, its logics will not update and it will continue to apply the same transforms as on the last frame before being paused.
  • enable, disable
    Enable or disable the controller, setting its disabled parameter. The controller will fire a notifying event enabled or disabled. While the controller is disabled, its .update() method will not be called, so its logics will not update and it will stop applying any transforms. Note that this means that the transforms that have been applied on the last frame before the controller was disabled will disappear, as the engine expects controllers to request their transforms on every frame.
  • params
    Supply new values of controller parameters. Note that you can supply new values of controller parameters (supplied as message parameters) when sending any message to the controller, not only message params, but this message does nothing other than setting the parameters. Sending of message params is equivalent to using the controller's .set() method:
  • remove
    Order removing of the controller from the element's list of controllers. Upon removal, the controller will clean (remove event listeners, etc.) and fire event remove.

Events

Controllers fire 'events', which notify the user scripts or other controllers when the controller changes its behavior, like when it finishes its current task. A behave3d event is a string, optionally accompanied by an object containing event parameters as its named properties.

Events can be listened for by user-defined functions or by message-on-event triggers, which automatically send a message to the controller upon its own or another controller's event:

Note that currently, as of version 0.80, functionality is still not implemented and you can't remove behave3d event listeners.

Common Events

Apart from the specific events related to its function, every controller type fires the following common events, generated by the base class Behave3d.Controller:

  • paused, unpaused
    Fired when the controller is paused or unpaused (i.e. has its paused parameter changed).
  • enabled, disabled
    Fired when the controller is enabled or disabled (i.e. has its disabled parameter changed).
  • frame
    Fired on every frame, right before the controller's .update() method is called. Disabled controllers will not fire this event.
  • remove
    Fired upon removing of the controller from the element's list of controllers.