Advertise here via BSA

Rumors that Apple has been working on a television set have been going for quite some time. The fire was stoked on the release of Walter Isaacson’s Steve Jobs biography, in which Jobs declares that he “finally cracked it” — referring to television user interfaces — and again in the past week after DigiTimes claimed the company was working on a summer 2012 timeline with 32″ and 37″ models (at those sizes, I hope DigiTimes is wrong — their track record is hit and miss).

The current Apple TV, a fantastic product but not a television set in itself, runs a version of iOS that has no support for third-party App Store applications. In the last few months, we’ve had the smallest taste of what apps on an iOS TV platform could do with the introduction of AirPlay, which allows an iPad to serve as a controller, serving up the control interface on the tablet and another view on the television.

We can assume that a fully-fledged television set from Apple, with the interface Jobs says he finally perfected before his death, will do what the iPhone 3G did for third-party developers and allow applications on the platform. But just what exactly is it that we can look forward to? What innovative ideas will take root on Apple’s television platform in ways that could be significantly different from the apps present on existing iOS devices?

Gaming

With AirPlay, some of the most interesting developments have been in the gaming world. When the feature was announced in June, I wondered about the potential that could be unlocked by using iOS devices as controllers for console-like gaming, with many parallels to the upcoming Wii U. The big question is: will AirPlay setups eventually dent console sales as much as devices like the iPhone and iPad have put a dent in sales of dedicated mobile gaming devices like the PlayStation Vita and Nintendo 3DS?

The iPad is a pretty great mobile gaming device but the current Apple TV is decidedly underpowered; it still can’t run 1080p video content, which is at this stage otherwise pretty ubiquitous. It pretty much goes without saying that the iTV would run 1080p video and there’s a good chance it would have the guts to run apps with 3D graphics of some quality if Apple has any plans to let developers near it.

With a television that can handle high-definition graphics processing and an iOS controller that can change to suit any game, I’d say this is one area that independent and big name studios alike will have a field day in. I don’t believe it would take serious gamers away from the Xbox 360 and the PlayStation but I can see the Wii losing market share.

Education

I’m not a fan of straight up educational video, and I’m not a huge fan of audio teaching either. I love learning using web apps or the reflective nature of learning via text where you can pause and think about certain concepts or lines, or the passive, reactionary mode of learning through video — which pretends to be more like classroom experiences where the teacher can interact with the students but is really anything but.

We’ve had heaps of great apps on computers, tablets and mobile devices for learning new skills, such as the plethora of language-learning apps that have been selling in droves since before the Internet was a common household utility, but I think an iTV running iOS, using voice or other iOS devices as an input, could make for a great learning environment in your living room.

Imagine, for example, pulling up guitar tablature on your iPad while watching the technique in practice, in real-time on the TV, and being able to quickly pull up related instruction — for instance, if there’s a pinch harmonic in the song you’re learning but you’re not sure of the technique, you can keep the context — the tablature for the song — on the tablet and learn the technique from the video instruction on the big screen; you wouldn’t have to leave the current exercise to learn prerequisite techniques as you went along.

As the Siri technologies of voice recognition and intelligent processing get more advanced it’s exciting to think about what teacher-student interactions our devices could emulate in the future.

Fitness

For longer than I can remember, aerobics on the beach has dominated early morning TV. One of the most popular product categories inspired by the Xbox Kinect is fitness gaming, with titles such as Zumba — which appeals primarily to women, not the Xbox’s traditional demographic — selling insanely well, along with other strong performers like UFC Personal Trainer.

It’s clear that, for those who can’t find, get to or afford fitness groups in their area, or are just taking baby steps off the couch, the television is a great facilitator of beginner exercise. I can see iOS developers building programs much like those seen on TV but that offer the user complete customization over their workouts, and integrated ways to track and graph things like weight loss and gain and logging of food consumption.

