Advertise here via BSA

What is Storytlr?

Lifestreaming is the aggregation of all of your actions throughout the web in one place to present a complete picture of your digital life. There are several lifestreaming applications out there, and Storytlr was one of the first.

Storytlr was originally a closed source, hosted web application started by Laurent Eschenauer and Alard Weisscher in 2008. In October 2009 they decided to close the service and in December they open sourced the code.

Considerable community development has occurred since the project was open sourced, including many new plugins, bug fixes and features.

Installing Storytlr

Storytlr is written in PHP and based around the Zend framework. It is usually run on Apache, but works fine on lighttpd and Nginx. The current stable release is 0.9.2, although there is an RC 0.9.3 that works well. Additionally you can use the bleeding edge code on GitHub. I currently maintain my own version of 0.9.3 that has a few more features and plugins you won’t find in the core. You can find it here.

Since it’s coming out of a close source system, expect some rough edges and thin documentation. This is improving all the time with the growing wiki and the issues board. Installation is still one of those rough edges, but it’s fairly easy anyway.

For simplicity I’ll be using the 0.9.2 release from the Google Code site, but these instructions can be easily adapted to other versions. I’ll be doing just about everything from the command line, so if you don’t have shell access, be prepared to tweak things a bit.

Requirements

First, let’s make sure our server is compatible. 0.9.2 has the following requirements:

• PHP 5
• mcrypt
• PDO
• Tidy
• MySQL
• Zend Framework

An easy way to check compatibility is to use this script.

Most hosts have these extensions. The rarest one is Tidy.  For instance, Dreamhost does not run Tidy. If your host doesn’t have Tidy, you can work around it by using a different version with the htmLawed patch.

If you are missing Zend, that can be downloaded here. Make sure to put it in your PHP include path.

Getting Started

Now that you’ve got the requirements met, download the 0.9.2 file and unpack it into your root web directory.

jmhobbs@katya:/var/www/lifestream$ wget http://storytlr.googlecode.com/files/storytlr-0.9.2.tgz
--2010-05-07 13:33:05--  http://storytlr.googlecode.com/files/storytlr-0.9.2.tgz
Resolving storytlr.googlecode.com... 74.125.45.82
Connecting to storytlr.googlecode.com|74.125.45.82|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 8748114 (8.3M) [application/x-gzip]
Saving to: “storytlr-0.9.2.tgz”

100%[============================================>] 8,748,114    233K/s   in 36s

2010-05-07 13:33:41 (239 KB/s) - “storytlr-0.9.2.tgz” saved [8748114/8748114]

jmhobbs@katya:/var/www/lifestream$ tar -zxf storytlr-0.9.2.tgz
jmhobbs@katya:/var/www/lifestream$ ls -a
.  ..  feeds  flash  friendconnect  .htaccess  images  index.php  INSTALL  js  LICENSE  protected  storytlr-0.9.2.tgz  style  themes
jmhobbs@katya:/var/www/lifestream$

The Database

Now you need to load the database schema. The schema files is located at protected/install/database.sql. If you don’t have a database or user set up, now is the time to do that as well.

jmhobbs@katya:/var/www/lifestream$ cd protected/install/
jmhobbs@katya:/var/www/lifestream/protected/install$ mysql -u root -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 5515
Server version: 5.0.81-1 (Debian)

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

mysql> create database lifestream;
Query OK, 1 row affected (0.05 sec)

mysql> grant all on lifestream.* to lifestream@localhost identified by 'supersecretpassword';
Query OK, 0 rows affected (0.11 sec)

mysql> flush privileges;
Query OK, 0 rows affected (0.08 sec)

mysql> use lifestream;
Database changed
mysql> source database.sql
Query OK, 0 rows affected (0.00 sec)

(Lines Removed For Brevity)

Query OK, 0 rows affected (0.00 sec)

mysql> Bye
jmhobbs@katya:/var/www/lifestream/protected/install$

