Create a Plugin

This base "class" provides the common abilities required by a collection plugin (one that operates on a jQuery selection) and supports inheritance of functionality from other plugins within the framework.

The functionality provided by the base "class" includes:

Following the creation of a new plugin, jQuery is updated to contain a singleton manager object through which you can access global settings and functions, and a collection plugin function to allow you to attach the plugin to selected elements.

Options for the plugin on a particular element can be set through global default options, through metadata included in the markup, or through values supplied to the initialisation call. Each source overrides any previous values. Metadata options are set in a data attribute named for the plugin and consist of a series of name/value pairs, with the values being basic numbers, Booleans, or strings. Dates can be specified as strings of the form 'new Date(2014, 1-1, 26)'.

<textarea rows="5" cols="50"
	data-maxlength="max: 300, truncate: false"></textarea>

Override functions may be invoked as methods by providing their name to the plugin call. The mapping is handled by the framework and the resulting function receives the current element as its first parameter. Any additional parameters supplied in the original call then follow as subsequent parameter values. Any function that starts with an underscore (_) is considered internal and cannot be called as a method.

$(selector).maxlength('disable');

The call above would map onto the following function within the plugin overrides.

disable: function(elem) {
	$(elem).prop('disabled', true);
},
SignatureReturnsComments
$.JQPlugin.createPlugin(superClass, overrides)- Create the infrastructure to support a new plugin with custom functionality.

superClass (string) is the name of an existing plugin "class" to extend. It is optional and defaults to the basic 'JQPlugin' if not supplied.

overrides (object) is the set of attributes and functions that override those provided by the parent "class". Within an override function, you can use this._super to refer to the inherited function and invoke its abilities at the appropriate time in the processing. See the Overrides tab for full details.

$.JQPlugin.createPlugin({
	name: 'myPlugin',
	defaultOptions: {...},
	_postAttach: function(elem, inst) {
		...
	}
});

$.JQPlugin.createPlugin('myPlugin', {
	name: 'myPlugin2',
	_postAttach: function(elem, inst) {
		this._super(elem, inst);
		...
	}
});
Plugin Overrides

Customise a plugin with these attributes and functions (most are optional):

defaultOptions | _getInst() | _getMarker() | _getters | _init() | _instSettings() | name | _optionsChanged() | _postAttach() | _preDestroy() | regionalOptions | setDefaults()

NameTypeDefaultComments
namestring- This is the name of the plugin and must be supplied. It is used to generate the jQuery bridging functions. For example, a plugin name of 'tabs' produces a singleton object $.tabs and the collection function $.fn.tabs. If the name contains hyphens (-), it is converted to camel-case before being used. For example, a plugin name of 'my-tabs' produces a singleton object $.myTabs and the collection function $.fn.myTabs.

The name is also used to identify the instance object held as data against each affected element, and for namespacing event handlers.

name: 'maxlength',
defaultOptionsobject{} The complete set of options that may be configured on this plugin, along with their default values. All possible settings should be listed here with accompanying comments to indicate their purpose. These options are used as the basis for the settings for each instance of the plugin.

defaultOptions: {
	max: 200,
	truncate: true,
	showFeedback: true,
	feedbackTarget: null,
	onFull: null
},
regionalOptionsobject{} The complete set of options that may be localised on this plugin, along with their default values. Each item within this object is indexed by the language and (optionally) region to which it applies, with '' denoting the default English/US. For example 'fr' denotes French, while 'fr-CH' denotes French as used in Switzerland. Other localisations should appear in separate files, suffixed by the language/region code. All possible settings should be listed here with accompanying comments to indicate their purpose. These options are used as the basis for the settings for each instance of the plugin.

regionalOptions: { // Available regional settings, indexed by language/region code
	'': { // Default regional settings - English/US
		feedbackText: '{r} characters remaining ({m} maximum)',
		overflowText: '{o} characters too many ({m} maximum)'
	}
},
_gettersstring[][] The list of method names that don't return the current jQuery object as their result. Such methods will break chaining and need to be identified.

_getters: ['curLength'],
SignatureReturnsComments
_getMarker()string Returns the class used to mark an element as having been initialised with this plugin.

if (elem.hasClass(this._getMarker())) ...
_init()- Initialise this plugin and create the jQuery bridging functions. This function can be overridden in a plugin to perform one-off initialisations.

_init: function() {
	this._super();
	$(document).on('click', function() {...});
},
setDefaults(options)- Sets the default options for subsequent plugin initialisations.

options (object) is the set of new options to be used as defaults.

$.maxlength.setDefaults({max: 300})
_instSettings(elem, options)object Override this function in a plugin to return an object containing any additional instance settings that should be saved against the affected element(s).

elem (jQuery) is the jQuery object for the current element.

options (object) is the set of options to be used for this element.

_instSettings: function(elem, options) {
	return {feedbackTarget: $([])};
},
_postAttach(elem, inst)- Override this function in a plugin to add the functionality specific to that plugin. It is invoked as part of the initialisation processing for the plugin on an element. Prior to this being called, the framework has set the marker class on the element and has saved the instance object as data against the element.

elem (jQuery) is the jQuery object for the current element.

inst (object) is the instance object for this element, containing the basic attributes name (string) the name of this plugin, elem (jQuery) the element to which it applies, and options (object) the current options set for this element.

_postAttach: function(elem, inst) {
	elem.on('keypress.' + inst.name, function(event) {...}).
		on('keyup.' + inst.name, function() {...});
},
_getInst(elem)object Retrieve the instance object for an element. Usually this would be used in a method function to obtain details regarding the current state of the plugin for the targeted element.

elem (Element) is the DOM element to retrieve from.

curLength: function(elem) {
	var inst = this._getInst(elem);
	...
	return {used: len, remaining: inst.options.max - len};
},
_optionsChanged(elem, inst, options)- Override this function to react to the options for a plugin instance being changed. This function is invoked in response to the 'option' method call, as well as at the end of the initialisation process. You should make any changes to the element based on the options values here.

You can compare the old (inst.options.xxx) and new (options.xxx) values of an option to determine whether any change should occur.

elem (jQuery) is the element having values changed.

inst (object) is the instance object for this element.

options (object) is the set of new options being applied.

_optionsChanged: function(elem, inst, options) {
	$.extend(inst.options, options);
	...
	if (inst.options.showFeedback) { // Add new feedback element
		...
	}
	elem.off('mouseover.' + inst.name + ' focus.' + inst.name +
		'mouseout.' + inst.name + ' blur.' + inst.name);
	if (inst.options.showFeedback == 'active') { // Additional event handlers
		elem.on('mouseover.' + inst.name, function() {...}).
			on('mouseout.' + inst.name, function() {...}).
			on('focus.' + inst.name, function() {...}).
			on('blur.' + inst.name, function() {...});
		...
	}
	...
},
_preDestroy(elem, inst)- Override this function to undo any changes made in the _postAttach or _optionsChanged functions so as to restore the element to its original state. It is invoked as part of the 'destroy' method processing. The framework will remove the marker class and the instance object.

elem (jQuery) is the element having the plugin removed.

inst (object) is the instance object for this element.

_preDestroy: function(elem, inst) {
	...
	elem.removeClass(this._fullClass + ' ' + this._overflowClass).off('.' + inst.name);
}