Where Xbox fitness titles can be pretty gimmicky, I can see iOS developers creating a cohesive system across devices: responsive video training in front of the TV and logging data on the go with the iPad and iPhone.

These are just three of the areas that developers will undoubtedly leap on first if the iTV arrives and if it opens up for App Store submissions. Let us know your own predictions in the comments section.

Advertise here via BSA

One sign of a developer power tool hitting critical mass is when a wellspring of Graphical User Interfaces explode onto the scene. It looks like Git — the distributed version control system authored by Linus Torvalds — has arrived. It brings with it a bevy of Git clients for Mac OS X.

Some are old, some are shiny new, and some haven’t even officially been released yet. Let’s run them down, shall we?

GitX

GitX may be the oldest of the lot, but this is a powerful and great looking Git client. It features a history viewer, GitHub’s gist integration, and most importantly a great commit interface which allows for easy hunk and single-line commits.

Best of all, it’s totally free & open source! There is a ton of activity on GitHub, most interesting of which is a fork by Brotherbard that adds many experimental features.

Git Tower

Free while still in beta, Git Tower is a commercial application claiming to be “the most powerful Git client for Mac”. Big words, but they’re doing a great job living up to them. Git Tower has a slick interface, a repo manager for easily loading previous projects, remote repo integration, and the list goes on.

Another thing that makes this application special is that they managed to capture FUEL editor Doug Neiner’s ugly mug on the History view screenshot. What are the odds?! :)

Gitbox

Gitbox hosts a bunch of powerful features while maintaining a minimal interface. Anybody who has designed interfaces for software knows how difficult a task that can be.

The app is free for a single repository and $39 for multiple repositories. Its features include single-click operations, automated remote commit fetching, local/remote branches, and external diffing tool integration.

GitMac

We don’t know too much about GitMac since it hasn’t entered its beta stage yet, but its definitely one to keep an eye on as development progresses.

Review

It’s exciting to see the maturation and adoption of a tool as powerful as Git. While graphical interfaces aren’t necessary for us “hardcore developers”, they are really nice for those who could benefit greatly from distributed version control, but have a case of Terminalitis®.

Give these tools a try and be sure to let us know in the comments if we missed any!

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

Today’s software development culture promotes rapid development methodologies, minimum viable products, releasing early & often, and the axiom that “real artists ship.” What common thread weaves its way through all of these things?

SPEED.

If you haven’t felt the pressure to squeeze one more feature in before the release date, to fix an interface bug “RIGHT NOW!”, to get your product launched before your competition, or to shave a week off of your development schedule then you haven’t been developing software for all that long.

What many people fail to realize — and what I’ll emphasize in this post — is that the compromises we often make when optimizing for development speed can actually slow us down. More succinctly:

If you want to move faster, you have to slow down.

Allow me to demonstrate this concept in a few key areas of software development.

Testing

Automated tests are one of the first things to get tossed out when on a time crunch. Writing tests takes time, and that time could be spent implementing features. The problem with this line of thought is that one way or another the software needs to be tested before it’s released, and the less you automate the more you end up testing manually (how many times have you stepped through the same web form to test server responses?).

The added benefit of writing tests alongside your implementation code (preferably before it) is that it forces you to think about the problem space and you go into your implementation having put much more thought into it. So yes, you spend time writing tests, but you make it up in reduced implementation time.

The Big Win™ with building up a solid test suite is it reduces the amount of work you have to perform later when you refactor or add new features, making it a HUGE time savings as the system becomes more complex. Regressions suck. A solid test suite helps avoid them.

Naming Things

It’s been said that there are only two hard problems in Computer Science: cache invalidation, naming things and off-by-one errors.

When it comes to naming things people often mail it in because it is hard and they think they are wasting a lot of time doing it. This “speed optimization” can manifest itself in variables named “x”, “foo”, or “tmp3”. Those are ridiculous names, but even “okay” names that don’t properly describe what they represent can be quite troublesome.

