Controller

A controller is a plain object holding whatever methods your markup and route need. You never call these methods yourself, Bindary does, from several different places, each with its own argument shape.

The file

$bindary.controller is whatever object the active route's controllerURL loaded. The usual shape and what every controller on this site uses, wraps assignment in an IIFE so ctrl stays a short local alias rather than a global:

(function (ctrl)
{
    ctrl.load = () =>
    {
        $bindary.appData.orders = [ /* ... */ ];
    };

    ctrl.isOption1 = (templateItem) => templateItem.context.value === 1;

})($bindary.controller);

Nothing here is special syntax, it's an ordinary object being handed methods. What makes it "the controller" is only that Bindary knows to look at $bindary.controller for a method whenever markup or a route asks for one by name.

Where a controller method gets called from

Several different places and the arguments a method receives depend entirely on which one called it. This page is a map of those, not a re-explanation of each, most already have their own page.

Route lifecycle

Seven hooks, all optional, called automatically for whichever route is active. This is the full set:

(function (ctrl)
{
    // fires after loading the required route data and sources
    ctrl.load = function ()
    {
    }

    // fires when data is received, before the client data is updated.
    // return false to cancel further processing of the data object
    ctrl.preDataUpdate = function (data)
    {
    }

    // fires after the client data is updated
    ctrl.postDataUpdate = function ()
    {
    }

    // fires before the view is rendered/updated
    ctrl.preRender = function ()
    {
    }

    // fires after the view is rendered/updated
    ctrl.postRender = function ()
    {
    }

    // fires once the route has fully loaded
    ctrl.postLoad = function ()
    {
    }

    // fires when the current route is about to be unloaded, either because a new
    // route was requested or the window itself is unloading.
    // return false to cancel and keep the current route active
    ctrl.unload = function (routeIndex, routePath, pageHide)
    {
    }

})($bindary.controller);

load and postLoad fire once, at the start and end of the route's lifetime. unload fires once too, at the end and can cancel the navigation by returning false. Its routeIndex/routePath refer to the requested route, not the current one. Cancelling while pageHide is true is unlikely to actually stop the window from closing, browsers don't generally let script cancel that outright. Everything else, preDataUpdate, postDataUpdate, preRender, postRender, fires repeatedly over that lifetime, once per incoming update or render pass.

A route can point these at different method names instead, through controllerLoad, controllerPreDataUpdate, controllerPostDataUpdate, controllerPreRender, controllerPostRender, controllerPostLoad and controllerUnload on the route definition, useful if one controller file serves more than one route without its hooks clashing.

Per-element render hooks

b-pre-render and b-post-render are a different pair from the route-level ones above, these are tied to one specific element, not the whole route and fire on every render pass for that element. preRender receives the element's own templateItem plus a render callback, returning false stops that element from rendering and shows a placeholder instead. postRender receives just the templateItem, returning false hides the element after it rendered.

ctrl.preRenderDate = (templateItem, render) =>
{
    if (!someCondition)
        return false; // don't render this element right now
};

Conditionals, filters, formatters

if/else-if methods receive the templateItem and return a boolean. filter receives the templateItem and the collection and returns the filtered version. view-formatter and data-formatter both receive (templateItem, element, value) and return the transformed value.

DOM events

b-on-* attributes call a controller method directly in response to a browser event, (templateItem, event).

Expressions

{{ methodName() }} inside an expression also resolves to a controller method, unless it's inside a component that has one by that name instead, see calling a controller or component method for the exact resolution order.

$component is a different object

A component has its own load, and event handlers, written and wired up from markup exactly the same way a controller method is. To invoke methods on the component instance instead of the loaded controller you use $component.

<a b-on-click="pickColor"></a>  <!-- the page's controller -->
<a b-on-click="$component.click"></a> <!-- that component's own instance -->

Same attribute, same calling convention, two unrelated objects on the receiving end. $bindary.controller is the one object this whole page describes, swapped out per route. $component is whatever that specific component's initiator returned, its own instance, its own state, a different object for every component on the page and none of them are the controller.

A bare method name here defaults to the controller, not the component, the opposite of how {{ methodName() }} resolves inside an expression, which checks the component first and only falls back to the controller if it doesn't have that method. Same two objects, opposite default, see Expressions for that side of it.