Module: JQPlugin

Abstract base class for collection plugins v1.0.2.

Written by Keith Wood (wood.keith{at}optusnet.com.au) December 2013.

Licensed under the MIT license (http://keith-wood.name/licence.html).

Use $.JQPlugin.createPlugin to create new plugins using this framework.

This base class provides common functionality such as:

  • Creates jQuery bridge - allowing you to invoke your plugin on a collection of elements.
  • Handles initialisation including reading settings from metadata - an instance object is attached to the affected element(s) containing all the necessary data.
  • Handles option retrieval and update - options can be set through default values, through inline metadata, or through instantiation settings.
    Metadata is specified as an attribute on the element: data-<pluginName>="<option name>: '<value>', ...". Dates should be specified as strings in this format: 'new Date(y, m-1, d)'.
  • Handles method calling - inner functions starting with '_'are inaccessible, whereas others can be called via $(selector).pluginName('functionName').
  • Handles plugin destruction - removing all trace of the plugin.
Source:

Members

(inner) deepMerge

Whether or not a deep merge should be performed when accumulating options. The default is true but can be overridden in a sub-class.
Source:

(inner) defaultOptions

Default options for instances of this plugin (default: {}).
Source:
Example
defaultOptions: {
  selectedClass: 'selected',
  triggers: 'click'
}

(inner) name

Name to identify this plugin.
Source:
Example
name: 'tabs'

(inner) regionalOptions

Options dependent on the locale. Indexed by language and (optional) country code, with '' denoting the default language (English/US). Normally additional languages would be provided as separate files to all them to be included as needed.
Source:
Example
regionalOptions: {
  '': {
    greeting: 'Hi'
  }
}

Methods

(protected, inner) _getInst(elem) → {object}

Retrieve the instance data for element.
Parameters:
Name Type Description
elem Element The source element.
Source:
Returns:
The instance data or {} if none.
Type
object

(protected, inner) _getMarker() → {string}

Retrieve a marker class for affected elements. In the format: is-<pluginName>.
Source:
Returns:
The marker class.
Type
string

(protected, inner) _init()

Initialise the plugin. Create the jQuery bridge - plugin name xyz produces singleton $.xyz and collection function $.fn.xyz.
Source:

(protected, inner) _instSettings(elem, options) → {object}

Retrieve additional instance settings. Override this in a sub-class to provide extra settings. These are added directly to the instance object. Default attributes of an instance object are shown as properties below:
Parameters:
Name Type Description
elem jQuery The current jQuery element.
options object The instance options.
Properties:
Name Type Description
elem Element The element to which this instance applies.
name string The name of this plugin.
options object The accumulated options for this instance.
Source:
Returns:
Any extra instance values.
Type
object
Example
_instSettings: function(elem, options) {
  return {nav: elem.find(options.navSelector)};
}

(protected, inner) _optionsChanged(elem, inst, options)

Plugin specific options processing. Old value available in inst.options[name], new value in options[name]. Override this in a sub-class to perform extra activities.
Parameters:
Name Type Description
elem jQuery The current jQuery element.
inst object The instance settings.
options object The new options.
Source:
Example
_optionsChanged: function(elem, inst, options) {
  if (options.name != inst.options.name) {
    elem.removeClass(inst.options.name).addClass(options.name);
  }
}

(protected, inner) _postAttach(elem, inst)

Plugin specific post initialisation. Override this in a sub-class to perform extra activities. This is where you would implement your plugin's main functionality.
Parameters:
Name Type Description
elem jQuery The current jQuery element.
inst object The instance settings.
Source:
Example
_postAttach: function(elem, inst) {
  elem.on('click.' + this.name, function() {
    ...
  });
}

(protected, inner) _preDestroy(elem, inst)

Plugin specific pre destruction. It is invoked as part of the destroy processing. Override this in a sub-class to perform extra activities and undo everything that was done in the _postAttach or _optionsChanged functions.
Parameters:
Name Type Description
elem jQuery The current jQuery element.
inst object The instance settings.
Source:
Example
_preDestroy: function(elem, inst) {
  elem.off('.' + this.name);
}

(inner) destroy(elem)

Remove all trace of the plugin. Override _preDestroy for plugin-specific processing.
Parameters:
Name Type Description
elem Element The source element.
Source:
Example
$(selector).plugin('destroy')

(inner) option(elem, nameopt, valueopt) → {any|object}

Retrieve or reconfigure the settings for a plugin. If new settings are provided they are applied to the instance options. If an option name only is provided the value of that option is returned. If no name or value is provided, all options are returned. Override _optionsChanged for plugin-specific processing when option values change.
Parameters:
Name Type Attributes Description
elem Element The source element.
name object | string <optional>
 The collection of new option values or the name of a single option.
value any <optional>
 The value for a single named option.
Source:
Returns:
If retrieving a single value or all options.
Type
any | object
Example
$(selector).plugin('option', 'name', value) // Set one option
$(selector).plugin('option', {name: value, ...}) // Set multiple options
var value = $(selector).plugin('option', 'name') // Get one option
var options = $(selector).plugin('option') // Get all options

(inner) setDefaults(options)

Set default options for all subsequent instances.
Parameters:
Name Type Description
options object The new default options.
Source:
Example
$.pluginName.setDefaults({name: value, ...})