Why is it so important to name things well and how could dedicating time towards that effort speed up development? Remember, code is written once and read many times. The ability for you (or more often, somebody else) to return to your software and pick up the context quickly is paramount in maintaining development speed. Nothing makes picking up context more difficult — and therefore time consuming — than non-semantic (devoid of meaning) variable, function, and/or class names.

Do yourself a favor: slow down & put some thought into naming things. Future-you will reap the benefits.

Documentation

When time is of the essence documentation is often pushed to last or thrown out altogether. The problem with this is that it also impacts how quickly new developers (including yourself 6-12 months later) can come up to speed and be efficient. There is no better time to document your code than after you have just finished writing it. At that point it is still fresh on your mind and you know all the little gotchas that will cost hours & days of development time if the next programmer doesn’t see them coming.

One reason people think documentation slows them down is that they formalize it too much or end up writing novels about their software. If your code needs a novel to explain it, it is too complicated and needs to be refactored into smaller, simpler pieces.

How can you document code and keep up the speed of development? Follow these guidelines and you’ll find that adding documentation as you go (which is far less daunting than going back and documenting everything at the end) adds trivial amounts of time to the overall development.

1. Put a brief summary at the top of multi-line functions.
2. Include inline warnings or explanations for tricky bits of code. This is also a red flag for refactoring later
3. Always document the intent instead of implementation
4. Make exceptions to these guidelines when it is prudent

The importance of documentation (as well as the form of it) varies from project-to-project, but almost all code needs these little breadcrumbs to be easily maintained & extended.

The Principle

That’s just a handful of examples. I could go on to talk about code style & establishing conventions, optimizing for readability, habitual refactoring, and other such concepts, but it is the overriding principle that is most important:

Invest time to think about what you’re trying to accomplish and the best way to proceed from the start when your software is simple. That way when complexity rears its ugly head your development won’t come to a screeching halt.

Need to develop something quickly? Just remember that sometimes you have to slow down to go faster.

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

A few weeks ago, I tweeted:

General service announcement: it is written “jQuery” not “Jquery” or “JQuery”… even if it comes first in a sentence!!!! ∞

Then Saturday I put out a stronger tweet, and caught some stronger feedback for it:

Test: “If you want jQuery help, which misspelling will greatly hurt your chances: a) Jquery b) JQuery c) jquery d) All of the above. ∞

At the end of the day, does it really matter how someone writes the name “jQuery”? Does it make them a better or worse programmer based on how they type it out?

Let me clarify that I have never failed to answer a question on Stack Overflow (Where I like to hang out and answer jQuery questions) because the asker typed jQuery with incorrect capitalization. I would never fail to respond to an email because the asker wrote it as Jquery or JQuery. I would hate to be that petty an individual, and I think that is the feeling some people were picking up from my tweets.

However, I can say I notice it and it bothers me when people seeking help don’t type out the library name correctly. It really is a small thing, and maybe it shouldn’t bother me, but it does. It got me thinking about things that might negatively affect a request for help, and I came up with a list of six suggestions. I hope these suggestions are helpful when you need to ask for help with open source software.

Asking for Help

If you need help with an open source project, you will often be dealing with people that 1) don’t have a lot of time and 2) must use the time they have wisely. With that in mind, here are few suggestions that might help you get answers easier:

1. Take the time to make sure your question makes sense. Complete sentences, clear code examples, and links to a page demonstrating the problem all go a long way in ensuring a quality answer.
2. Run spell-check before sending your question. There are at least two reasons there would be a lot of spelling errors in a question: 1) English is not the native tongue of the person requesting help 2) The person requesting help didn’t take the time ensure a quality question. Most applications have spell check. If they don’t, you can copy and paste your question to an application that does have spell check. Reason #1 is understandable and should be overlooked; reason #2 is what will stand out most to someone reading your question. It may affect that person’s decision to answer you.
3. Getting back to my original statement regarding Jquery, JQuery and jquery. Some libraries have really weird spelling or capitalizations, some are more straight forward. Write the library/plugin name correctly when asking for help with it! jQuery should be very easy, but so many people get it wrong. It is like the names iPad and iPhone: the first letter is lowercase! For another example, the popular blogging platform is WordPress, not Wordpress or Word Press.
4. At the very least, run a Google/Yahoo/Bing search (pick one) with some of the words from the question you plan on asking. I almost always take time to run a few searches to answer a question myself before asking on Stack Overflow or emailing someone for help. It is just common courtesy to spend some of your time before asking for the time of someone else.
5. If you find the answer yourself after asking for help, be sure to let the person know you no longer need their help. Sometimes emails will sit around until there is time to answer them while in the mean time you find the answer somewhere else. It might reduce your chance of getting future emails answered if the person who takes the time to answer your question finds out they wasted their time.
6. Be respectful and kind. If an open source project is screwing up your project, you have a few choices 1) use a different project 2) pay for help 3) Ask kindly for help from the project. Notice I didn’t put “4) Demand help for free.” On a very positive note, I have to say every request I have gotten for help on the few small projects I maintain have been both respectful and kind. This is really important!

What It All Means

The bottom line is this: If it appears to someone reading your question that you have not put any time into either solving the problem yourself or writing a decent request for help, they will be less likely to put any time into answering it.

Remember, it isn’t always about just getting an answer. Sometimes its about getting the right person to answer your question. For instance, there are tons of programmers answering questions on Stack Overflow, but not all of them have equal qualifications and skill. Put in the effort up front when asking the question. It will be worth it when you get a solid answer!

Do you have any tips to add? If so, please let me know about them in the comments!

Advertise here via BSA

MongoDB is an open-source, document-based datastore that has been gaining traction with developers lately. Its popularity is most likely due to the “middle ground” it provides between relational databases like MySQL and key-value stores like Redis.

We’ve found the datastore a joy to use and wanted to feature it somehow on FYC. However, there are many, many introductory articles and getting started tutorials for MongoDB (also the information on the project’s website is spectacular), so we would be remiss to provide yet another basic intro.

Instead, we decided to highlight how the datastore is used from a few popular dynamic languages. 10gen – MongoDB’s creator – provides many official client drivers (libraries) and the open-source community has produced a handful of libraries as well. We couldn’t feature them all, so we chose three favorites – Ruby, Python, and PHP – to include in the series.

The Plot

Many demonstrations use throwaway “Hello World” type programs. We thought it would be much cooler to write something that we can actually use, build upon, and maybe derive some value from. With that in mind, we tried to think of an application that had the following characteristics:

1. Real-world use case
2. Few lines of code (~ 100)
3. Simple to understand and implement
4. No 3rd party libraries or frameworks
5. Demonstrate the basic CRUD operations

For better or worse, we chose to write a command-line todo list app as it fit the requirements well.

The Spec

Our todo application is invoked from the command-line and works as follows:

• 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

The only requirement outside of the user interface outlined above is that MongoDB be used to persist the todo list.

The Setup

An identical application will be written in Ruby, Python, and PHP using the official MongoDB drivers. Each language will get its own article in the series. You have the application requirements so feel free to code along in your language of choice. Also, we’d love to see versions in some other languages that we won’t be covering. Show us your skills by submitting them in the comments. We’ll happily tweet them out and link them up in our final article in the series!

Be sure to grab our RSS feed or follow @fuelyourcoding on Twitter so you don’t miss out as we get down & dirty with MongoDB!

Advertise here via BSA

The trouble with having over 200,000 iOS apps in the App Store is how difficult it is to find high quality apps to fit our needs. With that in mind, I have compiled this list of eight apps that I’ve found invaluable as a developer.

Without any further ado, here they are listed alphabetically:

Air Display

Price: $9.99
Type: iPad
Version: 1.0.1

Air Display lets you use your iPad as a wireless display for your Mac OS X computer. Why is this great for developers? Because we need screen real estate, baby!

Here’s a pic of Air Display in action as my 3rd monitor. The iPad monitor is perfect size for your Skype windows, API documentation, or a browser session with programming tutorials.

DomainStorm

Price: Free
Type: iPhone
Version: 1.0

When inspiration for that new web application hits you, the first (and most fun) thing to do is buy a great domain name for it.

DomainStorm is a relatively new app from Network Solutions built to help you accomplish just that. It tells you if domains are available, helps you brainstorm name ideas, lets you mark domains as favorites for later purchase, and even provides you WHOIS information so you can contact current domain owners about a purchase. A must have for sure!

Ego

Price: $1.99, $4.99
Type: iPhone, iPad
Version: 2.1

Obsessed with checking your site analytics? There is no better way to get a quick glance at your traffic than the beautifully designed Ego by Garrett Murray.

With support for Google Analytics, Ember, FeedBurner, Twitter, Mint, Vimeo, Tumblr, and SquareSpace this app has your analytics needs covered. Did I mention it was beautifully designed?

Evernote

Price: Free
Type: Universal
Version: 3.3.5

Evernote is a wonderful way to store all the programming tips, tricks, tutorials and gotchas that we accumulate as we go about our development efforts. The power of Evernote is the universal access to your notes that it provides. They have a web interface, Mac/Windows clients, and mobile apps including a highly polished iOS app.

If you haven’t tried Evernote yet, now is a great time to put all your notes in one highly accessible place. You can even save passwords in Evernote as they provide encrypted strings inside your notes.

iOctocat

Price: $4.99
Type: iPhone
Version: 1.7.1.1

iOctocat is, hands down, the best way to keep up to snuff with open-source development on GitHub from your iPhone.

This app features access to your personal news feed, repositories, individual commits, issues, user profiles and site search. While the app is not free as in beer, it is free as in speech and the source is aptly hosted on GitHub. That makes it a great candidate for learning iOS development as well!

iSSH

Price: $9.99
Type: Universal
Version: 4.2.5

Most developers have found themselves AFK when a very important server is having problems. If you know the feeling, then iSSH is your new best friend.

There are a few remote server control iOS apps available, but this one is the best one that I’ve come across. It allows SSH, telnet, and even VNC connections and boasts many features. The iPad version provides a display size large enough to allow determined coders like myself to fire up vim and get some coding done. The price is a bit steep, but if iSSH saves your butt one time then it has already earned its keep.

iStat

Price: $0.99
Type: iPhone
Version: 1.2

Bjango makes gorgeous and useful software including the OS X system monitoring tool iStat Menus. They also offer a similar app called iStat which displays your iPhone’s system stats.

The beauty of the iStat app for developers is that you can also use it to monitor remote servers running Mac, Linux or Solaris! You simply install a daemon on the server you need monitoring and iStat will show you its CPU, memory, disk, temps, uptime, and tons more information. It feels great to have intimate details about your servers always at your fingertips.

Nezumi

Price: $4.99
Type: iPhone
Version: 1.2

This one is specific to Ruby-using web developers. For those who fit that description, you absolutely need to try deploying an application to Heroku. It is the dead simplest way to get deployed and if you haven’t tried it yet then you don’t know what you’re missing out on.

For those who’ve seen the Heroku light, Nezumi is a must-have companion app for the Heroku service. Nezumi gives you instant access to your Heroku apps from your iPhone so you can add collaborators, manage your dynos, toggle maintenance mode, execute rake/console tasks, and even restart your application on the go. Love it!

So there you have ‘em. Eight great iOS apps for developers. Hopefully you’ll find that one or more of these apps helps you increase your productivity as a developer. I know I’m better off with them than I was without.

