Creating jQuery plug-ins for an unordered list

I've been writing a lot more JavaScript recently, sometime's following other peoples code and sometime's writing my own from scratch. A lot of this JavaScript has been done using jQuery. As most of our development team was new to JavaScript the code quickly became unstructured and messy. There had to be a better way.

I was really pleased to discover that it didn't have to be this way and jQuery had created a really easy to use plug-in architecture. As you'll see from this quick guide it's very easy to create a neat and elegant JavaScript solution using a jQuery plug-in. What I really like about the jQuery plug-in solution is that it makes it easy to provide "Progressive Enhancement" to your site. So that if JavaScript has been disabled, the mark-up will remain unchanged. It' like you are rewarding people with JavaScript and providing a richer browsing experience.

The following example is similar to a real world example I was recently asked to create. The client wanted an un-ordered list to only show the first 5 elements and then provide the user with a link to see the other element. They also wanted the list to be sorted. For this I decided to break the problem down into it's 2 parts.

Part 1 would be to create a "listsort" plug-in, Part 2 would be the "hideextra" plug-in to
show/hide the extra elements.

Here's what the final List ended up looking like:

...and these are the steps to create the above:

Part 1 - Creating the listsort Plug-in

• First up we'll need an unordered list on a page to work with, for this example I've chosen fruit:

• First up you need to create a new JavaScript file, it should be named as follows:
  
• Name your file jquery.[insert name of plug-in].js, e.g.. jquery.listsort.js
  
• The basis for all jquery plug-ins is the same you loop around the jQuery object using jQuery.each and when your finished you should return the jQuery object, so the next plug-in can work with the object. What this amounts to is the following

(function ($) {
$.fn.sortlist = function (options) {

return this.each(function () {

// Guts goes here

});

};

})(jQuery);

• Now we have the basics, we can build on this to create our plug-in. We'll loop around the current unordered list element and sort by the elements text().

(function ($) {
$.fn.sortlist = function (options) {

return this.each(function (listIndex, listInstance) {

var listItems = $(listInstance).children('li');

listItems.sort(function (a, b) {
var compA = $(a).text();
var compB = $(b).text();
return (compA < compB) ? -1 : (compA > compB) ? 1 : 0;
});

$.each(listItems, function (listItemIndex, listItemInstance) { $(listInstance).append(listItemInstance); });

});

};

})(jQuery);

• While the above will work, we can make use of jQuery's plug-in architecture by using the options parameters. This way if a user wants to change our sort function to say sort on the class name of the list item element they can do this by overriding.

(function ($) {
$.fn.sortlist = function (options) {

var defaults = {
sortElement: 'li',
sortFunction: function (a, b) {
var compA = $(a).text();
var compB = $(b).text();
return (compA < compB) ? -1 : (compA > compB) ? 1 : 0;
}
};

var options = $.extend(defaults, options);

return this.each(function (listIndex, listInstance) {

var listItems = $(listInstance).children(options.sortElement);

listItems.sort(options.sortFunction);

$.each(listItems, function (listItemIndex, listItemInstance) { $(listInstance).append(listItemInstance); });

});

};

})(jQuery);

• To call this from another script would be very easy, all you'd have to do is:

$(document).ready(function () {
$("ul").sortlist();
});

• As i mentioned before, if the user doesn't have JavaScript enabled, nothing will change and the unordered list will remain unsorted. However if they have it installed the list will go from this:

• To this

• Now if you want to change the order, you can override the sort function by using jquery options parameters and extend function:

$(document).ready(function () {

$("ul").sortlist(
{ 
sortFunction: function (a, b) {
var compA = $(a).text();
var compB = $(b).text();
return (compA > compB) ? -1 : (compA < compB) ? 1 : 0;
} 
});
});

• Pretty cool huh?

Part 2 - Creating the hideextra Plug-in

• You already know the basics for creating a jquery plug-in, so let's get on with the code for the hideextra plug-in.

(function ($) {

$.fn.hideextra = function (options) {

var defaults = {
extraElement: 'li',
extraClass: 'extra',
buttonClass: 'showMore',
maxItems: 4,
moreText: "more...",
lessText: "less..."
};

var options = $.extend(defaults, options);

return this.each(function (listIndex, listInstance) {

var listItems = $(listInstance).children(options.extraElement);

for (i = 0; i < listItems.length; i++) {

if (i > (options.maxItems - 1)) {
$(listItems[i]).hide();
$(listItems[i]).addClass(options.extraClass);
}
}

var hiddenLis = $(options.extraElement + '.' + options.extraClass, $(listInstance));

// Add More/Less Link
if (listItems.length > options.maxItems) {
$(listInstance).append('<li><a href="#_" class="' + options.buttonClass + '">' + hiddenLis.length + ' ' + options.moreText + '</a></li>');
}

// Add the click events
var moreLink = $('.' + options.buttonClass, $(listInstance));

moreLink.click(function () {

if (moreLink.text().indexOf(options.moreText) > 0) {
hiddenLis.show();
moreLink.text(options.lessText);
}
else {
hiddenLis.hide();
moreLink.text(hiddenLis.length + ' ' + options.moreText);
}
});

});

};

})(jQuery);

This will create a list like the following:

Putting it all together

Now I've got 2 plug-ins created I can chain them together to get a list that is sorted and hide's extra elements just like this:

Chaining jquery plug-ins together

$(document).ready(function () {

$("ul").sortlist().hideextra();

});

Working Example

Conclusion

I've created an ASP.NET MVC 2 version of this code, which can be found on my sky drive here. Or if you just want the jquery plug-ins they can be found here: jquery.hideextra.js jquery.sortlist.js
Please feel free to down load the example or Js files and check it out.