Skip to content

Commit 7320f3e

Browse files
OOPManOOPMan
committed
#6: Replaced README.rst with README.md
1 parent 324ecf4 commit 7320f3e

File tree

2 files changed

+180
-375
lines changed

2 files changed

+180
-375
lines changed

‎README.md

Lines changed: 180 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,55 @@
1-
jQuery PluginCreator v2.0.0
2-
============================
1+
# jQuery PluginCreator v2.0.0
32

43
A jQuery plugin for creating stateful, extensible jQuery plugins using ES6
54

65

7-
Contents
8-
--------
6+
## Contents
97

108
1. Introduction
119
2. Why v2.x?
1210
3. Requirements
1311
4. Usage
14-
5. The jQueryPlugin class
15-
6. The jQuery.addPlugin API
16-
7. The jQuery.fn.yourPlugin API
12+
5. The jQuery.addPlugin API
13+
6. The jQuery.fn.yourPlugin API
14+
7. The jQueryPlugin class
1715
8. Tests
1816

1917

20-
Introduction
21-
------------
18+
## Introduction
2219

23-
jQuery PluginCreator is a small JavaScript library that can be used in conjunction with jQuery to easily
24-
create jQuery plugins.
20+
jQuery PluginCreator is a small JavaScript library that can be used in
21+
conjunction with jQuery to easily create jQuery plugins.
2522

26-
Creating a plugin with PluginCreator is pretty easy, you simply implement your plugin as an ES6 class
27-
extending the `jQueryPlugin` class exported by PluginCreator. PluginCreator creates a new jQuery plugin
28-
function that can be executed against jQuery selections to instantiate the class against selected elements.
23+
Creating a plugin with PluginCreator is pretty easy, you simply implement
24+
your plugin as an ES6 class extending the `jQueryPlugin` class exported
25+
by PluginCreator. PluginCreator creates a new jQuery plugin function that
26+
can be executed against jQuery selections to instantiate the class against
27+
selected elements.
2928

30-
Plugins created using PluginCreator can also be extended using standard ES6 inheritance semantics to
31-
implement new plugins that extend functionality in the base plugin.
29+
Plugins created using PluginCreator can also be extended using standard
30+
ES6 inheritance semantics to implement new plugins that extend functionality
31+
in the base plugin.
3232

3333

34-
Why v2.x?
35-
---------
34+
## Why v2.x?
3635

37-
v2.x of jQuery PluginCreator was initiated in order to simplify the project and leverage the simplified
38-
inheritance scheme provided by ES6.
36+
v2.x of jQuery PluginCreator was initiated in order to simplify the project
37+
and leverage the simplified inheritance scheme provided by ES6.
3938

40-
v1.x implemented a custom single-inheritance scheme along with a number of additional features that allowed
41-
for some more complex behaviours including post-definition patching of plugin members and plugin instance
42-
members. This scheme was implemented using the `esprima` library and, as a whole, worked fairly well. It
43-
has seen production usage and generally does the job, albeit with a few caveats.
39+
v1.x implemented a custom single-inheritance scheme along with a number
40+
of additional features that allowed for some more complex behaviours including
41+
post-definition patching of plugin members and plugin instance members.
42+
This scheme was implemented using the `esprima` library and, as a whole,
43+
worked fairly well. It has seen production usage and generally does the
44+
job, albeit with a few caveats.
4445

45-
Going forward, however, the desire was to reduce the amount of custom implementation code and capacity to
46-
engage in _funny business_ while also bringing the project as a whole closer to the ES6 way of doing things.
46+
Going forward, however, the desire was to reduce the amount of custom
47+
implementation code and capacity to engage in *funny business* while also
48+
bringing the project as a whole closer to the ES6 way of doing things.
4749
Thus, v2.x was born.
4850

4951

50-
Requirements
51-
------------
52+
## Requirements
5253

5354
jQuery PluginCreator can be used in any of the following JavaScript environments:
5455

@@ -57,14 +58,13 @@ jQuery PluginCreator can be used in any of the following JavaScript environments
5758
* Browser + CommonJS
5859
* Browser + ES6 Modules
5960