If you know of any other iOS apps that did not make my list, please give them a shout out in the comments, so we can all check them out!

Advertise here via BSA

The most obvious way to improve your coding is to write more code. Everybody knows that. However, another activity which I guarantee will improve your coding is the complete opposite of writing. I will state this as plainly as I possibly can:

If you want to dramatically increase your programming skills you need to be reading other people’s code.

Maybe you believe that, maybe you don’t. You should. And if you’re willing to give it a shot, I believe you will be rewarded greatly for your time.

In this article I will help you choose what to read and give you practical advice on how to go about reading it. If you’re already a code reader you may find a few ways to get more from your efforts. If you aren’t, you absolutely must read on.

What to Read

This is a big decision, and one that is difficult to advise on. I won’t simply point you toward code I think you should read, because it really comes down to what you’re in to. However, I will provide some guidelines which you can follow to help you choose what to read.

» Read Code That You Rely On

A great place to start is with any plugins or libraries that you are already using.

• A WordPress plugin that you really like
• A Ruby gem that you’ve found useful
• A jQuery plugin that you keep going back to

These are all great candidates for learning. You are already familiar with their public APIs so the barrier to understanding their inner workings is lower. Also, as a user of the code you have an opportunity to add documentation, implement a new feature, or generally give back to the project in some way.

» Read Code That Impresses You

I remember the first time I saw 280 Slides and I thought to myself, “Now that is impressive.” I quickly learned that the code driving that site was the open-source Cappuccino project. I tucked that knowledge into the far recesses of my brain and when I eventually came across another impressive app running on Cappuccino I knew I had a project that I could learn a lot from. What have you been impressed by lately? Is it open-source? If so, it’s a great choice for reading since the code is likely to impress you as much as the resulting application.

» Read Code Written By Somebody You Respect

If you’ve been coding with open-source software for more than a little while, there are probably other programmers who have earned your respect. I can think of a few developers off the top of my head whose code is downright enviable.

If you don’t have a respected developer in mind, it’s easy to find one. He or she has probably authored some code in one of the previous two sections (code you rely upon, or that impresses you).

» Read Code That You Can Actually Grok

If you’re the adventurous type you may be considering diving into a large project like Ruby on Rails, Drupal, or jQuery. I suggest avoiding projects like these for now unless you are an experienced code reader.

Large projects have a lot more moving pieces, and you may end up struggling too much with the concepts to learn anything of immediate value. Confusion leads to discouragement, and larger projects more likely to confuse and discourage you in your reading. The advantage of picking a small project to read is that you can hold the entire program logic in your head at once. This leaves you with just the details to discover and learn from.

How to Read

Now that you’ve chosen some code to read, what is the best way to go about reading it? I’ve read a lot of code in my days, and I can suggest a few ways to maximize your ROI.

» See the Big Picture

I’m going to assume that you at least know at a macro level what the code you’re reading accomplishes. If not, I suggest reading the project’s website, tutorials, documentation, and anything else you can get your hands on except the code.

Okay, with that cleared I suggest your first step is to wrap your head around the project’s structure. This is a variable amount of work depending on the size of the codebase you’ve chosen, but anything larger than one file will require a little bit of time.

First, note the file structure. This step is aided by an editor that has a folder hierarchy view like TextMate. For example, here is a nice overview of the Twitter Ruby gem:

The goal with this step is to just get familiar with the source. Find out which files include/require/load other files, where the bulk of the code is, the namespaces used if any, and things of this nature. Once you’ve got the big picture you’ll be ready to dig into the details.

» Document Your Findings

Reading code should not be a passive activity. I encourage you to add comments as you go, documenting your assumptions and your conclusions as you begin to understand the program flow. When you first get started your comments will probably look something like:

# I think this function is called after 'initialize'

# What does this equation even do?

# Pretty sure this variable loses scope after line 17

