base.md

Base Class

The base class that all components, behaviors, and their children extend from.

Usage

Understanding the base class may require prior knowledge of Toolkit's class system.

Options

Extensibility of classes can be achieved through customizable options. Each class has a different set of options and these options can be used to alter functionality.

Options can be set globally by modifying the static options object on the class. These options will need to be modified before a class is initialized.

// Single option
Toolkit.Tooltip.options.position = 'top-right';

// Multiple options
$.extend(Toolkit.Tooltip.options, {
    position: 'top-right',
    follow: true,
    mouseThrottle: 75
});

Options can also be set on a per instance basis when initializing a class. These options will inherit and override the global options.

$('.js-tooltip').tooltip({
    position: 'top-right'
});

Responsive Options

For situations where class options need to change depending on the size of the device, the responsive option can be used (this option can be used by all classes). This option should define an object of settings, with each setting having a breakpoint to compare against and the custom options to override with.

For example, our carousel should have different item counts depending on device size. The default options will apply to all devices not found in the breakpoints.

$('.carousel').carousel({
    itemsToShow: 3,
    responsive: {
        tablet: {
            breakpoint: '(min-width: 768px) and (max-width: 1024px)',
            itemsToShow: 2
        },
        mobile: {
            breakpoint: '(max-width: 480px)',
            itemsToShow: 1
        }
    }
});

Breakpoint detection uses the built in matchMedia() function. All breakpoint definitions should follow the media query specification.

Breakpoint detection only triggers on the initial page load and will not trigger if you resize your browser manually by resizing the OS window.

The matchMedia() function is not available in IE9 and below and will require a polyfill.

Hooks

Similar to native DOM events, the class layer has a system for dispatching callbacks at specific events called hooks. The difference between DOM events and hooks is that hooks are set as options through the class constructor or manually added through the addHook() and addHooks() methods. When setting through options, any option that begins with on, is named after an event, and defines an anonymous function, is considered a hook.

Now anytime fireEvent() is called, all attached hooks will also be triggered.

// Set through options
$('.carousel').carousel({
    onInit: function() {
        // Do something
    }
});

// Set through method
$('.carousel').toolkit('carousel').addHook('init', function() {
    // Do something
});

The "this" context within hooks will be bound to the class instance.

Hooks are triggered before native DOM events.

Options

Option	Type	Default	Description
cache	bool	true	Whether to cache internal data or the response of AJAX requests.
debug	bool	false	Whether to enable debugging for this class.

Events

Event	Arguments	Description
init		Triggered after a plugin has initialized.
destroying		Triggered before a plugin is destroyed.
destroyed		Triggered after a plugin is destroyed.

Properties

Property	Type	Description
enabled	boolean	Whether the instance is currently enabled or not. Disabled plugins will not trigger events or functionality. Can be toggled through enable() and disable() methods.
cache	object	Cached data by key.
name	string	The name of the class. This should not be modified.
options	object	Configurable options. More information can be found above.
uid	int	A unique identifier for the plugin instance. The value correlates to the number of instances in the page.
version	string	The last version this class was updated. This should not be modified.

Methods

Method	Description
addEvent(string:event, string:context, string|func:callback[, string:selector])	Add an event that will be bound during bindEvents(). The context should be the name of a class property, or the document, or the window. The callback should be the name of a class function, or a function itself. The selector can optionally be defined to apply delegation.
addEvents(array:events)	Add multiple events. Each item in the array should be an array with 3-4 items, with each index representing an argument of addEvent().
addHook(string:type, func:callback)	Add a hook callback that will be executed during specific events.
addHooks(string:type, array:callbacks)	Add multiple hooks. The callbacks should be an array of functions.
bindEvents(string:type)	Bind or unbind events for elements found in the events mapping. The type should either be "on" or "off".
destroy()	Disable the plugin, unbind events, remove elements, and delete the instance.
disable()	Disable the plugin and unbind events.
enable()	Enable the plugin and bind events.
fireEvent(string:type[, array:args])	Trigger an event with optional arguments to pass. Will execute all hooks for the defined type and any DOM events that are attached to related elements. Will also log to console if debugging is enabled.
initialize()	Triggered at the end of construction. Will trigger event binding and init events.
removeHook(string:type[, func:callback])	Remove a hook callback by type. If no callback is provided, all hooks for that type will be removed.
setOptions(object:options)	Set the options unique for the current plugin instance. Will also apply any responsive options and automatically add hooks.