Configuration

Your last major step is the configuration file, which goes at protected/config/config.ini. Storytlr provides an example file with good defaults, so we’ll edit that. The key settings to change are:

• db.username
• db.password
• db.dbname
• security.cookie
• web.host
• web.timezone

jmhobbs@katya:/var/www/lifestream$ cd protected/config/
jmhobbs@katya:/var/www/lifestream/protected/config$ ls
config.ini.sample
jmhobbs@katya:/var/www/lifestream/protected/config$ cp config.ini.sample config.ini
jmhobbs@katya:/var/www/lifestream/protected/config$ vim config.ini

[general]

;Database connection settings
db.adapter=PDO_MYSQL
db.host=localhost
db.username=lifestream
db.password=supersecretpassword
db.dbname=lifestream

;Security
security.cookie = kg89y6gbval

;Caching
;cache.content = 1
;cache.metadata = 1
;cache.path = /tmp/cache/

;Web deployment settings
web.host=lifestream.velvetcache.org
web.path=/
web.redirect = 1
web.timezone=America/Chicago
jmhobbs@katya:/var/www/lifestream/protected/config$

The Fruits of Our Labor

At this point your lifestream should be working, open a browser and take a look.

Now we need to change our password, so go to the admin page http://www.example.com/admin and log in. The default username and password are admin and storytlr respectively. You can find that under Configure » Password.

There are lots of options to browse through, and I won’t cover them all, but I’d like to run through setting up a source. Sources are the core of lifestreaming, and there are lots of options to choose from. In the admin interface go to Sources and click Add next to a source you want to add, I’ll use Delicious in my example.

This should present you with a form asking for some information. Each source is going to be slightly different, but all should be pretty easy to understand. Fill that out and it should import what it can from that source.

There you have it! Add some more sources until your lifestream really fleshes out.

Keeping Current

The very last step, which is often overlooked, is updating your sources. The primary means for this is the PHP script protected/tools/update.php. This must be run from the command line with the name of the user to update. Here’s an example:

jmhobbs@katya:/var/www/lifestream$ php5 protected/tools/update.php admin
Memory usage on startup: 4997940
Memory: 5351904
Memory: 5351904
Updating source delicious for user admin [0/2] (5).... found 0 items
Updated 1 out of 2 sources in 1 seconds.
jmhobbs@katya:/var/www/lifestream$

It’s common to set up a cron job to handle these updates. It’s often important to put in full paths for your cron jobs. This example will update my sources every 10 minutes. You can learn more about cron here.

jmhobbs@katya:/var/www/lifestream$ crontab -e
MAILTO=jmhobbs@towncommons.com
# m h  dom mon dow   command
*/10 * * * * /usr/bin/php5 /var/www/lifestream/protected/tools/update.php admin
jmhobbs@katya:/var/www/lifestream$

Storytlr has lots more features and configuration options, I would encourage you to browse around and make your installation suit your taste. To see an example of a fully customized Storytlr installation, you can visit mine at http://lifestream.velvetcache.org/

Going Further

Storytlr is rich with opportunities to contribute. It’s fairly young and has lots of finicky little things to figure out, and it can always use one more plugin. Lots of stuff is in the works, including a much simpler installer which will make most of this article obsolete!

Documentation is in need of some TLC, and more eyes on the bug reports would be great.

To get involved visit the Storytlr Google Code site or hop onto Github and fork the project. Finally, you can also join us on Freenode IRC in #storytlr.

Advertise here via BSA

In Part I and Part II we looked at how to set up our file structure, how to get URL routing working and how to set up templating for our little framework. In this final part to the series, we are going to briefly look at database access.

Mini-series Overview

• Part 1: URL Routing and Directory Setup
• Part 2: Templating
• Part 3: Database Interaction

You can download all the files put together during this three part series here:

