One fun (and useful) example of a Rack middleware is a Firebug logger written by Simon Jefford for the CodeRack competition. This middleware allows you to send arbitrary messages directly to Firebug. Why? Since you’re already debugging much of your Rails app in a browser anyway, sending debug output to your browser’s console (instead of tailing a log file) makes a lot of sense.

NOTE: FirebugLogger plays nice with WebKit’s Web Inspector as well.

Simon also released a Rails plugin that you can install to set up the middleware for you, but it’s more fun (and informative) to set it up yourself. Here’s how:

Setup

The goal is to be able to send arbitrary messages to Firebug from any controller or view.

Rails autoloads (and namespaces) any code placed in the lib directory, so that is where we’ll place our FirebugLogger code. Grab the code from my gist, which is a fork of Simon’s original with minor improvements, and place it inside your Rails app in:

lib/rack/firebug_logger.rb

Rails will load the code for us, but we need to manually activate the middleware. Since this bit of code is only useful during development, we’ll load it up in that environment only.

# config/environments/development.rb
# ... other stuff ...
config.middleware.use ::Rack::FirebugLogger

Using FirebugLogger

Using the middleware is pretty straight forward. It will process an array of arrays, each of which has a log level and a message. Add a single line like the one below to an existing controller action and load up the page:

# app/controllers/posts_controller.rb
class PostsController < ApplicationController
  def index
    @posts = Post.all
    request.env['firebug.logs'] = [[:info, "hello from rack!"]]
  end
  # ... other actions ...
end

Open Firebug and you should see “hello from rack!” glaring back at you. You can do the same thing in views:

# app/views/posts/index.html.erb
<% request.env['firebug.logs'] = [[:warn, "inside a view!"]] %>

Adding a Helper

Using the logger like this is a bit tedious, and it’s not easy to create multiple messages for a single request. Let’s wrap the functionality up into a method that we can call. This method should be placed in the application controller so that all other controllers inherit it.

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
# ... other stuff ...
helper_method :firebug

  private

  def firebug(message,type = :debug)
    request.env['firebug.logs'] ||= []
    request.env['firebug.logs'] << [type.to_sym, message.to_s]
  end
end

This method will initialize an empty array the first time it is called and then push new messages on to the array on subsequent calls. Notice that it calls to_s on the message variable before passing it on. This means you can send the method a string or any object that responds to to_s and it will just work. Specifying a log type is optional, the method is private and it is explicitly added as a helper_method so that you can access it from views as well.

Now writing logs to Firebug is as easy as:

firebug "woop woop!"
# optionally specify a log level
firebug "it's a trap!", :warning

Here are a few ideas of helpful messages to send to Firebug:

# inspect the attributes of an object
firebug @posts.first.inspect
# dump the session
firebug session
# check a user's roles
firebug current_user.roles.inspect

I highly encourage you to try this in one of your Rails apps. It has proven a useful addition to my toolkit. Let me know how it works for you by leaving a comment!

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Set Rails Logging on Fire

All this was inspired yesterday by Janko’s article yesterday, “Automatically generate table of contents using jQuery.” Start by reading his article to get a background on the topic, then head over to the documentation page for the download link as well as three different examples of usage.

This plugin is version 0.8, so please comment on any bugs you find. Feel free to follow or fork the project on github as well! Keep in mind I didn’t spend ages getting the CSS on the example pages to be cross-browser ready, though the plugin itself has full cross-browser support.

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Table of Contents jQuery Plugin

Benefits

• The input element or textarea never really has content, so validation can proceed without first checking for the field value.
• It uses standard markup for form elements
• It is under 1KB when minified and gzipped
• It takes one line of jQuery code to implement.
• The overlay can contain images and other HTML elements
• Its compatible with all modern browsers (And even IE6, the “not-so-modern” browser).

Issues

