Have a nice day! @@ -183,19 +183,19 @@ choose: - +``` And now we can hilight each of these divs uniquely using a single line of script: - +``` $('.hilight').hilight(); - +``` ###Bob and Sue Let's say Bob has created a wicked new gallery plugin (called "superGallery") which takes a list of images and makes them navigable. Bob's thrown in some animation to make it more interesting. He's tried to make the plugin as customizable as possible, and has ended up with something like this: - +``` jQuery.fn.superGallery = function(options) { // Bob's default settings: var defaults = { @@ -226,7 +226,7 @@ jQuery.fn.superGallery = function(options) { // ---------------------------- }); }; - +``` The first thing that probably comes to your mind (ok, maybe not the first) is the prospect of how huge this plugin must be to accommodate such a level of customization. The plugin, if it weren't fictional, would probably be a lot larger than necessary. There are only so many kilobytes people will be willing to spend! @@ -254,7 +254,7 @@ Developers who use your plugin shouldn't have to learn a new language or termino Bob thought he was offering maximum customization with his *delay* option (look above). He made it so that with his plugin you can specify four different delays, "quite short," "very short," "quite long," or "very long": - +``` var delayDuration = 0; switch (settings.delay) { case 'very short' : delayDuration = 100; @@ -267,7 +267,7 @@ switch (settings.delay) { break; default : delayDuration = 200 } - +``` Not only does this limit the level of control people have, but it takes up quite a bit of space. Twelve lines of code just to define the delaying time is a bit much, don't you think? A better way to construct this option would be to let plugin users specify the amount of time (in milliseconds) as a number, so that no processing of the option needs to take place. @@ -279,7 +279,7 @@ If your plugin creates elements to be used within the DOM, then it's a good idea A bad implementation: - +``` // Plugin code $('<div id="the_gallery_Wrapper" />').appendTo('body'); $('#the_gallery_wrapper').append('...'); @@ -291,7 +291,7 @@ var $wrapper = $('<div />') .attr(settings.wrapperAttrs) .appendTo(settings.container); $wrapper.append('...'); // Easy to reference later... - +``` Notice that we've created a reference to the injected wrapper and we're also calling the 'attr' method to add any specified attributes to the element. So, in our settings it might be handled like this: @@ -309,7 +309,7 @@ Notice that we've created a reference to the injected wrapper and we're also cal // We can use the extend method to merge options/settings as usual: // But with the added first parameter of TRUE to signify a DEEP COPY: var settings = $.extend(true, {}, defaults, options); - +``` The *$.extend()* method will now recurse through all nested objects to give us a merged version of both the defaults and the passed options, giving the passed options precedence. @@ -317,7 +317,7 @@ The plugin user now has the power to specify any attribute of that wrapper eleme The same model can be used to let the user define CSS styles: - +``` var defaults = { wrapperCSS : {}, @@ -331,7 +331,7 @@ The same model can be used to let the user define CSS styles: .attr(settings.wrapperAttrs) .css(settings.wrapperCSS) // ** Set CSS! .appendTo(settings.container); - +``` Your plugin may have an associated StyleSheet where developers can add CSS styles. Even in this situation it's a good idea to offer some convenient way of setting styles in JavaScript, without having to use a selector to get at the elements. @@ -341,7 +341,7 @@ Your plugin may have an associated StyleSheet where developers can add CSS style If your plugin is driven by events then it might be a good idea to provide a callback capability for each event. Plus, you can create your own custom events and then provide callbacks for those. In this gallery plugin it might make sense to add an 'onImageShow' callback. - +``` var defaults = { onImageShow : function(){}, // we define an empty anonymous function @@ -366,7 +366,7 @@ If your plugin is driven by events then it might be a good idea to provide a cal Instead of initiating the callback via traditional means (adding parenthesis) we're calling it in the context of 'this' which will be a reference to the image node. This means that you have access to the actual image node through the 'this' keyword within the callback: - +``` $('ul.imgs li').superGallery({ onImageShow : function() { @@ -378,7 +378,7 @@ Instead of initiating the callback via traditional means (adding parenthesis) we // ... }); - +``` Similarly you could add an "onImageHide" callback and numerous other ones... diff --git a/page/plugins/basic-plugin-creation.md b/page/plugins/basic-plugin-creation.md index 6cfd907e..70807dbb 100644 --- a/page/plugins/basic-plugin-creation.md +++ b/page/plugins/basic-plugin-creation.md @@ -10,9 +10,9 @@ In this case, you may want to write a plugin. Before we write our own plugins, we must first understand a little about how jQuery works. Take a look at this code: - +``` $('a').css('color','red'); - +``` This is some pretty basic jQuery code, but do you know what's happening behind the scenes? Whenever you use the `$` function to select elements, it returns an object. This object contains all of the methods you've been using (`css()`, `click()`, etc.), and all of the elements that fit your selector. The `$` function gets the methods from the `$.fn` object. This object contains all of the jQuery methods, and If we want to write our own methods, it will need to contain those as well. @@ -20,13 +20,13 @@ This is some pretty basic jQuery code, but do you know what's happening behind t Let's say we want to create a plugin that makes text green. All we have to do is add a function called `greenify` to `$.fn` and it will available just like any other method. - +``` $.fn.greenify = function () { this.css('color','green'); } $('a').greenify(); // makes all the links green - +``` Notice that to use `css()`, another method, we use `this`, not `$(this)`. This is because our `greenify` function is a part of the same object as `css()`. @@ -34,31 +34,31 @@ Notice that to use `css()`, another method, we use `this`, not `$(this)`. This i This works, but there's a couple of things we need to do for our plugin to survive in the real world. One of jQuery's features is chaining, when you link five or six actions onto one selector. This is accomplished by having all jQuery methods return the original jQuery object again (there are a few exeptions: `width()` called without parameters returns the width of the selected element, and is not chainable). Making our plugin chainable takes one line of code: - +``` $.fn.greenify = function () { this.css('color','green'); return this; } $('a').greenify().addClass('greenified'); - +``` ##Adding scope The `$` variable is very popular among javascript libraries, and if you're using one with jQuery, you will have to make jQuery not use the `$` with `jQuery.noConflict()`. However, this will break our plugin. To work well with other plugins, _and_ still use the jQuery `$` variable, we need to put all of our code inside of an [Immediately Invoked Function Expression](http://stage.learn.jquery.com/javascript-101/functions/#immediately-invoked-function-expression), and then pass the function `jQuery`, and name the parameter `$`: - +``` (function ($) { $.fn.greenify = function () { this.css('color','green'); return this; } }(jQuery)); - +``` In addition, the primary purpose of an Immediately Invoked Function is to allow us to have our own private variables. Pretend we want a different color green, and we want to store it in a variable. - +``` (function ($) { var shade = '#556B2F'; @@ -67,13 +67,13 @@ In addition, the primary purpose of an Immediately Invoked Function is to allow return this; } }(jQuery)); - +``` ##Minimizing Plugin Footprint It's good practice when writing plugins to only take up one slot within `$.fn`. This reduces both the chance that your plugin will be overriden, and the chance that your plugin will override other plugins. In other words, this is bad: - +``` (function ($) { $.fn.openPopup = function () { // Open popup code @@ -84,11 +84,11 @@ It's good practice when writing plugins to only take up one slot within `$.fn`. }; }(jQuery)); - +``` It would be much better to have one slot, and use parameters to control what action that one slot performs. - +``` (function ($) { $.fn.popup = function (action) { if( action === 'open') { @@ -99,7 +99,7 @@ It would be much better to have one slot, and use parameters to control what act }; }(jQuery)); - +``` ##Using the each() method @@ -109,13 +109,13 @@ If you want to do any manipulating with specific elements (eg: getting data an attribute, calculating specific positions) then you need to use `each()` to loop through the elements. - +``` $.fn.myNewPlugin = function() { return this.each(function(){ // do something to each element here }); }; - +``` Notice that we return the results of `each()` instead of returning `this`. Since `each()` is already chainable, it returns `this`, which we then return. @@ -128,7 +128,7 @@ customizable by accepting options. The easiest way do this, especially if there are lots of options, is with an object literal. Let's change our greenify plugin to accept some options. - +``` (function ($) { $.greenify = function (options) { // This is the easiest way to have default options. @@ -144,15 +144,15 @@ accept some options. }); }; }(jQuery)); - +``` Example usage: - +``` $('div').greenify({ 'color': 'orange' }); - +``` The default value for `color` of `#556B2F` gets overriden by `$.extend` to be orange. @@ -161,7 +161,7 @@ The default value for `color` of `#556B2F` gets overriden by `$.extend` to be or Here's an example of a small plugin using some of the techniques we've discussed: - +``` (function($){ $.fn.showLinkLocation = function() { return this.filter('a').each(function(){ @@ -172,22 +172,22 @@ we've discussed: // Usage example: $('a').showLinkLocation(); - +``` This handy plugin goes through all anchors in the collection and appends the href attribute in brackets. - +``` Foo Foo (page.html) - +``` Our plugin can be optimized though: - +``` (function($){ $.fn.showLinkLocation = function() { return this.filter('a').append(function(){ @@ -195,7 +195,7 @@ Our plugin can be optimized though: }); }; }(jQuery)); - +``` 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 diff --git a/page/plugins/stateful-plugins-with-widget-factory.md b/page/plugins/stateful-plugins-with-widget-factory.md index da61acec..f800c186 100644 --- a/page/plugins/stateful-plugins-with-widget-factory.md +++ b/page/plugins/stateful-plugins-with-widget-factory.md @@ -25,7 +25,7 @@ This is different from a standard jQuery plugin in two important ways. First, the context is an object, not a DOM element. Second, the context is always a single object, never a collection. -

+``` A simple, stateful plugin using the jQuery UI widget factory $.widget("nmk.progressbar", { @@ -36,7 +36,7 @@ A simple, stateful plugin using the jQuery UI widget factory .text(progress); } }); -

+``` The name of the plugin must contain a namespace; in this case we’ve used the `nmk` namespace. There is a limitation that namespaces be exactly one level deep — that is, we can't use a namespace like `nmk.foo`. @@ -52,13 +52,13 @@ In our example we use the `nmk` namespace. The `ui` namespace is reserved for of This makes it clear where the plugin came from and whether it is part of a larger collection.