Adding filters in WordPress is also a common practice. Combining this with the Options API can allow for, for example, the ability to change an option when in preview mode without committing to the change.

In the “Magazine” template in Canvas by WooThemes, for example, WooTumblog “image” and “video” posts are aware when they are present in the magazine-style grid. This is an example of filtering the Options API.

How do I use this?

Filtering the Options API is as easy as compiling any other filter. The filter hook is as follows: “option_optionname” (replace “optionname” with the name of the option you want to filter).

That filter is applied after the database lookup. What about before that even happens?

It is possible to short-circuit an option’s value using a second filter that has been made available. This means it’s possible to set a custom value, via a filter, for an option, bypassing the database lookup. My thoughts are packed with ideas for where to use this filter!

To short-circuit an option called, for example, “testoption”, you’d add the following code to your functions.php file:

add_filter( 'pre_option_testoption', 'matty_shortcircuit_options' );

function matty_shortcircuit_options ( $default ) {
	$value = 'this is a short-circuited option';
	return $value;
} // End matty_shortcircuit_options()

Using the “testoption” example again, this is how you’d override the value after it’s been retrieved from the database:

add_filter( 'option_testoption', 'matty_override_options' );

function matty_override_options ( $value ) {
	$value = 'this is an overridden option';

	// To override based on a condition, do this.
	if ( $value == 'test' ) {
		$value = 'this is an overridden option, based on a condition.';
	}

	return $value;
} // End matty_override_options()

This is just, however, a starting point as to how to do this. The possibilities are virtually limitless as to what is possible here and how to apply this in your projects.

While we all have our own preferences, it’s important to solidify a few areas when approaching code and to, ultimately, hone the developer’s mindset into certain guidelines. Below are a few thoughts I have running through my mind constantly while developing:

1. Minimize lookups.

This one is crucial when developing systems with heavy load. How many times are you hitting the database for information and how can you minimize that number? For example, when using the Transients API in WordPress, why would you run get_transient() again after you’ve just set the transient up? You’ve already got the data, so there’s no need.

2. D.R.Y (don’t repeat yourself).

This is a common development practice. Don’t repeat yourself. If you’ve got, for example, two functions that perform API requests, create a function that runs the API request with a few parameters to customise it in each case, rather than coding the request twice.

3. One function, one purpose.

This one helps me every day. It also ensures that your code is kept clean. If, for example, you have to display a collection of posts with specific criteria, why compile one function to do it all, when you could have a small function to get the data from the database and a second small function to output the data neatly? Surely that would make your code easier to read and maintain? Yep, it would.

4. Do I need this function here?

This one is about load and separation of code. Why load extra functions when you don’t need them in a specific context? Keeping this in mind ensures that you keep your code in “bite size chunks”, for example, splitting admin-related functions versus frontend functionality.

These items, while simple to adhere to, can alter the way a developer approaches a project, as well as creating a better end result. Most are also common development practices that most developers should be familiar with, making it easier for other developers to read and understand your projects.

Do you have any tips and tricks that help you day to day while developing?

The GROW Academy is an initiative to educate and empower the youth of today through technology. The Bootcamp session covers everything from social media and setting up e-mail, all the way through to search engine optimisation and an internet super-user course, for those who wish to continue on with more advanced studies. The GROW website’s “About” page (built on Canvas and Canvas BuddyPress by WooThemes) has a detailed explanation of the initiative and it’s founding partners.

This year, Jeff and I will be making some exciting additions to our presentation. While code, to some, can seem dry and boring, I can assure you that there’s nothing dry or boring about our presentation. We had such a blast at last year’s Bootcamp and are really looking forward to getting into some code with this year’s recruits.

If you’re keen to get involved with GROW, I’d encourage you to contact the GROW Academy and see how you can help out.

Remember: it’s all easy, and there’s no such thing as a stupid question.

With my mission at hand, I set to work. I’d been thinking about this for a while after writing the initial blog post and am please to say that I have found a solution. Please be sure you’ve read through the initial blog post, as the main points are covered over there.

There are a few steps we need to go through here. They’re pretty straight forward, so bear with me.

Reference the global $post object

First things first. How do we know what page, post or custom post type entry we’re working with? We need to get this information from WordPress. Luckily for us, WordPress also needs to know which entry we’re editing. We get this information by adding the following to the beginning of our function:

global $post;

