http://bililite.com/blog/understanding-jquery-ui-widgets-a-tutorial/
This was written largely to help me make sense of using UI to create my own widgets, but I hope it may help others. "Widget" to me means a user-interface element, like a button or something more complicated like a popup date picker, but in jQuery UI terms it means a class, members of which are associated with HTML elements; things like Draggable and Sortable . In fact, not everything that I would have called a widget uses $.widget
; the UI datepicker does not.
That being as it may, let's use $.widget
.
Let's take a paragraph of class target:
<p class="target">This is a paragraph</p>
This is a paragraph
And lets make it green. We know how; $('.target').css({background: 'green'})
.
Now, make it more general-purpose: a plugin :
$.fn.green = function() {return this.css({background: 'green'})}
<script> $('#test1 input[value=test]').eq(1).toggle(function() {$(this).prevAll('.target').green()}, function(){$(this).prevAll('.target').css({background: 'none'})}); </script>
But this allows us to perform some behavior on the selected elements; it does not leave us with any way to keep our plugin associated with that element, so we can do something with it later, like $('.target').off()
to remove the green background, but only if we used green to put it there in the beginning. We also have no way of associating state with the element, to do $('.target').darker(), which would require knowing how green the element is now.
We could create an object and associate it with an element using javascript expandos : element.myobject = new Myobject({'target': element})
. Sample code would be:
$.fn.green2 = function() {
return this.each(function(){
if (!this.green) this.green = new Green(this); // associate our state-keeping object with the element
this.green.setLevel(15);
});
};
$.fn.off = function() {
return this.each(function(){
if (this.green) this.green.setLevel(16);
delete this.green; // recover the memory
});
};
$.fn.darker = function() {
return this.each(function(){
if (this.green) this.green.setLevel(this.green.getLevel()-1);
});
};
$.fn.lighter = function() {
return this.each(function(){
if (this.green) this.green.setLevel(this.green.getLevel()+1);
});
};
function Green(target){
greenlevels = ['#000','#010','#020','#030','#040','#050','#060','#070','#080','#090','#0a0','#0b0','#0c0','#0d0','#0e0','#0f0','#fff'];
this.target = target; // associate the element with the object
this.level = 0;
this.getLevel = function() { return this.level; }
this.setLevel = function(x) {
this.level = Math.floor(Math.min(greenlevels.length-1, Math.max(0,x)));
this.target.css({background: greenlevels[this.level]});
}
};
But this pollutes the $.fn
namespace terribly, with off
, darker
and lighter
. There are ways to create real namespaces within $.fn
, but the usual design pattern is to use a string to specify which function to call. Thus, element.green2()
to instantiate the plugin, element.green2('darker')
or element.green2('lighter')
to manipulate it:
$.fn.green2 = function(which){
return this.each(function(){
if (which === undefined){ // initial call
if (!this.green) this.green = new Green($(this)); // associate our state-keeping object with the element
this.green.setLevel(15);
}else if (which == 'off'){
if (this.green) this.green.setLevel(16);
delete this.green
}else if (which == 'darker'){
if (this.green) this.green.setLevel(this.green.getLevel()-1);
}else if (which == 'lighter'){
if (this.green) this.green.setLevel(this.green.getLevel()+1);
}
});
};
function Green(target){
greenlevels = ['#000','#010','#020','#030','#040','#050','#060','#070','#080','#090','#0a0','#0b0','#0c0','#0d0','#0e0','#0f0', '#fff'];
this.target = target; // associate the element with the object
this.level = 0;
this.getLevel = function() { return this.level; }
this.setLevel = function(x) {
this.level = Math.floor(Math.min(greenlevels.length-1, Math.max(0,x)));
this.target.css({background: greenlevels[this.level]});
}
};
<p class="target">This is a test paragraph</p>
This is a test paragraph
<script> $('#test2 input[value=on]').click(function() {$(this).prevAll('.target').green2()}); $('#test2 input[value=darker]').click(function() {$(this).prevAll('.target').green2('darker')}); $('#test2 input[value=lighter]').click(function() {$(this).prevAll('.target').green2('lighter')}); $('#test2 input[value=off]').click(function() {$(this).prevAll('.target').green2('off')}); </script>But you get into trouble with circular references (note that "this.green = new Green($(this))
" gives a DOM element a reference to a javascript object and "this.target = target
" gives a javascript object a reference to a DOM element) and memory leaks : browsers (notably Internet Explorer) uses different garbage collectors for DOM elements and javascript objects. Circular references mean that each garbage collector thinks the other object is in use and won't delete them.
We also need to remember to reclaim the memory (with delete
) if we no longer need the plugin.
jQuery solves the circular reference problem with the $.fn.data
plugin: $(element).data('myobject', new Myobject({'target': element}))
. But now we've got a lot of "paperwork" to keep track of, and it hides the underlying program logic. As we know, design patterns reflect language weakness . If we are constantly re-implementing a pattern, we need to abstract it and make it automatic.
That's where $.widget
comes in. It creates a plugin and an associated javascript class and ties an instance of that class with each element so we can interact with the object and act on the element, without getting into trouble with memory leaks.
You still need to create the constructor of your class, but instead of a real constructor function, you need a prototype object with all the relevant methods. There are a few conventions: the function _init
is called on construction, the function destroy
is called on removal. Both of these are predefined but you can override them (and most likely will need to override init). element
is the associated jQuery object (what we called target
above).
Widget methods that start with "_
" are pseudo-private; they cannot be called with the $(element).plugin('string') notation
var Green3 = {
_init: function() { this.setLevel(15); },
greenlevels: ['#000','#010','#020','#030','#040','#050','#060','#070','#080','#090','#0a0','#0b0','#0c0','#0d0','#0e0','#0f0', '#fff'],
level: 0,
getLevel: function() { return this.level; },
setLevel: function(x) {
this.level = Math.floor(Math.min(this.greenlevels.length-1, Math.max(0,x)));
this.element.css({background: this.greenlevels[this.level]});
},
darker: function() { this.setLevel(this.getLevel()-1); },
lighter: function() { this.setLevel(this.getLevel()+1); },
off: function() {
this.element.css({background: 'none'});
this.destroy(); // use the predefined function
}
};
Notice it's all program logic, no DOM or memory-related bookkeeping. Now we need to create a name, which must be preceded by a namespace, like "ns.green
" . Unfortunately the namespacing is fake; the plugin is just called $().green()
. The constructor function is $.ns.green
, but you never use that, so you might as well use the "official" namespace of "ui
". But defining the widget couldn't be easier:
$.widget("ui.green3", Green3); // create the widget
What about our manipulating functions? All the functions defined in the prototype that don't start with an underscore are exposed automatically: $('.target').green3()
creates the widgets; $('.target').green3('darker')
manipulates them.
If your function is intended to be a "getter"; something that returns a value rather than manipulates the objects (like $('.target').html()
returns the innerHTML) then you need to tell the widget that by assigning a list of names (space or comma-delimited) or array of names. Note that only the value for the first element in the jQuery object will be returned; exactly like .html()
or .val()
.
$.ui.green3.getter = "getLevel otherGetter andAnother";
// or
$.ui.green3.getter = "getLevel, otherGetter, andAnother";
// or
$.ui.green3.getter = ["getLevel","otherGetter","andAnother"];
<p class="target">This is a test paragraph.</p>
This is a test paragraph.
<script> $('#test3 input[value=on]').click(function() {$(this).prevAll('.target').green3()}); $('#test3 input[value=darker]').click(function() {$(this).prevAll('.target').green3('darker')}); $('#test3 input[value=lighter]').click(function() {$(this).prevAll('.target').green3('lighter')}); $('#test3 input[value=off]').click(function() {$(this).prevAll('.target').green3('off')}); </script>
Pass arguments to the manipulating functions after the name: $('.target').green3('setLevel', 5)
.
The astute reader will have noticed that level
is a class variable; the same variable is used for every green3 object. This is clearly not what we want; each instance should have its own copy. $.widget defines two more functions that let us store and retrieve data for each instance individually: _setData
and _getData
. Note that these are functions of the widget object, not the jQuery one. They do not use the $(element).data('widgetName'); that returns the widget object itself. They store their data in an object this.options
. Thus:
var Green4 = {
getLevel: function () { return this._getData('level'); }, // note: we could use this.options.level directly, but using the
setLevel: function (x) { // functions gives us more flexibility
var greenlevels = this._getData('greenlevels');
var level = Math.floor(Math.min(greenlevels.length-1, Math.max(0,x)));
this._setData('level', level);
this.element.css({background: greenlevels[level]});
},
_init: function() { this.setLevel(this.getLevel()); }, // grab the default value and use it
darker: function() { this.setLevel(this.getLevel()-1); },
lighter: function() { this.setLevel(this.getLevel()+1); },
off: function() {
this.element.css({background: 'none'});
this.destroy(); // use the predefined function
}
};
$.widget("ui.green4", Green4);
$.ui.green4.getter = "getLevel";
The initial values for the data are stored in the widget's defaults
object:
$.ui.green4.defaults = {
level: 15,
greenlevels: ['#000','#010','#020','#030','#040','#050','#060','#070','#080','#090','#0a0','#0b0','#0c0','#0d0','#0e0','#0f0', '#fff']
};
And on creating an instance of a widget, pass an options object (the way most plugins do) and override the defaults: $('.target').green4({level: 8})
.
Note that I also put the list of colors into the defaults object, so it too can be overridden. This widget probably shouldn't be called "green" anymore!
<p class="target">This is a test paragraph.</p>
This is a test paragraph.
<script> $('#test4 input[value=on]').click(function() {$(this).prevAll('.target').green4()}); $('#test4 input[value=darker]').click(function() {$(this).prevAll('.target').green4('darker')}); $('#test4 input[value=lighter]').click(function() {$(this).prevAll('.target').green4('lighter')}); $('#test4 input[value=off]').click(function() {$(this).prevAll('.target').green4('off')}); </script>
<p class="target">
This is a test paragraph called with .green4({
level:3,
greenlevels: ['#000','#00f','#088', '#0f0', '#880', '#f00', '#808', '#fff']
}).
</p>
This is a test paragraph called with .green4({ level:3, greenlevels: ['#000','#00f','#088', '#0f0', '#880', '#f00', '#808', '#fff'] }).
<script> $('#test4-1 input[value=on]').click(function() {$(this).prevAll('.target').green4({ level:3, greenlevels: ['#000','#00f','#088', '#0f0', '#880', '#f00', '#808', '#fff'] })}); $('#test4-1 input[value=darker]').click(function() {$(this).prevAll('.target').green4('darker')}); $('#test4-1 input[value=lighter]').click(function() {$(this).prevAll('.target').green4('lighter')}); $('#test4-1 input[value=off]').click(function() {$(this).prevAll('.target').green4('off')}); </script>
The programmer who is embedding our widget in his page may want to do other things when the widget changes state. There are two ways to alert the calling program that something has happened:
var Green5 = {
setLevel = function(x){
//...
this.element.css({background: greenlevels[level]});
var callback = this._getData('change');
if ($.isFunction(callback)) callback(level);
},
// ... rest of widget definition
};
$.widget("ui.green5", Green5);
$('.target').green5({change: function(x) { alert ("The color changed to "+x); } });
var Green5 = {
setLevel = function(x){
//...
this.element.css({background: greenlevels[level]});
this.element.trigger ('green5change', [level]);
},
// ... rest of widget definition
};
$.widget("ui.green5", Green5);
$('.target').green5();
$('.target').bind("green5change", function(evt,x) { alert ("The color changed to "+x); });
$.widget
allows both forms with the _trigger
method. In a widget object, this._trigger(type, event, data)
takes a type {String}
with the name of the event you want (use some short verb, like 'change'
) and optionally a $.Event object (if you want to pass things like timestamps and mouse locations. Don't worry about event.type
; _trigger
changes it to the constructed event name), and any data to be passed to the handler. _trigger
creates a custom event name of widgetName+type
, like green6change
(why it doesn't do type+'.'+widgetName
the way jQuery expects is beyond me naming events this way has been the subject of some discussion ), sets event.type = custom event name
(creating a new $.Event
if it was not provided) and calls this.element.trigger(event, data)
and then looks for a callback with callback = this._getData(type)
and calls it with callback.call(this.element[0], event, data)
.
Notice that this means the function signature is slightly different for the event handler and the callback if data
is an array. element.trigger()
uses apply
to turn each item in the array into a separate argument. So this._trigger('change', 0, ['one', 'two'])
requires an event handler of the form function(event, a, b)
and a callback of the form function(event, data)
.
In practice, it's not as complicated as it sounds. For example, using both methods:
var Green5 = {
getLevel: function () { return this._getData('level'); },
setLevel: function (x) {
var greenlevels = this._getData('greenlevels');
var level = Math.floor(Math.min(greenlevels.length-1, Math.max(0,x)));
this._setData('level', level);
this.element.css({background: greenlevels[level]});
this._trigger('change', 0, level);
},
_init: function() { this.setLevel(this.getLevel()); }, // grab the default value and use it
darker: function() { this.setLevel(this.getLevel()-1); },
lighter: function() { this.setLevel(this.getLevel()+1); },
off: function() {
this.element.css({background: 'none'});
this._trigger('done');
this.destroy(); // use the predefined function
}
};
$.widget("ui.green5", Green5);
$.ui.green5.getter = "getLevel";
$.ui.green5.defaults = {
level: 15,
greenlevels: ['#000','#010','#020','#030','#040','#050','#060','#070','#080','#090','#0a0','#0b0','#0c0','#0d0','#0e0','#0f0', '#fff']
};
<p class="target">This is a test paragraph with green level <span class="level">undefined</span>.</p>
This is a test paragraph with green level undefined .
// The on button above does the following:
$('.target').green5({
change: function(event, level) { $('.level', this).text(level); } // callback to handle change event
});
$('.target').bind('green5done', function() { $('.level', this).text('undefined');alert('bye!') }); // event handler for done event
<script> $('#test5 input[value=on]').click(function() { $(this).prevAll('.target').green5({ change: function(evt, x){ $('.level', this).text(x); // callback function } }).unbind('green5done') // in case 'on' is clicked more than once .bind('green5done', function() { $('.level', this).text('undefined'); alert('bye!'); }); }); $('#test5 input[value=darker]').click(function() {$(this).prevAll('.target').green5('darker')}); $('#test5 input[value=lighter]').click(function() {$(this).prevAll('.target').green5('lighter')}); $('#test5 input[value=off]').click(function() {$(this).prevAll('.target').green5('off')}); </script>
Now, a lot of what we want to do with widgets involves mouse tracking, so ui.core.js
provides a mixin object that includes lots of useful methods for the mouse. All we need to do is add the $.ui.mouse
object to our widget prototype:
var Green6 = $.extend({}, $.ui.mouse, {other relevant functions});
And override $.ui.mouse
's functions (_mouseStart
, _mouseDrag
, _mouseStop
) to do something useful, and call this._mouseInit
in your this._init
and this._mouseDestroy
in your this.destroy
. You also have to incorporate the $.ui.mouse.defaults
in your defaults (most easily by doing $.ui.widgetName.defaults = $.extend({}, $.ui.mouse.defaults, {all my other defaults...})
.
Let's add some mouse control to our greenerizer:
Green6 = $.extend({}, $.ui.green5.prototype, $.ui.mouse,{ // leave the old Green5 alone; create a new object
_init: function(){
$.ui.green5.prototype._init.call(this); // call the original function
this._mouseInit(); // start up the mouse handling
},
destroy: function(){
this._mouseDestroy();
$.ui.green5.prototype.destroy.call(this); // call the original function
},
// need to override the mouse functions
_mouseStart: function(e){
// keep track of where the mouse started
this._setData('xStart', e.pageX);
this._setData('levelStart', this._getData('level'));
},
_mouseDrag: function(e){
this.setLevel(this._getData('levelStart') +(e.pageX-this._getData('xStart'))/this._getData('distance'));
}
});
$.widget("ui.green6", Green6);
$.ui.green6.defaults = $.extend({}, $.ui.mouse.defaults, {
level: 15,
greenlevels: ['#000','#010','#020','#030','#040','#050','#060','#070','#080','#090','#0a0','#0b0','#0c0','#0d0','#0e0','#0f0', '#fff'],
distance: 10
});
<p class="target">This is a test paragraph with green level <span class="level">undefined</span>.</p>
This is a test paragraph with green level undefined .
<script> $('#test6 input[value=on]').click(function() { $(this).prevAll('.target').green6({ change: function(evt, x){ $('.level', this).text(x); }, done: function(){ $('.level', this).text('undefined'); } }); }); $('#test6 input[value=darker]').click(function() {$(this).prevAll('.target').green6('darker')}); $('#test6 input[value=lighter]').click(function() {$(this).prevAll('.target').green6('lighter')}); $('#test6 input[value=off]').click(function() {$(this).prevAll('.target').green6('off')}); </script>
The ever-alert reader will note what we've just done: subclassed green5 to make green6, including calls to "super" methods. This ought to be abstracted out into its own method, something like $.ui.green5.subclass("green6", $.ui.mouse, {mouseStart: function(){}, mouseDrag: function(){}})
but that's a topic for another day .