Advertise here via BSA

Like webfonts, responsive design wasn’t something you heard much about until CSS3 specs started making it into popular browsers. Now, it’s the cool thing to do, and for good reason — it means one site to maintain for all devices. But it’s also a really challenging approach to web design. In this article, we look at 10 tools that’ll help you handle the challenge.

320 and up

Most responsive designs are built with full desktop size in mind and scaled down from there. Andy and Keith Clark, the developers behind 320 and up, believe the opposite approach works best: design for the small screen, and implement the layout working upwards in size. 320 and up contains Media Query increments for five viewport sizes, a vertical grid, preset styles for typography and components from HTML5 Boilerplate.

inuit.css

inuit.css is a HTML5 framework that uses a grid system that scales down to small screens ‘out of the box’. It’s a minimalist approach, giving you just what you need to get started without unnecessary styles, but it’s extensible and there are a range of handy plugins available for it — such as one that creates breadcrumb trails out of ordered lists.

Skeleton

Skeleton is a light collection of CSS and JavaScript files that make designing responsive sites based on the 960px grid easy. Skeleton includes some basic styling and typography presets to get you out of the gate quickly. This project is the brainchild of Dave Gamache, formerly of esteemed UX firm ZURB and now on Twitter’s design team.

Less Framework

Less Framework is a CSS starter with four layouts — default at 992px, and tablet, mobile and wide mobile sizes — based on a grid system and including a selection of typography presets. Because Less Framework is one of the most popular options, there’s a range of supporting tools such as a Rails gem, OmniGraffle stencil and Compass plugin built around Less.

BluCSS

BluCSS is a CSS framework that, as usual, uses a flexible grid to facilitate responsive design. One feature that stands out is its responsive images, something many of these frameworks leave out; apply a class to your images and they’ll scale with your design. No need to include multiple files at multiple sizes, though be wary of unnecessary load on mobile devices with this approach.

Mobile Boilerplate

From the developers behind the famous HTML5 Boilerplate comes Mobile Boilerplate, a responsive template that puts the focus on mobile devices, namely those running Android, iOS, Blackberry and Symbian software. Everything from viewport scaling to HTML5 offline caching to home screen icons are ready to go.

Tiny Fluid Grid

If you find all these CSS frameworks to be too much for your needs, Tiny Fluid Grid may be the alternative you’re looking for. Simply tell it how many columns your grid will need, how big you want your gutters and how wide the site will be, and this site will spit out a responsive fluid grid you can use right away.

Golden Grid System

The Golden Grid System is a 16 column grid that uses a folding method inspired by the DIN paper system to collapse down to 8 columns on tablet-size screens and 4 columns on mobile screens, making it work for designs that range from 240 to 2560 pixels wide. The GGS developers say their folding method is superior to others because the gutters are better at staying in proportion with the content, producing less of a squeezed (or sparse, depending on direction) look.

1140 CSS Grid

The 1140 CSS Grid takes the opposite approach of the 320 and up system. This is primarily aimed at people who really want to design for a wider 1280 pixel screen, and are sick of catering to a 1024 pixel baseline. 1140 CSS Grid allows them to do that while fluidly re-arranging to fit on smaller screens all the way down to mobile.

Respond.js

Even before you start working on a responsive design, you may be worried about visitors using browsers that don’t support media queries, the CSS3 feature that responsive sites depend on. With Respond.js, this problem is easily solved; the script makes min-width and max-width work in Internet Explorer 6, 7 and 8, and should work with other browsers lacking support.

Bonus: ZURB Foundation

ZURB’s Foundation is a newer entry among responsive design frameworks, and is one of the most promising, having already won over many users of other frameworks. Billed as an easy-to-use yet powerful framework for building both prototypes and production deployments that work across all kinds of devices, Foundation makes use of a flexible grid, a library of styles and elements for rapid prototyping, and professes to take the pain out of creating layouts for different formats with the same markup.

Advertise here via BSA

The very promising jQuery Mobile project is now in its first Alpha release! What better time to give it a spin with our (err… my) favorite web framework?!

You should read jQuery Mobile’s official introduction section to familiarize yourself with its principles, but in a few words: you include it on the page, format your markup to conform to its requirements and reap the benefits. Yay, let’s write a (very contrived) CRUD application with Rails 3 and jQuery Mobile!

Setup

Our application will allow us to create, read, update and delete blog posts (remember when I said it was contrived? Uhm..yah) from mobile devices. If you don’t have Rails 3 installed yet, you can get it via RubyGems:

gem install rails

Use the rails command line tool to generate a new application. We’ll call it jqmoblog.

rails new jqmoblog
# ... a bunch of files are created
cd jqmoblog

As of Rails 3.0.1 you cannot specify jQuery as the JavaScript tool of choice when you generate a Rails application, but we can easily swap it in by using the handy, dandy jquery-rails gem. Edit the Gemfile in the project’s root directory and add a dependency on the gem. Once finished your Gemfile will look something like this:

source 'http://rubygems.org'

gem 'rails', '3.0.1'
gem 'sqlite3-ruby', :require => 'sqlite3'
gem 'jquery-rails'

Install the required gems using the bundle command line tool:

bundle install

Now we’ll use the Rails generator added by the jquery-rails gem to get all the jQuery files we need:

rails generate jquery:install

When prompted, allow it to overwrite rails.js.

We’re almost ready. The application skeleton is in place and jQuery has replaced the Rails default JavaScript libraries, but we’re missing the basic model, controller, and views for our application.

Thankfully, Rails has a generator which will create these files for us and its called the scaffold generator. We’ll keep the blog posts in our app super-simple since we’re really just using them to learn about jQuery Mobile. Each post will have a title and a body. Generate the scaffold for a Post resource like this:

rails generate scaffold Post title:string body:text

This command will provide a list of files and directories it created. There should be a model (app/models/post.rb), a controller (app/controller/posts_controller.rb), and a directory of views (app/views/posts) for our Post resource.

Run the database migration that was created from the scaffold command so our database has a posts table with the required columns for storing our posts:

rake db:migrate

At this point you can fire up a Rails server and the app will load up in your browser:

rails server

Point your browser to http://localhost:3000 and you should see this:

Hmm, before we get to mobilizing this application, let’s make the root url load the list of our posts instead of the default Rails index file:

rm public/index.html

Edit the config/routes.rb and set the root route like so:

Jqmoblog::Application.routes.draw do
  resources :posts
  root :to => "posts#index"
end

Now load up http://localhost:3000 again and you should see the empty list of posts.

We still need to get the jQuery Mobile files on the page. Lets use the ones hosted on jquery.com. Add them to the application’s layout file so they’ll be on every page that gets served. In app/views/layouts/application.html.erb, edit the head section to look like this:

<head>
  <title>Jqmoblog</title>
  <link rel="stylesheet" href="http://code.jquery.com/mobile/1.0a1/jquery.mobile-1.0a1.min.css" />
  <%= javascript_include_tag :defaults %>
  <script src="http://code.jquery.com/mobile/1.0a1/jquery.mobile-1.0a1.min.js"></script>
  <%= csrf_meta_tag %>
</head>

Okay, everything is in place. Now we’re ready to turn this into a mobile app!

Getting Started

Before we flesh out our mobile CRUD actions, let’s get the posts index looking decent in mobile browsers. jQuery Mobile relies directly on the page’s markup to work its magic, so to invoke it we just need to change our views to conform to its conventions.

Each “page” in a jQuery Mobile application needs to be wrapped in a div with a data-role attribute of page. I put “page” in quotes because there can actually be many of them on a single webpage loaded from the server. In our app we’ll be loading each “page” from Rails, so we should just add this to our layout file which will wrap each of our individual views:

