The Proposition

As a WordPress developer/designer, how would you like if URLs on your WordPress site were automatically shortened as soon as you publish? This would mean instantly available shortened URLs for sharing/posting AND statistics of your links!

Here’s How

We are going to build the Auto URL Shortening feature within your WordPress theme using the bit.ly API. Let’s start with the functions.php file found within your theme.

The functions.php file is included in most WordPress themes as a place to drop custom functions to be used from the theme. If this file doesn’t exist in the theme you are using, go ahead and create it.

Add 3 functions within the functions.php file

function makeshorturl()
{

}

function shorturl_metabox()
{

}

function showshorturlbox()
{

}

The first function, makeshorturl(), as the name suggests will be creating a short URL for us. The second and the third functions will work together to show us the short URL in the admin editor.

Shortening the link

function makeshorturl()
{
    global $post;

    $short_url = json_decode(file_get_contents('http://api.bit.ly/v3/shorten?login=[username]&apiKey=[apikey]&longURL='.urlencode(get_permalink($post->ID)).'&format=json'));

    if($short_url->status_code=="200")
    {
         $short_url = $short_url->data->url;
    }
    else
    {
        $short_url = "Bit.ly Error! ".$short_url->status_txt;
    }

    do_action('makeshorturl');

    return $short_url;
}

The first line in this function declares WordPress’s global $post variable which holds all the data for the current post. We extract the permalink of the current post using the get_permalink() function and supplying the current post’s id. We then take the permalink and pass it on to bit.ly’s API which returns us a short URL within a JSON object. Next we extract the short URL. If an error occurs we simply return the error.

The do_action() method in WordPress makes this function hookable with other functions/hooks and the function can be used within theme using the hook – makeshorturl().

Want to know more about do_action() and wordpress hooks?

Lets look at the api call in more detail

http://api.bit.ly/v3/shorten?login=[username]&apiKey=[apikey]&longURL='.urlencode(get_permalink($post->ID)).'&format=json

It’s really quite simple.

The login parameter would expect your login over at bit.ly (don’t have one? create one here). The apiKey parameter accepts the API key given to each bit.ly account. If you already have an account you can find the API key here. The longURL parameter expects an encoded long URL string that needs to be shortened, and this is where our custom permalinks get passed. The format parameter expects one of the three values – json, xml or text; depending on the format value specified, the API returns the shortened url (and more data) as JSON, XML or text respectively. By default, if format is not specified, it returns a JSON object. For more info on the bit.ly API, refer the API documentation. Once the bit.ly API sends the JSON object back, we use PHP’s json_decode function to decode the JSON object into a PHP5 object.

Adding the shortened URL to the admin editor

Once the permalink has been shortened, we need to make it available in the backend. To do this, we use the two functions as outlined below.

function shorturl_metabox()
{
    if(is_admin())
    {
        add_meta_box('bitlyurl',__('Short URL','short-url'),'showshorturlbox','post','side');
        add_meta_box('bitlyurl',__('Short URL','short-url'),'showshorturlbox','page','side');
    }
}

The shorturl_metabox will first check if the user is within the admin section of the wordpress based site/blog. Then we add a meta box to the admin page.

A Meta box in WordPress basically is a box which sets and gets meta information about a post. Default meta boxes include Post Tags, Discussions and so forth.

More on meta boxes.

The add_meta_box function takes five parameters:

1. the HTML id of the box
2. the label/title of the box
3. the callback function which would render the box contents
4. the type of write screen – post or a page
5. the position or context where the box would be located – Normal, Advanced or Side.

More on add_meta_box().

As you can see, that when the function “adds” the meta box to the admin view, it calls the showshorturlbox function which renders the contents of the meta box, as shown below.

function showshorturlbox()
{
    echo '<label for="bitlyurl">'.__('Shortened URL','short-url-label').': '.makeshorturl().'</label><br/><br/>';
}

The function echoes the short URL in a label, thus making it available to be shared by the authors of the post/page. We are calling makeshorturl() which fetches or generates the shortened URL via the bitly API.

Bringing it together

Finally we use the following three lines which attach our makeshorturl() function to the publish_post and publish_page hooks and attaches shorturl_metabox to the do_meta_boxes hook that generates the meta boxes.

add_action('publish_post','makeshorturl');
add_action('publish_page','makeshorturl');
add_action('do_meta_boxes','shorturl_metabox');

Complete Code within functions.php

function makeshorturl()
{
global $post;

$short_url = json_decode(file_get_contents('http://api.bit.ly/v3/shorten?login=[username]&apiKey=[apikey]&longURL='.urlencode(get_permalink($post->ID)).'&format=json'));

if($short_url->status_code=="200")
    {
         $short_url = $short_url->data->url;
    }
    else
    {
        $short_url = "Bit.ly Error! ".$short_url->status_txt;
    }
    do_action('makeshorturl');
    return $short_url;
}

function shorturl_metabox()
{
    if(is_admin())
    {
        add_meta_box('bitlyurl',__('Short URL','short-url'),'showshorturlbox','post','side');
        add_meta_box('bitlyurl',__('Short URL','short-url'),'showshorturlbox','page','side');
    }
}

function showshorturlbox()
{
    echo '<label for="bitlyurl">'.__('Shortened URL','short-url-label').': '.makeshorturl().'</label><br/><br/>';
}

add_action('publish_post','makeshorturl');
add_action('publish_page','makeshorturl');
add_action('do_meta_boxes','shorturl_metabox');

Usage

If you did like to show off the shortened URL to your users simply insert this code where you want the short URL to show up:

<?php echo makeshorturl(); ?>

BONUS

Want a ready-to-use solution? Here’s the plugin version of the above code that will generate the shortened URLs on the fly for you to share. If you did like to call the functions from within the theme template, you can do so by using:

<?php echo wps_hook(); ?>

Note: Above tag is for the plugin only.

PS: The plugin can also show number of clicks on a shortened link :) per shortened URL

Download it!

Sponsored by

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

WordPress: Auto URL Shortening

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.

Sponsored by

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

Meet Storytlr

print_r( $post );
die();

One the statements are in place, the programmer refreshes the page and looks at the source to view a nicely indented array or object. Next they comment out the print_r and die statements, change some lines, and try the code again. If it fails, they are back to square one and in go the print_r,echo and die statements so the brutal cycle can begin again.

We know these methods partially work (who hasn’t done the above during a PHP project!), but we also know they are less than optimal. Is there a better way?

WordPress Debug Mode

WordPress offers quite a few ways to enable and customize a debug mode while developing. To enable debug mode, you want to define WP_DEBUG as true in your wp-config.php. Here is the complete code block I suggest you use. We will look at the individual parts shortly. Place this in your wp-config.php file after the lines that define the database variables. Be sure to change development_user to be your development database user name:

@ini_set('display_errors',0);
if( 'development_user' === DB_USER ){
  define('WP_DEBUG',         true);  // Turn debugging ON
  define('WP_DEBUG_DISPLAY', false); // Turn forced display OFF
  define('WP_DEBUG_LOG',     true);  // Turn logging to wp-content/debug.log ON
}

display_errors

The first line in our code block turns off the display of errors, regardless of php.ini or .htaccess settings to the contrary. This is important because though WordPress can force the display of errors to be on, it won’t force them to be off if display_errors is already turned on.

Testing for local vs. production