Like all in-field label implementations, this plugin still has problems when the browser tries to pre-fill the fields. When Safari and Firefox pre-fills the fields for the user, it never sends a “change” event to hook into. You can get around this by adding autocomplete=”off” to the input elements, but this is undesirable for longer forms. I am looking for a fix, but for now, this plugin is still usable for shorter forms!

Quick Overview

The effect is achieved by overlaying the label element over the input, password, or textarea and making it semi-transparent when the field has focus. Once a keystroke is detected the label disappears entirely until the field loses focus. If it is empty on blur, then the label fades back in. Clicking on the label auto sets focus on the field.

Download It

Head over to the Sample Page to read more about the plugin and to download it. Let me know your thoughts and suggestions in the comments below!

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

In-Field Labels: A Better Way + jQuery Plugin

Download Wordpress Console from Wordpress.org

As as a WordPress Developer myself, I am not easily wowed by plugins. If they work, I often will use them. If they don’t, I build my own. That is not the case with this plugin! I was truly stunned by the features this plugin boasted. Lets look at a few:

Interactive Prompt

In its most basic usage, it works like you would expect a console app to function. You can type any valid line of php, and see the response.

>> 'hi';
 => hi
>> print 'hi';
  hi

It supports variable placement and references:

>> $greetings = 'Hello';
 => Hello
>> print $greetings;
  Hello

Finally, it supports multi-line statements:

>> $coolness = true;
 => true
>> if( true == $coolness ) {
.. echo 'This is cool!';
.. }
  This is cool!

Command History

Just like in DOS or Mac/’nix Terminal, hitting the up arrow retrieves the previous command for reuse. Hitting it again gets the previous command, and so forth. Hitting down cycles through the history states the other direction.

Quick Shortcuts

• reload, or r and enter resets the environment
• clear, or c and enter clears the console screen
• help, or ? prints out the help text.

Tab Completion

Ok, so I saved to coolest feature to describe last: Tab Completion. This is what makes this console so incredibly useful. Want a quick listing of all the WordPress the_ functions? Just type the_ and hit tab. The console quickly prints out all the functions available (even those from plugins) starting with the_.

Forget a specific WordPress constant? Type WP_ and hit tab.

You really have to try it out for yourself to see how much this will affect your development with WordPress.

Behind the Plugin: Jerod Santo

I was so impressed with this plugin, I got on a Skype call with its creator, Jerod Santo. Jerod is a super nice guy that is just really good at what he does. He started in computer scripting and gradually moved into heavier programming. He is a Ruby, Rails, and Sinatra guy that also does a lot of development with WordPress.

Having gotten used to the Rails console, and IRB for Ruby, Jerod wanted something similar for WordPress. The CLI for PHP just didn’t cut it for him. He searched the internet for a tool like this that he was sure someone had built, only to find that it didn’t exist yet! After doing without for a bit longer, he decided to give it a shot, and Wordpress Console was born.

He has since gotten some contributions from others on Github (I actually contributed a few small changes myself!).

About Little More About Jerod

I asked Jerod what he does for fun, and the type of hobbies he enjoys. Jerod described himself as a Christian who enjoys church activities; a family guy who likes spending time with his wife and little girl; and a Geek, who enjoys extremely geeky things.

Being self-taught, Jerod is constantly learning and teaching himself new technologies. He loves jQuery, Ruby, WordPress, and is dabbling in iPhone App development.

I really appreciate Jerod for building such a great plugin, and for taking the time to give me some background into its creation and use.

Be sure to subscribe to his blog, and follow Jerod on twitter and on Github.

Video Overview

Here is a quick screencast Jerod made available on Vimeo. It does not demonstrate tab completion, but it is a great watch nonetheless.

WordPress Console Introduction from Jerod Santo on Vimeo.

A Word of Caution

Read the disclaimer when installing and ONLY use this plugin in development. Though steps have been taken to make this plugin secure, Jerod still warns that using this plugin in production could create a huge security problem.

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Plugin Review: Wordpress Console

The only problem is that bios are not standard in WordPress. This article will tell you how to hack your own bio box into WordPress without using a single plugin! A great way to start developing in WordPress.