I’m not going into detail about how to create an ORM or ActiveRecord clone. We are just going to write a simple helper class to setup our connection and query. Also I’m going to assume you know how to create a database and table in the database.

I have created a database called “peanut” and created table:

users:
+----------+--------------+------+-----+---------+----------------+
| Field    | Type         | Null | Key | Default | Extra          |
+----------+--------------+------+-----+---------+----------------+
| id       | int(11)      | NO   | PRI | NULL    | auto_increment |
| username | varchar(255) | NO   |     | NULL    |                |
| password | varchar(255) | NO   |     | NULL    |                |
+----------+--------------+------+-----+---------+----------------+

In this example we are going to use Mysql and the php mysql_ methods. So break open system/database.php and drop the following in:

<?php

// Here is where we are setting up a simple wrapper class around mysql
// functions just to make it a little more convenient.  Our models will
// simple extend our database class and simplify making queries just a bit.
class Database
{
	protected var $connection;
	// Every time you instantiate this class you are going to create
	// a new connection to the database.
	public function __construct()
	{
		// First we setup up a nice little connection to the database,
		// make sure you use your connection information.  If the
		// connection fails we just die with the error.
		$this->connection = mysql_pconnect("localhost", "root", "somepassword") or die("MySQL Error: " . mysql_error());

		// And let's tell mysql which db we are going to use.
		mysql_select_db( "peanut", $this->connection );
	}

	// This is just a helper function to help out against
	// possible sql injection attacks.
	public function escapeString($string)
	{
		// we call mysql's 'cleaning' function on strings
		// just to make sure we get a little safer item to query
		// with.
		return mysql_real_escape_string($string);
	}

	// Here we will query the database with the passed query string,
	// build up an array of objects and return them, simple enough.
	public function query($qry)
	{
		// Here we make our query and set the result to a $result variable
		$result = mysql_query($qry) or die("MySQL Error: " . mysql_error());

		// Create a container array variable to hold all of our result objects.
		$resultObjects = array();

		// This might look weird, but all we are doing is saying,
		// While you are still getting results, please put the next
		// result into the next spot on my array.
		while($resultObjects[] = mysql_fetch_object($result));

		// Now we just return our array that has all our result objects in it
		return $resultObjects;
	}

	// Here we add a simplier method for handling INSERTs and UPDATEs since
	// they do not return a result set.
	public function execute($qry)
	{
		$exec = mysql_query($qry) or die("MySQL Error: " . mysql_error());
		return $exec;
	}
}
?>

So we have our database class in place and ready to use, now we just need to require it in the index.php like we did the others, so pop that bad boy open and after the template require, do one just like it but for the database.php

Now let’s crack open actions/helloworld/models.php and let’s write a simple addUser and getAllUsers method to it. We are going to make our model a class as well so that it can extend our Database class that we wrote.

Here are the guts:

<?php

// All of our database back-and-forth will be handled in our models file
// Don't be mistaken, this is no where close to an ORM (Object Relational Mapper)
// it's just simplified database access.

class myModel extends Database
{
	// When our model is instantiated we just need
	// to also instantiate our parent class (Database)
	// so it knows to make the connection to the database.
	public function __construct()
	{
		// We just call the __construct of Database class.
		parent::__construct();
	}

	// addUser will use the execute method of Database
	// since we are inserting a value and not expecting
	// anything in return.
	public function addUser($username, $password)
	{
		// Here we use that little cleaning method we
		// wrote to make our strings pretty and make sure
		// they will play nice with mysql
		$username = $this->escapeString($username);
		$password = $this->escapeString($password);

		// We execute our insert and if it worked $success
		// will be true else it will be false.
		$success = $this->execute("INSERT INTO users (username, password) VALUES ('{$username}','{$password}')");

		// We return $success to inform our page action that it has or hasn't worked.
		return $success;
	}