There are probably fifty ways of doing this part, so use a method that works for you. In my environments, my local development database rarely if ever has the same user name as the production database. Simply checking what I expect the local user name to be against what is defined in DB_USER is a simple way of knowing if the files are on the development or production servers.

WP_DEBUG

This is the most important constant as it determines if WordPress will use any of the other debugging constants. Thankfully it is quite simple. If set to true, debug mode is turned on. If undefined or set to false, debug mode is kept off.

WP_DEBUG_DISPLAY

This constant confused me at first, but it is actually quite simple. If set to true, it will override the current display_errors configuration setting and turn it on. However, if set to false it will not turn off display_errors. This setting is simply an override. This is the reason we turn display_errors off before setting any of these constants.

Set this constant to true if you want to see errors displayed in your browser when they occur. Keep in mind this will sometimes complicate errors because once at least one error has been written to the page, all redirect requests will fail. This is because the header information can no longer be modified once content is sent, and a displayed error counts as content.

WP_DEBUG_LOG

This constant is the whole reason I found the WordPress debug methods so helpful. Set this constant to true and WordPress will set up PHP to write to an error log in wp-content/debug.log. Sadly you can’t specify a different file location that is not in the content folder, but at least you know where it is!

Note: because this is written to a public directly, be extremely careful not to upload the log by mistake. Additionally, if you run WP_DEBUG on a production server, do so only for immediate troubleshooting then turn it off and remove wp-content/debug.log.

Leveraging WP_DEBUG

In addition to PHP errors being sent to debug.log we can also send our own output using the error_log PHP function. The only problem with this, is even in production mode your errors will still most likely be written to a PHP log; it just won’t be debug.log. Because of this, its a good idea to provide a wrapper function to handle the logging for your theme or plugin.

Place the following code in your functions.php in your theme, or in the plugin file for your WordPress plugin:

if(!function_exists('_log')){
  function _log( $message ) {
    if( WP_DEBUG === true ){
      if( is_array( $message ) || is_object( $message ) ){
        error_log( print_r( $message, true ) );
      } else {
        error_log( $message );
      }
    }
  }
}

Feel free to expand on this function if it doesn’t exactly meet your needs, but the concept is simple: Centralize all your log calls to use your custom function. Then, in that _log function, only output the message if WP_DEBUG is set to true. There is no reason to test if WP_DEBUG has been defined because as soon as wp-settings.php is processed, WP_DEBUG will be defined, even if it wasn’t already defined in wp-config.php.

This particular _log snippet will call a print_r on arrays and objects passed to the function for simple debugging.

Trying it Out

If you have followed these steps, you can run a quick test by adding these lines into your header.php file in your theme folder:

_log('Testing the error message logging');
_log(array('it' => 'works'));

After refreshing your page once, you should see a newly created debug.php file with a few lines of output. Use any log viewing utility that supports tailing the file for maximum productivity. On Mac, Unix and Linux systems, you can use this command from the main directory of your site:

tail -f wp-content/debug.log

More Solutions

If you are looking for a more interactive console for debugging, be sure to look at our review on the WordPress Console.

What about you? If you didn’t already know about this built in WordPress feature, what methods did you come up with to make debugging WordPress easier? Please leave us your tips in the comments below!

Sponsored by

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

Simple Debugging with WordPress

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.

Sponsored by

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

Roll Your Own PHP Framework: Part III

Below is a screen capture of the final gallery. To see the gallery in action, click here