Before

<body>
  <%= yield %>
</body>

After

<body>
  <div data-role="page">
    <%= yield %>
  </div>
</body>

Next edit the post’s index (index.html.erb) and change the markup to create a header and a content section which lists all the posts in the database.

Before

<h1>Listing posts</h1>

<table>
  <tr>
    <th>Title</th>
    <th>Body</th>
    <th></th>
    <th></th>
    <th></th>
  </tr>

<% @posts.each do |post| %>
  <tr>
    <td><%= post.title %></td>
    <td><%= post.body %></td>
    <td><%= link_to 'Show', post %></td>
    <td><%= link_to 'Edit', edit_post_path(post) %></td>
    <td><%= link_to 'Destroy', post, :confirm => 'Are you sure?', :method => :delete %></td>
  </tr>
<% end %>
</table>

<br />

<%= link_to 'New Post', new_post_path %>

After

<div data-role="header">
  <h1>Listing posts</h1>
</div>

<div data-role="content">
  <ul data-role="listview">
    <% @posts.each do |post| %>
    <li>
      <%= link_to post.title, post %>
      <%= link_to 'edit post', edit_post_path(post), "data-icon" => "gear" %>
    </li>
    <% end %>
  </ul>
</div>

Load up the page and it should look like this:

Two things to note here. First, we are once again using the data-role attribute to create the header and the styled list. This is a major theme of jQuery Mobile (as of the Alpha, I’m told they *might* be switching to class names instead of data- attributes). Second, each list item has two links, and jQuery Mobile automatically knows that this means we want to use a split button list. Pretty cool, huh?

Let’s add a button which will take us to a page where we can create new posts. Add this line to the end of the header div:

<%= link_to 'Add', new_post_path, "data-icon" => "plus", "class" => "ui-btn-right" %>

Again, jQuery Mobile “just knows” that this should be a button in our header and we pass it a class and a data-icon attribute to tell it where to place it and which icon to use. We now have a button in the header which links to the new post path!

Create

We’re gonna need to create posts so we can read, update and delete them, so lets handle creation first. The “Add” button on the posts index links to the new.html.erb view. It works as is and looks okay too. We’ll just tweak the markup to make it fit into the jQuery Mobile styles:

<div data-role="header">
  <h1>New Post</h1>
</div>

<div data-role="content">
  <%= render 'form' %>
</div>

We can now add new posts using the mobile interface! Go ahead and create a few so the posts index shows a list with links to edit each post:

Read

People will read posts from their show.html.erb view. Again, no change to the underlying controller or model code needs to happen. Just update the view file to look like this:

<div data-role="header">
  <h1><%= @post.title %></h1>
  <%= link_to 'Home', posts_url, "class" => "ui-btn-right" %>
</div>

<div data-role="content">
  <%= @post.body %>
</div>

Update

When we set up the posts index we added links to the edit.html.erb view using the gear icon on the right side of the split list. Now we just need to change the markup on that view to conform to jQuery Mobile’s requirements. Have you sniffed out a pattern to this development process yet?

<div data-role="header">
  <h1>Editing Post</h1>
</div>

<div data-role="content">
  <%= render 'form' %>
</div>

Again, it just works as expected and it will look great on many mobile devices. On to the final action, delete!

Delete

To facilitate deleting a post we just have to modify the delete links created by Rails’ scaffold generator to fit the rest of the mobile site. I think the edit page is a good place to add a delete link, so lets add a button to the header of edit.html.erb:

<%= link_to 'Delete', @post, :method => :delete, "data-icon" => "delete", "class" => "ui-btn-right" %>

The edit view is now complete, and it lets us update and delete our post.

Closing Up

If you’ve made it this far, you’ve probably realized that working with jQuery Mobile is pretty painless and it fits in with Rails quite well. There are a bunch of other things that jQuery Mobile can do, but this should hopefully whet your appetite. Remember, the framework is still in the Alpha stage so things can and probably will change.

I encourage you to read more about the project and get involved at an early stage so we can all benefit from a strong community!

***Download the source code for the application built in this post***

Advertise here via BSA

The trend toward rich client-side web applications has brought with it a need for robust JavaScript development tools. Firebug lead the way in this arena, but WebKit’s Web Inspector has caught up in a big way and ships with all recent versions of Safari and Chrome.

One powerful tool inside Web Inspector that is likely under utilized is the Profiles pane. I write a lot of client-side JavaScript and it still took me a long time to work up the gusto to dig into this tool and get anything out of it. If you find yourself in the position I was in, hopefully this post will give you what you need to get up and running quickly.

Basics

The JavaScript profiler is used to find and alleviate CPU bottlenecks in your code. To use it you invoke one or more “profile” runs in which Web Inspector tracks all JavaScript executed on the page and the time taken to execute it. In the picture below you will see a single profile called “Profile 1” being displayed.

There are two ways to run a profile:

1) Manually

The pane itself has a little button in the lower left-hand corner which can be used to start and stop a profile. This is the least precise of the two methods, but is sometimes good enough for one-off profiles. Click it once, go perform whatever action on the page that invokes the code you want profiled, and then click it again to stop.

2) Programmatically

The way I suggest you invoke profile runs is by calling into the console directly from your code. This will allow you to precisely position the start and stop of the profile for maximum signal to noise ratio. Here is how you might profile a totally contrived for loop programmatically:

console.profile('for loop');
for (var i = 0; i < 100; i++) {
  console.log('i is: ', i);
}
console.profileEnd('for loop');

After that bit of code is executed a new profile titled “for loop” will appear in the Profiles pane to be reviewed. The string argument to these functions is optional. If you don’t provide one it will simply increment “Profile [x]” like it does when run manually.

The Lingo

Now we know what the Profiles pane looks like and how to make it run, but its of no use unless we can derive meaning from the results. We can’t do that without understanding the terms used, so here are explanations as I understand them:

Self — the amount of time spent directly in the corresponding function

Total — the amount of time spent in the corresponding function and all functions called by it

Calls — how many times the corresponding function was called

Average — the value of the corresponding function’s Self divided by its Calls

Of these, Self and Total are the most confusing. The key thing to know is that the profiler tracks not only the time spent in each individual function, but also the time spent in functions called by that function. This is very useful when “drilling down” on a stack of function calls because you can look to see if the Total is bigger than the Self and if it is you know the time-consuming function is nested beneath the current one.

Everything’s Relative (or Absolute)

By default the Profiles pane displays all information in relative times so that each function is assigned a percentage of the total time of the profile. This is helpful in some scenarios, but I find the absolute times (measured in milliseconds and seconds) much more useful most of the time. To switch the profile result to absolute times, just click the little % sign at the bottom of the pane.

Top to Bottom. Bottom to Top

You can also sort the profile results using two different approaches. The default is the “Heavy” view or bottom up approach, which will more quickly float up the offending functions to the top of the heap. This is helpful to quickly identify trouble areas, but sometimes confusing because it doesn’t follow the logical structure of your code. For that, switch to the “Tree” view or top down approach. It looks like this instead:

Focus

One more feature of the Profiles pane is the ability to remove sections of the results and focus solely on the interesting bits. Do this by highlighting the interesting function and clicking the little eye icon in the lower lefthand corner. Other results will disappear and time percentages will be recalculated in the scope of the focused function.

Conclusion

I hope the above information explains what Web Inspector’s Profiles pane is, how to invoke it, what the results mean, and how to better organize them to increase their value. Give this power tool a try the next time you have some CPU intensive JavaScript that needs optimizing!

Advertise here via BSA

