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!

Sponsored by

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

Down & Dirty with MongoDB Part 2: Ruby ToDo

The Proposition

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

Here’s How

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

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

Add 3 functions within the functions.php file

function makeshorturl()
{

}

function shorturl_metabox()
{

}

function showshorturlbox()
{

}

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

Shortening the link

function makeshorturl()
{
    global $post;

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

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

    do_action('makeshorturl');

    return $short_url;
}

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

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

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

Lets look at the api call in more detail

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

It’s really quite simple.

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

Adding the shortened URL to the admin editor

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

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

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

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

More on meta boxes.

The add_meta_box function takes five parameters:

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

More on add_meta_box().

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

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

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

Bringing it together

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

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

Complete Code within functions.php

function makeshorturl()
{
global $post;

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

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

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

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

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

Usage

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

<?php echo makeshorturl(); ?>

BONUS

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

<?php echo wps_hook(); ?>

Note: Above tag is for the plugin only.

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

Download it!

Sponsored by

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

WordPress: Auto URL Shortening

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!

Sponsored by

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

Create a simple “shop” page in Textpattern

• 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!

Sponsored by

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

Emailify Your App with Gmail and Ruby

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

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

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

Installing Storytlr

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

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

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

Requirements

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

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

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

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

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

Getting Started

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

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

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

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

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

The Database

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

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

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

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

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

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

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

(Lines Removed For Brevity)

Query OK, 0 rows affected (0.00 sec)

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

Configuration

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

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

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

[general]

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

;Security
security.cookie = kg89y6gbval

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

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

The Fruits of Our Labor

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

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

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

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

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

Keeping Current

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

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

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

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

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

Going Further

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

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

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

Sponsored by

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

Meet Storytlr

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!

Sponsored by

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

Open-Source Spotlight: Underscore.js

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

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

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

Setup

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

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

lib/rack/firebug_logger.rb

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

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

Using FirebugLogger

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

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

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

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

Adding a Helper

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

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

  private

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

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

Now writing logs to Firebug is as easy as:

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

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

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

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

Sponsored by

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

Set Rails Logging on Fire

print_r( $post );
die();

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

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

WordPress Debug Mode

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

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

display_errors

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

Testing for local vs. production

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

WP_DEBUG

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

WP_DEBUG_DISPLAY

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

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

WP_DEBUG_LOG

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

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

Leveraging WP_DEBUG

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

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

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

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

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

Trying it Out

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

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

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

tail -f wp-content/debug.log

More Solutions

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

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

Sponsored by

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

Simple Debugging with WordPress

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.

Sponsored by

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

jQuery Plugin Design Patterns: Part I

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!

Sponsored by

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

jQuery Enlightenment: Book Review and Giveaway (Winners Announced!)

Technologies

Firerift

Firerift launched earlier this year as a completely new breed of Content Management Systems.  Firerift is, at its core, a JSON server with an amazing user interface. The mind behind Firerift Drew Wilson refers to it as a Client side CMS. All the tagging is done using CSS classes and valid markup. Released along with Firerift was Titan, an open source JSON templating engine built on top of jQuery. Firerift is a glimpse into the future of highly dynamic, AJAX powered websites.

LESS Framework

The LESS framework for CSS provides simplified execution of advanced CSS. With support for variables, mixins, nested rules and mathematical operations. LESS lives up to its name by letting you write shorter, optimized CSS. Though it is packaged as a Ruby gem, it can be used to prepare CSS files for any technology, even straight HTML/CSS websites. Since it uses CSS syntax, it’s as easy as renaming your .css files to .less and parsing through the LESS engine.

BuddyPress

BuddyPress is an amazing addition to WordPress MU (soon to be merged into WordPress core) that turns WPMU into an open-source social networking platform. From their website:

BuddyPress is a suite of WordPress plugins and themes, each adding a distinct new feature. BuddyPress contains all the features you’d expect from WordPress but aims to let members socially interact.

New Browsers All Around

This year saw major advances in pretty much all the major browsers. Safari 4 saw extreme speed increases in its JavaScript performance as well as support for advanced CSS3 properties. Firefox saw many of the same improvements and support with the 3.5 release. Even the browser developers love to hate saw significant improvements with the release of Internet Explorer 8. (Sadly, still no border-radius support!). Google Chrome seems to see major version number updates much faster than the other browsers, but of significant importance was the final release of a slightly limited Chrome for Mac Beta. Opera continued to improve and innovate their browser as well, but I think a great change this year was that Opera got an icon facelift and the dreaded drop shadow on the “O” is gone!

Notable Events

jQuery Joins The Software Freedom Conservancy

The jQuery team has been planning for a while to join the Software Freedom Conservancy to protect the jQuery project, open the door for future growth, as well as to move the copyright from John Resig’s own name into the Conservancy’s name. From the overview page:

One of the principal benefits of joining the Conservancy is that member projects get all the protections of being a corporate entity without actually having to form and maintain one. These benefits include, most notably, the ability to collect earmarked project donations and protection from personal liability for the developers of the project.

The jQuery team made the first step this year by joining the Conservancy as planned, and are now working to move the copyright as well.

Fix Outlook

A great movement from the guys over at Campaign Montior launched Fix Outlook as a web campaign to make Microsoft aware of how many people disliked the limited email rendering engine in Office 2005 and newer. The campaign saw over 20,000 tweets in the first 24 hours! Microsoft at first responded rather negatively, then changed face a bit and became very thankful of the effort raised by the website. You can read the full account for more details.

Books

Digging Into WordPress

Digging into WordPress is a fantastic new book by Chris Coyier and Jeff Starr. It is only available currently as a PDF book, but a printed version is coming soon. Written in an extremely down to earth manner, this book will provide useful information for anyone looking to take WordPress to the next level. This isn’t a book solving hypothetical problems: the authors only present techniques they have used themselves.

jQuery Enlightenment

Written by jQuery core team member Cody Lindley, jQuery Enlightenment picks up where the jQuery docs leave off. The book is probably 80% code examples and 20% explanation. This is a no fluff, crystal clear presentation of intermediate to advanced jQuery techniques, though I think even beginners would learn a lot through reading this PDF book. An additional innovative feature that I hope other book writers pick up is that almost every code example is linked to a live example on JSBin.com so you can actually play with his examples, even changing the code, to see how they work.

Operating Systems

Windows 7

After nothing less than a PR nightmare with Windows Vista, Microsoft released a fantastic new operating system this year in Windows 7. Far more stable than its predecessor, Windows 7 takes many of the principles and innovations introduced with Vista, but makes them both useable and reliable to users of Windows 7.

Snow Leopard

The innovative and trendy OS for Macintosh computers saw an upgrade this year with the release of Snow Leopard. As its name indicates, this OS is not that different an animal from the previous release of OS X (Leopard). Maintaining the same look and feel, Snow Leopard introduced many innovated technology features to further speed up the already finely tuned Mac line of computers. This has to be the first time in history that the install of a new version of an operating system actually gave you back 7GB of hard drive space!

iPhone 3.0

In the third version of the popular OS in use on iPhones and iPod Touches, users finally were allowed to Cut, Copy, and Paste! In addition, Multimedia Messaging (MMS), Spotlight Search, Voice Memos and Voice Dialing were also introduced. From a developers perspective, Apple opened up over 1,000 new API’s to allow iPhone developers even more freedom and power in their development process.

Android 2.0

For those that prefer an alternative to the Apple iPhone, many users have gravitated to the Android phones. This year saw an upgrade to the Android 2.0 OS and several UI and functional enhancements. Support for Exchange accounts, Combined Inboxes, and Macro Focus and White Balance for the Camera were all features added in this release.

Web Tools

Build It With Me

Some developers can do everything themselves from marketing, to design, to development. The rest of us would rather work on the part of the project we love, and leave the rest to someone better suited for the job. BuildItWith.me is the goto place to meet other developers that either have ideas or time on their hands to work on your ideas. Form new partnerships, find great projects to work on, all within the stylish interface of BuildItWith.me. I love their tag line: “Skip the funding.”

Notable App

Notable provides a great way for web developers to seek responses from their clients during the design process. Simply use one of the provided tools to make a screenshot of the a web page you are working on, and send it to your client for approval. The client can draw on the screenshot and make notes, all through a simple web interface. If you are a developer that works remotely from your clients, this service might be just what you are looking for.

Flagrant Self-Promotion

Downloadify

This year saw the release of Flash 10 and with it, the support for client-side file generation and download. Why is this important? Now developers can make web applications that can run fully in the browser, including file saving capabilities, without a round trip to the server. As a personal project, I built and released Downloadify to provide a JavaScript bridge to this amazing Flash functionality. Since the alternate server methods (dataURIs and IE functions) are all prone to usability problems, Downloadify provides a nice simple way to repurpose client side data and turn it into a savable file.

WANT MORE?

Sponsored by

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

Best of 2009 in the Coding Industry

This is accomplished by using the prototype object. Each native object in JavaScript includes a prototype object. Don’t get this confused with the PrototypeJS framework… the prototype object is a way to extend all objects that have inherited from the base object you extended. You can easily extend the prototype object by adding functions to it like this:

Object.prototype.functionName = function(){

}

You can then call them directly:

var obj = new Object();
obj.functionName();

There are a number of advanced uses of the prototype object, but this is the important thing to remember: any function added to the prototype of an object is available on any object that inherits from it. So if you extend the prototype on the Number object, all numbers will have access to the new function; if you extend the Array object, all arrays can access your custom function. You only use the prototype.functionName syntax when declaring the new function, not when calling it.

Enough theory, lets see some (somewhat) practical uses:

Do you find yourself capitalizing a lot of words in a particular JavaScript app? Just add a capitalize method to the String object.

String.prototype.capitalize = function(){
  if(this.length == 0) return this;
  return this[0].toUpperCase() + this.substr(1);
}

Now you can capitalize any string in your application by calling "lower".capitalize() and get "Lower" in return. Since it returns a string, you could chain it with any other function you can execute on a string.

Do you always find yourself forgetting you can call Number(”25″) to turn a string into a number? Just add a toNumber() function to the String prototype:

String.prototype.toNumber = function(){
  return Number(this);
}

If you need to split large JSON arrays into groups of two or three each, you could extend the Array object like this:

[js]
Array.prototype.inGroupsOf = function(num){
	var ret = [],
		length = this.length,
		groups = Math.ceil(length / num);

	for(var i = 0; i < groups; i++){
		var start = i * num,
			end   = start + num;

		ret.push(this.slice(start, end))
	}
	return ret;
}

Now calling inGroupsOf(3) on any Array would return that same array split into as many parts as needed to ensure no group has more than three items in it.

There are a number of objects you can extend, but the ones you will use the most are String, Array, Object, Number, Date. One trouble area you might face is calling methods on numbers. The following example will fail:

Number.prototype.to_s = function(){
  return this + "";
}

25.to_s();

The prototype function is correct, but the way we called it is wrong. There are two ways to call our custom functions on numbers:

var n = 25;
n.to_s(); // Returns "25"

(25).to_s(); // Also returns "25"

Think Start, Not End

Its important when deciding what object to extend that you focus on what object type you are starting with, not so much which type you plan on ending with. For instance, if you wanted to extend an object to easily parse Twitter date strings you would not extend the Date object. You would extend the String object, and your function would return a Date object.

Load Your Extensions First

It is normally a good idea to load these extensions prior to any other library, including jQuery. Anytime you extend the prototype object, the new method is instantly available to all objects of the same type or any object that has inherited from that type. However, since you want to be sure your methods are always available, you guarantee their availability by loading them first.

How to Group The Extensions

Naming your files Prototype.Date.js and Prototype.Array.js is an easy way to keep all your extensions in one part of your JS folder, and easy to access during development. If you follow this method, you would simply put Date.prototype methods in the Prototype.Date.js file, etc. This starts to break down when you have parallel functions. You might have a toDateFromTwitter() method on the String object and a toTwitterFromDate() method on the Date object. Putting these in separate files might not make sense. At that point, you should put both these extensions in a file named TwitterHelpers.js or something similar. Obviously use what makes sense to you and works with your flow.

Don’t Bloat

Just because you write 500+ awesome Array extensions in the next 2 years, does not mean you need to include them on every project. Be sure to only use this technique when it makes sense for the project and when it helps clean up your code.

Sponsored by

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

JavaScript Can Learn: Now Teach It Tricks!

Mini-series Overview

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

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

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

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

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

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

<?php

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

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

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

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

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

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

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

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

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

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

Here are the guts:

<?php

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Take care,
Wess “Wattz”

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

Sponsored by

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

Roll Your Own PHP Framework: Part III

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

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

Galleriffic

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

Upload the files

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

Install the relevant plugins

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

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

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

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

Set up your forms

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

gallery

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

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

article_image_form

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

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

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

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

Basically we have taken this code from galleriffic:

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

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

Set up your page

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

numThumbs: 9,

Set up your style

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

Add your images

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

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

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

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

Thanks, and happy coding!

Sponsored by

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

Easy to update thumbnail gallery using Textpattern and Galleriffic

Mini-series Overview

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

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

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

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

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

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

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

	public function __construct($template)
	{

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Sponsored by

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

Roll Your Own PHP Framework: Part II