How to Write a jQuery Plugin – Part 3: Usage

In the parts one and two of my series on how to write a jQuery plugin, we learned how to create a simple jQuery plugin with the proper structure. We allowed the user to provide values for their own set of options and we allowed them to use our plugin with multiple elements by using a single class. Now we have a simple version of our plugin in a JS file ready to be used. In this post I will demonstrate how to import our plugin file to an HTML page and apply it to some elements on the page.

Importing Plugin Script File

If you have used jQuery plugins before, then this process is nothing new for you. You need only two things to use a jQuery plugin on a page; links to jQuery and the plugin file. We do that by adding these script tags to the head section of our page:

<script type="text/javascript" src="http://code.jquery.com/jquery-1.10.1.min.js"></script>
<script type="text/javascript" src="jquery.highlight.js"></script>

The first line loads the minified version of jQuery from the content delivery network (CDN) hosted by jQuery. This allows jQuery to be imported by your page without hosting on your server, but requires an internet connection so it cannot work with offline apps. The second line imports the file of our jQuery plugin. The sample file is available for download below.

Usage

Let’s say we have now added some content to our page. We have a couple of blocks of content that we want to use our plugin on. To identify these elements, we have added a class of “highlight” to each one. We want our plugin to activate when the page has finished loading. We can use the following JavaScript:

$(function () {
     $('.highlight').highlight();
});

The dollar sign ($) function is a shortcut for the $(document).ready() function in jQuery. So once jQuery has finished loading, it calls our plugin using the highlight function. Remember in the previous parts in the series we used jQuery’s extend features to add our highlight function directly into jQuery. Our plugin already handles multiple elements, so it will apply the effect to every element on the page that has the class “highlight”.

But what about our user options? How do we use those? Our plugin has an option called “cssClass” that allows us to control the class that gets added to the element to define the highlight options. All that we need to do is create an object that defines that value and pass it into our highlight function. Here is an example:

$(function () {
     $('.highlight').highlight({ cssClass: 'highlight-red' });
});

Our plugin will take the option values specified here and merge them with the default values we have set. The only thing we need is to define the highlight classes in CSS.

.highlight-yellow { background-color: yellow; }
.highlight-red { background-color: red; }

I’d like to note that in effect what we have done here is just add a class for the highlight effect to the elements through the plugin. Normally, we would not do this through a plugin, we would just use CSS, but it is a good learning example. If we wanted to, we could provide additional features that could not be done through CSS alone.

That’s it! Thanks so much for reading this far. Any questions or thoughts? Feel free to leave a comment here or let me know on Twitter!

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s