This lets us work with the variable $post, which was previously created outside of our function. This variable is an object that holds information about the entry we are currently editing (ID, title, content, template, etc). We will be using this information at a later stage to insert our custom CSS file(s).

Due to this being a custom solution specific to a particular page, post or custom post type entry, this solution will only truly take effect on the “Edit” screens when targeting a specific entry or an entry with a particular custom template applied.

Check if the file we’re looking for exists

We wouldn’t want to call a file that we know doesn’t exist. Therefore, we will use a conditional (in this case, an IF statement) to determine whether or not to look for our custom CSS file, based on whether or not it exists.

If the CSS file exists, add it to the list of CSS files to include

After the line where we include our main editor-style.css file, add the following code:

if ( file_exists( trailingslashit( get_stylesheet_directory() ) . 'assets/css/editor-style-' . $post->post_type . '.css' ) ) {

	if ( !empty($url) )
 	$url .= ',';

	// Change the path here if using sub-directory
 	$url .= trailingslashit( get_stylesheet_directory_uri() ) . 'assets/css/editor-style-' . $post->post_type . '.css';

} // End IF Statement

The above code checks if our custom CSS file (in this case, for a post type-specific CSS file) exists and, if it does, adds it to the list of CSS files to include in the tinyMCE editor. We include it after checking for our main editor-style.css file so that any of our custom CSS declarations override the defaults we have in the main editor-style.css file.

Extending this functionality

In the above example, I am including a custom CSS file based on the post type of the entry being edited. Altering this is relatively straight forward and can allow for custom CSS files depending on date published, post publish status, custom template being used and virtually any condition imaginable.

As an example of extending this functionality, we will include a file based on post ID. To do this, simply paste the above code into the function again and replace all instances of `post_type` with `ID` (such that $post->post_type becomes $post->ID). Thus, if a post has an ID of 7 (for example), the system will look for a file called editor-style-7.css and, if it exists, include it in the tinyMCE editor.

Please note that using post IDs can result in a large quantity of custom CSS files and is not recommended. The above is simply an example for extending the functionality we just created.

Folks, there you have it. Not too difficult, I hope. This allows for further customisation of the WordPress tinyMCE editor, creating a richer user experience for the bloggers using your theme, as well as creating a more accurate representation of what the post will look like on the front end of their WordPress website.

What are we going to achieve today?

Today, we’re going to style the editor in the WordPress backend to resemble the content as it is in the theme that is being used on the frontend. Simple objective, so lets get started.

What do we need?

We’ll need three things to get this done: an editor-specific CSS stylesheet (I usually call this editor-style.css), a PHP function to do the work and a WordPress filter to piece things all together.

Creating the editor-specific CSS stylesheet