Hack your template

First thing we need to do is to hack a file in your theme’s template. The file we want to edit is called “single.php” in most WordPress themes.

Open up this file.

This is the template file that shows a single post. Typically the template file has the following code somewhere “the_content()” looks for this.
Beneath this line of code paste the following:

<?php
if (get_post_custom_values("bio")) {
?>

<div class='writer_bio'>
<img src='<?php the_author_aim(); ?>' alt='' />
<?php the_author_description(); ?>
</div>
<?php
}
?>

Adding a bio to a writer

We now want to add / edit writers, you can create them in the user panel of WordPress. I am guessing you are already using this to display the author’s name on your blog. We can use the fields available per user to set the bio.

Go and edit an existing user that has an article posted (You can change the user that posted the article when you edit an article.)
Now fill in the “Biographical Info” text area with the HTML to go into the bio block.

My bio, for example is: “Gaya Kessler is a 21 year old web developer writing about a kinds of thing. He’s the editor of <a href=”http://www.fuelyourcoding.com”>Fuel Your Coding</a> and owner of <a href=”http://www.gayadesign.com”>Gaya Design</a>. You can also <a href=”http://www.twitter.com/gayadesign”>catch him on twitter</a>.”

To add the avatar we need to fill in the “aim” field. I am not using this field anywhere in the theme, but now I am going to use it in the bio. Put the absolute path to the image here, eg: “http://fuelyourcoding.com/files/writer-rob.png”.

Now all there is left to do is enable the bio on a post. To do this you only need to add a custom field to a post.
Go to a post you want to add bio to and create a name custom field called “bio” and give it the value “1″.

If all went well the bio should now be visible in that post!

Is that all?

Jep! The hacking is done.

You might want to add some styling though, to make it more appealing to the eye.

Good luck with this easy hack!

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

WordPress hack: Adding a bio block to a post

For those who use WordPress on a daily basis, this is a no-brainer. However, as everyone seems to have their own pet CMS, it is sometimes hard for them to understand why anyone would use WordPress for something other than just a blogging platform. I am sure there are many pros and cons, but I will just give my personal answer: I feel very comfortable using and pushing the limits of WordPress for projects because of the huge install and developer base, the active development work being done, the amount of documentation available to my client, and the extensibility and integration my code has with the WordPress core.

Why WordPress Plugins?

A WordPress plugin can be a single PHP file or a complex collection of PHP, CSS, JS and images all used together to add new or enhanced functionality to the WordPress core.

Since almost everything you can put in a plugin you can also just dump into a functions.php file in your theme directory, why should you bother building a plugin? Here are a few reasons I find important:

• Plugins are focused pieces of code structured to accomplish one task. The very nature of a plugin makes it easy to maintain.
• Because of the modular nature of a plugin, it makes your code instantly reusable on other projects (Depending on your code ownership agreements with your clients, of course.)
• If over time it grows into a truly helpful collection of code, having it in a plugin allows you to release it to the public quickly and easily.
• Having large chunks of functionality split into plugins makes changes to the PHP and related files easier to make later.

I think WordPress plugins should be especially important to anyone running a web application that could benefit from direct integration into the WordPress platform. This could include a WordPress sidebar widget that pulls information from your website, a shortcode for quickly embedding your site content in WordPress posts, etc.

Getting Started

File Naming

The first choice you should make is whether you need a single PHP file or a folder with multiple files and assets. Here are some questions help you think through this:

• Am I going to have associated images, CSS, or JS related to this plugin
• Will I have more than one admin panel needed for users to manage this plugin
• Will there be multiple distinct pieces to this plugin (i.e. widgets, template tags, etc).

If you are building anything more than a simple plugin with a few methods and no associated files, you should go with a directory structure for your plugin.

If we were going to build a plugin called “Fancy Plugin,” your file would look like this:

wp-content/plugins/fancy_plugin.php

or

