easyPlug : création de plugin jQuery, the easy way !
Bonjour tout le monde, aujourd'hui je voulais vous présenter easyPlug.
N'hésitez pas à me faire part de vos impressions, critiques, idées,… ce n'est qu'une première version et il y a matière à développer !
Pour le télécharger, le forker,… http://cahnory.github.com/jQuery.easyPlug
jQuery.easyPlug
EasyPlug a pour but de faciliter la création de plugin jQuery en s'occupant à votre place du code commun à la majorité des plugins jQuery.
Il s'occupera notamment de relier votre plugin à l'object jQuery en maintenant la chainabilité, permettant l'appel de méthodes publiques…
La courte documentation qui suit développe plus en détails ce qu'easyPlug fait pour vous et comment. Elle a été rédigé en anglais (certainement pas un excellent anglais d'ailleurs ^^) pour toucher le plus grand nombre mais si vous y voyez un intérêt je prendrai le temps d'en faire une copie française.
[Note de modération]
Traduction en cours disponible sous peu ...
[/Note de modération]
Usage
EasyPlug is (until now) a single function attached to the jQuery object.
It allows you to define a jQuery plugin easily.
Code:
1
2
|
$.easyPlug( constructor [, settings ] ); |
Parameters
constructor
A function called on instantiation. A plugin instance is created for each element in the set of matched elements.
The constructor has four arguments :
- Plugin: the Plugin object
- element: jQuery object with a single element from the original set of elements
- settings: Merged contents of plugin presets and user options
- options: Original user options
settings
An object of settings providing informations to easyPlug in order to prepare the plugin.
Here is the list of properties:
- name: the name of your plugin. If you don't provide a name, an unique one will be generated
- presets: default settings objects. A copy of it, merged with user options, is provided on instantiation.
- events: an array of event name. Event names will be prefixed by easyPlug (e.g. *ready* become *pluginName-ready*)
None of this properties is required.
Returns
Plugin object
The Plugin object. You can, for example, add "static" properties and/or methods to it.
How it helps ?
Add to jQuery
EasyPlug attach the plugin controller to the jQuery *fn* property (prototype). The controller instantiate plugin if needed and/or call public method.
The controller is called each time you call your plugin:
Code:
1
2
|
$( selection ).pluginName(); |
EasyPlug also attach the Plugin object directly on the jQuery object, acting as "static":
Chainability
If no public method is called or, if the method returns undefined, the controller returns the set of matche elements.
If a public method does not return undefined, the value is directly returned.
Code:
1
2
|
$( selection ).pluginName().attr( 'foo', 'bar' ); |
Public methods
Declaration
To declare your public method, you have to add it to the *methods* property in your constructor:
Code:
1
2
3
4
5
6
|
$.easyPlug(function() {
this.methods.methodName = function( [ argument, … ] ) {
// instructions
};
}); |
Calling
To call a public method, all you have to do is to pass its name as first argument:
Code:
1
2
|
$( selection ).pluginName( 'methodName' [, argument, … ] ); |
Predefined methods
Until now there is a single predefined method.
- settings(): returns a copy of the settings object
Custom events
All custom events are automatically prefixed in order to avoid conflicts between public and standard events.
Custom events are defined in the *events* property of the Plugin objects.
Code:
1
2
|
$.pluginName.events.custom; // pluginName-custom |
"Static" public methods
Declaration
To declare your static public method, you have to add it directly on the Plugin object:
Code:
1
2
3
4
|
$.pluginName.methodName = function( [ argument, … ] ) {
// instructions
}; |
Calling
Static public method are called like any javascript method:
Code:
1
2
|
$.pluginName.methodName( [ argument, … ] ); |
Predefined methods
- name(): returns the plugin name
- local( string ): returns a string prefixed with '*pluginName*-'
- space( string ): returns a string suffixed with '.easyPlug-*pluginName*'
