Private Thoughts Made Public

For those not in the least bit interested in how a Wordpress plugin is put together, move along. There’s nothing for you to read here. For those that are left, here’s a description of how my wordpress widget to show images from a pixelpost gallery is put together.

Installation:

Copy the l2pp.php file into /wp-content/plugins/pixelpost-widget. Download your pixelpost config file from wherever it is currently, and re-upload it into /wp-content/plugins/pixelpost-widget/includes

Log on to your Wordpress control panel as an administrator.

Activate the plugin.

Look at the “Pixelpost Widget” section in the “settings” tab on the admin menu, and set the display options there.

Add the widget to your sidebar and save changes.

Take a look at your site to see if it’s worked!

Behind the scenes:

The plugin is a pretty straightforward one, which is why I’m going to explain it line by line here. At the top of the plugin is the header, the first few lines have to be entered according to Wordpress’s rules, so that the plugin details appear on the admin control panel. Following that is the GPL licence.

<?php
/*
Plugin Name: Link To PixelPost
Plugin URI: http://www.danielfreedman.co.uk
Description: Plugin for displaying random thumbnails from a pixelpost database
Author: Daniel Freedman
Version: 0.2
Author URI: http://www.danielfreedman.co.uk
*/

/* Copyright 2009 Daniel Freedman (email : )

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/

Now we come to some actual code. I don’t think it matters which order the functions appear in the plugin code, they are executed as and when needed. The first function I’ve put in is one that registers the widget with your Wordpress install, and the add_action statement inserts a “hook” into your blog’s startup code, telling it to initialise the widget once all the plugins have been loaded.

function init_linktopp() {
register_sidebar_widget("PixelPost Gallery", "l2pp_showthumb");
}

add_action("plugins_loaded", "init_linktopp"); // get wordpress to start the widget once all the other plugins are loaded

The next function tells Wordpress where to find the settings page for your plugin, and the add_action statement hooks it into Wordpress itself so it appears on the menu.

function l2pp_admin_actions() {
add_options_page("PixelPost Widget", "PixelPost Widget", 1, "PixelPost Widget", "l2pp_admin");
}

add_action('admin_menu', 'l2pp_admin_actions');

Next up is the code that handles the settings page, which allows the user to tweak how the widget displays on the screen. The options are stored in Wordpress’s internal options database, with the get_option and update_option functions used to read and update the option values. The form is a fairly straightforward html form, when the “Update Options” button is pressed the form “loops back” on itself, so we check to see if $_POST['update_options'] is set. If it is, then we have some options to update, if it isn’t, then we retrieve the current values for the options from Wordpress.

There are three fields on the form, the first being the number of thumbnails to show on the screen, the second being the heading to use if we’re only showing one thumbnail (for example “one of my photographs”) and the third being the heading to use if we want to display more than one thumbnail (for example “some of my photographs”).

The “require” statement inserts the code from the pixelpost config file, and as it’s a requirement and not an include, the code will stop running at this point if the file doesn’t exist. The downside to this is that any other widgets below this one on the sidebar won’t be displayed either.

function l2pp_admin() {
require "includes/pixelpost.php";
if (isset($_POST['update_options'])) {
// we're updating the form, so save all the options

$numthum = $_POST['l2pp_numthum'];
$stitle = $_POST['l2pp_singletitle'];
$mtitle = $_POST['l2pp_multititle'];

update_option('l2pp_numthum',$numthum);
update_option('l2pp_singletitle',$stitle);
update_option('l2pp_multititle',$mtitle);

?>
<div class="updated"><p><strong><?php _e('Options saved.' ); ?></strong></p></div>
<?php
} else {
$numthum = get_option('l2pp_numthum');
$stitle = get_option('l2pp_singletitle');
$mtitle = get_option('l2pp_multititle');
}

?>
<!-- the options entry screen -->
<div class="wrap">

<h2><?php _e( "Settings for Pixelpost Widget") ?></h2>

<form method="post" action="">
<table>
<tr><td><?php _e("How many thumbnails to show?" ); ?></td><td><input type="text" name="l2pp_numthum" value="<?php echo $numthum ?>"/></td></tr>
<tr><td><?php _e("Heading for one photo (e.g. Random photo):");?></td><td><input type="text" size="30" name="l2pp_singletitle" value="<?php ECHO $stitle; ?>"/></td></tr>
<tr><td><?php _e("Heading for multiple photos (e.g. Random photos):");?></td><td><input type="text" size="30" name="l2pp_multititle" value="<?php echo $mtitle; ?>"/></td></tr>
</table>
<p><?php _e("If the second heading is left blank the first heading will be used.") ?></p>

<p class="submit">
<input type="submit" name="update_options" value="<?php _e('Update Options') ?>" />
</p>
</form>
</div>

<?php
}

Finallly we come to the main function in the plugin, the one that actually shows the thumbnails on the screen. Once again we check for the pixelpost config file, so we know where the database is and how to log on to it. Then we make a connection to it. Wordpress has a “database object” defined somewhere in its code, and this means we can create a new object and give it the details of a different database. This is how the plugin is able to get information from the pixelpost database while still leaving the rest of Wordpress to use its own database.

function l2pp_showthumb() {
require "includes/pixelpost.php";

// connect to the PixelPost database
$ppdb = new wpdb($pixelpost_db_user,$pixelpost_db_pass, $pixelpost_db_pixelpost, $pixelpost_db_host);

Next we find out how many thumbnails we’re supposed to display, and we run a query on the pixelpost database to get that number of records, and order them randomly. We also check that the date and time of the image on pixelpost is before the current date and time, so it shouldn’t show any images you’ve set to be posted in the future.

//Get random image(s)
$numthum = get_option('l2pp_numthum');

$random = $ppdb->get_results("SELECT id, image, datetime FROM " . $pixelpost_db_prefix . "pixelpost where datetime <now() ORDER BY RAND( ) LIMIT " . $numthum );

We do another query on the pixelpost options table, to get the mail url for the pixelpost blog, and the path to the thumbnails folder on pixelpost. This is so the images are actually displayed, and the link to the pixelpost blog still works when you click on a thumbnail.

After that query we start outputting some data. First we output the heading to the screen (if more than one thumbnail required and a suitable heading is set, then use that one, otherwise use the heading for a single thumbnail).

$meta = $ppdb->get_row("Select siteurl, thumbnailpath from " . $pixelpost_db_prefix . "config");

echo $before_widget;
if ($numthum > 1 && get_option('l2pp_multititle')) {
$title = get_option('l2pp_multititle');
} else {
$title = get_option('l2pp_singletitle');
}
echo $before_title . $title . $after_title;
echo '<div class="box">';

Then we enter a loop to print each thumbnail. The foreach statement looks at the results from the “random image” query we performed earlier, and executes the code in the loop with each image’s information set to the $oneimage object. We then make up an html link, with the link “text” being the image itself.

foreach ($random as $oneimage) {
echo '<a href="'. $meta->siteurl . 'index.php?showimage=' . $oneimage->id . '"><img src="' . $meta->siteurl . $meta->thumbnailpath . 'thumb_' . $oneimage->image . '" /></a>&amp;amp;amp;nbsp;';
}
echo '<br />';
echo '</div>';
echo $after_widget;
return;
}

The last bit looks complicated, but actually produces a link that looks like this:

<a href="www.mysite.com/pixelpostblog/index.php?showimage=1"><img src="www.mysite.com/pixelpostblog/thumbnailfolder/thumb_img001.jpg></a>

And that’s it! It used to be a bit more complicated than this, but the more I learned about plugins and widgets the less code I found I actually needed in order for it to work properly. You can download the plugin from Wordpress if you want to try it for yourself.

I’m a bit of a geek, and having worked in the computer industry for 20 years or so, I can’t help this geekery spilling over into my home life. So when I get something new (in this case the Wordpress blog) I like to delve behind the scenes and see how it all fits together.

As a result, I’m able to tweak the system to get it to work the way I want it to work. Nothing major, just little things here and there. The first thing I did is to find a theme I liked the look of. You’re looking at it now But there were one or two things about it I didn’t like. For example, the monthly archives. When you click on a monthly archive, I want the entries to be shown chronologically, instead of “last post first”, which is the default behaviour. Doesn’t it make more sense to have the first entries at the top of the page, so you can just read it all in the right order? I think it does, so I changed that. I still need to play around with the stylesheet and layout a little bit, I don’t like the way the post headings show up differently in archive listings to the way they show on the main page. This may mean that I develop my own theme from scratch, we’ll see how it goes.

The other thing I’ve done, is to write a plugin for Wordpress that shows random images from my Pixelpost photo blog over in the sidebar. As this was the first plugin I’d written, it took a few hours, even though I’d done some php and mysql stuff before. I just wasn’t familiar with the way Wordpress wanted things to be done. But, as you can see, I got there in the end. The plugin went through many changes before it ended up as the finished article.

I first thought about having it show the latest image, one random image, and a random category. Then I simplified the idea just to show a few random images. Then I wrote a settings page for the admin user to enter the details of the pixelpost database (since the plugin would have to get its data from the pixelpost database it would make sense if it knew how to connect to it). Then I realised that the settings for the database are held in a config file, just as they are with wordpress, so it might as well read the settings straight from the file. Then I widgetised the plugin, and moved all the settings to the widget control panel. Then I realised that if you log in to the blog as an author instead of an administrator, you can’t see the widget control panel, but you can still see the settings. So I moved them all back again. Then I put some code in so the user can define the headings, and to say how many columns they wanted the images showing in. Then I realised that the sidebar automatically wraps the images when it needs to, changing from three columns to two, so I took that bit out. And the final result is what you see here! Easy, isn’t it?

That’s the beauty of open source software, if you don’t like something, you can change it. Mind you, that’s the same as saying if you don’t like having to go to work on public transport, why don’t you learn to fly a plane and do it that way instead?

Ok, so I’ve got Wordpress installed and running, and now I’m trying to figure out how it all works behind the scenes. I’m a bit of a geek that way, you see. I want to be able to tweak the layout and operation of my site to suit my own needs, and not what anyone else thinks I should want. For example, although it’s set to show ten posts per page by default with the most recent post at the top, I’ve tweaked the monthly archive page so that it shows every article in that month, with the oldest at the top. That way, you can start at the top of the page and just read everything chronologically.

Now, it’s taken me a little while to get to grips with something here, and I wanted to write it down before I lost track of what it was. Wordpress uses something it calls “the loop” to display posts on the screen. The basic format of it is:

 do we have any posts to display? 
      Yes: loop through them one by one and show them
      No: show a short “no posts founds” message instead.

It this “short message” I’ve been trying to understand.

Each theme has template pages, and I’m concerned here with three of them:

• index.php, which is the default page
• archives.php, which is the template for monthly and category archives
• 404.php, which is an error page displayed if it can’t find what you’re looking for.

Both the index and the archive templates have the same loop structure as defined above, and both have their own short messages.

The reason I’m looking into all this is that I want to put a “next month” and “previous month” link at the bottom of the monthly archive page, but not every month will have entires, since I abandoned the blog for quite a while.

So, I’m calling up a page to show me the a monthly archive for a month that has no posts. Still with me?

If the theme defines a 404 error page, the short message in either template file never seems to be displayed. It always redirects to the 404 error page. So, why define the short message in the template in the first place? There must be a reason why it’s there, you can’t have code defined in a file that’s been downloaded thousands of times, and modified by hundreds of people when they write their own themes, if there’s no point to it at all. If you take away the 404 error page, the theme defaults back up to index.php and shows the short message defined there, instead of showing the one in archives.php.

For ages I couldn’t work out why it was never showing the short error message in the archives template. And then it dawned on me. It’s to do with how you’ve set your blog to show permalinks. If you have it set to the default permalink (www.mysite.org/?p=123) then the short message in each template is displayed regardless of whether a 404 template is defined or not. If you use a pretty permalink (www.mysite.org/2009/05/sample-page/) then the short message in the archives template never shows up. It always redirects to the 404 page, and if that doesn’t exist, it shows the short message in the index.php file.

I don’t know if this helps me write the “next month/previous month” link code, but at least I’ve worked out the answer to something that’s been bugging me for ages.