Skip to content

Commit 8c37bc2

Browse files
danheberdendanheberden
committed
First four sections of plugins
1 parent 317ea38 commit 8c37bc2

File tree

4 files changed

+264
-0
lines changed

4 files changed

+264
-0
lines changed

‎content/plugins/basic-plugin-creation.md

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
chapter : plugins
3+
section : 2
4+
title : How to create a basic plugin
5+
attribution: jQuery Fundamentals
6+
---
7+
## How to create a basic plugin
8+
9+
The notation for creating a typical plugin is as follows:
10+
11+
<div class="example" markdown="1">
12+
(function($){
13+
$.fn.myNewPlugin = function() {
14+
return this.each(function(){
15+
// do something
16+
});
17+
};
18+
}(jQuery));
19+
</div>
20+
21+
Don't let that confuse you though. The point of a jQuery plugin is to extend jQuery's prototype object, and that's what's happening on this line:
22+
23+
<div class="example" markdown="1">
24+
$.fn.myNewPlugin = function() { //...
25+
</div>
26+
27+
We wrap this assignment in an immediately-invoked function:
28+
29+
<div class="example" markdown="1">
30+
(function($){
31+
//...
32+
}(jQuery));
33+
</div>
34+
35+
This has the effect of creating a "private" scope that allows us to extend jQuery using the dollar symbol without having to risk the possibility that the dollar has been overwritten by another library.
36+
37+
So our actual plugin, thus far, is this:
38+
39+
<div class="example" markdown="1">
40+
$.fn.myNewPlugin = function() {
41+
return this.each(function(){
42+
// do something
43+
});
44+
};
45+
</div>
46+
47+
The `this` keyword within the new plugin refers to the jQuery object on which the plugin is being called.
48+
49+
<div class="example" markdown="1">
50+
var somejQueryObject = $('#something');
51+
52+
$.fn.myNewPlugin = function() {
53+
alert(this === somejQueryObject);
54+
};
55+
56+
somejQueryObject.myNewPlugin(); // alerts 'true'
57+
</div>
58+
59+
Your typical jQuery object will contain references to any number of DOM elements, and that's why jQuery objects are often referred to as collections.
60+
61+
So, to do something with a collection we need to loop through it, which is most easily achieved using jQuery's `each()` method:
62+
63+
<div class="example" markdown="1">
64+
$.fn.myNewPlugin = function() {
65+
return this.each(function(){
66+
67+
});
68+
};
69+
</div>
70+
71+
jQuery's `each()` method, like most other jQuery methods, returns a jQuery object, thus enabling what we've all come to know and love as 'chaining' (`$(...).css().attr()...`).
72+
We wouldn't want to break this convention so we return the this object.
73+
Within this loop you can do whatever you want with each element.
74+
Here's an example of a small plugin using some of the techniques we've discussed:
75+
76+
<div class="example" markdown="1">
77+
(function($){
78+
$.fn.showLinkLocation = function() {
79+
return this.filter('a').each(function(){
80+
$(this).append(
81+
' (' + $(this).attr('href') + ')'
82+
);
83+
});
84+
};
85+
}(jQuery));
86+
87+
// Usage example:
88+
$('a').showLinkLocation();
89+
</div>
90+
91+
This handy plugin goes through all anchors in the collection and appends the href attribute in brackets.
92+
93+
<div class="example" markdown="1">
94+
&lt;!-- Before plugin is called: -->
95+
&lt;a href="page.html">Foo&lt;/a>
96+
97+
&lt;!-- After plugin is called: -->
98+
&lt;a href="page.html">Foo (page.html)&lt;/a>
99+
</div>
100+
101+
Our plugin can be optimized though:
102+
103+
<div class="example" markdown="1">
104+
(function($){
105+
$.fn.showLinkLocation = function() {
106+
return this.filter('a').append(function(){
107+
return ' (' + this.href + ')';
108+
});
109+
};
110+
}(jQuery));
111+
</div>
112+
113+
We're using the `append` method's capability to accept a callback, and the return value of that callback will determine what is appended to each element in the collection.
114+
Notice also that we're not using the `attr` method to retrieve the href attribute, because the native DOM API gives us easy access with the aptly named href property.
115+
116+
Here's another example of a plugin.
117+
This one doesn't require us to loop through every element with the `each()` method.
118+
Instead, we're simply going to delegate to other jQuery methods directly:
119+
120+
<div class="example" markdown="1">
121+
(function($){
122+
$.fn.fadeInAndAddClass = function(duration, className) {
123+
return this.fadeIn(duration, function(){
124+
$(this).addClass(className);
125+
});
126+
};
127+
}(jQuery));
128+
129+
// Usage example:
130+
$('a').fadeInAndAddClass(400, 'finishedFading');
131+
</div>

‎content/plugins/finding-evaluating-plugins.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
chapter : plugins
3+
section : 3
4+
title : Finding &amp; Evaluating Plugins
5+
attribution: jQuery Fundamentals
6+
---
7+
## Finding &amp; Evaluating Plugins
8+
9+
Plugins extend the basic jQuery functionality, and one of the most celebrated aspects of the library is its extensive plugin ecosystem.
10+
From table sorting to form validation to autocompletion ... if there’s a need for it, chances are good that someone has written a plugin for it.
11+
12+
The quality of jQuery plugins varies widely.
13+
Many plugins are extensively tested and well-maintained, but others are hastily created and then ignored. More than a few fail to follow best practices.
14+
15+
Google is your best initial resource for locating plugins, though the jQuery team is working on an improved plugin repository.
16+
Once you’ve identified some options via a Google search, you may want to consult the jQuery mailing list or the `#jquery` IRC channel to get input from others.
17+
18+
When looking for a plugin to fill a need, do your homework.
19+
Ensure that the plugin is well-documented, and look for the author to provide lots of examples of its use. Be wary of plugins that do far more than you need;
20+
they can end up adding substantial overhead to your page.
21+
For more tips on spotting a subpar plugin, read [Signs of a poorly written jQuery plugin](http://remysharp.com/2010/06/03/signs-of-a-poorly-written-jquery-plugin/) by Remy Sharp.
22+
23+
Once you choose a plugin, you’ll need to add it to your page.
24+
Download the plugin, unzip it if necessary, place it your application’s directory structure, then include the plugin in your page using a script tag (after you include jQuery).

‎content/plugins/whats-a-plugin.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
chapter : plugins
3+
section : 1
4+
title : What exactly is a plugin?
5+
attribution: jQuery Fundamentals
6+
---
7+
## What exactly is a plugin?
8+
9+
A jQuery plugin is simply a new method that we use to extend jQuery's prototype object.
10+
By extending the prototype object you enable all jQuery objects to inherit any methods that you add.
11+
As established, whenever you call `jQuery()` you're creating a new jQuery object, with all of jQuery's methods inherited.
12+
13+
The idea of a plugin is to do something with a collection of elements.
14+
You could consider each method that comes with the jQuery core a plugin, like `fadeOut` or `addClass`.
15+
16+
You can make your own plugins and use them privately in your code or you can release them into the wild.
17+
There are thousands of jQuery plugins available online.
18+
The barrier to creating a plugin of your own is so low that you'll want to do it straight away!

‎content/plugins/writing-plugins.md

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
chapter : plugins
3+
section : 4
4+
title : Writing Plugins
5+
attribution: jQuery Fundamentals
6+
---
7+
## Writing Plugins
8+
9+
Sometimes you want to make a piece of functionality available throughout your code;
10+
for example, perhaps you want a single method you can call on a jQuery selection that performs a series of operations on the selection.
11+
In this case, you may want to write a plugin.
12+
13+
Most plugins are simply methods created in the `$.fn` namespace. jQuery guarantees that a method called on a jQuery object will be able to access that jQuery object as this inside the method.
14+
In return, your plugin needs to guarantee that it returns the same object it received, unless explicitly documented otherwise.
15+
16+
Here is an example of a simple plugin:
17+
18+
<div class="example" markdown="1">
19+
Creating a plugin to add and remove a class on hover
20+
21+
// defining the plugin
22+
(function($){
23+
$.fn.hoverClass = function(c) {
24+
return this.hover(
25+
function() { $(this).toggleClass(c); }
26+
);
27+
};
28+
})(jQuery);
29+
30+
// using the plugin
31+
$('li').hoverClass('hover');
32+
</div>
33+
34+
For more on plugin development, read Mike Alsup's essential post, [A Plugin Development Pattern](http://www.learningjquery.com/2007/10/a-plugin-development-pattern).
35+
In it, he creates a plugin called `$.fn.hilight`, which provides support for the metadata plugin if it's present, and provides a centralized method for setting global and instance options for the plugin.
36+
37+
<div class="example" markdown="1">
38+
The Mike Alsup jQuery Plugin Development Pattern
39+
40+
//
41+
// create closure
42+
//
43+
(function($) {
44+
//
45+
// plugin definition
46+
//
47+
$.fn.hilight = function(options) {
48+
debug(this);
49+
// build main options before element iteration
50+
var opts = $.extend({}, $.fn.hilight.defaults, options);
51+
// iterate and reformat each matched element
52+
return this.each(function() {
53+
$this = $(this);
54+
// build element specific options
55+
var o = $.meta ? $.extend({}, opts, $this.data()) : opts;
56+
// update element styles
57+
$this.css({
58+
backgroundColor: o.background,
59+
color: o.foreground
60+
});
61+
var markup = $this.html();
62+
// call our format function
63+
markup = $.fn.hilight.format(markup);
64+
$this.html(markup);
65+
});
66+
};
67+
//
68+
// private function for debugging
69+
//
70+
function debug($obj) {
71+
if (window.console && window.console.log)
72+
window.console.log('hilight selection count: ' + $obj.size());
73+
};
74+
//
75+
// define and expose our format function
76+
//
77+
$.fn.hilight.format = function(txt) {
78+
return '<strong>' + txt + '</strong>';
79+
};
80+
//
81+
// plugin defaults
82+
//
83+
$.fn.hilight.defaults = {
84+
foreground: 'red',
85+
background: 'yellow'
86+
};
87+
//
88+
// end of closure
89+
//
90+
})(jQuery);
91+
</div>

0 commit comments

Comments
 (0)