	// This method does just what you think it would.
	// We are going to use the query function because
	// we are expecting data back, then we are just
	// going to return the array of user objects.
	public function getAllUsers()
	{
		// Populate the $users variable with the results of our query
		$users = $this->query("SELECT * FROM users");

		// Now we return our results
		return $users;
	}
}
?>

Now we need to change our actions/helloworld/actions.php mypage page action to:

<?php
// We need to include our models file so we can access the database
require(PEANUT_ROOT_DIR . 'actions/helloworld/models.php');

// We simply define the function (the second item in our request url)
// making sure it is the same name as the one in the url.

function mypage()
{
	// Let's do some database work!
	// Here we are going to instantiate our model
	$model = new myModel();

	// Now let's add a user
	// On a funny note, if you keep refreshing it will add this
	// user over and over in your users table so your getAllUsers call
	// will result in a list that grows by one each time.
	$model->addUser("wess", "password");

	// Now let's fetch all of our users and put them in our users
	// variable.
	$users = $model->getAllUsers();

	// Let's create a new template object and pass it the path to our template
	$template = new Template("helloworld/templates/helloworld.php");

	// I bet you want to display a table in your template with all your newly
	// created users. So let's do it

	// That's write we use the same set command, and it will set our array of users
	// to our template variable $users, and since php is our template language
	// it's real easy to print them to the screen.
	$template->set('users', $users);

	// Set our page variable "title" with the value "Hello World"
	$template->set('title', 'Hello World');

	// Set our page variable "message" with our little message
	$template->set('message','This is my first message for my template');

	// Now we can call render and return it to dispatch to
	// display in our browser
	return $template->render();
}
?>

So now you are handing all your users from your database to the template, so let’s display them. Change your actions/helloworld/templates/helloworld.php file to:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
	<head>
		<meta http-equiv="Content-type" content="text/html; charset=utf-8">
		<title>My PEANUT Page</title>

	</head>
	<body>
		<h1><?php echo $title ?></h1>
		<p><?php echo $message ?></p>

		<h2>Users:</h2>
		<table>
			<thead>
				<tr>
					<th>ID</th>
					<th>Username</th>
					<th>Password</th>
				</tr>
			</thead>
			<tbody>
				<!--
					Here we are going to use native php foreach look
					to create each row of the table with our list of users.
					Notice how the foreach is done with a : and surrounding php tags.
				-->
				<?php foreach($users as $user): ?>
					<tr>
						<td><?php echo $user->id ?></td>
						<td><?php echo $user->username ?></td>
						<td><?php echo $user->password ?></td>
					</tr>
				<?php endforeach; ?>
			</tbody>
		</table>
	</body>
</html>

Now if all went well, you should save all your files and open up: http://mywebapp.local/helloworld/mypage and see all the users that you added in a table.

So you have created a template class, url basic url routing, simplified database access, and a page action. You have all the core basics of a PHP Framework at your hands now. This is just for a starting point or foundation of understanding, please do not use this in a production environment.

I have really enjoyed writing this and I hope you learned something from my rambling! The source code is available for download at the top of this article.

Take care,
Wess “Wattz”

Updated October 26, 2009: Thanks to Alex and Ian for spotting some errors in the code and supplying the fixes. The code examples have been updated to reflect the changes as has the ZIP file.

Advertise here via BSA

A little over a week ago, we looked at how to set up our file structure and how to get URL routing working in our little framework. So we now have something to handle urls and display a page, but we want to make the page a little more attractive. Since there is nothing fun about making php print html, let’s add a template piece to the puzzle. We won’t have to do too much since php is a great template language by itself.

Mini-series Overview

• Part 1: URL Routing and Directory Setup
• Part 2: Templating
• Part 3: Database Interaction

Note: I’m assuming you have a little OOP (Object Oriented Programming) experience. There are a ton of tutorials out there, so just a heads up: I won’t be teaching/explaining OOP here.

We are going to create a class Template and add a little code to it so it will return our pretty new page to our browser.

Wipe out system/template.php and add the following code to it:

