Outlast

Data attributes

Introduction

In addition to the standard OFW Javascript API, you can also use some built-in data-attributes within OFW projects. These are detailed below.

Make a library available

Outlast Framework javascript plugins are separate objects defined in separate files that are loaded on demand via Require.js. On demand loading can happen in a couple of ways – via data attributes, via programmatic loading. In each case you must first make the library available:

ofw.addDataAttributeHandler('pluginname', 'plugins/myplugin/js/');

This will make the library available for use in data attributes or in code. See below for use…

System libraries are already activated automatically. See defaultOptions.dataAttributes in ofw-jquery.js.

Loading/calling via data-attributes

Outlast Framework javascript plugins will often be called directly from data attributes. One example of this is the event plugin. When a data-event data attribute is encountered the registered event.js plugin file is loaded and the api is made available.

After it is loaded, the registered actions for the given element will be triggered. What does this mean? Say you have an element that contains data-event="trigger". When the element is loaded on screen, the trigger() function in activations object of event.js is called; when the element is clicked, the trigger() function in actions object of event.js is called. This allows the plugin writer to define basic reactions to things that happen related to the element that has the data-attribute defined.

Often times you also want to pass additional data to the function, this is done with additional data attributes. In the case of data-event="trigger" you can optionally specify data-event-trigger-minor="keyup" for example. This will be passed as the first parameter, in dataset like so:

trigger: function (dataset, $el) {
    // This would be triggered when the element is loaded
    // - it would receive dataset.eventTriggerMinor, dataset.eventTriggerMajor (assuming these attributes are set; of course also any other attributes...)
    // - $el is the element where the data attr was found
},

Refer to the documentation (or directly to the code) to see what is supported for each data attribute.

Warning! Don’t forget to activate the library using ofw.addDataAttributeHandler(). See above!

Loading/calling programmatically

Anything defined in the public api section of a js plugin will be accessible via ofw.plugins.pluginName.functionName() – an example might be the built in block plugin, which allows you to dynamically refresh the content of blocks via ofw.plugins.block.refresh('blockname').

If the plugin is already loaded elsewhere and you are calling such a function right away (on load) you should wrap it in a ready function like so:

ofw.ready(function() {
    ofw.plugins.event.ready(function () {
        // ofw.plugins.event api is now ready to use!
        ofw.plugins.event.subscribe(...)
    })
})

Or if you are doing the loading yourself anyway, you can add a callback:

ofw.addDataAttributeHandler('popup', 'plugins/popup/js/data/', function(popup){
    // optional callback after the handler has been activated.
    // the only param is the library object.
});

@TODO MOVE THESE TO THEIR OWN PAGE!

data-autosave

Autosave allows you to save the value of an input automatically on the client side in local storage. The input will also clear the autosave automatically once you submit (or post) its parent form using $('#form').$ofw().submit().

@attr data-autosave The unique key of the item as it should be saved in localStorage. It will be saved with an additional ‘data-autosave-‘ prefix. This is required and there is no default value.
@attr data-autosave-clear You can set this attribute to ‘false’ to disable automatically clearing the key when the parent form is submitted. (Default: “true”)

data-action

Toggles/adds/removes the given value of any HTML5 attribute (usually a class) on a given event (usually a click or tap).

@attr data-action-type The possible action types. Can be “add”, “remove” or “toggle” (Default: “toggle”)
@attr data-action-source-selector This attribute determines a custom source DOM element by a DOM CSS selector. It’s useful when we’d like to check the event triggering of another DOM element than the current HTML5 element. These are typically the “window” and the “document” objects (eg for checking window scrollTop) (default: this – the element with data-action-value).
@attr data-action-destination-selector A selector which determines the destination DOM element (default: this – the element with data-action-value).
@attr data-action-value The string value which will be added/removed/toggled. Multiple, comma separated values are allowed. In that case every value will be handled as single, independent action. (required, no default value)
@attr data-action-attribute The attribute where the toggle value will be switched (default: ‘class’)
@attr data-action-event The jQuery event name that fires the toggle action (default: ‘click’)
@attr data-action-extra-condition The name of a custom function which provides an extra condition beyond the successfully triggered event. The custom function must return with a boolean. For example if the click event triggered successfully on a button, but the extraCondition function (data-action-extra-condition=”extraCondition”) returned false, the given action will not be executed. (Optional, no default value)
@attr data-action-interval-time The interval time of scroll event checker function calling in milliseconds. (default: 100)
@attr data-action-event-threshold Custom event (swipe) threshold value (default: 10)

Custom source selectors (data-action-source-selector) can be:

window:
The window DOM object
document:
The document DOM object

Basically the default source selector (data-action-source-selector) refers to “this”, namely the current DOM element which contains the attributes. When you omit destination selector (data-action-destination-selector) it will automatically refer to source selector. If source selector refers to a collection of DOM elements (eg $(‘p’)) (and you omitted destination selector) the given events (data-action-event) will be examined at the current element from the collection selected by the source selector.
It’s very useful when you’d like to assign the same action to a collection of DOM elements, but also want to handle every single event independently. Lets say you want to add the “active” class to a specific clicked button from a collection,
but also want to remove existing “active” class from the previously clicked button. You can do it like:

<div data-action-source-selector=".button-container button" data-action-destination-selector=".button-container button" data-action-type="remove" data-action-value="active" class="dummy-container"></div>
<div data-action-source-selector=".button-container button" data-action-type="add" data-action-value="active" class="button-container">
<button>Item 1</button>
<button>Item 2</button>
<button>Item 3</button>
<button>Item 4</button>
<button>Item 5</button>
</div>

There are also custom (non native) events available (data-action-event values):

scroll-start:
Scrolling has been started
scroll-end:
Scrolling has been ended
scroll:
Scrolling is in progress
scroll-up:
Scrolling up is in progress
scroll-down:
Scrolling down is in progress
scroll-dir-change:
The direction of the scrolling has been changed
scroll-dir-change-up:
The direction of the scrolling has been changed to up
scroll-dir-change-down:
The direction of the scrolling has been changed to down
scroll-reached-top:
The scrolled element has reached its top
scroll-reached-bottom:
The scrolled element has reached its bottom
swipeup:
Event triggers when element has been swiped up (by touch)
swipedown:
Event triggers when element has been swiped down (by touch)
swipeleft:
Event triggers when element has been swiped left (by touch)
swiperight:
Event triggers when element has been swiped right (by touch)
anim-end:
Event triggers when CSS3 animation of the source element ends
trans-end:
Event triggers when CSS3 transition of the source element ends

data-track

The data-track attributes can be used to track events in Google Analytics.

@attr data-track-category (required) If set on an element, any click on the element will trigger a Google Analytics event and send the category.
@attr data-track-label (required) The label to send to Analytics.
@attr data-track-action (optional – defaults to ‘click’) The action label to send to Analytics. If the action label is set to ‘read’, the value label is accordingly set to 25, 50, 75, 100% based on the elements position and the events are automatically sent.
@attr data-track-value (optional) The value to send to Analytics. Must be an integer.

You can also subscribe to the ofw:track:trigger event which will be fired on the dom object whenever a data-track event is triggered. The category, label, action, and value will be passed in this order. See example.

API reference