Writing a last.fm plug-in for Wordpress – Part Three: The Plug-In
This is the third and final post describing how to write a plug-in to last.fm for Wordpress. In the first post, we looked at the last.fm API. In the second post, we took this information and made a PHP application to create a weekly Album Chart using the API. In this post, we use the PHP appication as the basis for a Wordpress plugin.
The first step to create a Wordpress plug-in is to create a directory for it to live. Although you can write a plug-in as a single PHP file and just drop it into your plug-in directory, this is not recommended. Ideally, each plug-in will live in it's own directory, and will use sub-directories to organize whatever additional files are needed for the plug-in to work.
For our plug-in, we'll create a directory structure that looks like this:
/wp-content
/plugins
/lastfm-album-chart
Within the lastfm-album-chart directory, create a subdirectory called PHP. Into this directory, copy the Album.php and AlbumChart.php files that we created in the last post. The next step is to write a plug-in that uses these two PHP classes to construct our last.fm Album Chart.
The code for the first draft of our plug-in is here:
<?php
/*
Plugin Name: last.fm Album Chart
Plugin URI: http://www.keithlawless.com/
Description: Displays a last.fm user's Weekly Album Chart as a sidebar item.
Version: 0.1
Author: Keith Lawless
Author URI: http://www.keithlawless.com/
*/
include 'php/AlbumChart.php';
/* Create a Wordpress template tag to allow Album Chart to appear on blog
wherever the lastfm_album_chart() template is called.
*/
function lastfm_album_chart( $username, $apikey, $maxentries ) {
print "<h2>last.fm Recent Albums</h2>";
$chart = new AlbumChart( $username, $apikey, $maxentries );
print $chart->render();
}
?>
The first thing to note in this script are the comments at the top. This comment block is used to identify this code as a Wordpress plug-in. Even without any implementing code, you can create a PHP script that will be recognized by Wordpress and that will show up in the administration panel. Here is ours:
The remainder of the plug-in script is a single function called lastfm_album_chart() that closely follows the logic of the PHP application we wrote in the last post. To use this plugin, the Wordpress site owner simply activates the plug-in, then inserts a call to lastfm_album_chart() wherever in the theme the owner wants the Album Chart to appear - usually in the sidebar.php script. Then, the theme's stylesheet is updated as needed to make the Album Chart blend in with the rest of the site.
The final step before we are finished is to create an options panel for our plug-in. In the current implementation, the site owner has to specify their last.fm username, api, and chart size in the call to the lastfm_album_chart() method. This means that if any of these values change, the owner has to update a php script and FTP the new script to the Wordpress web server. Not a very user-friendly solution.
Creating a Wordpress options panel isn't very difficult; however, you do have to pay attention to detail to make sure your option panel is recognized by the Wordpress administration console. Here is the script above, modified to use an options panel:
<?php
/*
Plugin Name: last.fm Album Chart
Plugin URI: http://www.keithlawless.com/
Description: Displays a last.fm user's Weekly Album Chart as a sidebar item.
Version: 1.0
Author: Keith Lawless
Author URI: http://www.keithlawless.com/
*/
include 'php/AlbumChart.php';
/* Create a Wordpress template tag to allow Album Chart to appear on blog
wherever the lastfm_album_chart() template is called.
*/
function lastfm_album_chart() {
print "<h2>last.fm Recent Albums</h2>";
$username = get_option( "lastfm_albumchart_username" );
$apikey = get_option( "lastfm_albumchart_apikey" );
$maxentries = get_option( "lastfm_albumchart_maxentries" );
$chart = new AlbumChart( $username, $apikey, $maxentries );
print $chart->render();
}
function lastfm_albumchart_plugin_menu() {
add_options_page( 'last.fm Album Chart Options',
'last.fm Album Chart',
8,
__FILE__,
'lastfm_albumchart_plugin_page' );
}
function lastfm_albumchart_plugin_page() {
// This is the standard class for Wordpress option pages
echo '<div class="wrap">';
echo '<h2>last.fm Album Chart</h2>';
echo '<form method="post" action="options.php">';
// Add some hidden fields needed for proper page flow.
echo wp_nonce_field('update-options');
// Create a form to gather input values for our option fields. This
// format will give you the "standard" Wordpress look.
echo '<table class="form-table">';
echo '<tr valign="top">';
echo '<th scope="row">last.fm username</th>';
echo '<td><input type="text" name="lastfm_albumchart_username" value="';
echo get_option('lastfm_albumchart_username');
echo '"/></td></tr>';
echo '<tr valign="top">';
echo '<th scope="row">last.fm API key</th>';
echo '<td><input type="text" name="lastfm_albumchart_apikey" value="';
echo get_option('lastfm_albumchart_apikey');
echo '"/></td></tr>';
echo '<tr valign="top">';
echo '<th scope="row">Number of entries</th>';
echo '<td><input type="text" name="lastfm_albumchart_maxentries" value="';
echo get_option('lastfm_albumchart_maxentries');
echo '"/></td></tr>';
echo '</table>';
// Hidden field to pass a command to options.php
echo '<input type="hidden" name="action" value="update"/>';
// Enumerate the option fields on this page in a hidden field. Needed
// by options.php for processing.
echo '<input type="hidden" name="page_options" value="';
echo 'lastfm_albumchart_username,';
echo 'lastfm_albumchart_apikey,';
echo 'lastfm_albumchart_maxentries';
echo '"/>';
// Add a submit button.
echo '<p class="submit">';
echo '<input type="submit" name="Submit" value="';
echo _e( 'Save Changes?' );
echo '"/>';
echo '</p>';
echo '</form>';
echo '</div>';
}
add_action( 'admin_menu', 'lastfm_albumchart_plugin_menu' );
?>
The first change to note is that our lastfm_album_chart() method no longer requires any parameters. Instead, the three values are obtained by calling the standard Wordpress method get_options(). Note that we chose some long and descriptive names for our three options (eg. lastfm_albumchart_username). This is to make sure our option names do not conflict with any other plug-ins, or with the core set of Wordpress options.
To create and activate the options page, we add two functions. lastfm_albumchart_plugin_menu() is called whenever the options main menu is created. The line line of this script contains a call to add_action() that registers this method with the Administration menu. Within the lastfm_albumchart_plugin_menu function, we make a call to the Wordpress function add_options_page(). This is the trickiest part of the process - it creates a new option page called 'last.fm Album Chart Options', which is invoked by a menu item called 'last.fm Album Chart'. The value 8 specifies that only site editors can access this menu item. This is part of Wordpress' security system for multi-user sites. The __FILE__ parameter specifies that the method for creating the options page is in this PHP script. The final parameter is the name of the method to use to create the option page.
The lastfm_albumchart_plugin_page() method uses the PHP echo command to output the HTML needed to build the options page. Note that this isn't a complete HTML page with <head> and <body> tags - this is just the markup needed to display our option form within the larger Wordpress administration console.
When creating your own options pages, you should copy another page to make sure you are following the Wordpress guidelines for option pages. An option page contains both CSS styles to make sure the option page is displayed correctly, as well as hidden fields used to inform the Administration console what options you are updating, and what values to change.
The administration panel that is created after our revised plug-in script is uploaded and activated looks like this:
This is a very basic options page that just shows the three field names and their current values. By making the lastfm_albumchart_plugin_page() method more elaborate we could add additional refinements like detailed instructions for each field, or friendlier form elements like a drop down list.
That's the final step in creating our last.fm plugin. Once the sidebar.php script is updated to call the plug-in, and some CSS styling is applied, the final product looks like this.
I hope you found this series helpful. Please feel free to leave a comment or contact me via Facebook.
