How to turn any jQuery plugin into a WordPress one
Creating one of those modules is not that difficult, but if you are not familiar with their syntax, it could end up being a headache. There are many jQuery plugins that have been transferred into a WordPress one already, but what can you do when it is not the case? How do you do when you have found the perfect jQuery plugin for your latest site, but it is not yet available as a WordPress plugin?
In this tutorial, we'll see how you can easily create a WordPress plugin from a jQuery one. We'll review what a jQuery, or a WordPress plugin is actually made of, so we'll find the elements they both have in common. From there, we'll show how it leads us to perform some simple operations to allow us to benefit from our jQuery plugins in a WordPress template.
Part 1: Anatomy of a jQuery Plugin
In this part, we'll analyse what a jQuery plugin is usually made of, where each of those elements should be placed, and how do we usually work with them. Throughout this article, we'll take for example the jQuery FancyBox plugin, (even if there is an existing WordPress adaptation for it already, it's just to have a concrete example).
A) The Javascript Source
jQuery is a javascript library, and plugins are there to help us extend the capabilities of it, so they are written following the same jQuery syntax. Every plugin you'll download is written within a javascript file. That is the core of your plugin, what the developer wrote to allow you to enjoy its functionalities. You then have to include this script in your application:
B) The Javascript Snippet
Once you have included the plugin script within your application, most of the time you'll be asked to write a little snippet of code that will make your site or application use the plugin when required. Most of the time, those few lines of code you'll have to write are here to make the plugin work with a particular element of your page, and after a particular event, for example, you say that a FancyBox will appear after a click on a particular link, for example:
C) Additional Styles
Some plugins sometimes come up with their own stylesheet, modal windows for example. Those styles are required for the plugin to work and therefore need to be included in your application:
D) How to set everything up?
Once you have all your files ready, it's a common good practice to put the styles in the header, and the scripts in the footer, just before the closing </body> tag.
Part 2: How can we translate this into WordPress?
Now that we understand what the different elements we find in a jQuery plugin are, and where they are supposed to go, let's see how we can do that in WordPress.
How to declare a WordPress plugin?
A) In WordPress, plugins are stored in the /wp-content/plugins directory. So just go in there, and create a directory named after your plugin. In our case, we'll just create a directory called FancyBox.
B) In this directory, copy all your jQuery plugin files, (script, styles, images or anything that has to be included with the plugin).
C) Then, create a file called init.php. Init.php is the particular file we need to build to allow WordPress to recognize our plugin. Open init.php and copy the following information in it:
As you can see, in those few lines, we specify a name, a URL, a description and a few other similar piece of information. Those information are being used by WordPress inside the plugin administration interface as you can see on the following picture:
From this picture, we see that our 'plugin' has been recognized by WordPress, and contains all the information we wanted. It is time to make it work now. From what we've seen in part one, we need to tell WordPress to put some of our plugin files in the page header, and some in the page footer.
How to specify what goes in the Header ?
What we want to do is to put our plugin stylesheet inside the page header. In html, we do so by adding a link tag in the header. In WordPress, there is a specific method called wp_enqueue_style() (Codex ref here), that allows you to do that.
wp_enqueue_style() takes several parameters, mainly the name of your stylesheet and its source for it to work. You can also add dependencies (other styles that need to be included before), and a version number. So In our case, in order to tell our plugin to put its stylesheet inside the header, we would add this inside our init.php file:
Line 3 you can see the name we gave to our stylesheet, line 4 we specify its source, with the constant WP_PLUGIN_URL holding the path to the plugin directory. So if the user decides to move its plugin directory the path won't break. Line 5 false means that this stylesheet has no dependencies, and line 6 1.3.1 is the stylesheet version.
That's it for the header, in fact, to recapitulate, instead of adding the stylesheet in our header by ourselves as you would do in a normal application, you just ask WordPress to do it for you.
How to specify what goes in the Footer ?
In a very similar fashion, to add our scripts inside the WordPress footer, there's a function we can use as well. It is called wp_enqueue_script(), (Codex ref here).
wp_enqueue_script() accepts parameters that are very similar to wp_enqueue_style, meaning a script name, path, dependencies, en version. The last parameter is a boolean, and specifies whether you want to enqueue the script in your header (if set to 0), or in your footer (if set to 1), so in our case, because we want to enqueue them in the footer, we'll set the boolean to 1.
Let's then use wp_enqueue_script() to add our scripts:
Line 3 and 6, you can see wp_enqueue_script in action. We add our plugin scripts by specifying their name, path, dependencies, version and we place them in the footer with the 1 in the end. As you can see, the FancyBox script has one dependency, which is jQuery, and the FancyBox setup has 2, (jQuery and the FancyBox).
Time To Test
Your plugin is now ready to work. If you go back to the administration interface, in the plugin section, and activate the plugin, WordPress will add your files in the correct places, and your plugin will start working!
How to use the plugin on specific pages only?
Now that your plugin is activated, from the code we wrote in our init.php file, WordPress will automatically add our files in the header and the footer of every page of our application. This can be right if you effectively need to use this plugin on nearly every page of your site, but if it is not the case, it's more of a waste of resource, and a bigger page load time for nothing.
I'm going to show you a little technique if you'd like to include the plugin only on certain pages. It's very simple
The trick is to gather the little snippets of code we just wrote, and to put them into one function, that we're going to call FancyBox_wp_setup():
This has actually 2 different effects. It prevents WordPress from including your pages on every page, which is something we wanted, and it also gives you access to the function FancyBox_wp_setup(), that you can call on every page template you want to use the plugin on.
Conclusion
When you find the perfect jQuery plugin for your design, integrating it properly for a WordPress use is just a few lines of code away! I hope that next time you'll find a plugin you wish to use, you'll remember this article and you'll turn your plugin into a WordPress one in 5 minutes.
This code is specific to the plugin, I therefore place it inside my little init.php. That way, everything that has to do with the plugin code and declaration is all in the same place in the plugin folder.
Regards.
Jeremy
//Hook into wp_head....etc.
Into which page do I insert this code? the init.php in my themes file or the header.php or footer.php???? Very important.
Thank you for your comment.
I didn't mean to say that the plugin file has to be named init.php. I reworded my sentence so it less ambiguous.
You are right about using constants for the plugin path, I updated them with the WP_PLUGIN_URL, which according to the codex refers to the server path to the plugins directory. Regards.
Deluxe is right. Your plugin file DOES NOT need to be named init.php. The plugin file is declared by the comment at the start of the file, not its name. Also, there are constants you can use to get to the plugin directory, rather than using the siteurl + 'wp-content/...'. What if someone moves their wp-content folder for security reasons? Your path would be broken.
If you put fancybox_wp_setup() in the head section, it will include the plugin on every page, which defeats the purpose of having a setup function really.
Usually, in any template file, I make a call to the function get_header(), which returns the header. I only have to call fancybox_wp_setup() before get_header() only on specific pages then.
Thank you for sharing this knowledge! I agree with you that using wp_enqueue_scripts() and wp_enqueue_style() is a better way of including scripts and styles.
I did it that way to keep it simple and because I felt it would make it easier to spot the similarities between the two approaches, but yeah you are definitely right.
No problem ;) keep up the good work
Thanks for noticing, I corrected the mistake. You are right, the function name should be the same than in the hook.
add_action('wp_footer', 'fancybox_wp_foot');
but the function name is
function haccordion_wp_foot()