compu.terlicio.us

In this tutorial we will examine a simple plug in created primarily as a jQuery script with just enough php to load the script. The purpose of this plug in is to change the functionality of links to audio files. If there is a link to an mp3 file on the page and the user clicks it we will add a small flash media player below the link. A second click on the link will hide the media player. In a later tutorial we will examine how to extend this to a wider range of audio types. At the end of this series of tutorials, you will have something akin to my “Dynamic-MP3″ plug in, without the administration pages.

If you read my previous post about the possibilities of jQuery + WordPress, you’ll know that I contend that one of the major advantages of using jQuery for certain types of modification is that it allows you to easily manage the page without needing the complexity of the WordPress PlugIn API. While many plug ins use the API to great effect, including the many which power this site, they can be daunting to write, even for a fairly advanced php programmer, and completely inaccessible to a relatively new programmer. In addition, writing large chunks of the plug in in php may lead to a feature whose code is split fairly evenly between the php and JavaScript sections, making it harder to create and debug.

I am going to attempt to write these tutorials in such a way that no knowledge of programming is required, although a decent familiarity with computers is assumed. As a base prerequisite you should read my So You Want to Start Developing post. In addition, I will be using jQuery instead of the $ character for constructing the jQuery object. To my mind this is better programming practice and it can be extremely confusing as $ is also the php variable identifier.

To start with, create a file to hold the JavaScript and input the jQuery ready function:

jQuery(document).ready(function() {
     // Stuff
});

This code executes Stuff when the page is sufficiently loaded that the Document Object Model (DOM) — the stuff that makes up the page — can be manipulated. Sounds pretty simple, huh? It is! In most other JavaScript based systems there is a onLoad() event which you can listen for. The problem is that there is only one onLoad event and that whichever script “captures” it must properly pass it on or other scripts will not work. This is the genius of jQuery. You can include as many .ready()s on a page as you want and they will all work. What this means is that you don’t need to know anything about the other scripts being loaded in order to start your script.

Now that we have a way to start executing code, we need to actually insert the mp3 player. I have elected to use Jeroen Wijering’s excellent JW MP3 player, available from his website.

To set up the player, download the zip, extract, and upload the swf file to your site. Keep track of the location. While you could use the WordPress upload manager, it probably makes more sense to put it in a different folder, I used /includes. In this example, the URL becomes http://my.site.com/include/mp3player.swf. Figure out what it is for your installation and make a note.

Now we’re ready to actually add the player. In the JavaScript snippet, we will make use of jQuery’s implementation of the XPath selection syntax:

jQuery(document).ready(function() {
     jQuery("a[href$='mp3']").after("<embed src="http://my.site.com/include/mp3player.swf" allowfullscreen="false" allowscriptaccess="always" flashvars="&amp;file=" + jQuery(this).attr("href") + "&amp;height=20&amp;width=320" height="20" width="320"></embed>");
});

This code is quite a mouthful, so lets break it down a little.

The first thing we do is create a jQuery object with the links whose href attribute ends with ‘mp3′. The selector a[href$='mp3'] means: Select links (a) whose target (href) ends with ($=) mp3 ('mp3'). The single quotes around the ‘mp3′ are not strictly necessary, but they are good practice to help disambiguate a complex and potentially confusing statement.

Next we say: After each of these links add (.after()) the embed tag with the reference to the mp3player.swf. I won’t go into the details of the embed at this point, as you can simply copy the configuration out of the automatic configurator on the JW MP3 website. Finally, for each player that we add, we need to tell it which file it should play. To do this we choose the item we are working with (jQuery(this)) and use the link attribute (.attr("href")).

Save your file — I’ll assume a name of my-audio-plugin.js — into a folder of the same name. I told you that I would avoid php as much as possible, and I will, however, in order to get your JavaScript onto the page, you will need just a tiny bit of php:

/*
Plugin Name: My Dynamic Audio Plugin
Plugin URI: http://my.site.com/
Description: Converts links to mp3 files to a small flash player.
Version: 0.1
Author: Christopher O'Connell
Author URI: http://compu.terlicio.us/
*/
 
// Hook to add scripts
add_action('wp_head','da_head');
 
// Add the script
function da_head() {
	echo "<script src="%5C%27http://my.site.com/wp-content/plugins/my-audio-plugin/my-audio-plugin.js%5C%27" type="\'text/javascript\'"></script>\n";
}
?&gt;

Save this as “my-audio-plugin.php” (or whatever the name of your folder is. This php script includes the self explanatory required header (/* . . . */). Then we say: When you create the page header, run my plug in:

// Hook to add scripts
add_action('wp_head','da_head');

Finally, we say add the link to my js file to the page:

function da_head() {
	echo "<script src="%5C%27http://my.site.com/wp-content/plugins/my-audio-plugin/my-audio-plugin.js%5C%27" type="\'text/javascript\'"></script>\n";
}

Don’t worry too much about this for now, you can just copy and paste the php code above, substituting in the URL of your own site.

Upload your “my-audio-plugin” folder into your /wp-content/plugins folder. Log into your blog, goto the “Presentation” tab and log in. You’ll see your plug in listed. Activate and view the site. If all went as planned, each of your links to an mp3 will have a small Flash player underneath

Congratulations! This is your first simple plug in, although this does not really qualify as a plug in. For one, all of the links point to your specific site (http://my.site.com), instead of asking WordPress to automatically fill it in. Because of this, you would need to manually edit these files to deploy it on another site. In addition, there is none of the dynamic adding and subtracting of elements (flying out, fading in and out, etc). Don’t despair however, in the next installment we’ll expand the plug in to fly in and out as the links are clicked. Stay Tuned!