To do this, we need to keep in mind one thing: we’re cloning the styling of our theme’s content area into a new stylesheet. Simply loading the existing stylesheet in place of this file will not work out properly. One other thing to note is, the content area styles are now to be placed within the .mceContentBody{} CSS style. In addition to copying and pasting the content styling from my theme  (and changing all instances of #content to read .mceContentBody), I have also imported the CSS reset script I use via an @import call. This is to ensure added consistency within the editor styling. If your theme uses a CSS reset file, I would recommend importing it as well.

A snippet from my editor-style.css file looks like this:

.mceContentBody { color: #666666; font-family: Arial, Helvetica, sans-serif !important; font-size: 12px; line-height: 18px; width: 640px; }
		.mceContentBody a, .mceContentBody a:visited { background: none; color: rgb(60, 130, 170); text-decoration: underline; }
		.mceContentBody a:hover { background: none; color: rgb(60, 140, 180); text-decoration: underline; }

Writing the PHP function to do the work

Right, folks. This is where we do the main work involved with this. We’ll be writing a function to add our new editor-style.css file into the mix with the existing tinyMCE stylesheet in the backend. The function looks like this:

/**
 * matty_editor_style()
 */

function matty_editor_style( $url ) {

  if ( !empty($url) )
    $url .= ',';

  // Change the path here if using sub-directory
  $url .= trailingslashit( get_stylesheet_directory_uri() ) . 'assets/css/editor-style.css';

  return $url;

} // End matty_editor_style()

And in English, this function reads like this:

The function accepts $url as a parameter. This is the existing tinyMCE stylesheet, passed through the WordPress filter. More on that in a bit. If the URL is provided (and not empty), add a comma (,) at the end of it. After that, create the URL to our editor-style.css file, as it sits in our theme folder, and add it to the end of $url. Return out the newly filtered $url back to the system.

The WordPress filter that makes it all happen

The last line. Nice and simple.

add_filter( 'mce_css', 'matty_editor_style' );

This is using the native WordPress function, add_filter(), to take in the ‘mce_css’ stylesheet (the apply_filters() function is applied to the main tinyMCE CSS stylesheet before it is loaded into the system) and add the editor-style.css file into the mix with the existing file. No mess, no fuss.

Place the above PHP function and filter in your theme’s functions.php file, and you’re set.

And there we have it, folks. The editor in the WordPress backend no resembles the frontend of our WordPress theme. I hope this tutorial helps you in creating beautiful and easy to use content managed websites with WordPress.

“Callback”, you say? Erm… what’s that?

“callback” is one of the arguments we can pass to the wp_list_comments() function. The “callback” argument expects a string which, in this case, is the name of our callback function. Essentially, by using the “callback” argument, we’re saying to WordPress; “okay, that layout looks cool, but use this awesome layout instead”.

So… this function…

Right. The meat of this method is the callback function itself. This is the code that will be used to display each comment in the list. No need to create the list itself, just the items (as is most likely done in your comments.php theme file at this time). The callback function we’ll be creating looks something like this:

<?php
/**
* matty_comment_layout()
* A callback function to be used with the wp_list_comments() function.
*/
function matty_comment_layout ( $comment, $args, $depth ) {
$GLOBALS['comment'] = $comment;
$path_to_default_gravatar = get_bloginfo('stylesheet_directory') . '/assets/images/gravatar.png';
$twitter = '';
$twitter = get_comment_meta( get_comment_ID(), 'twitter', true );
if ( $twitter != '' ) {
$twitter = strtolower($twitter);
$twitter = str_replace(' ', '', $twitter);
$twitter = str_replace('.', '', $twitter);
$twitter = ' <span>(<a href="http://twitter.com/' . $twitter . '" rel="nofollow">' . $twitter . '</a>)</span>';
} // End IF Statement
// Sanitise gravatar and make sure the image has an ALT attribute that isn't empty.
$gravatar = get_avatar($comment,$size='48',$default=$path_to_default_gravatar );
$gravatar = str_replace ("alt=''", 'alt="' . $comment->comment_author . '\'s Gravatar"', $gravatar);
?>
<li <?php comment_class(); ?> id="comment-<?php echo $comment->comment_ID; ?>">
<div><?php echo $gravatar; ?><?php printf( __('<cite>%s</cite>'), get_comment_author_link(), $twitter ); ?></div>
<div><?php printf(__('Posted %1$s at %2$s (%3$s ago)', 'matty'),
get_comment_date(),
get_comment_time(),
human_time_diff(get_comment_date('U'), current_time('timestamp')) ); ?></div>
<?php if ($comment->comment_approved == '0') _e("\t\t\t\t\t<span class='unapproved'>Your comment is awaiting moderation.</span>\n", 'matty') ?>
<div><?php comment_text(); ?></div><!--/.comment-content-->
<div><?php printf(__('<a href="%1$s" rel="bookmark" title="Permalink to ' . $comment->comment_author . '\'s comment">Permalink</a>', 'matty'),
'#comment-' . $comment->comment_ID );
edit_comment_link(__('Edit', 'matty'), '<span>', '</span>'); echo get_comment_reply_link(array_merge( $args, array('depth' => $depth, 'max_depth' => $args['max_depth']))) ?></div><!--/.comment-links-->
<?php
} // End matty_comment_layout()
?>

Okay, that’s a long snippet. Lets go through it.

function matty_comment_layout ( $comment, $args, $depth ) {

This is our opening function tag. What’s important to note here is the passing of three arguments: the $comment we’ll be displaying, the $args that go along with that comment and the $depth of the comment in the structure.

$GLOBALS['comment'] = $comment;
$path_to_default_gravatar = get_bloginfo('stylesheet_directory') . '/assets/images/gravatar.png';
$twitter = '';
$twitter = get_comment_meta( get_comment_ID(), 'twitter', true );

if ( $twitter != '' ) {

$twitter = strtolower($twitter);
$twitter = str_replace(' ', '', $twitter);
$twitter = str_replace('.', '', $twitter);
$twitter = ' <span>(<a href="http://twitter.com/' . $twitter . '" rel="nofollow">' . $twitter . '</a>)</span>';

} // End IF Statement

// Sanitise gravatar and make sure the image has an ALT attribute that isn't empty.
$gravatar = get_avatar($comment,$size='48',$default=$path_to_default_gravatar );
$gravatar = str_replace ("alt=''", 'alt="' . $comment->comment_author . '\'s Gravatar"', $gravatar);

I’ve bundled the above together as it’s all extra information that isn’t directly part of the comment itself.

The first line is to ensure we have the correct data for our comment. Below that, $path_to_default_gravatar is where we set the URL of a custom gravatar that we would like to use to replace the default gravatar used. This can be really useful when doing advanced premium WordPress themes. Now, onto the Twitter username.

We create a variable called $twitter, to which we will assign whatever is returned from the native WordPress function, get_comment_meta(). This function takes in the ID of the comment we’re currently processing, the field name (in this case “twitter”) and whether to expect a single value, instead of an array of values (in most cases, this should just be set to true, as we’re only expecting a single value here). If $twitter isn’t empty, we remove and spaces or full-stops from it and create an anchor XHTML tag pointing to the user’s Twitter profile page.

The last two lines get the user’s gravatar and make sure it has alternative text, to keep things neat and tidy. We’ve also told the get_avatar() function that, should it not find a gravatar for the user, it must use $path_to_default_gravatar as the default gravatar to display.

The rest of the comment function looks like this:

<li <?php comment_class(); ?> id="comment-<?php echo $comment->comment_ID; ?>">
<div><?php echo $gravatar; ?><?php printf( __('<cite>%s</cite>'), get_comment_author_link(), $twitter ); ?></div>
<div><?php printf(__('Posted %1$s at %2$s (%3$s ago)', 'matty'),
get_comment_date(),
get_comment_time(),
human_time_diff(get_comment_date('U'), current_time('timestamp')) ); ?></div>
<?php if ($comment->comment_approved == '0') _e("\t\t\t\t\t<span class='unapproved'>Your comment is awaiting moderation.</span>\n", 'matty') ?>
<div><?php comment_text(); ?></div><!--/.comment-content-->
<div><?php printf(__('<a href="%1$s" rel="bookmark" title="Permalink to ' . $comment->comment_author . '\'s comment">Permalink</a>', 'matty'),
'#comment-' . $comment->comment_ID );
edit_comment_link(__('Edit', 'matty'), '<span>', '</span>'); echo get_comment_reply_link(array_merge( $args, array('depth' => $depth, 'max_depth' => $args['max_depth']))) ?></div><!--/.comment-links-->

The one very important thing to note here is the lack of a closing </li> tag. WordPress inserts this automatically for us. While this still puzzles me, I’m sure there’s a decently good reason for it.

This code looks a bit random, doesn’t it? Well, it’s not really all that bad. Lets take a look.

We open the <li> tag and call the comment_class() WordPress function. This adds necessary microformats and comment-specific classes to the <li> for this comment. We also give it a unique ID.

Next up, we create a containing <div> tag and echo out our $gravatar image, as well as a prepared statement containing the comment author’s name and a link to their website (via the get_comment_author_link() function) and our $twitter URL, created in the snippet above.

Below the comment author information, we echo out a prepared statement with three values: the comment date, comment time and a human-readable version of how long ago the comment was posted (for example, 3 days ago).
If the comment has not yet been approved, we let the user know this with <?php if ($comment->comment_approved == '0') _e("\t\t\t\t\t<span class='unapproved'>Your comment is awaiting moderation.</span>\n", 'matty') ?>.

Now for the main event. The comment itself. A simple function called comment_text() gets this part of the show done.

Next up we create links that apply to this comment. In the above snippet, we create a permalink to the comment, an edit link for users who are logged in and have access to edit comments and a reply link (if we’re not too deep into the comments thread) that users can use to reply to the comment.

That’s all, folks!

Yep, that’s it. In the above snippet (which is almost a store-and-use-without-thinking snippet, in my opinion), we’ve created a customised layout for the way each comment is displayed, integrated a custom default gravatar, displayed a human-readable version of how long ago the comment was posted and integrated a Twitter username, submitted by the user when the comment was first made.

I’d really appreciate your thoughts on and ideas for this in the comments below.

Pretty cool, hey?

* While this tutorial uses a Twitter username as an example, virtually any additional information supplied by the user can be stored along with their comment (a rating, a selection of their social media profiles, etc).

Asking for it by name (aka. creating the Twitter username textfield)

Here we’ll add a field to the comment form, in which the user can input their Twitter username. The snippet of code I’ve used for this is as follows:

<p><label for="twitter">Twitter</label><input type="text" name="twitter" id="twitter" value="" /></p>

The above code adds a field to the comment form of the theme in question. I’d recommend making a copy of the way the website field is generated and replacing all instances of the word “website” with the word “twitter”. This is an easy way to ensure consistency with the theme to which you are adding this functionality.

Okay, lets store this thing!

Right. The user has entered their Twitter username. Lets store it along with the comment, using the comment meta functionality provided by WordPress.

What we’ll be doing here is the following:

1. Check if the user inputted a Twitter username.
2. Sanitize the username.
3. If there are any characters left after we’ve sanitised the username (it removes all unwanted characters), store the Twitter username along with the comment.

And here’s how that looks in code:

<?php
/**
* Storing the commenter's Twitter username.
*/
function matty_store_twitter_username ( $post_id ) {
$twitter_username = $_POST['twitter'];
if ( $twitter_username ) {
$twitter_username = sanitize_user( $twitter_username, true );
$twitter_username = str_replace( ' ', '', $twitter_username );
$twitter_username = str_replace( '.', '', $twitter_username );
} // End IF Statement
if ( $twitter_username ) {
add_comment_meta( $post_id, 'twitter', $twitter_username, true );
} // End IF Statement
} // End matty_store_twitter_username()
add_action( 'comment_post', 'matty_store_twitter_username', 1 );
?>

Pretty simple, right?

If you make use of the above or know of other ways of achieving this, please share your thoughts in the comments below.

In a follow-up tutorial, I’ll discuss how to integrate this stored Twitter username into comments on your WordPress website, using a custom comment callback function.

2010-05-03: Code updated thank to feedback from Ben in the comments below. Thanks man.

Before we get to those files…

Folks, before we dive into the files, lets get some concepts down that are crucial to understanding how the Magento theme files play together.

Magento themes consist of, aside from styling assets (CSS, images, Javascript, etc) a collection of *.phtml (essentially, XHTML files that can execute PHP) and *.xml (Extensible Markup Language) files that make the theme work.

The *.xml files define blocks and regions, which template files get used for which blocks & regions as well as various attributes and parameters for each if these definitions, where applicable.

While the *.xml files tell everything where to be and what to look like, the *.phtml files contain the actual XHTML code required for each block and region.

• At the time of writing this tutorial, I have upgraded my Magento installation to Community Edition 1.4. All further tutorials, as well as this one, will be  referencing Magento Community Edition 1.4 unless otherwise stated. Please be sure you have the latest version.

Blocks and regions? Huh?

Yes, blocks and regions.

Magento has a system called “Static Blocks”, which allows theme authors to define areas which are updatable via the administration console using a simple textarea. This is used, by default, in the footer as well as for one or two other areas, and can be very  useful for allowing the theme users to update small chunks of content on their store. These are referred to in this tutorial as “blocks”.

Regions. This is where we need to get conceptual.

The easiest way I’ve found to explain this concept is by comparing regions to widgetised areas in WordPress. When users create widgetised areas in WordPress, they are creating areas that are open for the user to insert blocks of content (widgets) that will take on appropriate styling. The region concept is similar.

In Magento, by default, certain blocks are placed in certain regions (for example, Layered Navigation in the left column). This is the reason why it is so important to make use of all possible template types when theming for Magento (3 columns, 2 columns, 1 column, etc), as there is a tried and tested reason why each block is placed in a particular region. This can, however, be modified via the *.xml file (which does all the “do this, do that”, remember?), so its not a major worry if you need to move a block.

So, what’s a *.phtml file anyway?

A *.phtml file is a template file. It can either define a page template to be used when displaying a particular type of page (product page, category page, CMS page, etc) or a template to be used in a particular area, for example, the way each single product is displayed when a category is in list mode or grid mode, or the way your footer links static block (activated by default when Magento is installed) is displayed within your theme.

Lets take a look at a fairly standard *.phtml file, 2columns-right.phtml, found in your theme’s directory within the “app > design” folder.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<?php echo $this->getLang() ?>" lang="<?php echo $this->getLang() ?>">
<head>
<?php echo $this->getChildHtml('head') ?>
</head>
<body<?php echo $this->getBodyClass()?' class="'.$this->getBodyClass().'"':'' ?>>
<?php echo $this->getChildHtml('after_body_start') ?>
<div class="wrapper">
    <?php echo $this->getChildHtml('global_notices') ?>
    <div class="page">
        <?php echo $this->getChildHtml('header') ?>
        <div class="main-container col2-right-layout">
            <div class="main">
                <?php echo $this->getChildHtml('breadcrumbs') ?>
                <div class="col-main">
                    <?php echo $this->getChildHtml('global_messages') ?>
                    <?php echo $this->getChildHtml('content') ?>
                </div>
                <div class="col-right sidebar"><?php echo $this->getChildHtml('right') ?></div>
            </div>
        </div>
        <?php echo $this->getChildHtml('footer') ?>
        <?php echo $this->getChildHtml('before_body_end') ?>
    </div>
</div>
<?php echo $this->getAbsoluteFooter() ?>
</body>
</html>

The above code is a direct copy/paste of the 2columns-right.phtml file, packaged with the base > default theme in Magento 1.4. The use of $this->getChildHtml() is directed at retrieving specific template files, declared within the page.xml file. The other functions, getAbsoluteFooter() and getBodyClass() are, for the scope of this tutorial, not relevant.

… and the XML?

This file defines our regions, sets up blocks within those regions and tells each region which template to use. It is also used for loading theme-specific CSS and JavaScript, as well as activating and deactivating blocks within specific regions in particular sections of your Magento theme. Essentially, the XML file controls everything related to the module in question.

In most cases, the majority of your time when theming will be spent within page.xml. As this file is well and truly gigantic for pasting into a blog post (approximately 182 lines), I’ll paste just the relevant snippets for getting the aim of this tutorial across.

<block type="core/text_list" name="left" as="left" translate="label">
<label>Left Column</label>
</block>

<reference name="left">
<block type="core/template" name="left.permanent.callout" template="callouts/left_col.phtml">
<action method="setImgSrc"><src>images/media/col_left_callout.jpg</src></action>
<action method="setImgAlt" translate="alt" module="catalog"><alt>Our customer service is available 24/7. Call us at (555) 555-0123.</alt></action>
<action method="setLinkUrl"><url>checkout/cart</url></action>
</block>
</reference>

The block of code above is from catalog.xml, the controller XML file for all things related to the Magento catalog. The above block of code creates one of the default callout blocks (a block with an image and a URL) that is bundled with the default Magento theme. Lets spend some time on this block of code.

So… how do I use these files?

The first and last lines, in this case, are the most important. They tell Magento that anything within them (ie: the block inside the <reference> tags) will be assigned to the “left” region. Inside that, the <block> tags setup the callout block with it’s various attributes. As the <action> tags are rather specific to this callout (they use specific image-related methods to setup the source of the image, it’s alternate text and the URL to which it points), lets focus on the opening <block> tag.

The opening <block> tag has the following attributes: type, name and template. These do exactly what they say on the tin.

type- Tells Magento what type of block this is (it could be a product list, catalog, a display of only new products, etc). This is dependent on the type of content within the block. In this case, it’s a raw image using a specific template, so it’s a core/template.

name- What this block is referred to as within the XML files.

template- What template file is used to render this block within the theme. In this case, it’s a template called left_col.phtml within the “callouts” folder. This file looks like this:

   <div class="block block-banner">

<div class="block-content">
        <?php if(strtolower(substr($this->getLinkUrl(),0,4))==='http'): ?>
            <a href="<?php echo $this->getLinkUrl() ?>" title="<?php echo $this->__($this->getImgAlt()) ?>">
        <?php elseif($this->getLinkUrl()): ?>
            <a href="<?php echo $this->getUrl($this->getLinkUrl()) ?>" title="<?php echo $this->__($this->getImgAlt()) ?>">
        <?php endif; ?>
            <img src="<?php echo $this->getSkinUrl($this->getImgSrc()) ?>"<?php if(!$this->getLinkUrl()): ?> title="<?php echo $this->__($this->getImgAlt()) ?>"<?php endif; ?> alt="<?php echo $this->__($this->getImgAlt()) ?>" />
        <?php if($this->getLinkUrl()): ?>
        </a>
        <?php endif ?>
    </div>
</div>

Above you can see some familiar functions such as getImgSrc() (related to setImgSrc() within the XML file). These functions retrieve the data that is set within the <reference> tags in the XML file.

… and to sum it all up …

Okay. Lets sum this up in a single paragraph.

Wherever dynamic content is set within your theme, it is more often than not done using a region. These regions are usually set within the page.xml file, as the “page” module defines the main skeleton of the Magento theme. Blocks specific to the module they work with are set in that modules XML file, with a <reference> to the region in which they are displayed. A template file, usually stored within the module in question, is used to render the content that is retrieved by the block it is used on.

Wow, this was a busy tutorial. There’s a lot to take in above, folks. If any of it seems unclear, please leave a comment and I’ll do my best to help clarify things.

Okay, what are we doing here?

We’re going to enqueue the Javascript files, used by our WordPress plugin or theme, using the correct method and the wp_enqueue_script()function. We will be adding an action to the wp_print_scripts() action and, inside a function within our theme or plugin, running the wp_enqueue_script() function. We will also be including the Javascript in the administration area only, creating dependencies between our various custom Javascript files and enqueuing the scripts on only a specific page in the administration area.

How do we enqueue the Javascript?

Okay, you will need:

1. 1 x custom function in either your theme’s functions.php file or in your plugin.
2. 1 x selection of Javascript files required by your theme or plugin.
3. 1 x add_action() line within your code.

Lets follow this like a recipe. The above ingredients each form part of the recipe we need to follow in order to correctly enqueue Javascript in WordPress.

1. Write a function in your theme or plugin that will run the various enqueue commands.

This function is the heart of enqueuing the JavaScripts in WordPress. It tells the system which scripts to include, what they require (if anything) and in what order to enqueue the scripts. An example of this function may look like this:
function matty_enqueue_theme_js () {
wp_enqueue_script('matty-functions', get_template_directory_uri() . 'js/functions.js', array('jquery'), '1.0', false);
} // End matty_enqueue_theme_js()

Okay. Lets run through this function and work out what it does.

For each Javascript file you wish to include, add another wp_enqueue_script() line to the function. This line reads as follows:

The name by which I would like to refer to this JavaScript file is `matty-functions`. It is located at get_template_directory_uri() . ‘js/functions.js’ *, requires jQuery to run and has a version number of 1.0. The `false` at the end denotes whether or not the script is to be loaded in the footer of the theme (on wp_footer()). If false, the script will load in wp_head() of the current theme.

Each parameter can be explained as follows:

$handle – A lowercase text string, no spaces, that is the “identifier” of the JavaScript file being loaded on that line. Can be used if one of your files requires another of your files in order to run.

$src – The full URL path to the Javascript file being loaded.

$deps – Does your script require anything to run? It could require a specific library (for example, jQuery) or another of your Javascript files being loaded in (referred to by its $handle).

$ver – The version number of the script being loaded. This is an optional parameter.

$in_footer – Should the script be loaded in the footer or in the header? If set to false, the script will load in the header. This is an optional parameter that defaults to `false`.

And hey presto! We’ve got a function that we can tell to include all our JavaScripts!

Run the function when the WordPress wp_print_scripts() action occurs.

No sweat. We’re going to run the above function on the WordPress wp_head()action (when the system initialises). This is how we do it: add_action('wp_print_scripts', 'matty_enqueue_theme_js', 1);

Explaination? Okay.

When the WordPress wp_print_scripts() function runs, add the `matty_enqueue_theme_js` function to the list of functions to run. Give it a priority setting of 1 (this can be used to control which functions execute before others).

Easy, right?

What JavaScript libraries are already bundled with WordPress?

In a word; loads. Here’s a comprehensive list of Javascript libraries bundled with WordPress. Try to stick to one library, as it will greatly minimize potential conflicts between your scripts. Where possible, be sure to use the bundled version of the script your code requires, as it will minimize load times and generally be a lot easier to work with your scripts (unless the version you require is not yet bundled with WordPress… *cough* jQuery 1.4 *cough*.).

I only want the Javascript in the WordPress aministration area. How do I do that?

No sweat. Simply run the following script instead of the above add_action():

add_action('admin_print_scripts', 'matty_enqueue_theme_js');

To include the Javascript on only one particular administration page, run something like the following:

add_action('admin_print_scripts-widgets.php', 'matty_enqueue_theme_js');

The above line will enqueue the JavaScript only on the widgets screen of the administration area.

One of my scripts relies on another. What do I do?

Remember that `$handle` parameter we discussed earlier? Lets use it.

When one script relies on another script (note: not a bundled library but another custom Javascript file), the ‘handle’ parameter is used in the `$deps` to let the script know that another script is required. Lets take a look at our function again:

function matty_enqueue_theme_js () {
wp_enqueue_script('matty-some-cool-code', get_template_directory_uri() . 'js/some-cool-code.js', array('jquery'), '1.0', false);
wp_enqueue_script('matty-functions', get_template_directory_uri() . 'js/functions.js', array('jquery', 'matty-some-cool-code'), '1.0', false);
} // End matty_enqueue_theme_js()

See what we did there? We added the handle of the first line to the dependencies array of the second line. Therefore, ‘matty-some-cool-code’ requires jQuery ** to run, and ‘matty-functions’ requires both jQuery and ‘matty-some-cool-code’ in order to run. Please note that, because I have specified that my scripts require jQuery, there is no need to load the jQuery library itself on it’s own line.

Right. Lets sum it up.

What did we discuss here today? We learned how to correctly enqueue Javascript files in WordPress, how to create dependencies between files and how to load Javascript libraries that come bundled with WordPress.

And all the code we discussed above:
function matty_enqueue_theme_js () {
wp_enqueue_script('matty-some-cool-code', get_template_directory_uri() . 'js/some-cool-code.js', array('jquery'), '1.0', false);
wp_enqueue_script('matty-functions', get_template_directory_uri() . 'js/functions.js', array('jquery', 'matty-some-cool-code'), '1.0', false);
} // End matty_enqueue_theme_js()

add_action( 'wp_print_scripts', 'matty_enqueue_theme_js', 1 );
I hope this post is found useful. If you have any queries, please post them in the comments.

* get_template_directory_uri() should be changed to get_stylesheet_directory_uri() if the JavaScript file is within a child theme.

** Notice how jQuery is required by both JavaScripts but is only loaded once in your code? This is why we use the wp_enqueue_script() action… to avoid a) multiple versions or instances of a script being included and b) to avoid script conflicts because of these load issues.

Over the last few weeks, WordPress plugin development has become one of my favourite things to do. I find it exciting to be able to create functionality, incorporate it seemlessly into the WordPress system and see it work smoothly with the other modules. While plugin development for WordPress is incredibly powerful, it also carries with it a few areas where people commonly stumble over and potentially lose interest in their code… which could be the next big thing. Here are a few guidelines I’ve picked up in order to step over the stumbling blocks.

1. Understand actions, filters and hooks, where to use which action and their limitations.

Actions, filters and hooks are what allow developers to insert their code into virtually any part of the WordPress system. While there are only almost 400 hooks documented, there are in fact around 800 hooks in the WordPress system. The WordPress codex has a great reference for actions, filters, hooks and how to use them.

2. register_activation_hook() does not function the same way as add_action().

While looking through the WordPress forums, the register_activation_hook() function (runs the function you pass to it when the plugin is activated) has come up as a regular topic of conversation. Users are attempting to display text on activation, using it as if it were the add_action() function. register_activation_hook() does not function the same way. The function, the way I understand it, works in an almost overall scope, not having access to variables within your plugin for display purposes. In short, don’t try to echo or print variables with this function. It won’t work. The function is best used for doing common setup such as installing database tables, setting default options, etc.

3. Use dbDelta instead of mysql_query or $wpdb->query() when installing database tables.

The dbDelta function (which you pass your database query to) is used when installing tables into your WordPress database. It is also used as an upgrade script in the same area. Don’t forget to include the WordPress upgrade script before running dbDelta(). The include looks like this:

require_once(ABSPATH . 'wp-admin/includes/upgrade.php');

4. Understand the scope of your plugin and work within it.

As mentioned above, WordPress plugins can be used to hook into essentially any area of the WordPress system. This includes standalone menus, as well as running actions when a post or page is saved, for example. Understanding the objective/s and scope of one’s WordPress plugin is essential to choosing the correct approach for the plugin. If it’s a short plugin with specific objective, there’s no need, in my opinion, for more than one or two files. Keep it simple. On the other hand, if the plugin is a large, standalone module, I don’t believe there’s any reason to have cluttered files of hundreds of lines of code, where an Object Oriented approach would ultimately serve as a much cleaner and more extendable solution.

5. Plan, plan, plan.

Planning on paper, drafting a code map on screen, talking it through with other developers. Planning a plugin can never be done too much. It helps with all of the above steps as well as helping to see where you need to be at the end of the development and planning a solid roadmap for the journey to get there. Also, other users may have ideas that could streamline your plugin even further.

These are just a few things I’ve picked up on my WordPress plugin development journey. I’ll post more if and when they come up. I hope these tips are useful and help in overcoming the potential stumbling blocks when getting started with WordPress plugin development.