Earlier this summer, we kicked off a series on MongoDB where the goal was to write a simple todo application using native MongoDB drivers and three of our favorite scripting languages.

• Part One: the Plot
• Part Two: Ruby ToDo

This article is part 3 in that series, in which we write said application in PHP.

The Interface

In case you missed it you can look back at the introductory article for the complete details, but real quick I’ll review interface here:

• todo – list all incomplete tasks sorted by priority then chronologically
• todo next – list all incomplete tasks that are high priority
• todo done – list all complete tasks chronologically
• todo high “pay bills” – add high priority task called “pay bills”
• todo low “get milk” – add low priority task called “get milk”
• todo finish “pay bills” – complete task called “pay bills”
• todo dont “get milk” – delete task called “get milk”
• todo help – list all commands and their usage

Looks simple enough, let’s dive in!

The Driver

10gen distributes the PHP extension as a PECL package, or you can install from source. For more details, refer to the PHP.net Guide

We will go ahead and just use PECL, which is as easy as running one command.

pecl install mongo

You will also need to edit your php.ini file to add the following line, and probably reload your server.

extension=mongo.so

Go ahead and start a file called ToDo.php and stub out the first few lines. Since this is a command line application, it’s a bit different from a standard PHP script. We need to add a shebang and we’ll go ahead and change our error reporting levels to keep things quiet. Changing your error reporting is optional, if you aren’t sure of your coding skills, just leave the error reporting at full blast, you can turn it down when we finish the app.

#!/usr/bin/env php
< ?php

error_reporting( E_ERROR | E_PARSE );

The ToDo Class

PHP5 has great support for object-oriented programming, so we will employ a single object of a class we’ll write called ToDo. The class will take in the required command-line arguments, connect to the MongoDB collection that stores our todos, and execute the appropriate commands on them.