60-
In order to make use of jQuery PluginCreator you will need jQuery. For a browser environment, any recent version should
61-
do the trick.
61+
In order to make use of jQuery PluginCreator you will need jQuery. For a
62+
browser environment, any recent version should do the trick.
6263

6364

64-
Usage
65-
-----
65+
## Usage
6666

67-
# Browser
67+
#### Browser
6868
```html
6969

7070
<html>
@@ -92,7 +92,7 @@ $.addPlugin(myPlugin, {
9292

9393
```
9494

95-
# Browser + AMD
95+
#### Browser + AMD
9696
```javascript
9797

9898
define(["jquery", "jquery.plugincreator"], function ($, pluginCreator) {
@@ -110,7 +110,7 @@ define(["jquery", "jquery.plugincreator"], function ($, pluginCreator) {
110110

111111
```
112112
113-
# Browser + CommonJS
113+
#### Browser + CommonJS
114114
```javascript
115115

116116
var $ = require("jquery"),
@@ -129,7 +129,7 @@ $.addPlugin(myPlugin, {
129129

130130
```
131131
132-
# Browser + ES6 Modules
132+
#### Browser + ES6 Modules
133133
```javascript
134134

135135
import addPlugin, { jQueryPlugin } from "jquery.plugincreator";
@@ -145,4 +145,147 @@ addPlugin(myPlugin, {
145145
defaultSomething2: 10
146146
});
147147

148-
```
148+
```
149+
150+
151+
## The jQuery.addPlugin API
152+
153+
jQuery PluginCreator extends the global jQuery object with the following function:
154+
155+
##### addPlugin(pluginClass, defaults={})
156+
The addPlugin function accepts two parameters, one of which is optional.
157+
158+
The first parameter must be a class that inherits from the *jQueryPlugin*
159+
class, the second is an optional plain object of default values to be
160+
available on the `options` member of instances of the class plugin.
161+
162+
When called, addPlugin generates a new function attached to the
163+
`jQuery.fn` object. This function is attached using the `name` property
164+
provided by the plugin class. Thus, a plugin class defined as
165+
`class myPlugin extends jQueryPlugin {}` will be bound to `jQuery.fn.myPlugin`
166+
when passed in to the `addPlugin` function.
167+
168+
##### addPlugin.jQueryPlugin
169+
To aid development in environments that don't support ES6 modules, the
170+
`jQueryPlugin` class is also made available as a property of the `addPlugin`
171+
function that is bound to `jQuery`.
172+
173+
174+
## The jQuery.fn.yourPlugin API
175+
176+
Once the `jQuery.addPlugin` function has been used to attach a new plugin,
177+
that plugin can be accessed as normal using the `jQuery.fn.NAME` object
178+
and applied to jQuery selections using the standard `jQuery("selector").NAME()`
179+
method:
180+
181+
##### jQuery.fn.NAME(options, ...args)
182+
183+
###### options
184+
A `string` or plain `object`.
185+
186+
###### args
187+
Additional parameters may be passed to `jQuery.fn.NAME` and will be passed on to the plugin processing logic and
188+
from there to any plugin instance member functions or constructors called.
189+
190+
###### Function behaviour
191+
The base plugin function which can be used to instantiate plugin
192+
instances or interact with existing plugin instances.
193+
194+
When `jQuery.fn.NAME` is called on a given jQuery selection it does the following:
195+
196+
1. If the selection contains exactly 1 element, it returns the result of
197+
executing the plugin processing logic on that element. This allows a
198+
call to like `jQuery("#your-element").yourPlugin("getInstance")` to
199+
work as expected. In instance where a call like `jQuery("#your-element").yourPlugin("yourMethod")`
200+
would return no value or return the `undefined` value then the return
201+
value will be the jQuery selection, preserving the jQuery chaining effect.
202+
2. If the selection does not contain exactly 1 element and...
203+
204+
a. `options === "map"`, it applies the plugin processing logic to the
205+
selection using the `map` operation, returning
206+
the resultant selection. This output selection can be converted to
207+
a standard `Array` by applying the `get` operation on the selection.
208+
When applying the plugin processing logic the initial `options` value
209+
of `"map"` is discarded. The next argument is considered to be the
210+
`options` value and any further arguments are treated as additional parameters.
211+
212+
b. `options !== "map"`, it applies the plugin processing logic to the
213+
selection using the `each` operation, returning the selection as expected.
214+
215+
The plugin processing logic does the following:
216+
217+
1. Attempt to retrieve plugin instance associated with input element.
218+
2. If an instance is found and `options` is a `string` and `instance[options]`
219+
is a function, treat the call to `jQuery.fn.NAME` as an attempt to call
220+
a member function on the plugin instance. The member function, `instance.[options]`
221+
is called and any additional parameters supplied to `jQuery.fn.NAME`
222+
will be passed to the member function being called. If `options` is not
223+
a `string` or `instance[options]` is not a function, a `jQueryPluginCreatorError`
224+
exception will be thrown.
225+
3. If no instance is found, instantiate a plugin instance on the element
226+
using the contents of the `options` parameter to override values supplied
227+
by `jQuery.fn.NAME.defaults` to the plugin instance. Additionally, any
228+
additional parameters supplied to `jQuery.fn.NAME` will be passed in
229+
to the `init` member function of the plugin instance. The plugin instance
230+
is associated with its parent element using a data attribute of the form
231+
`data-jquery-plugincreator-NAME`. The instantiated plugin is returned,
232+
allowing plugin instantiation on single-element selections to be used for assignments.
233+
234+
235+
##### jQuery.fn.NAME.defaults
236+
The `defaults` supplied to `addPlugin`. This is exposed in order to allow
237+
the key-value pairs stored to manipulated.
238+
239+
240+
## The jQueryPlugin class
241+
242+
The jQueryPlugin class provides a base for stateful jQuery Plugins. The
243+
following methods are provided by the jQueryPlugin class:
244+
245+
##### constructor(element, defaults={}, options={})
246+
The default constructor performs a number of important set-up tasks
247+
for a plugin instance.
248+
249+
It binds `this.element` to `element`, `this.context` to `jQuery(element)`
250+
and `this.options` to the result of mering `options` over `defaults`.
251+
252+
While it is possible to override the `constructor` method, it is not
253+
recommended. Rather, implement your initialization code in the `init`
254+
method. If you must override `constructor`, ensure you call the
255+
ancestor `constructor` to preserve initialisation behaviour.
256+
257+
##### init()
258+
The default `init` method does nothing. If you wish to perform
259+
custom initialization it should be implemented by overriding this
260+
method.
261+
262+
Although the default method accepts no parameters you can provide
263+
ones when you override it.
264+
265+
##### getInstance()
266+
The `getInstance` method exists in order to allow for jQuery usage
267+
such as `let pluginInstance = jQuery("#something").myPlugin("getInstance")`.
268+
269+
##### update(options)
270+
This method can be used to updated the data stored in `this.options` for
271+
a plugin instance. The `jQuery.extend` function is used to perform this
272+
update with the recursive merge option enabled.
273+
274+
##### destroy()
275+
The `destroy` method is essentially a destructor, albeit one that needs
276+
to be manually called. The default implementation does the following:
277+
278+
1. Triggers an event named `jquery-plugincreator-NAME.destroy` on `this.context`
279+
2. Removes the `jquery-plugincreator-NAME` class on `this.element`
280+
3. Removes the `jquery-plugincreator-NAME` data associated with `this.element`
281+
4. Removes the `data-jquery-plugincreator-NAME` attribute on `this.element`
282+
283+
If you override this method, you should ensure you call through to the
284+
ancestor `destroy` function to ensure it the method continues behave as
285+
expected by users.
286+
287+
288+
## Tests
289+
290+
In order to run the tests you will need to checkout the project source,
291+
execute `npm install` in the source root and then run `npm run-script test`.

0 commit comments

Comments
 (0)