As your understanding progresses you can remove the little breadcrumb comments you left yourself and perhaps write more meaningful and authoritative comments that could possibly be committed back to the project.

» Use the Tests, Luke

Hopefully the project you’ve chosen has a test suite. If not, you can skip this section altogether (or find one that does).

Tests are a great place to start whenever you read somebody else’s code because they document what the code is supposed to accomplish. Some tests are more informative than others, but no matter how well written, you’ll often find the programmer’s intent in the tests much more easily than you’ll find it in the implementation. While you’re reading, try to get the test suite to run successfully. This will make sure your development environment is configured properly and will make you more confident when making changes.

» Execute, Change Stuff, Execute

Who said reading code had to be hands off? You’ll really start to understand things once you’ve broken everything and put it back together again. Remember those tests you got passing? Make them fail, add some more, or try changing the implementation without breaking them. Try adding a small feature that you think is cool, or setup project-wide logging so you can print output at various stages of the code. Is this still reading? Absolutely, but at this point its more of a choose your own adventure than a mystery novel. And that’s a good thing!

» Rinse and Repeat

Once you finish reading one codebase, pick another one and start the process over again. The more code you read, the better you get at reading it and the more you get out of it in less time. I think you’ll find that the ROI increases quite quickly and that it’s actually a very enjoyable way to learn.

Where To Start

The single most influential factor in my code reading is GitHub. The site makes it so easy to find new projects and great coders that you’re doing yourself a disservice if you’re not leveraging it. I suggest starting on GitHub and reading code right on the site until you find a project you know you can learn from. Then git clone that baby and get to reading!

How about you? Do you read code as a learning tool? Which projects would you recommend to others? Read any good code lately?

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

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

Twitter recently announced and released a JavaScript API called @Anywhere which makes it super-simple to integrate Twitter-related content on any website. This means developers no longer have to roll their own integration or use 3rd party libraries. @Anywhere, despite its unfortunate naming, appears to be a big win for all. Here is a brief overview of its features and usage.

To get started, register an @Anywhere application and get an API key. Then plug this snippet into your page:

<script src="http://platform.twitter.com/anywhere.js?id=YOUR_API_KEY&v=1" type="text/javascript"></script>

Now you can begin using any of the following features:

Auto-linkification of Twitter usernames

This is a convenient way to link Twitter usernames on your site to the appropriate user’s profile page on Twitter. The most basic usage looks like this:

<script type="text/javascript">

  twttr.anywhere(function (T) {
    T.linkifyUsers();
  });

</script>

Hovercards

A Hovercard is a small, context-aware tooltip that provides access to data about a particular Twitter user. It looks like this:

To enable hovercards on a page:

<script type="text/javascript">

  twttr.anywhere(function (T) {
    T.hovercards();
  });

</script>

Follow buttons

The feature name pretty much says it all. Let people follow Twitter users from your page. To enable it for user sant0sk1 inside a span with id of `follow-me`:

<span id="follow-me"></span>
<script type="text/javascript">

  twttr.anywhere(function (T) {
    T('#follow-mei').followButton("sant0sk1");
  });

</script>

The buttons look like this:

Tweet Box

Let Twitter users tweet from inside your webpage or web application. An example of using this on a div with id of `tweetbox`:

<div id="tbox"></div>
<script type="text/javascript">

  twttr.anywhere(function (T) {
    T("#tbox").tweetBox();
  });
</script>

User login & signup

This feature allows users to perform some of the authentication-required activities like following users and tweeting from your page. It uses OAuth and provides authComplete and signOut callbacks that you can hook into. It’s more complicated than the others so we won’t provide an example here.

Try it!

@Anywhere looks like a solid API that can provide immediate advantages over other solutions. If you need quick, easy and official Twitter integration on your site we highly recommend trying it out. Start with the official documentation from which we derived much of this overview. Then you can move on to the full API documentation which is (at the time of posting) in a preview state. Enjoy!

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!