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.

Activation

@todo update with info about site/index.php activation!
@todod add non-singleton info!

To manually activate data attribute libraries on certain pages:

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

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.

Outlast Web & Mobile Development (c) 2018 | Privacy Policy |