wp-content/plugins/fancy_plugin/fancy_plugin.php

Keep in mind when you name your plugin file that it is unique to what your plugin is and does. Since two plugins cannot both be installed if they have the same file name, be sure to run a Google search and check the Extend section of WordPress.org before settling on a name.

Folder Structure

For complex plugins, I follow this format for my directory structure:

plugin_folder/
-- plugin_file.php  <= Primary Plugin File
-- css/             <= All CSS
-- images/          <= All Images
-- js/              <= All JS
-- php/             <= Supporting PHP Files
-- views/           <= All Administrative Panels and Metaboxes

Plugin Metadata

The very first thing you need in your plugin is the metadata block that is used by WordPress to both activate your plugin and notify the user of pertinent information. It should look like this (Taken directly from “Writing a Plugin”:

<?php
/*
	Plugin Name: Name Of The Plugin
	Plugin URI: http://URI_Of_Page_Describing_Plugin_and_Updates
	Description: A brief description of the Plugin.
	Version: The Plugin's Version Number, e.g.: 1.0
	Author: Name Of The Plugin Author
	Author URI: http://URI_Of_The_Plugin_Author
*/
?>

This metadata block is a simple cut and paste into your primary plugin PHP file.

Extending WordPress With Your Plugin

Template Tags

One of the most simple things your plugin can do, is offer custom template tags for use in your themes. Template tags are just PHP functions. A good rule of thumb is to follow the direction of the WP team by prefixing functions that return data with get_, and functions that echo out directly with the_. For example:

function get_map_widget_code(){
	return "<script src='...'>My really long widget code...</script>";
}

function the_map_widget_code(){
	echo get_map_widget_code();
}

These functions could then be used in any theme like this:

<p>The two ways to use these template tags are echo it myself:</p>
<?php echo get_map_widget_code() ?>
<p> or let the function echo it (cleaner): </p>
<?php the_map_widget_code() ?>

Template Tags, like all top level functions, have to be unique across the entire set of plugins, WP Core, and theme files. Be sure to choose names that are unique enough as not to conflict with existing method names.

Shortcodes

Shortcodes were introduced in WordPress 2.5 and allows the programmer to solve some complex HTML problems in an extremely easy way. Perhaps you want to provide an easy way for a client to list a few products on any page or post. You could just give them the HTML, and tell them to be sure to copy it anywhere they want products… but we all know how well instructions like those work out. Instead, you should provide a simple short code for them to use:

[products]
[product name="My Special Product" price=3.99]
[product name="An Amazing Book" price=12.99]
[/products]

That is a lot easier for a client to remember than a bunch of nested HTML that they have to switch into HTML view to edit or create. Here is the PHP code that would allow this shortcode to function:

function products_shortcode_callback( $atts, $content=null ){
	// Set a blank return by default
	$ret = "";

	// If there is content between the shortcodes
	// then add our wrapping tags
	if($content){
		$ret = '<ul class="products in-post-products">';

		// Nested shortcodes are not processed by default
		// be sure to make this call if you want
		// to process nested shortcodes
		$ret .= do_shortcode($content);

		$ret .= '</ul>';
	}

	// Never echo output from a shortcode function!!!
	return $ret;
}

function product_shortcode_callback( $atts ){
	// Get the attributes and filter out
	// unwanted attributes
	$a = shortcode_atts( array(
		'name' => 'Product Name',
		'price' => 'No Price'), $atts );

	// Prepend a $ sign if price is supplied
	if ($a['price'] != 'No Price') $a['price'] = '$' . $a['price'];

	// Build HTML
	$ret = "<li><span class='product-name'>";
	$ret .= $a['name'] . "</span><br />";
	$ret .= '<span class="price">' . $a['price'];
	$ret .= '</span></li>';

	// Again, return NOT echo:
	return $ret;
}

// Finally, add the shortcodes to the system
// So WordPress knows about them
add_shortcode( "products", "products_shortcode_callback" );
add_shortcode( "product", "product_shortcode_callback" );

As you have seen twice in the comments of the previous code example, NEVER echo output from a shortcode! Be sure to always return the content so it can be inserted in the correct place.

The previous code example would replace the shortcodes with this HTML (lines split for clarity):

<ul class="products in-post-products">
<li><span class="product-name">My Special Product</span><br /><span class="price">$3.99</span></li>
<li><span class="product-name">An Amazing Book</span><br /><span class="price">$12.99</span></li>
</ul>

Reference Links

• Shortcode API

Filters and Actions

Much of your extensions to the WordPress core will happen with Filters and Actions. Thankfully, they are pretty easy to understand! A filter simply sends you content at the appropriate time, and expects content in return. Be sure to check the documentation on WordPress.org when creating filters because certain filters will pass you more than one parameter. The following code will add text before and after each post title:

function add_text_to_title( $title ){
	return 'Text Before << ' . $title . ' >> And After';
}
// Register filter with WP
add_filter( "the_title", "add_text_to_title" );

Actions are called when certain actions are about to happen or have just happened. Actions allow you to execute your code at the appropriate time. The following code adds a javascript file to each page of the front-end site:

function add_special_scripts(){
	wp_2_enqueue_script(
		'special_script',
		plugins_url('/test/special.js'),
		array( 'jquery' ), // require jquery
		'0.1' // Helps with cacheing
	);
}
// Register the action with WP
add_action("wp_2_print_scripts", "add_special_scripts");

Reference Links

• Plugin API/Action Reference
• Plugin API/Filter Reference

Widgets, Pluggable Functions, Settings, and User Interaction

Some of the more advanced techniques of building plugins, including user interaction through admin menus, storing settings in the database, and writing a sidebar widget will be covered in an upcoming article.

Closing Advice

1. When you begin to extend WordPress through plugins or theme additions, make the Codex your best friend. The amount of developer documentation availible is amazing and extremely helpful.
2. If you cannot find documentation on a particular function or hook, do a global search of your WordPress installation (Cmd+Shift+F in TextMate) to look for the definition of the function. Often looking at the source will give you an idea how it works.
3. Make sure you have PHP errors turned on locally, or have access to your PHP error log to troubleshoot your development. Not being able to catch small PHP errors can make your life miserable.

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Getting Started Writing WordPress Plugins

There are various reasons to use a framework. As you might know, frameworks provide you with convenience and code that you don’t have to write all over. Robin’s article about CakePHP is about a PHP Framework which will speed up your development.

A few reasons you should use Wordpress Frameworks:

• Save development time
• Have the HTML layout ready to use and valid
• Some SEO included
• No need to make all the template pages yourself
• You won’t forget to put in Wordpress features that quick
• Loops are already written for most pages

I’ve been using theme frameworks to get themes implemented for some time now and I must say I am very pleased with the results. I got the projects up and running in no time! It’s a real life saver if you have little time.

What it does is quite simple: being a basic template for your theme. You’ll only need to style the HTML and adjust anything in it.

It’s just a theme with nothing in it but HTML, template tags and some basic styling ready. You’ll have to download the theme, adjust it, upload it and use it in Wordpress. It’s as simple as that! No need for any special installation on your server or anything.

The following Wordpress theme frameworks are quite famous:

• Sandbox
  The framework I’ve been using for a while now. Must say I am very pleased with how it’s put together.
  Uses very strong HTML and is really easy to adjust.

• Thematic
  Has a bit more going on with styling than Sandbox and might make it easier for beginners to work with. Great integration of widget areas and implementations of various plugins. Looks nice too!

• Hybrid
  Even more themed than Sandbox and Themematic. Easy to configure and gets a beginner going in minutes! Really nice to try out and build your next theme on.

Feel free to share your thoughts and experiences with theme frameworks in the comments. I’d love to hear your stories!

Sponsored by

Advertise on Fuel Brand Network.
Fuel Brand Network 2010 cc (creative commons license)

Wordpress theme frameworks