ui JavaScript API Module

Ben Tiedt — Fri, 15 Jan 2021 21:43:58 GMT

Current Revision posted to API Documentation by Ben Tiedt on 01/15/2021 21:43:58

jQuery.telligent.evolution.ui

Implements the UI component framework, and exposes a few helper methods for calling it explicitly.

About the UI Component Framework:

What are UI components?

UI components are simple JavaScript objects defined on the namespace jQuery.telligent.evolution.ui.components. They are automatically invoked against any DOM elements matching a CSS class name of ui-COMPONENTNAME, where componentname matches a known UI component.

For example, given an HTML snippet:

<span class="ui-car" data-make="honda" data-model="civic"></span>

And a pre-defined UI component named car...

jQuery.telligent.evolution.ui.components.car = {
    setup: function() {
        // setup is called once per page if at least one element matches this component
    },
    add: function(elm, options) {
        // add is called for each unique instance of an element matching the component
        // elm is the matching element
        // options is an object containing all data attributes defined on the element
        $(elm).html('Car: ' + options.make + ' ' + options.model);
    }
};

Then all instances of the span will be transformed on the client side to contain 'Car: [make] [model]'.

What purpose do they serve?

UI components allow the server-side to render a non-UI-specific instruction for the client to implement rendering. This allows hard-coded Widget API extensions to emit UI instructions while still allowing a theme to define how that UI looks and behaves.

Default implementations of the components are provided in Core, but they are designed to be overriden by themes as necessary.

Automatic Behaviors

Additionally, UI components are invoked against all matching elements when the page is modified too, not only after the page first loads. This makes UI components an easy way to embed interactive behaviors in content without having to specifically bind to events or set up handlers.

Methods

These are not often needed, and are usually invoked internally. They can be invoked explicitly as necessary.

render

Invokes all currently-known UI components against the page or a given selection within the page.

As rendering is typically performed automatically, this is rarely needed.

// invoke currently-defined UI components against all matching elements in div.mydiv
jQuery.telligent.evolution.ui.render('div.mydiv');

suppress

Temporarily suppresses automatic rendering of ui-components for the duration of the method's scope. Returns response of callback. Supports nested suppression.

// invoke currently-defined UI components against all matching elements in div.mydiv
jQuery.telligent.evolution.ui.suppress(function(){
    // DOM manipulation without automatic ui component rendering
});

defer

Defers rendering of UI components on element until callback completes. Returns response of callback. Supports nested deferral. This is useful for improving performance when doing a lot of DOM manipulation that would otherwise also immediately trigger UI component rendering on manipuated items.

// invoke currently-defined UI components against all matching elements in div.mydiv
jQuery.telligent.evolution.ui.defer(element, function(){
    // DOM manipulation with deferred ui component rendering
});

data

Given an element, parses its data attributes into an object. If an attribute exists named data-configuration, it parses its assumed querystring-encoded values as a separate object, options.configuration.

As options are normally parsed by the UI component framework automatically, this is rarely needed.

var data = jQuery.telligent.evolution.ui.data(elm);