To facilitate these needs, our object will need to take some arguments from the user and store a reference to the MongoDB collection when it is instantiated:

  class ToDo {

    protected $argv = array();
    protected $mongo_connection = null;
    protected $mongo_db = null;

    public function __construct ( $argv ) {
      $this->argv = $argv;
      try {
        $this->mongo_connection = $mongo = new Mongo();
        $this->mongo_db = $this->mongo_connection->todo;
      }
      catch ( Exception $e ) {
        throw new Exception ( "Oops! Error connecting to MongoDB: " . $e->getMessage() );
     }
   }

The __construct function is the PHP5 way of adding a constructor to a class. This is called when you instantiate an object, like this for instance:

$my_todo = new ToDo( $argv );

When a new ToDo object is instantiated, our class will store the arguments passed in to it in an protected member called $argv and set up a connection to MongoDB in a member called $mongo_connection. Mongo is a class provided by the Mongo extension we installed earlier.

For convenience we will set up an instance of MongoDB in the member called $mongo_db. We do this since we will only be using one database.

Our ToDo class expects some arguments passed in to the constructor, so we need to provide them when we instantiate it. These arguments will be read in from the command-line when the program is executed, and PHP exposes these to our program via the $argv global variable.

However, $argv only exists in certain execution contexts of PHP, so we need to make sure we are executing from the command line. To ascertain this, we look at the constant PHP_SAPI, then we instantiate a ToDo object with the $argv array.

  if( 'cli' == PHP_SAPI ) {
    try {
      $app = new ToDo( $argv );
    }
    catch( Exception $e ) {
      print $e->getMessage() . "\n";
    }
  }

At this point, the ToDo.php should look like this:

#!/usr/bin/env php
<?php
   error_reporting( E_ERROR | E_PARSE );
   class ToDo {
     protected $argv = array();
     protected $mongo_connection = null;
     protected $mongo_db = null;
     public function __construct ( $argv ) {
       $this->argv = $argv;
      try {
        $this->mongo_connection = $mongo = new Mongo();
        $this->mongo_db = $this->mongo_connection->todo;
      }
      catch ( Exception $e ) {
        throw new Exception ( "Oops! Error connecting to MongoDB: " . $e->getMessage() );
      }
    }
  }

  if( 'cli' == PHP_SAPI ) {
    try {
      $app = new ToDo( $argv );
    }
    catch( Exception $e ) {
      print $e->getMessage() . "\n";
    }
  }

You can execute this program from the command-line, but nothing visible will happen. We still need to implement the bulk of the program, which parses the user’s command-line arguments and acts appropriately.

A Little Help

The first thing we’ll implement is also the simplest, a method that prints usage help for the program. It looks like this:

protected function help ( $error = null ) {
  if( ! is_null( $error ) ) {
    print "$error\n";
    print "\n";
  }

  $out = < <<EOF usage: {$this->argv[0]} <method>

== Methods ==

<none>             list all incomplete tasks sorted by priority then chronologically
help               show this help
next               list all incomplete tasks that are high priority
done               list all complete tasks chronologically
high <argument>    add high priority task called </argument><argument>
low </argument><argument>     add low priority task called </argument><argument>
finish </argument><argument>  complete task called </argument><argument>
dont </argument><argument>    delete unfinished task called </argument><argument>

EOF;
  print $out;
}

Run, Baby, Run

Now our application needs to be able to actually do it’s job, so lets create a method called run which will handle the program’s flow. In this method we examine the commands the user has given and call our other methods to get that work done. The default action is to list all incomplete tasks, and the catch-all is to execute the help method we implemented above. Here is what run looks like:

public function run () {
	try {
		if ( 1 >= count( $this->argv ) ) {
			$this->show(
				array( "complete" => false ),
				array( "level" => 1, "added" => 1 )
			);
		}
		else {
			$argument = strtolower( $this->argv[1] );
			if ( "help" == $argument )
				$this->help();
			else if ( "next" == $argument )
				$this->show(
					array( "level" => "high", "complete" => false ),
					array( "level" => 1, "added" => 1 )
				);
			else if ( "done" == $argument )
				$this->show(
					array( "complete" => array( '$ne' => false ) ),
					array( 'completed' => 1 )
				);
			else if ( "high" == $argument )
				$this->add( "high", $this->argv[2] );
			else if ( "low" == $argument )
				$this->add( "low", $this->argv[2] );
			else if ( "finish" == $argument )
				$this->complete( true, $this->argv[2] );
			else if ( "dont" == $argument )
				$this->complete( false, $this->argv[2] );
			else
				throw new Exception( "Bad Method" );
		}
	}
	catch ( Exception $e ) {
		$this->help( $e->getMessage() );
	}
}

$this->argv is an Array we were given when the ToDo constructor was run. It should hold all of the options and arguments that the user provided when they ran the application from the command line. If there is only one or fewer arguments we use a default action. Otherwise we move into the switch statement and choose a method there.

One item worth noting is that we assume that $this->argv[0] is the name of the program itself, which is how PHP (and most other languages) handle command line arguments.

Using Mongo

So far we’ve only dealt with setting up our class and parsing user arguments, we’ve hardly event glanced at MongoDB! Time to change that! I’ll work through each of the methods referenced in run

First, the show method:

protected function show ( $params = null, $sort = null ) {
  $cursor = $this->mongo_db->todos->find( $params );
  if( ! is_null( $sort ) )
    $cursor->sort( $sort );
  foreach ( $cursor as $row )
    print $row['task'] . "\n";
}

This method takes an array of selection parameters and an array of sort options (both optional) and passes them directly to the MongoDB cursor. The cursor will then let us extract the matching documents one at a time, sorted and returned as arrays. This style of interface is pretty easy to work with, it’s one of the great benefits of using a document store like MongoDB.

Now let’s find a way to store those item’s in MongoDB in the first place. This requires us to implement the add method.

protected function add ( $level, $item ) {
  if ( 2 >= count( $this->argv ) )
    throw new Exception( "missing argument" );
  $this->mongo_db->todos->insert( array(
    "task" => $item,
    "level" => $level,
    "complete" => false,
    "added" => time()
   ) );
}

Our add method takes two arguments. $level is the importance of the item, either “high” or “low”. $item is the text of the item itself. Once you have these two facts you can quickly pass them on to MongoDB’s insert method.

The insert method in MongoDB takes an associative array and persists it to the datastore as a document. You can store just about anything you like this way, as long as it can be serialized.

The final method we need is a bit more versatile, the complete method. This method can either finish a task or remove it from the system.

protected function complete ( $finish, $item ) {
  if ( 2 >= count( $this->argv ) )
    throw new Exception( "missing argument" );
  $document = $this->mongo_db->todos->findOne( array( "complete" => false, "task" => $item ) );
  if ( is_null( $document ) )
    print "No Matching ToDo Found\n";
  else {
    if ( $finish ) {
      $document['complete'] = time();
      $this->mongo_db->todos->save( $document );
    }
    else {
      $this->mongo_db->todos->remove( $document );
    }
  }
}

This method uses a variant of find (which we used in show) called findOne. Think of this as the MongoDB version of LIMIT 0,1. After we’ve tried to find a task matching the requested title, we then either abort (if not found) or complete (if found).

When completing we will use one of two MongoDB methods, depending on whether we are finishing or skipping the task. The save method will be used to finish a task. This method takes a MongoDB document that was previously retrieved and saves it back into the database. Any changes you make to the object (like setting the completed time, for instance) is persisted to the database. This is done through a unique (but not necessarily sequential) ID given to each document in the datastore.

To delete a task from our list we need to use remove. This method takes an existing document object (with a document id) and deletes it from the database.

Finishing Up

So there you have it, we’ve completed all of our methods. Now all we have to do is call run and we should have a working todo program!

if( 'cli' == PHP_SAPI ) {
  try {
    $app = new ToDo( $argv );
    $app->run();
  }
  catch( Exception $e ) {
    print $e->getMessage() . "\n";
  }
}

You can view/download the program in its entirety here. One thing to note is how little datastore code is needed to add CRUD to an application when using MongoDB as a datastore.

Hopefully this article has helped you with PHP or MongoDB, or both. Stay tuned for our next article in the series when we write the exact same application in Python!

Advertise here via BSA

Probably one of the first topics covered when you get started learning about jQuery events is the concept of canceling the browser’s default behavior. For instance, a beginner click tutorial may include this:

$("a.toggle").click(function () {
    $("#mydiv").toggle();
    return false; // Prevent browser from visiting `#`
});

This function toggles the hiding and displaying of #mydiv, then cancels the browser’s default behavior of visiting the href of the anchor tag.

It is in these very first examples that bad habits are formed as users continue to use return false; whenever they want to cancel the default browser action. I am going to cover two very important topics in this article relating to the canceling of browser events:

• Use the right method for the job: return false vs. preventDefault, stopPropagation, and stopImmediatePropagation
• Top, bottom or somewhere in the middle: where in the event callback should you cancel default behavior?

Note: in this article when I refer to event bubbling, I am talking about how most events will fire on the original DOM element, and then on each parent element in the DOM tree. Events do not bubble to siblings or children (When events “bubble” downward, it is called event capturing). Learn more about bubbling and capturing.

Use the Right Method for the Job

The main reason return false is so widely misused is because it appears to be doing what we want. Link callbacks no longer redirect the browser, form submit callbacks no longer submit the form, etc. So why is it so bad?

What return false is really doing

First off, return false is actually doing three very separate things when you call it:

1. event.preventDefault();
2. event.stopPropagation();
3. Stops callback execution and returns immediately when called.

“Wait a minute,” you cry! I only needed to stop the default behavior! I don’t need these other two items… I think.

The only one of those three actions needed to cancel the default behavior is preventDefault(). Unless you mean to actually stop event propagation (bubbling), using return false will greatly increase the brittleness of your code. Lets see how this misuse plays out in a real world scenario:

Here is our HTML for the example:

<div class="post">
    <h2><a href="/path/to/page">My Page</a></h2>
    <div class="content">
        Teaser text...
    </div>
</div>
<div class="post">
    <h2><a href="/path/to/other_page">My Other Page</a></h2>
    <div class="content">
        Teaser text...
    </div>
</div>

Now lets say we want the actual article to load into the corresponding div.content when a user clicks on either title link:

jQuery(document).ready(function ($) {
   $("div.post h2 a").click(function () {
      var a    = $(this),
          href = a.attr('href'), // Let jQuery normalize `href`,
          content  = a.parent().next();
      content.load(href + " #content");
      return false; // "cancel" the default behavior of following the link
   });
});

All is well (currently) and our dynamic page is well under way. Down the road we decide another piece of functionality we want is to add the class "active" to any div.post that has been clicked (or when a child element has been clicked) most recently. So, we decide to add a click handler to them as well:

// Inside Document Ready:
var posts = $("div.post");
posts.click(function () {
    // Remove active from all div.post
    posts.removeClass("active");
    // Add it back to this one
    $(this).addClass("active");
});

Will this work when we click a title link? NO! The reason it won’t work is because we used return false in the link click event instead of using what we really meant! Because return false really means event.preventDefault(); event.stopPropagation(); the click event never bubbled up to the parent div.post and our new event has not been called.

This becomes even more of an issue when mixing normal events with live or delegate events:

$("a").click(function () {
    // do something
    return false;
});

$("a").live("click", function () {
    // THIS WON'T FIRE
});

So what DO you really want?

preventDefault()

In most situations where you would use return false what you really want is e.preventDefault(). Using preventDefault requires you allow for the event parameter to be accessed in your callback (In this example, I use e):

$("a").click(function (e) {
    // e == our event data
    e.preventDefault();
});

This does everything we want without prohibiting parent elements from receiving these events as well. The fewer restrictions you place on your code the more flexible it will be to maintain.

stopPropagation()

Sometimes you just want to stop the propagation. Take the following example:

<div class="post">
    Normal text and then a <a href="/path">link</a> and then more text.
</div>

Now, lets pretend we want one thing to happen when you click anywhere in the div except on the link, and you want the user to actually be able to follow the link if they click on it. (From a usability standpoint, this is a poor example. You probably don’t want something else to happen if a user slightly misses clicking on the link!)

$("div.post").click(function () {
   // Do the first thing;
});

$("div.post a").click(function (e) {
    // Don't cancel the browser's default action
    // and don't bubble this event!
    e.stopPropagation();
});

In this case if we had used return false the div’s click event would not have fired, but the user would also not have been directed to the correct destination either.

stopImmediatePropagation()

This method stops any further execution of an event, even to other handlers bound on the same object. All events bound to a particular item will fire in the order they were bound. Take the following example:

$("div a").click(function () {
   // Do something
});

$("div a").click(function (e) {
   // Do something else
   e.stopImmediatePropagation();
});

$("div a").click(function () {
   // THIS NEVER FIRES
});

$("div").click(function () {
   // THIS NEVER FIRES
});

If you think this example looks contrived, it really is. However, the situation is a very real one. As you build more abstracted code, different widgets and plugins may be adding events to the same code you are working with. This makes understanding and using stopImmediatePropagation worth while when you come across a situation that needs it!

return false

Only use return false when you want both preventDefault() and stopPropagation() and your code can support not canceling the default behavior until you reach the end of your callback execution. I strongly encourage against using this method in any examples you may write for new jQuery developers. It promotes a poor use of event cancellation and should only be used when you are consciously deciding you need what it provides..

Top, Bottom or Somewhere in the Middle

Before, when you were (mis)using return false, it always had to go at the end of your function, or at least at the end of a particular line of logic where no further execution was needed. With e.preventDefault we have more choices. It can be called at any time during a callback function to take effect. So where should you put it?

1. During development, it should (almost) always be the very first line. The last thing you want is for your form you are trying to AJAXify to actually submit to another page while you try to debug a JavaScript error in the callback.

2. In production, if you are following progressive enhancement, put it at the bottom of the callback, or at the end of execution flow. If you are progressively enhancing a normal page, then your link click event or form submit event has the proper server side fallbacks needed for browsers that don’t support JavaScript (or don’t have support enabled). The benefit here, however, is not related to browsers with JS turned off, but rather browsers with it turned on in the situation where your code throws an error! Take a look at the following code:

var data = {};
$("a").click(function (e) {
    e.preventDefault(); // cancel default behavior

    // Throws an error because `my` is undefined
    $("body").append(data.my.link); 

    // The original link doesn't work AND the "cool"
    // JavaScript has broken. The user is left with NOTHING!
});

Now, lets take a look at the same event with the preventDefault call being placed at the bottom:

var data = {};
$("a").click(function (e) {
    // Throws an error because `my` is undefined
    $("body").append(data.my.link); 

    // This line is never reached, and your website
    // falls back to using the `href` instead of this
    // "cool" broken JavaScript!

    e.preventDefault(); // cancel default behavior
});

The same applies for form submit events as well, provided you have the proper fallback information in place. Never count on your code always working. It is far better to plan for a nice fallback than assume errors will never occur!

3. In production, if the functionality is JavaScript only, keep the call on the first line. Remember, it doesn’t necessarily have to be the first line in the function, but it should come as early as fits with your program logic. The concept here is this: If this part of your functionality was added with JavaScript in the first place, then a fallback is not really as necessary. In this case, having it first will just ensure random # characters don’t appear in the URL or cause the page to jump around. Obviously, provide as much error handling as needed to ensure your users aren’t left with nothing for their efforts!

Conclusion

I hope this article presented enough information for you to make the right choice when you cancel events. Remember to only use return false when you really need it, and make sure you cancel the default behavior at the right location in your callback. Always work to make your code as flexible as possible, and stop using return false!

Advertise here via BSA

Earlier this summer, we kicked off a series on MongoDB where the goal was to write a simple todo application using native MongoDB drivers and three of our favorite scripting languages.

This article is part 2 in that series, in which we write said application in Ruby.

The Interface

You can refer back to the introductory article for all the details, but I’ll reiterate the command-line interface here for easy reference:

• todo – list all incomplete tasks sorted by priority then chronologically
• todo next – list all incomplete tasks that are high priority
• todo done – list all complete tasks chronologically
• todo high “pay bills” – add high priority task called “pay bills”
• todo low “get milk” – add low priority task called “get milk”
• todo finish “pay bills” – complete task called “pay bills”
• todo dont “get milk” – delete task called “get milk”
• todo help – list all commands and their usage

Okay, let’s write this thing!

The Driver

10gen distributes the Ruby driver using Ruby’s most popular package distribution tool, RubyGems. To install the driver on your machine simply execute:

gem install mongo

Our program will need to load in the driver before anything else, and we’ll use RubyGems to do it, so create a new text file called mongo_todo.rb and begin it with the following:

require 'rubygems'
require 'mongo'

The ToDo Class

Ruby is a purely object-oriented language, so our program will employ a single object of a class we’ll write called ToDo. The class will take in the required command-line arguments, connect to the MongoDB collection that stores our todos, and execute the appropriate command on them.

To facilitate these needs, our object will need to take some arguments from the user and store a reference to the MongoDB collection when it is instantiated:

class ToDo
  def initialize(args)
    @args  = args
    @mongo = Mongo::Connection.new.db("todo").collection("todos")
  end
end

In Ruby, the initialize instance method is called when a new object of a class is instantiated, most often using the new class method, like this:

my_todo = ToDo.new

When a new ToDo object is instantiated, our class will store the arguments passed in to it in an instance variable called @args and store a connection to MongoDB in an instance variable called @mongo. Mongo::Connection is a class provided by the mongo gem that we’re using.

Since our class expects some arguments passed in to the initializer, we need to provide them to the new method. The arguments will be read in from the command-line when the program is executed, and Ruby exposes these to our program via the ARGV variable. So, we call new like this instead:

my_todo = ToDo.new(ARGV)

At this point, the entire program should look like this:

require 'rubygems'
require 'mongo'

class Todo
  def initialize(args)
    @args  = args
    @mongo = Mongo::Connection.new.db("todo").collection("todos")
  end
end

ToDo.new(ARGV)

You can execute this program from the command-line, but nothing will happen. Well, stuff will happen but you won’t see it displayed back to you. We still need to implement the bulk of the program, which parses the user’s command-line arguments and acts appropriately.

A Little Help

The first thing we’ll implement is a method that prints usage help for the program. It looks like this:

def help
  abort <<-HELP
  usage: #{__FILE__} <method>

  == Methods ==
  <none>            list all incomplete tasks sorted by priority
  help              show this help
  next              list all incomplete tasks that are high priority
  done              list all complete tasks chronologically
  high "argument"   add high priority task called argument
  low "argument"    add low priority task called argument
  finish "argument" complete task called argument
  dont "argument"   delete unfinished task called argument
  HELP
end

In Ruby, abort is a method you can call which will exit the application and display a string you pass to it. The string we’re passing in shows all the ways the program can be used, which will be displayed back to the user. This will be executed by default if the user doesn’t pass in an argument that we want to handle. More on that in the next section.

Run, Baby, Run

At some point, our application needs to run, so lets create an instance method called run which will handle the program’s flow. In this method we will determine what the user passed in from the command-line and call another method that handles the different use cases. The default action is to list all incomplete tasks, and the catch-all is to execute the help method we implemented above. Here is what run looks like:

def run
  if @args.empty?
    show :complete => false
  else
    case @args.first
    when "help"   then help
    when "high"   then add "high"
    when "low"    then add "low"
    when "next"   then show :complete => false, :level => "high"
    when "done"   then show :complete => true
    when "dont"   then complete false
    when "finish" then complete true
    else
      help
    end
  end
end

ARGV is an Array, so we can call methods like empty? and first on it. The meat of the run method is a Ruby case statement which checks if the first argument passed in by the user matches any of our predetermined keywords and calls other methods, add, show, and complete. These methods are the ones that actually interact with MongoDB and display information back to the user. We’ll implement them next.

Using Mongo

So far we’ve only dealt with setting up our class and parsing user arguments, we’ve barely even touched MongoDB! This is the meat of the application, so let’s get straight to it. First, the show method:

def show(params)
  sort = [["level", Mongo::ASCENDING], ["added", Mongo::ASCENDING]]
  @mongo.find(params, :sort => sort).each { |todo| puts "#{todo["task"]} (#{todo["level"]})" }
end

show takes a hash of params as an argument and passes that hash on directly to the mongo library’s find method, which will return an array of the found items in the collection.

We print each of the todo items returned from find along with the level of the todo. How do those items get in there in the first, place? That is up to the add method, which we will implement next.

def add(level)
  help unless @args.length == 2
  @mongo.insert "task" => @args.last, "level" => level, "complete" => false, "added" => Time.now
  puts "added #{level} level task: #{@args.last}"
end

add takes a single argument, the level of the todo to create (e.g.- “high” or “low”). It then makes sure that the user had passed in two arguments at the command line because it needs the second one for the name of the task. If not, it calls help which aborts the application.

If so, It calls Mongo’s insert method and passes it all the information to be stored in the datastore.

Finally, we need to implement the complete method, which is the most complex of the lot. Like add, it makes sure there were two command-line arguments given. Then it tries to find the todo by the “task” name. If found, it will either “finish” the task or “remove” the task depending on a boolean argument passed in. The method looks like this:

def complete(finish)
  help unless @args.length == 2
  if (document = @mongo.find_one("task" => @args.last, "complete" => false))
    if finish
      document["complete"] = Time.now
      @mongo.save(document)
      puts "finished: #{@args.last}"
    else
      @mongo.remove(document)
      puts "removed: #{@args.last}"
    end
  else
    puts "No ToDo matching #{@args.length} found"
  end
end

The mongo-related calls in the complete method are find_one, save, and remove.

Finishing Up

So, we’ve written our run method which calls the other methods using the user’s passed in arguments. Now all we have to do to get the class going is finish the program by creating a ToDo class object and calling run on it, like this:

ToDo.new(ARGV).run

You can view/download the program in its entirety here. One thing to note is how little code is needed to add CRUD to an application when using MongoDB as a datastore.

Hopefully this article has helped you with Ruby or MongoDB or both. Stay tuned for our next article in the series when we write the exact same application in PHP!

Advertise here via BSA

Everyday there are scores of new links shared, re-tweeted, posted, and emailed by people like you and I. Because of social media platforms like Twitter and Facebook, our love for sharing information, tutorials, freebies, etc., has never been stronger!

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!

Advertise here via BSA

This tutorial assumes that you have a fairly strong understanding of HTML and CSS, as well as a basic understanding of Textpattern and its tags. (I won’t be going into detail about the css) We will be building a very simple “shop” type page in Textpattern. There are plugins which allow Textpattern to integrate paypal support, but this is a fairly simple alternative. This allows you to feature products which you may sell through paypal, e-junkie, Amazon (or whatever else you may be using) The structure of this page is built with the client in mind – they don’t need to format the page with any html or div’s in order to get the products laid out nicely.

Two example links of this simple functionality in action are:

1. http://www.meghantelpner.com/shop/?c=books

2. http://www.elmwoodspa.com/shop/

In the first example, you can click on one of Meghan’s books to see more information before deciding to purchase. If you click on “buy now”, you will be taken to her e-junkie store. Additionally, if you click on a specific book to see more information, you get a small navigation block at the top of the article that allows you to quickly browse the next and previous products. You may notice that if you click on one of the other submenus within her store, such as the Books/DVDs/Audio, that you will be taken directly to the Amazon affiliate link for that product. The client has the capacity to choose whether or not to link the product to an external link (Amazon, e-junkie, paypal) or whether or not to link to the full product page itself first, with a “buy now” button.

In the second example, you can click to see details/shop online which takes you immediately to Elmwood Spa’s online store.

I will be using the first example as a basis for the tutorial.

Plugins used: cbs_category_list, zem_nth (both optional) and upm_image

First you’ll want to set up some custom fields, depending on how you want your shop to function. For Meghan’s shop, there are instances where she links to external products via a buy now button. Other times, she’ll want to link to an external site without the buy now button. So I have created 2 custom fields, “link to this site” and “buynow.” If you link exclusively to Paypal links, you could name it paypal, or whatever is easy for you to remember. (As long as you adjust it accordingly in the article forms)

Now let’s take a look at one of the product pages inside textpattern:

1. The title that will appear on the shop landing page

2. The description that will appear only one the item is clicked on

3. This is the link that the thumbnail and title will link to if you put a link (full url) here, otherwise:

4. A buy now button will appear and will link to the full url pasted here (if a link is not placed in either field, the title and thumbnail will merely link to the full article page automatically)

5. Place the image id number here that you want to associate with the article (the thumbnail version of this image will appear on the shop landing page, while the full image size will show on the individual article page.)

6. Choose the appropriate section for your article, in this instance, “shop.”

7. Select the appropriate categoryfor the article (if applicable. You may not have a need for categories)

8. IF USING THE BUY NOW FIELD you must use the override form named shop_listing2 (I’ll explain below)

SAVE your article!

shop subnav

In the actual page template for the shop, the code that calls the shop submenu (books and guides, etc) looks like this:

<txp:cbs_category_list parent="shop" wraptag="ul" break="li" class="subnav" section="shop" showcount="false" class="subnav" activeclass="active"/>

Using the plugin cbs_category_list, this pulls a list of all of the categories with a parent category of “shop”, wraps each category in a list tag, wraps the whole thing in an unordered list with a class of subnav, and assigns a class of active on list items when they are active. Handy dandy! You don’t necessarily need to use this plugin if your shop does not need this type of subnav.

Ok, so how do we pull all of our shop items into the page? The article tag in our shop page template looks like this:

<txp:article listform="shop_listing" form="shop" limit="99" sort="posted asc"/>

So this tag basically says: on the landing page (or listform version of the page), display the articles using the form of “shop_listing”. If you’re looking at an individual article page, (i.e. an individual product page) display the article using the form “shop”. Limit the amount of articles shown to 99, and sort them by date of Posted Ascending.

The “shop_listing” form looks like this:

<div class="shop-item">  <a href="<txp:permlink  />"><txp:upm_article_image type="thumbnail"  class="shopimg"/></a>  <h3><txp:permlink><txp:title  /></txp:permlink></h3>  <span><a href="<txp:custom_field  name="buynow" />">BUY NOW</a></span>  </div>

Translation: the thumbnail version of the article’s image is being pulled from the “Article image” field in the article, and assigned the class of “shopimg” for styling purposes. Both the title and thumbnail are linked to the permanent link to the article (which will show the body/description of the product. The Buy Now button links to whatever gets put into the custom field named “buynow.” The shop-item css looks something like: .shop-item {float:left; margin:20px 25px 10px 0; width:175px; }

Alternately, if you want to get really nerdy, you could use the plugin zem_nth to tell every third (or whatever number) post to display with different class. I use it to apply “shop-item-last” (which has a margin-right of zero) to every third item , so the last item in every row doesn’t have any extra margin space on the right. You can choose to do your layouts with or without zem_nth. This is what my shop_listing article form really looks like:

<txp:zem_nth step="1" of="3"><div class="shop-item"></txp:zem_nth><txp:zem_nth step="2" of="3" ><div class="shop-item"></txp:zem_nth><txp:zem_nth step="3" of="3" ><div class="shop-item-last"></txp:zem_nth><a href="<txp:permlink />"><txp:upm_article_image type="thumbnail" class="shopimg"/></a><h3><txp:permlink><txp:title /></txp:permlink></h3><span class="register"><a href="<txp:custom_field name="buynow" />">BUY NOW</a></span></div><txp:zem_nth step="3" of="3" ><hr class="space" /></txp:zem_nth>

The “shop_listing2″ form (for products without a buy now button, linking externally) looks like this:

<div class="shop-item">
 <a href="<txp:custom_field name="link to this site" />"  rel="external"><txp:upm_article_image type="thumbnail"  class="shopimg"/></a>
 <h3><a href="<txp:custom_field name="link to this site"  />"><txp:title /></a></h3>
 </div>

This tells the title and thumbnail on the listing page to link directly (in a new window/tab) to the link that is found in the “link to this site” field shown in the image above, #3. You could also include the <txp:excerpt /> tag if you wanted to include an excerpt. If you want the article to appear this way (without the buy now button), you need to ensure that you are using the override_form in the article named “shop_listing2″.

Now that we have set up what the listing page looks like for product pages, let’s look at how the individual product pages look. If you will recall the article form we used:

<txp:article listform="shop_listing" form="shop" limit="99"  sort="posted asc"/>

We need to create a form called “shop” that will determine how the individual pages look once you click on the thumbnail/title.

The “shop” article form looks like this:

<p><a href="/shop">Back to Shop</a> |  <txp:link_to_prev>Previous Product</txp:link_to_prev> |  <txp:link_to_next>Next Product</txp:link_to_next></p>
 <div class="right"><txp:upm_article_image/><br /><span  class="register" ><a href='<txp:custom_field  name="buynow"/>' >BUY NOW</a></span></div><txp:body />

Translation: The tags inside the paragraphs set up a small subnav which allows the user to click through to the next/previous products. Then it puts the full version of the article image in a div labelled “right” (which I float right in my css), below that place a Buy Now button which links to the url provided in the “buynow” custom field. Then display the body of the article. You could of course format the tags however you want. (image on top with text below, etc). Individual product page pictured below:

individual product page

Using custom fields is a great way to allow the client (who doesn’t know how to code) to be able to add new items to the shop easily without having to see any textpattern or html tags, and avoid them forgetting to close link tags and add things like rel=”external”. Yay!

This tutorial assumes that you have textpattern installed and ready to go, and have a good grasp of the tags.

( Download the latest version of Textpattern here: http://textpattern.com/download )

Did I miss anything? If you need any more clarity or have any questions, please feel free to put them in the comments, and I will do my best to help.

Happy Coding!

Advertise here via BSA

Sending and receiving email from your application isn’t hard, but lets be honest, its not as easy as you’d like either. If you haven’t considered using Gmail to manage inbound/outbound email, you really should! The advantages of using Gmail over a local SMTP server or Sendmail include:

• No tricky mail server configuration
• Google’s spam filtering is excellent
• Free archive/backup of your email history
• Easy manual administration when necessary

Any language with IMAP capabilities in its core, standard library, or 3rd party ecosystem can connect to Gmail for email processing. If that language happens to be Ruby, it’s even easier thanks the the ruby-gmail gem by Daniel Parker. Check it out.

Installing

Easy peasy.

gem install ruby-gmail

Connecting to Gmail

Connecting up is quite easy, and there are two options for how to proceed. First, you can perform all your activities inside a block. The advantage of this is the library will automatically log you out at the end of the block:

require 'gmail'

Gmail.new(username, password) do |gmail|
  # send commands
end
# logged out

Second, you can store the connection in a variable and logout it explicitly when done:

require 'gmail'

gmail = Gmail.new(username, password)
# send commands
gmail.logout
# logged out

Managing Email

The mailbox method takes a label as an argument and returns an object which has access to email with the given label.

inbox  = gmail.mailbox('inbox')
urgent = gmail.mailbox('urgent')

Since inbox is such a common label to access, there’s a handy shortcut method:

inbox = gmail.inbox

Now that you have a mailbox object in hand, you can access its emails or get counts:

inbox.emails #  an array of all emails in mailbox
inbox.emails(:unread) # an array of unread emails
inbox.emails(:from => "phb@work.com") # an array of emails from PHB

inbox.count # how many emails in the mailbox
inbox.count(:unread) # how many unread
inbox.count(:from => "phb@work.com") # how many from PHB

You can also perform many tasks on an individual email:

email = inbox.emails.first

email.mark(:read)
email.archive!
email.delete!
email.label('urgent')
email.move_to('followup')

Sending Email

Creating and sending emails is also a breeze. Just like connecting you can use the idiomatic Ruby block method, or the more object-oriented approach:

# with a block
gmail.deliver do
  to "phb@work.com"
  subject "Not feeling well"
  text_part do
    body "I won't be coming in today."
  end
  html_part do
    body "<p>I <em>won't</em> be coming in today.</p>"
  end
end

# or generate message and send it later
email = gmail.generate_message do
  to "phb@work.com"
  subject "Not feeling well"
  body "I won't be coming in today."
end

email.deliver!

The library will take care of sending it out your Gmail account and even set the “From” header for you. Nice!

Try It

If you’re already using Ruby to build an application and you need it to send or receive email, there is little excuse not to let Ruby-Gmail do the heavy lifting for you. Give it a try!

Advertise here via BSA

What is Storytlr?

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

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

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

Installing Storytlr

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

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

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

Requirements

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

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

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

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

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

Getting Started

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

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

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

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

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

The Database

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

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

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

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

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

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

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

(Lines Removed For Brevity)

Query OK, 0 rows affected (0.00 sec)

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

Configuration

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

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

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

[general]

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

;Security
security.cookie = kg89y6gbval

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

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

The Fruits of Our Labor

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

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

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

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

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

Keeping Current

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

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

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

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

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

Going Further

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

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

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

Advertise here via BSA

JavaScript is a powerful language, but it lacks some of the handy utilities that developers of other languages like Ruby & Python have come to know and love. Underscore.js is your utility belt. In the author’s own words:

Underscore is a utility-belt library for JavaScript that provides a lot of the functional programming support that you would expect in Prototype.js (or Ruby), but without extending any of the built-in JavaScript objects. It’s the tie to go along with jQuery’s tux.

Underscore.js provides collection functions like each, map, include, and reduce. It makes arrays more powerful by adding flatten, uniq, and intersect. It extends objects with many useful functions like keys, values, functions, isNaN, and many more.

A few examples to whet your appetite:

Using the each function to write each array value to the console:

// object-oriented way
_(['John', 'Paul', 'George', 'Ringo']).each(function(beatle) {
    console.log(beatle);
});
// functional way
_.each(['John', 'Paul', 'George', 'Ringo'], function(beatle) {
    console.log(beatle);
});

Using the reduce method to round three numbers down and sum the results:

_.reduce([1.5,2,3.7], 0, function(memo, num) { return memo + Math.floor(num) });
// => 6

Using the pluck method to to extract just the names from an array of objects:

var beatles = [
  {name: 'John', dead: true},
  {name: 'Paul', dead: false},
  {name: 'Ringo', dead: false},
  {name: 'George', dead: true}
]

_.pluck(beatles, 'name');
// => ["John", "Paul", "Ringo", "George"]

The library weighs in at just 2.5kb once packed and gzipped, so there is little excuse not to take advantage of its offerings. There are over 60 functions included, the documentation on how to use each function is great, the source code is freely available on GitHub, and the library is completely DOM-free which means you can use it server-side as well.

Thanks to Jeremy Ashkenas and the folks at DocumentCloud for a great open-source library that we can all benefit from!

Advertise here via BSA

Rails 2.3+ and Rails 3 rely on Rack, a minimal (and awesome) interface between Ruby and webservers. This has many advantages, one of which is the ability to easily swap Rack applications (middlewares) in & out of your Rails app. Modularity FTW!

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

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

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

Setup

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

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

lib/rack/firebug_logger.rb

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

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

Using FirebugLogger

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

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

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

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

Adding a Helper

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

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

  private

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

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

Now writing logs to Firebug is as easy as:

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

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

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

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

Advertise here via BSA

For simple WordPress theme development, what is the first thing most PHP developers do to troubleshoot problems?

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!

Advertise here via BSA

jQuery plugins come in all shapes and sizes. They perform very simple or very complex tasks depending on their intended use. When it comes time for you to design your own plugin, its really important to understand what patterns other developers use and what will best suits your needs.

As a side note, I have built a number of plugins for my own projects and client work that will never be released. The jQuery community needs to stop thinking of plugins only as releasable, open-source projects, and start thinking of them instead as a reusable pieces of code that can help optimize and DRY up a complex website. Take this little plugin as an example:

$.fn.notice = function(){
    return this.slideDown(500).delay(4000).slideUp(500);
}

It simply abstracts the animation for displaying a notice (using jQuery 1.4). Would I ever release this on an open source site? Of course not! But it is still a fully functioning jQuery plugin that can be used over and over throughout a website.

Design Pattern Series Overview

• Basics & Structure (this article)
• Options & Updating
• Callbacks & Custom Events
• Misc. General Practices

Basics

Filename

Every jQuery plugin sits in its own JS file, and is normally named using the following pattern:

jquery.pluginname.js
jquery.pluginname.min.js

Released plugins often also have a version number:

jquery.pluginname-1.3.js
jquery.pluginname-1.3.min.js

If you end up building a lot of plugins for your website, consider also including a namespace to keep all your files together (And of course you would combine and minify them for production, right?):

jquery.mysite.pluginname.js
jquery.mysite.pluginname.js

Basic File Layout

After any comments you choose to put at the top of your file, the very next thing you should have is a self executing anonymous function that will actually wrap your entire plugin. Say what!? Don’t worry, you have seen it before, and it looks like this:

(function($){

   ... code here ...

})(jQuery);

This gives your plugin a private scope to work in, and also allows your plugin to be used with $.noConflict mode without creating a problem. By passing jQuery into the function, the $ will equal jQuery inside the function even if $ means something different outside your plugin.

Structure

There are three basic structures you will see when you look at released plugins:

Contained Function

In this structure, (almost) all the code to run your plugin is contained within the function used to call your plugin. This is the most common format:

(function($){

   $.fn.myPlugin = function(){
      return this.each(function(){
         // do something
      });
   }

})(jQuery);

You should use this this structure when you are writing a simple plugin that acts once upon the jQuery result set on each execution. For complex plugins that need to maintain an adjustable state, you should consider the “Class and Function” structure.

Class and Function

In this structure, a class is used and an instance is created for each DOM element in the result set. You may see these objects attached in some way to the DOM elements they modify:

(function($){
   var MyClass = function(el){
       var $el = $(el);

       // Attach the instance of this object
       // to the jQuery wrapped DOM node
       $el.data('MyClass', this);
   }

   $.fn.myPlugin = function(){
      return this.each(function(){
         (new MyClass(this));
      });
   }

})(jQuery);

You should use this structure if you need to be able to access the object later that is associated with a DOM element. It is far easier to attach a single object vs several key/value pairs using the data() method. In this approach, you can access the object by calling $('selector').data('MyClass'). This functions more like a widget and is a plugin that maintains state and can adjust its state on the fly (Learn how in the next article.).

Note: Widget Factory: The next release of jQuery UI is going to see the addition of a Widget Factory that will be designed to specially assist in developing widget-like plugins.

Extend

In my opinion, this is the least idiomatic way to create a jQuery plugin. It uses the jQuery.fn.extend method instead of jQuery.fn.pluginName:

(function($){

   $.fn.extend({
     myPlugin: function(){
      return this.each(function(){
         // do something
     },
     myOtherPlugin: function(){
      return this.each(function(){
         // do something
     }
   });

})(jQuery);

You will find this structure helpful if you need to add a large number of plugin methods to jQuery. I would contend, however, that if your plugin needs to add that many methods, there may be a better way to structure its implementation.

I feel the extend method is used more by programmers transitioning from other JS libraries. I personally find the simple $.fn.pluginName = structure to be easier to read, and more in line with what you will normally see in jQuery plugins.

Up Next

In the next part of this series, we will look at passing options and providing methods for updating settings and functionality after a plugin has been called.

Advertise here via BSA

Winners Announced

I was really happy to see so much participation in this giveaway! After seeing how many people entered, I was feeling really bad that only one of them would leave with a copy of the book. I talked to Cody, and he graciously provided two more free copies so we can award a total of three books! I randomly picked three winners (using Random.org) and am happy to announce the following winners:

• Brad Rhine (truetech.org)
• Mila
• Geoff Woodburn (woodburndesigns.com)

Book Review

Late in 2009, Cody Lindley published a PDF book on jQuery titled jQuery Enlightenment. Today we are presenting our view of the book as well as offering a free copy to one lucky reader.

About The Author

Cody Lindley is a core team member of the jQuery project, and the original developer of the well known Thickbox plugin for jQuery. I had the pleasure of meeting and listening to Cody present at the jQuery Conference last year in Boston. He describes himself on his website:

Today I am a Christian, husband, son, brother, professional Web developer, and outdoor enthusiast. I spend a majority of my time sleeping and working, but who doesn’t? In between the daily routines of the average American, I desire an existence that entails a relationship with God, my family, and nature. I would like to consider myself a bookworm (a novice theologian at best), but truth be told, I simply enjoy watching movies and playing xBox way too much. I guess I also have the luxury of pursuing my profession as a personal passion. Yes, I often work even when I am not at work.

Overview

jQuery Enlightenment is a different type of book than I am used to seeing in the tech field. A list of what it is not might help shed light on what I mean. It is not documentation, a tutorial/walkthrough, or just conceptual material. jQuery Enlightenment is an amazingly clear montage of principals and code samples every jQuery developer needs to know grouped by topic. Cody covered topics both basic and profound throughout the pages of the book.

I consider myself quite adept at using jQuery, but found myself constantly amazed at the things I was learning while reading this book. Cody says it picks up where the jQuery documentation leaves off. I can see his point, but I think this book would be a better starting place for a new jQuery developer than even reading through the jQuery API site.

Pros

Code Samples

Code samples make up over 70% of the book (rough estimation). The book is not written in an editorial way at all. It is about presenting what you need to know, demonstrating it with an example, and moving on. For this reason the book is an extremely fast read and perfect for reference on a day to day basis.

Possibly one of the neatest features of the book itself is that (almost) every code sample provided in the book has a link to the same code on JSBin.com. JSBin is an online playground for testing and demonstrating JavaScript, HTML, and CSS technologies. jQuery Enlightenment isn’t a flat reading experience, it allows you to immediately jump in and play with the code samples until everything makes sense.

Additional Notes

Many of the topics are followed by a little box titled ‘Notes’. I am glad Cody didn’t choose some cheesy title for these boxes, but ‘Notes’ really does not sum up what they provide. You will find many undocumented (or hard to find) tips and tricks about the finer points of jQuery in these boxes. Skip over them at your own peril!

No Fluff Quality

Cody doesn’t waste any time on any of the topics presented in the book. The pattern used is simple: explain, demonstrate, move on. I personally will be using this book not just for reference, but for a quick read-through every few weeks to keep my jQuery senses sharp.

Cons

You will be hard pressed to find something negative to say about this book, and it wasn’t until I reached the end that I had one complaint about the content. The chapter on Ajax (Chapter 11) was far too short. Perhaps this is because the documentation is very clear, but I still wanted to learn more and have more examples to glean from. Perhaps the second edition of the book (which will cover jQuery 1.4) will provide more detail on jQuery’s AJAX implementation and associated methods.

Conclusion

I am confident new users and seasoned users alike will find much to learn in jQuery Enlightenment. After reading the book, my only concern is that I won’t remember all of the cool things I learned while reading it!

Win a FREE Copy!

Next Wednesday we will be selecting a winner to receive a free copy of jQuery Enlightenment. Entering the competition is easy!

Head over to jQuery Enlightenment and quickly look through table of contents. Then, leave a comment below telling us what chapter you think you would learn the most from if you were to win the book. Only comments referencing one of the actual chapters in the book will be eligible to win. We will randomly select a winner next Wednesday and announce it here on the site.. Sorry, but the contest is over!