This tutorial assumes that you have textpattern installed and ready to go.
( Download the latest version of Textpattern here: http://textpattern.com/download)

Galleriffic

This gallery is based on Galleriffic, a jQuery plugin for rendering fast-performing photo galleries. This is adapted from http://www.twospy.com/galleriffic/ to work with textpattern so you (and your clients!) can easily update the gallery. In a nutshell, the gallery works by associating image id #s with a specific article. The article form gallery and article_image_form work together to render the article in the form of all of the associated images (in their thumbnail format) to appear as an unordered list on the left, while the full version of the current image appears on the right. All that is necessary to add or change images, is to change the numbered list appearing in the advanced options on the left of the article containing the images. So easy once implemented, even a client that doesn’t speak nerd can add, subtract or change their own images.

Upload the files

Upload both of the galleriffic files included in the files folder of the download, by uploading them through the Content > Files tab. I modified the jquery.galleriffic.js file so that the pagination does not appear above the thumbnails. Should you wish to further customize the gallery, I do suggest checking out the original Galleriffic demo.

Install the relevant plugins

Install the following plugins (these are included in the Plugins folder in the download):

• upm_image by Mary Fredbord – more powerful image display
• ebl-image-edit by Eric Limegrover – introduces advanced image editing functionality

(I have had technical issues with v.2 of this plugin, so I continue to use v1. Both are included in the plugin folder.)

ebl-image-edit is great for sizing/creating thumbnails on the fly, without having Textpattern automatically centre the thumbnail. It is not essential to this tutorial, but it’s very very handy!

Set up your forms

You can find these forms in the forms folder in the download.

gallery

Create a new form called “gallery” and choose “article” for the type:

<txp:upm_article_image form="article_image_form" wraptag="ul"
class="thumbs noscript" />

article_image_form

Create a new form called “article_image_form” and choose “misc” for the type:

<li><a href="<txp:upm_img_full_url />" title="<txp:upm_img_caption />" class="thumb"><img src="<txp:upm_img_thumb_url />" alt="<txp:upm_img_alt />" /></a>

<div>
<div><txp:upm_img_alt /> </div>
<div><txp:upm_img_caption /></div>
</div>
</li>

If you don’t want captions, delete the whole caption div.

Basically we have taken this code from galleriffic:

<ul> <li> <a href="path/to/slide" title="your image title"> <img src="path/to/thumbnail" alt="your image title again for graceful degradation" /> </a> <div> (Any html can go here) </div> </li> ... (repeat for every image in the gallery) </ul>

and modified it so the article forms generate this code from the image numbers that we will associate with the gallery article. We’re basically saying, “take the images associated with this article, put the thumbnail versions of those images on the left with these classes and this formatting, and put the full version of the selected image on the right.” Huh? Just follow along, I promise it will all make sense soon…

Set up your page

In the pages folder I have included a template for this gallery page (gallery.html). Create a new page template in textpattern: Presentation > Pages. At the bottom, “copy page as”, name it gallery, and click “copy.” Make sure whatever section you are using for the gallery is in fact using the gallery page as its template. At the bottom of the page you will notice the galleriffic script. This is where you can make adjustments to sizes, number of thumbnails, etc. In this example I have set a limit of 9 to the thumbnails. At the bottom of the page, near the top of the script, it looks like:

numThumbs: 9,

Set up your style

I have created a master style sheet that incorporates some of the Textpattern defaults as well as galleriffic specific css. Copy the content from the screen.css file provided in the Styles folder and paste it into your default styles tab under Presentation > Style.

Add your images

Go ahead and start uploading some images, and create some thumbnails. Make sure your images are all using the same size of thumbnail. Take note of the image ID numbers, as that is what you will use to call your images into the article. Make sure to add the Alt text and Caption when you upload, as this is what will appear to the left of the main image (unless you opted to delete the captions).

Create a new article called gallery. On the left hand side, click advanced options, and enter the ID numbers of the images you want to appear in the gallery, separated by commas. Make sure you post the article to the gallery section, or whichever section you have set up to display the gallery, and click publish. Your article should look something like this:

View Site. You should notice that the images have been automatically formatted into thumbnails on the left, with the first one appearing in full on the right. That’s it! You have a galleriffic gallery integrated with Textpattern. Play around with the html, settings, scripts and CSS to customize it to suit your own needs.

If you have any questions, suggestions, or requests for future articles, please do not hesitate to leave a comment.

Thanks, and happy coding!

Sponsored by

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

Easy to update thumbnail gallery using Textpattern and Galleriffic

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.

Sponsored by

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

Roll Your Own PHP Framework: Part II

Mini-series Overview

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

To get started let’s setup our directory structure. We are going to call our framework “Peanut” (first thing that popped in my head).
So for our structure let’s make it really basic:

MyWebApp/
  '---actions/
    '---helloworld/
      '--- actions.php
      '--- models.php
      '--- templates/
        '--- yourTemplateHere.php
'---system/
  '--- template.php
  '--- database.php
  '--- dispatch.php
'---www/
  '--- js/
  '--- css/
  '--- images/
  '--- index.php

Let’s break this structure down, it’s simple.

MyWebApp: the root of your web app that will be using our “Peanut” framework

• actions: this will contain all the pages our web app will use.
  • helloworld: is the name of our page action or ’section’ of our site
    • actions.php: is where we will code our page actions
    • models.php: where we will write all our database interaction
    • templates: this is the folder we will store all our views/templates
• system: this is where we will store all our framework specific classes/source/libraries
  • template.php: This will handle all of our template rendering.
  • database.php: This is for our database connection and access
  • dispatch.php: This will parse our url and call the correct page action.
• www: this is our root web directory, it is also where we will pull everything together.
  • js: the directory where you store your javascript
  • css: put your style sheets in here
  • images: guess!
  • index.php: This is the file that will initiate and pull together the pieces of Peanut.

Now that we have a directory structure, let’s setup a virtual host in Apache to accommodate for Peanut. Here is an example of a virtual host you can use (here is what I do on my Mac):

NameVirtualHost *:80

<VirtualHost *:80>
        ServerName      mywebapp.local
        DocumentRoot    /Users/wcope/Sites/mywebapp/www

        AcceptPathInfo On

        RewriteEngine On
        RewriteRule     /*\.(css|js|gif|png|jpe?g)$ - [NC,L]
        RewriteRule "^(.*)$"    "/index.php?_url=$1" [QSA,L]

        <Directory "/Users/wcope/Sites/mywebapp/www">
                AllowOverride All
                Order allow,deny
                Allow from all
        </Directory>

</VirtualHost>

And In my /etc/hosts file I add this line:

127.0.0.1	mywebapp.local

That will allow ‘mywebapp.local’ to resolve to my localhost where Apache will pick it up and kick it off to the virtual host we created. Inside that virtual host we have some rewrite rules that will redirect all request made (except css, js, gif, png, jpeg/jpg) to index.php?_url=$1. To break that down in the simplest way, basically Apache takes: mywebapp.local/some/page and redirects it to index.php?_url=/some/page (but you never see the latter). Also notice that we made the root directory of our virtual host to our www folder where index.php is.

Ok, so now we have our directory structure, virtual host and rewrite rules all setup. If you have any detailed questions about Apache, mod_rewrite, virtual hosts, host files, etc. Sorry they will not be covered here due to the fact that there is tons on it out there… so hit up your local google.com :).

So now let’s get to some code.

So first lets write our dispatch code since that will be what is responsible for routing all our request to the proper pages.

Open up index.php in your favorite text editor and let’s slap some code in it:

In this file is a good place to put constant variables, include any files and call our dispatch (once we write it). But for right now let’s do a little test, and also write a little helper function I’m going to use to print stuff to the screen that can help us see what’s going on.

<?php
// First let's define our apps root directory
define("PEANUT_ROOT_DIR", realpath(dirname(__FILE__) . '/../') . '/');

// now a pretty little dump function (or if you have xdebug you can just use var_dump)
function dump($item, $die=true)
{
	$printString = '<pre>' . print_r($item, true) . '</pre>';
	if($die)
		die($printString);
	else
		echo $printString;
}

// Now let's just dump our URL to make sure that all paths lead here
dump($_GET);
?>

Now if we bring up our url: http://mywebapp.local/some/url/ we should see something like:

Array
(
    [_url] => /some/url/
)

So now we can see that our rewrite is working and we are ready to start writing our dispatch function, so let’s change our index.php code a little.

<?php
// First let's define our apps root directory
define("PEANUT_ROOT_DIR", realpath(dirname(__FILE__) . '/../') . '/');

// now a pretty little dump function (or if you have xdebug you can just use var_dump)
function dump($item, $die=true)
{
	$printString = '<pre>' . print_r($item, true) . '</pre>';
	if($die)
		die($printString);
	else
		echo $printString;
}

// Let's comment this out
// dump($_GET);
// and add this:

// first we are going to drop our dispatch file in here
require(PEANUT_ROOT_DIR . 'system/dispatch.php');

// then call our dispatch function to handle the url
// Notice Im not passing in $_GET or $_GET['_url'], being that
// $_GET is a global system variable, I don't have to worry about it
// here.

dispatch();
?>

So now let’s save that and crack open our system/dispatch.php file and and add some code to it to handle our new found url pattern. As I said before, this will only be a simple router with no config or predefined url pattern to page action mapping.

So, inside dispatch.php, let’s add:

<?php
// Here we are going to handle our url request

function dispatch()
{
	// First we are going to grab our url path and trim the / of the
	// left and the right
	$url = trim($_GET['_url'], '/');

	// Now we are going to split the url on the / which
	// will give us an array with 2 indexes.
	$url = explode('/', $url);

	// Let's just print out our array to get a visual of
	// what we are working with.
	dump($url);
}

?>

Now if you refresh your browser at our current url (http://mywebapp.local/some/url/) you should see:

Array
(
    [0] => some
    [1] => url
)

Great, now we have 2 clean items to work with. So let’s tell dispatch that the item at index 0 will be our folder and item at 1 will be the page action inside our actions.php file. Since our directory structure is setup to use actions/helloworld/actions.php, let’s setup dispatch to include the file with our action in it in the directory that was requested in the url. So change dispatch.php to look like:

// Let's handle that url
function dispatch()
{
	// First we are going to grab the url path and trim the / off
	// the left and the right.
	$url = trim($_GET['_url'], '/');

	// We changed this from before to make it easier to read and also so we can
	// work with easier variables.  using the list (http://php.net/list) function
	// will map the array indexes to the respected order of the var names inside
	// the list function call (better explanation at php.net/lists).
	list($directory, $action) = explode('/', $url);

	// Now we drop in our respected actions file from the directory in the url
	require(PEANUT_ROOT_DIR . 'actions/' . $directory . '/actions.php');

	// And call the action from inside our actions.php file
	// and since we want to end our request with the return value of our requested method
	// let's just die on the return.
	die($action());
}

Now we need to add our action inside our actions.php file, so open it up and drop the following
in it:

<?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()
{
	// For now we are simply going to return "Hello World" string
	return "Hello World";
}

?>

So let’s give this a shot. Open up your web browser and point it to: http://mywebapp.local/helloworld/mypage.You should see a pretty little “Hello World” in the browser. If you do, congrats! You now have routing in your new Peanut framework.

Next week we will see how to add templating into our framework.

Sponsored by

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

PHP Frameworks? Just roll your own! – PART 1

Why Textpattern?

Okay, I will be the first to admit that when I first started with Textpattern, I was in way over my head. I had never worked with a CMS before, and I wasn’t an expert with CSS. I had stumbled upon a beautiful portfolio website by another web designer, and I noticed in the footer that the website was built using Textpattern. I thought to myself, if this designer can build a dynamic portfolio website using Textpattern, surely I can too, right? So I made it my mission to learn and master Textpattern. I learned the hard way, since I didn’t know anyone who was familiar with it (Wordpress always seemed to be the CMS of choice). However, Textpattern has an enormously helpful community and many helpful articles, blogs, and forums where other users were generous enough to share their tips, tricks and plugins. Textpattern has now become my CMS of choice as I have found it to be undeniably powerful and flexible, and it doesn’t require any knowledge or experience with PHP (not to mention, it’s free and open source). Once you wrap your head around the basics, you can bend Textpattern to your will quite easily. Check out the publishing features on the textpattern website.

Getting started

This tutorial assumes that you have a fairly strong understanding of HTML and CSS, however I am using an adapted version of Google Blueprint CSS to keep things extra simple. We will be building a very simple portfolio website with a blog component. I will continue to add articles which will build on textpattern’s functionality, but for now I am stripping a lot of Textpattern’s defaults, which can be quite confusing if you’re not sure about the syntax.

Head over to the textpattern website to download the latest version. Follow the detailed install instructions.

You will also need the files I provided in this zip file:

Login to your site, and you should see something like this:

You will notice that Textpattern has 4 tabs at the top: content, presentation, admin, and view site. Go to your admin tab, and check your diagnostics to make sure that there are no errors in your installation. If all checks have passed, head over to your preferences, and change your site name and slogan (even if you choose for these not to appear as is, you should change them to be relevant to your own site). It is a matter of personal preference, but I like to change my permanent link mode to section/title, as I like the way it appears in my url. Since this is a beginner tutorial, I would recommend leaving the other settings as is until you are more comfortable with Textpattern.

In the Textpattern handbook, it is recommended that you code your site in HTML and CSS before building it on Textpattern. I tend to build my sites live within Textpattern because I find the textpattern tags and plugins can achieve what I want much faster than coding it by hand. It’s really a matter of personal preference.

What I am going to do is STRIP AWAY the Textpattern defaults, and simplify things a little bit. Once you get more comfortable with textpattern, you can begin to add in more functionality, but for the purposes of understanding how textpattern works, I think the defaults are a bit overkill when you’re learning.

In a nutshell

In a nutshell, textpattern works by posting articles (think of articles as your main content) to sections (main navigation) of your site. Each section is associated with a page template. The pages tab under Presentation is where you dictate the HTML structure of your page. This is where your html combines with txp tags to create the functionality of your templates. The style tab under presentation is where the css resides. Forms are the most powerful part of textpattern; they tell an article how, when, where, and why to appear! More details on forms below.

Set up your sections

Think of sections as the main navigation of your site. In this example, we’ll use about, work, blog and contact. There is no need to create a “home” section, as the “default” section IS the home section, and you will notice that textpattern already has an about section by default. So create a work, blog, and contact section. I tend to leave the “articles” section that is there by default, and I use it to post my articles that appear only on the homepage but nowhere else. For the about and contact page, I tend to select NO for the setting: “on front page” , since the homepage can display articles from all sections, and I do not want my contact page to appear on my homepage.

Install your plugins

There are a number of plugins that are incredibly useful that I tend to install by default each time I create a new site. In the download files I have provided a plugin folder where you will find a number of txt files that contain the plugins you will need for this tutorial. Open the txt files one by one, and install the plugins by going to your Admin > Plugins tab. Just copy and paste the text into the field, and hit upload. You will see a preview of the plugin. Scroll down and click Install. You will then see your plugin title, author, and description. By default, the plugins are NOT active until you click “no” under active to switch it to “yes.” Do this with all of the plugins provided in the plugins folder.

Create your forms

Forms work in one of two ways:

1. As a reusable snippet of information.

Your header, footer and navigation are likely to be the same on every page, so you would create this as a form, which you would then call into your page template.

An example of this type of form would be the header form, which you will find in the forms folder of the tutorial download. In your textpattern backend, go to Presentation > Forms, and create a new form. Call it header, and choose “misc” for the type. Copy and paste the following code into the body of the form and save:

 <div id="head">
<h1><txp:site_name /></h1>
<txp:section_list wraptag="ul" break="li" include_default="1" default_title="home" sections=", about, work, blog, contact" active_class="active"/>
</div> 

What this does it creates a div with an ID of head, uses your h1 tag to call your site name, and creates your main navigation. <txp:section_list /> creates a list of all the the site sections. What I have done is narrowed the selection down so it just calls the default section (while naming it “home”), the about section, work, blog and contact. It will wrap the entire list in a “ul”, and wrap each individual section with a “li”. It will also automatically add a class of “active” to the current section’s li. If you want more flexibility with your menu, you can always hard code it with HTML, however, this <txp:section_list /> tag is usually all you really need. By default, the section_list ul is assigned a class of .section_list.

2. It tells an article how to behave

One of the most important tags in your page template will be the <txp:article /> tag.

The following snippet:

<txp:article form="single" listform="default" />

basically means: display the article using the form named “single” if you are on an individual article page, and using the form named “default” when you are displaying a list of articles.

In your Presentation > Forms, the “single” form could look like this: (which would just display the title and the body of the article)

 <h3><txp:title /></h3>
<txp:body /> 

while the “default” form could look something like this: (which would display the title, and excerpt, with a link to the full version of the article)

 <h3><txp:title /></h3> <txp:excerpt />
<p><a class="more" href="<txp:permlink />">read more</a></p> 

A list of the most basic and useful forms are provided to you in the forms folder in the download for this tutorial. Create all of them in the Presentation > Forms. If you notice that some of the forms already exist, just override the textpattern defaults with the ones i’m providing. You should have the following forms (in brackets is the “type” you must select for the form):

• portfolio_listing (article)
• portflio (article)
• intro (article)
• single (article)
• subnav (article)
• article_listing (article)
• default (article)
• head (misc)
• foot (misc) – make sure you add your own copyright info
• meta (misc) – make sure you add your own meta data in this form!
• excerpt (article)
• (article)

Set up your page templates

I have created very simplified versions of the textpattern defaults, which you can build upon as you get more comfortable. In the Pages folder, you will find 3 files: default.html, archive.html and home.html. Override the textpattern defaults with the ones I am providing to you. Make sure you go back to your sections, and tell the default section to use page home, the blog page should use archive, and the rest should use default. You must hit save after each change, you cannot change multiple sections at once.

Set up your style

I have created a master style sheet based on Google Blueprint CSS and incorporates some of the Textpattern defaults. Copy the content from the screen.css file provided in the Styles folder and paste it into your default styles tab under Presentation > Style.

Add your portfolio

I have created this portfolio with certain defaults, to help you get a feel for how textpattern works. Once you understand the basics, you should feel free to use your own image sizes, css, etc. As a basis, portfolio images should be sized to maximum width of 620px. Upload a few of your own images (i’ve included a few placeholder images) through the content > images tab. Specify a size of 300px wide by 200px tall for your thumbnail. Click “crop” to avoid the image being squished to fit your dimensions. Hit save once you are finished. There are additional plugins which are fantastic for offering advanced image editing; if you are feeling adventurous, I highly recommend this plugin: ebl-image-edit, which will allow you greater flexibility for creating thumbnails and cropping, etc. Once you have uploaded an image, you will notice that Textpatern automatically assigns the image an id number. Take note of the id number, as that is how you will refer to your images in the future.

Head over to the Content > Write tab to write your first article. Give it a title, put a description in the body. On the left, click “advanced options” and under article image, enter the id #’s (separated by a comma) of the images you wish to be associated with this article. Then, assign the article to the “work” section. When you are finished, hit “publish.” Continue to write your articles, assigning your images to each article. When you have written a few articles, you should click “view site” in the top right of the textpattern window. I tend to leave one tab with the textpattern backend open, with the live site in another, so I can easily refresh and see any changes (or errors!)

You should see something like this:

This is basically the work page in its “listform.” If you click on any of the thumbnails or article titles, you will see the “individual article,” which should look something like this:

If you take a look at the code in the page template for work, you will notice this textpattern tag:

 <txp:article listform="portfolio_listing" form="portfolio" sort="posted desc" limit="30" /> 

If we analyze the form portfolio_listing, it looks like this:

 <div class="span-8">
<txp:permlink> <txp:upm_article_image type="thumbnail" limit="1" class="border"/>   </txp:permlink>
<h3><txp:permlink><txp:title /></txp:permlink></h3>
<txp:excerpt />
</div> 

This basically tells the page to list articles in the form of a div with a class of .span-8, which contains the “image associated with the article”, in the form of a thumbnail, limit it to 1 image, and link the image to the full version of the article. Underneath the image is the “title” of the article in the style of h3, which also links to the full version of the article. Beneath that, show the excerpt associated with that article.

If you take a look at the form “portfolio”, you should see this:

<div class="span-8">
  <h3><txp:title /></h3>
  <txp:body />
</div>
<div class="span-16 last">
   <txp:upm_article_image />
</div>  

This basically creates a div with a class of .span-8 which contains the title and body of the article. Beside it floats a div with a class of .span-16 last, which contains the images associated with the article. Should you wish for the title to appear above the images on the right, you would simply move the <h3><txp:title /></h3> over to the div with the class of .span-16. These forms basically determine the layout for your articles.

A note about article and article_custom

You will notice in the home.html template, that there are two different ways to call articles: <txp:article /> and <txp:article_custom />. It took me a while to wrap my brain around the difference between the two, but here is how it works:

<txp:article /> will call your full article in whatever form you tell it to use. It is section-specific, which means it will automatically call an article from the section you are currently visiting. You must always have an article tag on your page.

<txp:article_custom /> Think of this as a LIST of your articles, in whatever form you tell it to use. Using this tag, you can call articles from ANY section into a page. For example, one the homepage, I am using the article_custom tag to display a snippet from the work, blog, and articles sections. In the archive template for example, on the left-hand side, I am using article_custom to display a full list of all articles posted to the blog page (in the form of subnav), and I am using the plugin “rvm_if_this_article” to automatically detect the current article and make it active.

Create your contact page

You can use the plugins provided (zem_contact_lang and zem_contact_reborn) to create a contact form on your contact page. If you have already installed the plugins provided, and wish to use the contact form, copy and paste the following details into the body of a new article. To avoid formatting with textile, (textile will automatically render things in paragraphs) put a space before each line. Putting a space tells textpattern to format as is, with html, not textile.

<txp:zem_contact to="recipient@example.com" label="">
<txp:zem_contact_text label="Name" break=""/>
<txp:zem_contact_email label="Email" break=""/>
<txp:zem_contact_textarea label="Message" rows="10" cols="23" break=""/>
<txp:zem_contact_submit label="Send" />
</txp:zem_contact> 

In the excerpt, paste any information you wish to be on the left hand side of the page, such as links to your facebook, twitter, or other profiles. And/or you could place an image here; it’s up to you. Assign the article to the “contact” page, and publish.

Create your about page

Create a new article for your about page. In the body write your bio. In the excerpt, place your photo (or other additional information you wish to provide). In order to call an image, you would write the following: <txp:image id=”#” /> and of course, replace the # with the proper image id number. Assign the article to the about section and publish. If you want to change how this page is displayed, you can edit the form named about.

Create your blog page

There are a million and one ways to organize your blog, and I am just demonstrating a very simplified way, since this is probably a whole other tutorial.

Write your blog article. Add an excerpt (usually the first paragraph of your blog). Publish it to your blog section. (You can feel free to create categories, and assign your article to categories, but I won’t get into how to navigate by category in this tutorial- stay tuned). When you click on the blog page, you should see a list of your articles in the form of a Title with an h3 style, followed by the articles’ excerpt. You can click on the title to reach the full version of the article. You will notice a list of your blog articles on the left. I have limited the page to 10 articles on the listing page. When there are more than 10 articles, the page will display a link on the bottom that says “older” and “newer”. This page will always display the most recent articles first. Should you wish to change the order, you can change the timestamp of the article. Click on the article you wish to edit, and on the bottom right you will see a link that says “more.” Click that and you will notice that you can manually reset the timestamp. Hit save. Obviously, this is somewhat of a temporary solution for a blog, since having many blog postings would create quite a long list on the left. Stay tuned for an article on navigating your blog by category. If you wish for comments to be allowed, you must turn them “on” in the actual article itself. On the right hand side of the article page, you will see “allow comments.” Choose yes or no.

Bring it all Home

Now it’s time to create your homepage.

Create an article that will be an introductory paragraph on the homepage. We are using the form “intro” on this article, so it won’t display the title. If you want this article to use a title, change the form in the tag to “single” instead of “intro”. To clarify, you are looking for this tag in your home page template:

<txp:article_custom status="sticky" sort="posted asc" form="intro"/> 

Otherwise, use the heading of h3 in your body by typing h3. (with a space after the period) before your copy. (As opposed to wrapping your copy in <h3> tags) On the right, choose a status of “sticky”. We are making this article “sticky” because we don’t want it to be affected by newly written articles- it is more or less “static” content. Your work articles will always be displayed with the status of live, and the homepage will always display the most recent work.

You will notice in the “home” page template, that there is this tag: <txp:image id=”3″ />. Replace this number with the # of the image you want to appear here. The size is set to 940px wide by 350px high. Upload an image of that size through your images tab, and then replace the number in that tag with the appropriate id #.

Also on the homepage is a snippet from the most recent blog posting. If you want to change how the blog appears, you must edit the form “article_listing”. Keep in mind, this will change how your blogs appear on your blog page as well. If you wish for your blog to appear differently on the homepage than it does on the blog page, simple change the form used in this tag on your home template form:

 <txp:article_custom form="article_listing" section="blog" limit="1" sort="posted desc"/> 

Try it out!

I’ve provided templates/forms/css to you to help simplify some of Textpattern’s funcionality, but its really up to you to make it work how you want it to. It is a very powerful CMS, and I would recommend looking through some of the textpattern tags to see what is available. There are many powerful “if” statements that provide even greater flexibility. Feel free to change any of the pages/forms/html and css I have provided to tailor it to your own needs. There are tons of resources out there to help you understand how to use it better. I highly recommend setting up a test site where you can play freely and experiment. There are so many different ways to work with textpatterns functionality; this is just the tip of the iceberg! If you think you might want to consider textpattern as your cms of choice, I recommend checking out the following sites:

• http://www.txptips.com
• http://www.textpattern.com
• http://www.welovetxp.com
• http://www.textpattern.org

Stay tuned for articles on how to build an extremely easy to update gallery page with thumbnail and captions, as well as category-based blog navigation, and easy nested sub-menus with automatically detected active class.

This is my first official “tutorial”, so if anything is unclear, feel free to post your comments/questions in the comments below, and I will do my best to answer any questions. I am also open to any feedback you may have as well, or suggestions for future articles.

Sponsored by

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

Create a Simple Portfolio Website and Blog with Textpattern

Introduction

In the world of web development, when building a blog, you don’t always want to refer to a slow, over-featured blogging engine like Wordpress. Thankfully, there is a solution, and its name is Chyrp. Chyrp is a blogging engine that is designed to be extremely lightweight, while still retaining functionality. Alex Suraci, the developer behind Chyrp, codes it in Twig, a language specifically created for this project. The Twig is then put through a compiler and its output is solid PHP.

Before we start, it is important to know how Chyrp is extended: Feathers extend post formats, Modules add functionality, such as a commenting system, and Themes change the look and feel. Keep this in mind.

Interested? Well then, let’s get started!

Installation

Download Chyrp, and open up the folder Chyrp v2.0, which should be in the same directory as the archive. Select all the contents and copy and paste it to a directory on your web server (for the purposes of this article, we’ll be using the /chyrp/ directory). Now would be the time to read the COPYING file, so you don’t break any copyright laws. You can delete it or keep it, along with the README.markdown file. If your server isn’t already started, start it. Go to http://localhost/chyrp/ (Or whatever address you use to access your testing server) in your web browser and you should have two errors at the top of the browser window: one for the .htaccess file, and the other for permissions.

Go ahead and create the .htaccess file with the contents it shows, and save it in the /chyrp/ directory. You also need to CHMOD the /chyrp/includes/ directory to 777. This means changing the permissions to all read and write. Once you’ve done that, refresh the web browser page. Now, go ahead and fill in your database information. In this article, we’ll be using MySQL.

Back at the installation screen, insert your database information. The host is usually localhost. As for a table prefix, we can leave that blank, unless we’re installing multiple instances of Chyrp on the same database.

Once you filled out the form, hit Install. It fills the database with the information and configures the files within the instance. When it is complete, this page will show:

So, delete install.php within /chyrp/, as it poses a security risk if you keep it. If you speak German, you’re in lucky, because that is the only language pack available at the moment. So now, click Take me to my site! and you’ll be taken to the home page.

As you can see, there are no posts. Go to the sidebar and click Login, and use your credentials from before. Once that is done, a toolbar will appear in the top. Click the Admin link and you’ll be taken to the backend.

Writing in Chyrp

When you open the backend (it is located at /chyrp/admin/), the Write section is automatically visible. And because Chyrp is a blogging engine, you can make posts and pages. Posts can come in many different forms, such as photos, videos, and plain old text. These different forms come in extensions called Feathers. If you add a photo, you’ll need the photo Feather in order to do that. The text Feather already comes with Chyrp, and is already activated. The photo, video, link, audio, quote, and chat Feathers already come with the installation, but are not yet activated. We’ll go through activating them later.

To create a post or page, just select the type on the tabs and type up what you’d like to say. If you click More Options you can choose a permission status, slug, trackback, timestamp, and pinned status (whether or not you’d like it as first post, no matter what). Once you’re done, you can save it, or Publish it. Once you hit Publish, Chyrp will take you to the home page, where you can view your post. It’s just that easy!

Manage your Install

Head back to the backend and click on the Manage tab, near the top. This will bring you to this page:

From here you can manage everything about your install. If you click one of the tabs near the middle of the page, you can select what you want to manage. As you add Modules, more tabs will appear.

Modules are ways to extend your install. For example, one Module creates a commenting system, and another allows you to cache pages. We’ll get into this later.

What you need to focus on in the Manage section is the Groups tab. This allows you to change permissions for groups. Currently, you are part of the Admin group. Click on the edit link (it’s on the right side) and you’ll be taken to the page for editing group permissions, as well as the name of the group. Click Save when you’re done.

Change the Settings

The next navigation option is Settings. Under General, you can change your blogs’ name, description, and other settings. Under Content, you can edit posts per page, uploads path, and allowing XML-RPC support. Then, in Users, you can allow r disallow users registering themselves, the default user group, and what group Guests are in (you can even allow all un-registered guests to have Admin permissions, though it is not suggested). Finally, under Routes, you can allow clean URL’s, which will make the URL’s formatted as stated in the form below (I highly recommend it—who wants a URL with a question mark in it?).

Extending your Install

The Extend section is very important. Extensions are what make Chyrp so very powerful and functional. Modules are very powerful, and the ones that are made by the head developer come with Chyrp. Those are:

• Textilize
• SWFUpload
• Paging
• Aggregator
• Tagginator
• Read More
• Comment System
• Markdown
• SmartyPants
• Cacher

All these do exactly what they’re named for. To activate them, just drag it from the red zone into the green zone. When you do that, a dialog pops up, reminding you to change the permissions. Once you’ve added all the Modules you want, go back into Manage > Groups and change the permissions so you can manage the Modules.

Now, go ahead and go into the Feathers section. As you can see, the following Feathers come with Chyrp:

• Photo
• Video
• Link
• Audio
• Quote
• Chat

Plus, the Text Feather, but it is already activated. To activate them, it is the same action as before. If you enable the Photo, Video, or Audio Feather, then you need to create a uploads directory in /chyrp/ and CHMOD it to 777 so you can upload media.

And finally, Themes. The theme that comes with Chyrp is called Stardust. It may be fine for a casual blogger, but for a designer, like me, you need to design your own. That will be in a follow-up article.

Downloading Extensions

There are some more extensions on the Chyrp site. There are not many, but the user base is growing rapidly, and so is the development base. To add Feathers, Modules, Themes, etc, just download it and extract the archive to /themes/, /modules/, or /feathers/, respectively. Then, just go into the backend and activate it. It’s just that simple.

Chyrp vs. Wordpress

You may be questioning, “Why Chyrp? Why not just go with the popular solution: Wordpress?” Well, why Wordpress? There are a lot of functions in Wordpress that you’ll never need or use, so why have them. A fresh Chyrp install is bare bones, and you’re free to install what you need. Plus, Chyrp is a lot faster than Wordpress, on the front and backend.

As well as speed, Chyrp has better code than Wordpress—Alex (founder and sole core-developer) uses Ruby on Rails and Python helpers to have perfect code that is easy to edit.

While retaining functionality, Chyrp is more flexible than Wordpress. It can do a lot of different functions, and is easy to mod to your hearts content.

So why use Wordpress?

The Chyrp Community and Support

Chyrp has a strong community and support group. In the Discuss section of the Chyrp site, you can ask for help or just discuss… whatever. Or, to get instant help, log on to good ol’ IRC on irc://freenode.org/chyrp (that would be irc.freenode.org as the server, then #chyrp as the channel).

In the next article, we’ll be building a custom theme!

Sponsored by

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

Getting Started with Chyrp

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

This article assumes a working knowledge of web development programming in general, including working with Apache, a MySQL database and most obviously, PHP.

CakePHP is a development framework similar to Ruby on Rails, although written in PHP. CakePHP is modelled on “Convention over Configuration” paradigm, meaning that there should be as little configuration as possible to enable you to very quickly set up a working website. This method of programming is often called RAD (Rapid Application Development).

Important Resources

• CakePHP CookBook
• CakePHP API Documentation

Before we grab the source code of Cake (PHP) and get stuck in, let us first find out the requirements.

Required Setup

1. Apache HTTPD Server (2.0 – 2.2)
2. PHP (4.x – 5.x)
3. MySQL (3.x – 5.x)

As well as the above, some kind of IDE such as Eclipse PDT or E-Text Editor is also recommended for ease of development. Assuming you have all of these set up correctly, it’s time to grab the source code of Cake from their most excellent website.

As of writing, the latest stable version of the “Cake Core” is 1.2.3.8166. The large download button shows the way, and the rest is easy. Once downloaded, extract to your configured document root.

The easiest way to get started, is to create a database using your preferred database management tool (in my case, phpMyAdmin or you can use MySQL Workbench)

For the purposes of this tutorial, I will use a very simple database, the app we will be making is a list of sorts, be it a wish list or a to-do list, whatever you want to do to expand on it will be possible with the help of future tutorials.

Requirements

• Ability to view a list of “wishes”
• Each item should include a link to the particular wish
• Each item should be editable to check off whether it has been bought/completed
• The list of wishes should order the uncompleted wishes at the top, and the completed wishes at the bottom.

A very simple set of requirements makes for a very simple and quickly made application. To start off, let’s create the database.

CREATE DATABASE `wishlist`;

CREATE TABLE `wishlist`.`wishes` (
	`id` INT NOT NULL AUTO_INCREMENT PRIMARY KEY ,
	`name` VARCHAR( 100 ) NOT NULL ,
	`link` TEXT NOT NULL ,
	`complete` BOOL NOT NULL ,
	`created` DATETIME NOT NULL
) ENGINE = InnoDB;

And that’s all there is to creating the database and its table. Notice that the table is named as a plural. This is fundamental to creating tables which CakePHP can understand easily. Also the `created` field is an automagic field, which Cake will automatically populate on creation of a row. ‘modified’ is also another automagic field. Information on field types can be found in the CookBook.

Baking your Cake

Now we’re getting into the technical part. Open a command prompt. If you’re using Linux, I’d expect you to already know how to do this. If you’re using Windows, press the Windows Key and R on your keyboard and type “cmd” without the quotes. In OS X, press Command + Space and type “Terminal” and hit enter.

It should look something like the following in Windows:

Find the directory you installed Cake Core into, and navigate to the console directory. We are going to use the automatic baking application to create the website at light speed!

The command that has to be run is “cake bake” as you can see above. This will run the CakePHP Console application. When run with no parameters it will take you through a wizard of sorts. Use this tool to create a new directory somewhere inside your DocumentRoot.

This will dump the default system into the directory, and update its own configuration so it knows where to find the core files.

The next step, it will ask you to specify your database configuration. You can pretty much enter the default values (just hit enter at each option).

When it asks you for the database name, choose “wishlist” or whatever database you chose at the beginning.

If everything went smoothly, you should end up with the following:

Follow the on screen instructions for editing the current page and its layouts if you wish.

Now is the time to bake the models and controllers for your system. The easiest way to accomplish this is to use the built-in baking tool once more and create these quickly.

As we have already set up the Database Configuration, select M first to create the models.

Don’t forget to specify –app on the command line in order for the application to know what CakePHP project you are working with.

As you can see, CakePHP has automatically detected our only model and has given it as an option to create a model with. Select ‘y’ so that we can create validation criteria that will be included with the model.

For each field, a screen like the following will be shown, choose the type of the field for each field you have in your table. CakePHP usually does a pretty neat job of automatically choosing for itself, but sometimes it needs a hand.

In our example, CakePHP does not automatically detect the `link` field as a URL field, nor does it detect the BOOL field `complete` as a Boolean. Select 27 for the `link` field, and 4 for the `complete` field.

Select 8 for the `created` field and you should be all set.

Answer ‘n’ for the model associations question, as there are no other models to associate with in this particular instance.

When your model baking is complete, this is how it should all look:

Answer ‘n’ again to the testing question. The testing suite is pointless this early in your CakePHP career, but will come in handy once you start getting more advanced.

Next you need to bake your controllers (The actual processing part of your application). Select C on the list:

The controller section is very easy. You do not need to build your controller interactively, you only need the basic functions, and you do not need to set up admin routing for now.

Again select ‘n’ for the SimpleTest question and continue.

As long as you have selected as I have above, you should end up with something similar to this:

This is the baked index screen, which can be edited in wishlist/views/wishes/index.ctp

The add wish screen

The wish index with an item

A single wish view page

Conclusion

CakePHP is incredibly versatile in the way it works, and its configurability. You can literally make a site in a lunch break. The next tutorials will show you how easy it is to customize the app you’ve created today, to finish the remainder of the original requirements of the application, and hopefully bring you a deeper understanding on how good it is to have tasty Cake once in a while.

Sponsored by

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

Getting to know CakePHP (Part 1)

First things first

Before we start seeing stuff on the screen, we have to make something out of nothing. We start at the basics of web developing: HTML. This markup language will draw shapes on the web page and display text.

HTML is not only very important, your whole markup will depend on it. Don’t touch CSS yet! We’ll come to that later.
CSS is worthless with a bad markup supporting it.

1. Learn HTML

1. Learn basic HTML
2. Learn about xhtml and validation
3. Make valid xhtml and validate

Learning perfect HTML will take some time but it will really pay off later. It’s way easier to prevent mistakes and track down bugs when the markup is perfect.

Next step is what you’ve been waiting for; applying CSS.

2. Know CSS

1. How to apply CSS
2. Know all the important aspects of styling
3. Learn about positioning
4. Get to advanced CSS

You don’t have to be perfect at CSS. But being good at it will save a lot of time for your designer.

If you plan on becoming a server side programmer you are best off learning a server side language to generate HTML pages now. Take a look at PHP, ASP.NET, JSP etc. if you want to know more.

Now that you know good HTML and CSS it’s time to put in a little Javascript.
Don’t start by using a framework now, you first need to understand what Javascript is and what it can do to alter the layout of the web page.

3. Rock Javascript!

1. Read a good book about Javascript.
2. Get to know some funny Javascript effects and concepts. (There are a lot on the Internet)

After I read a good book and experimented with Javascript on some projects a bit, I wanted to get everything out of Javascript by making nice effects like the other guys do. For this there are a lot of frameworks available, which also happen to make your Javascript coding a lot easier!

4. Pick your framework

There are a few great Javascript frameworks out there. The biggest players in the game are: MooTools, jQuery and script.aculo.us.

MooTools is a lightweight Javascript framework which can be used to utilize simple effects on the elements on your page. It doesn’t have a lot of fancy features, but it does the job. Good choice for beginners.

jQuery might be the most popular one out there. Not without a reason! It’s easy to apply, it has great docs, maybe even easier to learn and does a wonderful job. Does require some plugins for extra functionality but it’s a really nice framework. Also has a large community.

script.aculo.us is the mother ship of the Javascript frameworks. It’s big and weights a ton. It might be a bit slower and requires a bit more programming than its competitors, but it is powerful in what it does. The capabilities of script.aculo.us take a lot up in speed, but for that you get complete control. You can create excellent Rich Internet Applications with this framework.

Conclusion

In just a few step you can become a front-end web developer. This might take a while and it might take some time to get used to a language, but it will pay-off in the end.
There is a lot to be learned on the Internet and it is never too late to try out web development and make the web a little more exciting.

Sponsored by

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

Steps to becoming a front-end web developer

In this article I wish to share my view on AJAX and the possibilities it gives to web developers and designers, and why AJAX is wrong in several situations.

Case 1: Page loading

What’s up with websites and dynamically loading pages through AJAX? Isn’t it a bit strange that when you want to switch to another page, there is no real page switch?
Sure, I like it when content is loaded into the website dynamically, saving me bandwidth, time and irritation. But a whole page? Isn’t that kind of missing the point?

• First of all: What about the back and forward buttons of your browser? No use for them if you load a whole page in AJAX.
• Second: Funny when a user tries to copy the URL and send it to a friend. Oops, the page is loaded without the content the user expected.
• Third: Search Engines can’t pick it up since it is not really a new page.

A better way to load content through AJAX is to load only small parts of information on the page. If the users wishes to visit another page, let the browser go to another page.
Loading content in a small part of the page isn’t a bad thing. If you have a container with tabbed content, it’s easy to load the content of other tabs with AJAX, not a problem.

Loading a whole page in AJAX is just overusing the functionality and really missing the point of web browsing.

Case 2: The content manager

Being able to adjust the information of your web profile on a web page with the use of AJAX is cool. Fast feedback, fast loading times and convenient. But is it really secure?
I’ve seen sites where the HTTP calls to the server contained the key and value of the part they wanted to configure. Which means the record which will be adjusted is defined. This means you could also change information of other rows in the database. Why? You need to wonder what parts of the profile can be adjusted, and if it applies only to the user who is trying to configure their information, why do you need a key to tell the server which record to adjust?
In PHP, for example, it only takes little effort to remember a value in a session. With this, you know which user is using the website and if you open the session in the AJAX server side pages, you can still read that session. Makes it easy to tell which record to update and doesn’t give a user the opportunity to mess around in your system.

If you do want to send along a key + value, which could be needed in some situations (like inserting a comment), be sure to check the given values in the server side scripts. Can’t say this enough to people, but please be sure the user that is trying to insert / update data has access to that data. This also applies to normal usage of forms, but adjusting an AJAX request is harder for most users. Still it is possible! So be on your guard.

Case 3: One click update

This one is something I love about AJAX. The vote buttons on sites, the follow button on Twitter, delete entry buttons and many more of those. The convenience of just clicking once without having to refresh the page is awesome. It’s so simple, yet so powerful.
If you are using such a thing, keep case 2 in mind.

Case 4: Content loading

One of the most important things of dynamic loading: it has to be quick. Sending a request to a server doesn’t always have to take up most of the time, but loading the response can be a real pain.
Keep the response clean and small. I’ve seen examples (I’ve been guilty in the past) of people giving HTML back in the response. With this they’ll adjust the innerHTML of a container. In the worst case they’ll load a whole new page (like in case 1).

To solve this, please use JSON or anything of that kind. JSON helps you convert server side variables to Javascript variables. The response the server will give are Javascript variables for Javascript to read. JSON has been implemented in PHP since version 5.2.0 and is easy to use.

Don’t give HTML back to your web page, but arrays of information. This helps keeping the presentation of your site and the calculation apart from each other. Do the adjusting of the DOM in Javascript.

Case 5: External Services

When you use external services and feeds to build a web page in server side scripting, you rely on an external service. This can also result is pages loading slower than needed. The is why AJAX is ideal for loading external services.

Load information from an external source after loading the page. This will prevent slow loading of the rest of the page and let’s the information just easily slip in the page when it’s ready.

Conclusion

I hope I’ve given my point of view on AJAX and how to use it. If you wish to discuss the things that I’ve said; please do so!

Share your AJAX stories with me =)

Sponsored by

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

Dos and don’ts of AJAX

This post will show you how easy it is to read XML in PHP.

In this tutorial I’ll teach you how to read information which a simple webservice provides. The webservice I choose is Last.fm. It’s quick, fun and has a lot of features. We’ll use the Recent Tracks information of a user profile.

According to the API of Last.fm the XML which will be returned will look something like this:

<?xml version="1.0" encoding="utf-8"?>
<lfm status="ok">
	<recenttracks user="xgayax">

		<track nowplaying="true">
			<artist mbid="1bc41dff-5397-4c53-bb50-469d2c277197">The Dillinger Escape Plan</artist>
			<name>Party Smasher</name>
			<streamable>1</streamable>
			<mbid></mbid>
			<album mbid="">Ire Works</album>
			<url>http://www.last.fm/music/The+Dillinger+Escape+Plan/_/Party+Smasher</url>
			<image size="small">http://userserve-ak.last.fm/serve/34s/19117171.jpg</image>
			<image size="medium">http://userserve-ak.last.fm/serve/64s/19117171.jpg</image>
			<image size="large">http://userserve-ak.last.fm/serve/126/19117171.jpg</image>
			<date uts="1230497786">28 Dec 2008, 20:56</date>
		</track>

		...

	</recenttracks>
</lfm>

This is a part of the actual XML Last.fm gave me. We can see that is not too complicated, which is a good thing!

So what do we need to do now? First, we need that XML file in PHP. We can accomplish that by using the simplexml_load_file function in PHP (Introduced with PHP5).

It only needs the URI to the XML file and it will convert the string into an XML object. Pretty neat.

Create a new PHP file and place this code somewhere:

$completeurl =
"http://ws.audioscrobbler.com/2.0/?method=&user=xgayax" .
"&api_key=b25b959554ed76058ac220b7b2e0a026";
$xml = simplexml_load_file($completeurl);

This will load the given file into an object. The url can be adjusted to your needs, preferably the API key since I borrowed it from the Last.fm site.

All what’s left for us to do is to loop through the given object.

Take a look at the following code:

$tracks = $xml->recenttracks->track;

for ($i = 0; $i < 3; $i++) {
	$nowplaying = $tracks[$i]->attributes()->nowplaying;
	$trackname = $tracks[$i]->name;
	$artist = $tracks[$i]->artist;
	$url = $tracks[$i]->url;
	$date = $tracks[$i]->date;
	$img = $tracks[$i]->children();
	$img = $img->image[0];

	echo "<a href='" . $url . "' target='TOP'>";

	if ($nowplaying == "true") {
		echo "Now playing: ";
	}

	echo "<img src='" . $img . "' alt='album' />
	$artist . " - " . $trackname . " @ " . $date . "
	</a>
	";
}

To understand what is happening, I’ll explain some of the actions I did to get the right information.

Going through the XML tree is easy. $xml will refer to the root element, which is <lfm> in this case. From this element we can navigate through the XML tree.
If you want: <lfm><recenttracks><track> you’ll get $xml->recenttracks->track in PHP. And because recenttracks contains multiple tracks an array will be given.

The size of the loop is limited to 3, you can however replace this with sizeof($tracks) is you please.

Just like explained above, getting the information inside a tag is done like this: $tracks[$i]->tagname. You’ll get the text which is inside (if it contains text, or else you’ll get an object or an empty string.)

To read attribute information, you need to use the attributes() method. Like I did in this line: $tracks[$i]->attributes()->nowplaying. If the attribute doesn’t exist you’ll get an empty string.

I hope this gets you into reading XML’s using PHP. It is easy and takes little time to learn.
I’ve used XML reading for serveral purposes now like synchronizing information with a database and displaying upcoming event information.

The power of XML is now in your hands.

Sponsored by

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

Reading XML with PHP