<?php
// We are creating a simple class here to handle our templating.
// All this class will do is set some variables and return
// a rendered webpage using native php as the template language.
class Template
{
	// We setup $pageVars to hold all our pages
	// variables.
	private $pageVars = array();

	// We setup $template to define what file is our
	// template and were to get it.
	private $template;

	// When a new Template object is instantiated we want to make sure
	// we pass it a shortened path to the file we want it to use
	// as our template.
	// example: $template = new Template("helloworld/templates/helloworld.php");

	public function __construct($template)
	{

		// We setup our action directory
		$actionsDirectory = PEANUT_ROOT_DIR . 'actions';

		// Let's build and set our class var $template to the
		// value of $template that was passed into our __construct method
		$this->template = $actionsDirectory . '/' . $template;
	}

	// Now we create out set method to allow use to set variables that
	// we want in the template.
	// So in our page action we would do:
	// $template->set("title", "hello world");
	// and in our template:
	// <h1><?php echo $title; ?></h1>
	public function set($var, $val)
	{
		// This may look weird, but it's not to bad;
		// what we are doing is setting the index name
		// of our associative array pageVars
		// (we setup earlier at the top of the class)
		// to the value that we pass. so $pageVars["yourVar"] = "yourValue"
		// is basically what it's doing.
		$this->pageVars[$var] = $val;
	}

	// To render we will need to do a couple of things.
	// First we will need to extract those pageVars then
	// include the template, populate the values in the template
	// and return a rendered page to the browser
	//
	// This is far more easy than you think it is
	// trust me!
	public function render()
	{
		// The extract function is a weird bird
		// when you call it on an associative array
		// it creates regular vars.
		// For instance:
		// 		$this->pageVars["yourVar"]
		// becomes:
		// 		$yourVar
		// so basically we are converting all the
		// index keys (with their values), in pageVars to
		// their own respected variables
		extract($this->pageVars);

		// Now that we have all the variables extracted, the vars we set
		// in the template will be replaced by the value of the pageVars variables.
		// Now we start up our output buffer, grab our template and return the
		// buffer with it's "rendered" template
		ob_start();
			require($this->template);
		return ob_get_clean();
	}
}

Well hello templating! Now let’s do a couple of things to hook it up to our framework. First, let’s open up our www/index.php one more time and add the following line:

require(PEANUT_ROOT_DIR . ’system/template.php’);

Right underneath the dispatch.php require statement. Now let’s change our actions/helloworld/actions.php mypage function to look like:

// We simply define the function (the second item in our request url)
// making sure it is the same name as the one in the url.
function mypage()
{
	// Let's create a new template object and pass it the path to our template
	$template = new Template("helloworld/templates/helloworld.php");

	// Set our page variable "title" with the value "Hello World"
	$template->set('title', 'Hello World');

	// Set our page variable "message" with our little message
	$template->set('message','This is my first message for my template');

	// Now we can call render and return it to dispatch to
	// display in our browser
	return $template->render();
}

Ok, so now our page action is setup to use our new found template class, now we need to setup our template

So inside actions/helloworld/templates/helloworld.php template put the following:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
	<head>
		<meta http-equiv="Content-type" content="text/html; charset=utf-8">
		<title>My PEANUT Page</title>

	</head>
	<body>
		<!--
		See how we use native php here?
		echo out a variable, this is the same
		variable name that you use in your template
		set method ($template->('title', "hello")).
		-->
		<h1><?php echo $title ?></h1>
		<p><?php echo $message ?></p>
	</body>
</html>

Ok, so let’s see where we are at. We have basic url routing, templating, and page actions. We are only missing one thing, a way to talk to the database! That will be the next and final article in our mini-series on rolling your own PHP Framework.

Advertise here via BSA

Why WordPress?

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.

Advertise here via BSA

You got to love Wordpress theme frameworks when trying to put together a theme for Wordpress.

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!