Harry Love » Portfolio http://harrylove.org Neat wheelie, Mrs. Schmouse, don't lose it! Thu, 25 Jun 2009 05:22:19 +0000 http://wordpress.org/?v=2.8 en hourly 1 The Building of Jetrecord: Episode 4: Cucumbers and Webrats! http://harrylove.org/2009/01/19/the-building-of-jetrecord-episode-4-cucumbers-and-webrats.html http://harrylove.org/2009/01/19/the-building-of-jetrecord-episode-4-cucumbers-and-webrats.html#comments Mon, 19 Jan 2009 22:07:26 +0000 Harry Love http://harrylove.org/?p=659

The message here is that with automated tests, we don’t have to worry about code being fragile. We can try out some stuff we think might work, and test it in seconds. We can be more courageous with our coding, and not have to code with cotton gloves on. — Test Driven Development

In the last episode I started my Rails code, committed it to a Git repository, and released my first deployment with Capistrano. In this episode I’m going to start my first feature by writing some tests and then implementing the code.

Cue film.

Download (right-click and save) QuickTime MOV (72 Mb) | QuickTime iPod MP4 (19 Mb) | QuickTime SMIL with captions (72 Mb) [Note: you must choose to open the SMIL file with QuickTime]

Adding RSpec, Cucumber, and Webrat to our Rails App

With the RSpec-Rails, Cucumber, and Webrat gems installed, let’s start a new branch in our Git repository and set up our app for testing:

$> git branch cucumber
$> git checkout cucumber
$> script/generate cucumber
$> script/generate rspec

Now edit RAILS_ROOT/features/support/env.rb. This file was created when we ran script/generate cucumber. We need to change a few lines. Here is what my env.rb file looks like after editing.

# Sets up the Rails environment for Cucumber
ENV["RAILS_ENV"] = "test"
require File.expand_path(File.dirname(__FILE__) + '/../../config/environment')
require 'cucumber/rails/world'
require 'cucumber/formatters/unicode' # Comment out this line if you don't want Cucumber Unicode support
Cucumber::Rails.use_transactional_fixtures
 
# Comment out the next two lines if you're not using RSpec's matchers (should / should_not) in your steps.
require 'webrat/rails'
require 'cucumber/rails/rspec'

We can add autotesting capability by installing the ZenTest gem. Autotest re-runs our tests after every code change, greatly speeding up our testing process. After getting the gem installed, we need to set some global variables so autotest knows to run our RSpec and Cucumber tests. Open up your .bash_profile file (usually located in your user’s home directory on your system). Add the following lines to the bottom of the file.

export RSPEC=true
export AUTOFEATURE=true

Additionally, if you’re on a Mac, I think it’s worth setting up Growl notifications for autotest. It’s not a requirement for testing or even using autotest but it’s a nice enhancement. Search Google for “autotest+growl” and you’ll find a number sites that will show you how to set it up.

Note: Growl notifications currently don’t work with Cucumber but they do work with RSpec and we will get into using RSpec eventually.

Let’s write a feature test to check our output from the last episode. If you remember, all we did was set up our home page to say “Hi.” I’m going to write a test to make sure it says that.

$> script/generate feature Page
      exists  features/step_definitions
      create  features/manage_pages.feature
      create  features/step_definitions/page_steps.rb

Open up the RAILS_ROOT/features/manage_pages.feature file. I’m writing my test like so:

Feature: First Test
  In order to prove that I can write a quick feature
  Harry
  wants to write a simple test
 
  Scenario: Friendly home page
    Given I am on the home page
    Then I should see "Hi."

Now I save that and run the test with rake:

$> rake features
(in /Users/harry/Sites/jetrecord)
Feature: First Test  # features/manage_pages.feature
  In order to prove that I can write a quick feature
  Harry
  wants to write a simple test
  Scenario: Friendly home page  # features/manage_pages.feature:6
    Given I am on the home page # features/manage_pages.feature:7
    Then I should see "Hi."     # features/step_definitions/webrat_steps.rb:83
 
1 scenario
1 step skipped
1 step pending (1 with no step definition)
 
You can use these snippets to implement pending steps which have no step definition:
 
Given /^I am on the home page$/ do
end

So the test ran but didn’t pass because I don’t have a step defined that tells Cucumber how to get to the home page. Thankfully, it gives me a snippet of code at the end of the output there. I open up RAILS_ROOT/features/step_definitions/page_steps.rb and add that in, filling it in with the code it needs to fulfill that step.

Given /^I am on the home page$/ do
  visit '/'
end

Quite simply, I’m telling Cucumber to visit the URL that looks like ‘/’, which is the home page. I run the test again.

$> rake features
(in /Users/harry/Sites/jetrecord)
Feature: First Test  # features/manage_pages.feature
  In order to prove that I can write a quick feature
  Harry
  wants to write a simple test
  Scenario: Friendly home page  # features/manage_pages.feature:6
    Given I am on the home page # features/step_definitions/page_steps.rb:1
      No route matches "/" with {:method=>:get} (ActionController::RoutingError)
      [stacktrace info]
 
1 scenario
1 step failed
1 step skipped
rake aborted!

Okay, we’re getting somewhere but we didn’t move very far. Cucumber barfed because it was looking for a route defined by the Rails application. Cucumber runs in the context of the Rails application, not of the whole site architecture. It doesn’t care that I have an index file in the public directory because it’s not actually crawling my web site like a browser would.

This is not necessarily a bad thing. If I wanted I could install Selenium, hook into it via Cucumber and re-run the tests. This would catch my index.html page because Selenium acts like a web browser. Eventually, I can see myself doing that because I’m going to need to test some Ajax interactions. But right now it’s not necessary.

In order to run my application I need to remove the index file anyway, so the real solution is to define my home page in Rails and then test again. To do that I need to add a route to my RAILS_ROOT/config/routes.rb file. Then I need to define the controller and a view for the home page.

# config/routes.rb
ActionController::Routing::Routes.draw do |map|
  map.root :controller => 'pages', :action => 'home'
end
# app/controllers/pages_controller.rb
class PagesController < ApplicationController
  def home
  end
end
# app/views/pages/home.html.erb
Hi.
# app/views/layouts/application.html.erb
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
  <head>
    <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
    <title>Hello</title>
  </head>
  <body>
    <%= yield %>
  </body>
</html>

Alright. One last thing. We need to rename or remove the public/index.html file. I’m just going to remove it. Then we try the test again.

$> git rm public/index.html
$> rake features
(in /Users/harry/Sites/jetrecord)
Feature: First Test  # features/manage_pages.feature
  In order to prove that I can write a quick feature
  Harry
  wants to write a simple test
  Scenario: Friendly home page  # features/manage_pages.feature:6
    Given I am on the home page # features/step_definitions/page_steps.rb:1
    Then I should see "Hi."     # features/step_definitions/webrat_steps.rb:83
 
1 scenario
2 steps passed

Bingo! Now let’s try running autotest.

$> autotest
loading autotest/cucumber_rails_rspec
/opt/ruby-enterprise-1.8.6-20080810/bin/ruby /opt/ruby-enterprise-1.8.6-20080810/lib/ruby/gems/1.8/gems/cucumber-0.1.15/bin/cucumber features --format progress --format autotest --color --out /var/folders/f1/f1HkdqHjFe43ByUhxU-FO++++TI/-Tmp-/autotest-cucumber.5265.0 
..

Great! It’s working. Two passing steps (the two dots at the end) and autotest is still running, waiting for me to do something stupid. I’m going to introduce an error into home.html.erb.

# app/views/pages/home.html.erb
Hello.

And then back to the terminal.

/opt/ruby-enterprise-1.8.6-20080810/bin/ruby /opt/ruby-enterprise-1.8.6-20080810/lib/ruby/gems/1.8/gems/cucumber-0.1.15/bin/cucumber features --format progress --format autotest --color --out /var/folders/f1/f1HkdqHjFe43ByUhxU-FO++++TI/-Tmp-/autotest-cucumber.5265.1 
.F
 
Failed:
 
1)
expected: /Hi./m,
     got: "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n        \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">\n<html>\n  <head>\n    <meta http-equiv=\"Content-type\" content=\"text/html; charset=utf-8\" />\n    <title>Hello</title>\n    \n  </head>\n  <body>\n    Hello.\n  </body>\n</html>" (using =~)
Diff:
@@ -1,2 +1,2 @@
-/Hi./m
+"<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n        \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">\n<html>\n  <head>\n    <meta http-equiv=\"Content-type\" content=\"text/html; charset=utf-8\" />\n    <title>Hello</title>\n    \n  </head>\n  <body>\n    Hello.\n  </body>\n</html>"
 
[stacktrace info]
 
./features/step_definitions/webrat_steps.rb:84:in `Then /^I should see "(.*)"$/'
features/manage_pages.feature:8:in `Then I should see "Hi."'

And that’s how it works. We write a test, it fails, we write some code to pass the test, it passes.

I have to apologize. This post has already become too long. I like the direction it took but I don’t think moving on to writing an actual Jetrecord feature would be wise right now. So, really, next time I’m going to write tests for the first feature. I’ll even include some RSpec in there.

Coming Up in the Next Episode

No more rhymes now, I mean it. I’m going to write some tests for the first feature. Until next time, cheers and happy flying.

Material You May Find Useful Related to This Episode

Cucumber: Behaviour Driven Development with elegance and joy

Creative Commons License The Building of Jetrecord by Harry Love is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License. When code, text, or media in this series is not created by me and is not in the public domain I will provide links to their sources from which you can find their respective licenses and terms of use.

]]> http://harrylove.org/2009/01/19/the-building-of-jetrecord-episode-4-cucumbers-and-webrats.html/feed 5 The Building of Jetrecord: Episode 3: Git, Capistrano, and A Test Release http://harrylove.org/2009/01/12/the-building-of-jetrecord-episode-3-git-capistrano-and-a-test-release.html http://harrylove.org/2009/01/12/the-building-of-jetrecord-episode-3-git-capistrano-and-a-test-release.html#comments Mon, 12 Jan 2009 16:08:48 +0000 Harry Love http://harrylove.org/?p=598

What Mayer thinks will be essential for continued innovation is for Google to keep its sense of fearlessness. “I like to launch [products] early and often. That has become my mantra,” she says. She mentions Apple Computer and Madonna. “Nobody remembers the Sex Book or the Newton. Consumers remember your average over time. That philosophy frees you from fear.” — Managing Google’s Idea Factory

In the last episode I briefly sketched out what I want to build. In this episode I’m going to start the project by creating a Git repository and deploying a test release with Capistrano.

Cue film.

Download (right-click and save) QuickTime MOV (74 Mb) | QuickTime iPod MP4 (9 Mb) | QuickTime SMIL with captions (74 Mb) [Note: you must choose to open the SMIL file with QuickTime]

A Few Quick Changes

First, I changed my mind about setting up the complicated user management system from the beginning. I realized that I would be violating one of the tenets of Agile/XP: YAGNI. It reminds us to keep focused on the current feature and save details of any related features for the stories that describe them. Flights don’t need to know about the implementation details of users. Therefore, I’m only going to worry about flights for the time being. When called for I will stub out a User model, authentication, et cetera.

Second, I forgot to add a couple gems that will help us write stories and integration tests: Webrat and FactoryGirl. Webrat is a library for writing tests that crawl your site in memory, visiting links, testing inputs, submitting forms, and so on. FactoryGirl is a library that replaces test fixtures with factories. You can install both with RubyGems. We’re not going to need them until the next episode; I just wanted to mention them now.

Some Conventions

  • $> is the command line prompt. Anything coming after it is a command that I’m typing into my terminal.
  • RAILS_ROOT is the root directory of the Rails app.
  • REMOTE is my remote server

Starting the Rails App

Depending on your personality this is either the best part of the project or the worst: the blank canvas. You installed Rails and all of the prerequisites I listed in episode 2. All of our hopes and dreams for a perfect app begin with this command:

$> rails jetrecord

I have set up my development environment to use Apache + Passenger to serve the site and have configured a virtualhost on my local machine to use “ld.com” for the site. (It doesn’t matter if ld.com actually exists or not. As far as my machine is concerned, it points to my local Rails app.) If you’re using Mongrel, Webrick, Thin, or something else as your development server you can run script/server from the RAILS_ROOT.

Since I’m using Apache and I’ve set it to launch at boot time I don’t need to use script/server. I can just browse to ld.com. When I do, I see this.

Rails app home screen for Jetrecord

Great! We’re off and running.

Setting Up Our Repository with Git

Git is installed on my machine. To make a repository, I cd to RAILS_ROOT and do this:

$> git init
Initialized empty Git repository in /Users/harry/Sites/jetrecord/.git/
 
$> git status
# On branch master
#
# Initial commit
#
# Untracked files:
#   (use "git add ..." to include in what will be committed)
#
#	README
#	Rakefile
#	app/
#	config/
#	doc/
#	log/
#	public/
#	script/
#	test/
nothing added to commit but untracked files present (use "git add" to track)

If I run git add right now, Git will recursively add everything in RAILS_ROOT to the repository. But I don’t want that. There are a few items I don’t want to track. To have Git automatically ignore those items, I will create a .gitignore file. Each line tells Git what to ignore.

$> nano -w .gitignore                                                                 
 
config/database.yml
*~
*.cache
*.log
*.pid
tmp/**/*
.DS\_Store
db/cstore/**
doc/*.dot
doc/api
doc/app
doc/plugins
coverage/*
db/*.sqlite3
*.tmproj
Capfile

I save that file. Now I add everything to the repository and make the initial commit.

$> git add .
$> git commit -m "First commit"
 
Created initial commit 4d55351: First commit
 46 files changed, 8525 insertions(+), 0 deletions(-)
 create mode 100644 .gitignore
 create mode 100644 README
 create mode 100644 Rakefile
 create mode 100644 app/controllers/application.rb
 create mode 100644 app/helpers/application_helper.rb
 create mode 100644 config/boot.rb
 create mode 100644 config/environment.rb
 create mode 100644 config/environments/development.rb
 create mode 100644 config/environments/production.rb
 create mode 100644 config/environments/test.rb
 create mode 100644 config/initializers/inflections.rb
 create mode 100644 config/initializers/mime_types.rb
 create mode 100644 config/initializers/new_rails_defaults.rb
 create mode 100644 config/locales/en.yml
 create mode 100644 config/routes.rb
 create mode 100644 doc/README_FOR_APP
 create mode 100644 public/404.html
 create mode 100644 public/422.html
 create mode 100644 public/500.html
 create mode 100755 public/dispatch.cgi
 create mode 100755 public/dispatch.fcgi
 create mode 100755 public/dispatch.rb
 create mode 100644 public/favicon.ico
 create mode 100644 public/images/rails.png
 create mode 100644 public/index.html
 create mode 100644 public/javascripts/application.js
 create mode 100644 public/javascripts/controls.js
 create mode 100644 public/javascripts/dragdrop.js
 create mode 100644 public/javascripts/effects.js
 create mode 100644 public/javascripts/prototype.js
 create mode 100644 public/robots.txt
 create mode 100755 script/about
 create mode 100755 script/console
 create mode 100755 script/dbconsole
 create mode 100755 script/destroy
 create mode 100755 script/generate
 create mode 100755 script/performance/benchmarker
 create mode 100755 script/performance/profiler
 create mode 100755 script/performance/request
 create mode 100755 script/plugin
 create mode 100755 script/process/inspector
 create mode 100755 script/process/reaper
 create mode 100755 script/process/spawner
 create mode 100755 script/runner
 create mode 100755 script/server
 create mode 100644 test/performance/browsing_test.rb
 create mode 100644 test/test_helper.rb

The application is now being tracked by Git. One last thing before we move on to Capistrano. I’m going to change the default index page to show a simple “Hello, World.” I’m using TextMate, which is the reason for the mate command.

$> mate public/index.html

All I did was replace the dynamic stuff on the home page with “Hi.” You’ll see it in a minute. Alright. That’s all I’m going to do for the first release. Now I need to move the repository to a remote location so I can pull from it when I release new code.

$> ssh REMOTE
REMOTE $> mkdir etc/git/jetrecord.git
REMOTE $> cd etc/git/jetrecord.git
REMOTE $> git init --bare
Initialized empty Git repository in /home/user/etc/git/jetrecord.git/
REMOTE $> exit
Connection closed
 
$> git remote add origin ssh://user@REMOTE/home/user/etc/git/jetrecord.git
$> git push origin master
Counting objects: 68, done.
Compressing objects: 100% (61/61), done.
Writing objects: 100% (68/68), 80.67 KiB, done.
Total 68 (delta 17), reused 0 (delta 0)
To ssh://user@REMOTE/home/user/etc/git/jetrecord.git
 * [new branch]      master -> master

Good. Now I have a remote Git repository. Any changes that I push will go to this remote location that will also be accessible to Capistrano. And so we move on to Capistrano.

Capistrano

I have the Capistrano gem installed. I just need to initialize it for my app and then fix up my deployment recipe.

$> capify .
[add] writing './Capfile'
[add] writing './config/deploy.rb'
[done] capified!
 
$> mate config/deploy.rb

Here’s my deploy.rb

set :use_sudo, false
set :application, "jetrecord"
set :repository,  "ssh://user@REMOTE/home/user/etc/git/jetrecord.git"
set :deploy_to, "/var/www/apps/#{application}"
set :user, 'user'
set :runner, user
set :scm, :git
set :domain, 'REMOTE'
role :app, domain
role :web, domain
role :db,  domain, :primary => true
set :server_name, "landingdeparting.com"
set :server_alias, "*.landingdeparting.com"
depend :remote, :command, :gem
 
# Allow ssh to use ssh keys
set :ssh_options, { :forward_agent => true }
 
deploy.task :restart do
  # Restart Passenger
  run "touch #{current_path}/tmp/restart.txt"
end
 
deploy.task :symlinks do
  run "ln -nfs #{shared_path}/config/database.yml #{release_path}/config/database.yml"
end
 
after :deploy, 'deploy:cleanup'
after 'deploy:update_code', 'deploy:symlinks'

Cool. Commit the changes.

$> git add .
$> git commit -a -m "First stab at Capistrano deployment recipe"
Created commit e80f9dc: First stab at Capistrano deployment recipe
 1 files changed, 28 insertions(+), 0 deletions(-)
 create mode 100644 config/deploy.rb
 
$> git push
Counting objects: 6, done.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 775 bytes, done.
Total 4 (delta 2), reused 0 (delta 0)
To ssh://user@REMOTE/home/user/etc/git/jetrecord.git
   ba68814..e80f9dc  master -> master

Okay, one more thing on the remote end. In my deploy recipe I added a symlink from the database.yml file in the shared directory to the RAILS_ROOT/config directory. I’m doing this because I don’t want to track database.yml in my Git repository and it’s cheaper to create a symlink than to copy an actual file from one release to the next. But I still need to create the file manually. I’ll do that now.

$> ssh REMOTE
REMOTE $> mkdir /var/www/apps/jetrecord
REMOTE $> mkdir /var/www/apps/jetrecord/shared
REMOTE $> mkdir /var/www/apps/jetrecord/shared/config
REMOTE $> nano -w /var/apps/jetrecord/shared/config/database.yml
 
production:
  adapter: postgresql
  database: jetrecord_production
  user: dbuser
  password: pass
  pool: 5
  timeout: 5000

Save and exit. Don’t forget to set up the actual database on the remote server with the correct credentials!

With that done, all that’s left to do is make sure my domain name is set up and ready to be seen by the world. This will depend on a great number of things, such as where your site is hosted, what operating system it’s on, what DNS services you’re using, and so on.

I’m not a sysadmin and I’m not going to pretend to be one. The focus of this series is the application so I’ll move on assuming that we’ve got our domain set up and we’ve tested that we can reach the site with a text index page of some kind.

Now we’ll run the setup command, check our deployment recipe, and then do a deploy. For the deploy I’m going to run cap:deploy instead of cap:deploy:cold because I don’t have any database migrations to run yet.

$> cap deploy:setup
  * executing 'deploy:setup'
  * executing "mkdir -p /var/www/apps/jetrecord /var/www/apps/jetrecord/releases /var/www/apps/jetrecord/shared /var/www/apps/jetrecord/shared/system /var/www/apps/jetrecord/shared/log /var/www/apps/jetrecord/shared/pids &#038;&  chmod g+w /var/www/apps/jetrecord /var/www/apps/jetrecord/releases /var/www/apps/jetrecord/shared /var/www/apps/jetrecord/shared/system /var/www/apps/jetrecord/shared/log /var/www/apps/jetrecord/shared/pids"
    servers: ["REMOTE"]
    [REMOTE] executing command
    command finished
 
$> cap deploy:check
  * executing 'deploy:check'
  * executing "test -d /var/www/apps/jetrecord/releases"
    servers: ["REMOTE"]
    [REMOTE] executing command
    command finished
  * executing "test -w /var/www/apps/jetrecord"
    servers: ["REMOTE"]
    [REMOTE] executing command
    command finished
  * executing "test -w /var/www/apps/jetrecord/releases"
    servers: ["REMOTE"]
    [REMOTE] executing command
    command finished
  * executing "which git"
    servers: ["REMOTE"]
    [REMOTE] executing command
    command finished
  * executing "which gem"
    servers: ["REMOTE"]
    [REMOTE] executing command
    command finished
You appear to have all necessary dependencies installed
 
$> cap deploy
  * executing 'deploy'
  * executing 'deploy:update'
 ** transaction: start
  * executing 'deploy:update_code'
    executing locally: "git ls-remote ssh://user@REMOTE.joyent.us/home/user/etc/git/jetrecord.git HEAD"
  * executing "git clone -q ssh://user@REMOTE/home/user/etc/git/jetrecord.git /var/www/apps/jetrecord/releases/20090108224035 &#038;& cd /var/www/apps/jetrecord/releases/20090108224035 &#038;& git checkout -q -b deploy dbd8430254cd5bd2860c2b73349c149b1038512f &#038;& (echo dbd8430254cd5bd2860c2b73349c149b1038512f > /var/www/apps/jetrecord/releases/20090108224035/REVISION)"
    servers: ["REMOTE"]
    [REMOTE] executing command
    command finished
  * executing 'deploy:finalize_update'
  * executing "chmod -R g+w /var/www/apps/jetrecord/releases/20090108224035"
    servers: ["REMOTE"]
    [REMOTE] executing command
    command finished
  * executing "rm -rf /var/www/apps/jetrecord/releases/20090108224035/log /var/www/apps/jetrecord/releases/20090108224035/public/system /var/www/apps/jetrecord/releases/20090108224035/tmp/pids &#038;&\\\n      mkdir -p /var/www/apps/jetrecord/releases/20090108224035/public &#038;&\\\n      mkdir -p /var/www/apps/jetrecord/releases/20090108224035/tmp &#038;&\\\n      ln -s /var/www/apps/jetrecord/shared/log /var/www/apps/jetrecord/releases/20090108224035/log &#038;&\\\n      ln -s /var/www/apps/jetrecord/shared/system /var/www/apps/jetrecord/releases/20090108224035/public/system &#038;&\\\n      ln -s /var/www/apps/jetrecord/shared/pids /var/www/apps/jetrecord/releases/20090108224035/tmp/pids"
    servers: ["REMOTE"]
    [REMOTE] executing command
    command finished
  * executing "find /var/www/apps/jetrecord/releases/20090108224035/public/images /var/www/apps/jetrecord/releases/20090108224035/public/stylesheets /var/www/apps/jetrecord/releases/20090108224035/public/javascripts -exec touch -t 200901082240.37 {} ';'; true"
    servers: ["REMOTE"]
    [REMOTE] executing command
    command finished
    triggering after callbacks for 'deploy:update_code'
  * executing 'deploy:symlinks'
  * executing "ln -nfs /var/www/apps/jetrecord/shared/config/database.yml /var/www/apps/jetrecord/releases/20090108224035/config/database.yml"
    servers: ["REMOTE"]
    [REMOTE] executing command
    command finished
  * executing 'deploy:symlink'
  * executing "rm -f /var/www/apps/jetrecord/current &#038;& ln -s /var/www/apps/jetrecord/releases/20090108224035 /var/www/apps/jetrecord/current"
    servers: ["REMOTE"]
    [REMOTE] executing command
    command finished
 ** transaction: commit
  * executing 'deploy:restart'
  * executing "touch /var/www/apps/jetrecord/current/tmp/restart.txt"
    servers: ["REMOTE"]
    [REMOTE] executing command
    command finished
    triggering after callbacks for 'deploy'
  * executing 'deploy:cleanup'
  * executing "ls -xt /var/www/apps/jetrecord/releases"
    servers: ["REMOTE"]
    [REMOTE] executing command
    command finished
 ** keeping 5 of 6 deployed releases
  * executing "rm -rf /var/www/apps/jetrecord/releases/20090108222452"
    servers: ["REMOTE"]
    [REMOTE] executing command
    command finished

Okay, done. Now we check to see if landingdeparting.com shows my Rails app.

LD says 'hi'

So that’s it. We have our Rails project started. We have our source code in a Git repository. We can deploy the app to our server with Capistrano. And we can view our handiwork live on the web. Now it’s time to build the real application. We’ll take it bird by bird.

Epilogue

From now on when I type something into the terminal I’m only going to show the output of the command if I think it’s relevant for the topic of the episode. In this episode, for instance, I set up Git and Capistrano and I thought it would be good to see how these programs respond. In future episodes I’m not going to show output from Git or Capistrano unless it’s relevant.

I’m going to follow the same general rule for other commands. If it’s relevant to the topic at hand or if a special case needs to be addressed, I’ll show it. Otherwise, I’ll only show the commands I type in. You can also assume that I am making regular commits to git and pushing those changes live with Capistrano. I don’t intend to show you every commit message and the result of every deployment here in the text unless there’s a special case. Some of these things may show up in the videos, but they get a little tedious here. Does that make sense? Each episode will build on previous episodes with regards to the minutiae that I share.

Coming Up in the Next Episode

I’m going to start building the first feature by writing some tests and then writing the code that implements the feature. Until next time, cheers and happy flying.

Material You May Find Useful Related to This Episode

Git: the fast version control system

Capistrano

Phusion Passenger

Pragmatic Version Control Using Git by Travis Swicegood

Deploying Rails Applications by Ezra Zygmuntowicz, Bruce Tate, and Clinton Begin

Creative Commons License The Building of Jetrecord by Harry Love is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License. When code, text, or media in this series is not created by me and is not in the public domain I will provide links to their sources from which you can find their respective licenses and terms of use.

]]> http://harrylove.org/2009/01/12/the-building-of-jetrecord-episode-3-git-capistrano-and-a-test-release.html/feed 1 The Building of Jetrecord: Episode 2: Tell Me a Story http://harrylove.org/2008/10/29/the-building-of-jetrecord-episode-2-tell-me-a-story.html http://harrylove.org/2008/10/29/the-building-of-jetrecord-episode-2-tell-me-a-story.html#comments Wed, 29 Oct 2008 21:08:29 +0000 Harry Love http://harrylove.org/?p=561

Sketches are quick, dirty, and cheap and that’s exactly how you want to start out. Draw stuff. Scrawl stuff. Boxes, circles, lines. Get your ideas out of your head and onto paper. The goal at this point should be to convert concepts into rough interface designs. This step is all about experimentation. There are no wrong answers. — From Idea to Implementation — Getting Real

In the last episode I talked about high level goals for the project and I created a framework of rules for myself in order to help me make decisions. In this episode I’m going to follow one of the rules I created for myself:

11. Each feature must begin with a story discussing the feature and its impact, followed by sketches of APIs and GUIs, followed by test coverage, followed by implementation.

Cue film.

Download (right-click and save) QuickTime MOV (39 Mb) | QuickTime iPod MP4 (8 Mb) | QuickTime SMIL with captions (39 Mb) [Note: you must choose to open the SMIL file with QuickTime]

Am I Building the Right Thing?

One of the questions we ended with last time was, “How do I know that what I’m building is what people really want?” The answer is: ask them.

I’m going to follow a principle from Extreme Programming that says you should have a customer on site with you as you build. If you can’t get a real customer, one of you has to play the role of Customer. That means I’m going to play the customer for my own application.

Is this legal? Yes and no. Under ideal circumstances the customer should be someone who is not a developer because features are a business decision, not a programming decision. Really, it should be the client paying for the engagement or, in the case of retail software, someone from the business side of your organization who is familiar with the domain and the needs of your customers. By playing both roles there’s a possibility that competing demands will cloud the judgment either of the Developer role or the Customer role.

At the same time, I’m a customer of Jetrecord. At least, I plan to be. So in a sense I’m building software for myself, so perhaps the two conflicts cancel each other out.

In any case I don’t have a choice.

Why Agile (or something like it)?

In my limited experience as a developer I’ve come to discover that programming is simply a conversation you have with your code. Just like writing an article, it may begin on one topic and end up on something completely different. Thinking about programming this way fits my personality and the way I learn new things. I love things that grow and take on a life of their own. I also like to look at the big picture several times during the course of a project. If I keep my head down for too long it’s easy to get lost in the details and pretty soon I’ve veered off course.

Certainly every circumstance is different and you have to adjust for the needs of the project. Agile, Extreme Programming, and the like don’t work for everything. When the choice is up to me, though, and the type of engagement is a good fit, I like the communication, freedom, and feeling of progress Agile affords.

And, of course, let’s remember that I’m not following Agile methodologies to the letter. I’m using methods that will help me get the project done reasonably and responsibly. I believe this follows the spirit of Agile, if nothing else.

Assembling B-25 bombers at North American Aviation

The Basic Features

The customer’s job is to define the features of the application. Here they are in broad terms:

  1. Log flights
  2. Visualize flights and hours
  3. Export flights

I’m not going to worry about advanced and/or paying features yet. We’ll save those for later. If I don’t get these basic features right, there’s no point moving forward. These are the features that I, the Customer, believe bring the most value to the application at this point in the project.

Creating Stories

An Agile feature story is a “promise for conversation” according to Alistair Cockburn. That means, it’s important to get it down on paper so that we, the customer and developer, can talk about it at length later on. I’ll make sketches and write tests based on the stories I create. As for detail, I’m going to shoot for making each story completable in the span of one to two weeks, including tests.

Logbook Feature Stories

  • Users can log flights via a simple form
  • Users can log flights via a table/spreadsheet form, similar to paper logbooks
  • Users can log flights by importing CSV files from other logbook software
  • Users can log flights via authenticated API
  • Users can see tallies of their flights and hours, separated into categories of experience and aircraft
  • Users can export flights via RSS, JSON, XML, and a number of CSV formats based on the same logbook software supported by the import feature

Discussion

That’s enough to start. None of these have enough detail to tell me everything I need to know about the feature but they help me start conversations with the customer. They also tell me that there are some fundamental features that need to be developed in order support the ones listed. I would look at this list and begin discussing the following:

  • What fields are included in a flight? Are any of them required?
  • Please attach copies of example pages from a traditional paper logbook.
  • Which third-party logbook software should be supported? Please attach examples of the CSV output created by the software.

Also, we’ve talked about flights, but flights belong to users. That means we need a system in place for managing users and their needs.

  • What is required for someone to become a registered user?
  • How are users identified? By ID, by login, by real name, by nickname?
  • Do users manage themselves for things like registration, password changes and recoveries? How much intervention is required by admins?
  • Can users delete their own accounts? And what happens to everything they’ve created on the site when they do?
  • What about multi-user accounts? How are they managed? What happens to a user if the account they were associated with closes down?

New B-25 bombers lined up for final inspection

User Feature Stories

  • Users can self-register and manage every aspect of their account, including paying for services and deleting the account, without intervention by an admin. Since email is the only method used to communicate with members, email is required to signup. Users must verify their email in order to begin using their accounts. Users are identified on the web site by their nickname. Users should receive email notification upon successful signup.
  • Users can login from the web site or from third party applications.
  • When users delete their accounts, all of their flights are deleted, followed by any aircraft used (assuming they’re the only pilot of the aircraft), followed by any routes used (assuming they’re the only pilot of that route), followed by their user account and any associated files. Users should receive email notification that their account has been deleted.
  • Accounts with more than one user have certain admin users who manage the account, including payment details. Admins can manage permissions for other members and invite and kick members.
  • When multi-user accounts are deleted by an admin, associated users will have the option to continue paying for features at the same level, upgrade to higher paying options, downgrade to lower paying or free options with features removed, or have their accounts deleted.

Discussion

It looks like we need a fairly complicated user management system in addition to being able to log flights. Ideally, with a larger team, we could work on both at the same time. However, since it’s only me, and since I’m also the customer, I’ve decided that the user management system is the first thing I’ll do after setting up my development and production environments.

Sketches

Again, these are sketches. Not blueprints or wireframes. Not schematics or Photoshop comps. They have just enough detail to let me know what I’m building so I can begin creating HTML mockups, acceptance tests, and unit tests. Ideally, as the developer, I’m drawing these while seated next to the customer so we can make changes quickly and throw things away if need be.

Flight Forms

Flight forms sketch

User Forms

User forms sketch

User API

User API sketch

Inventory

At this point I should be able to take the sketches and start building the application using whatever language I choose. I had a great time using the Ruby on Rails framework to build version 1 and I’ve decided to use it again for version 2. It’s well-suited to handle an application of this type and the Ruby language is, for lack of a better word, fun.

These are the things I need to get going (note: gems are installed with RubyGems):

Optional: Ruby on Rails comes with a simple web server that we can use for development purposes. However, I’m going to set up and practice using the server that I will use in production, even though the OS will be different:

I’m not going to cover installation. I assume you can follow the instructions given on their respective web sites and that you know how to use Google. Assuming you’re going to follow along as I write code, if you’ve never worked with Rails before I recommend installing everything and working through any of the simple tutorials you can find on the web before continuing on.

Also, please note, from here on out I’m not going to talk about the topic of programming per se. If you’ve never programmed before, the rest of the series might be interesting to watch but otherwise might go over your head. Let me say, though, that there are hundreds of web-based tutorials that can teach you how to program. There are even some that use Ruby.

Coming Up in the Next Episode

I’m going to set up my Rails project and my Git source code repository. Then I’m going to make sure I can do an initial release. Until next time, cheers and happy flying.

Material You May Find Useful Related to This Episode

Extreme Programming Installed book cover Extreme Programming Installed by Ron Jeffries

Designing Interfaces book cover Designing Interfaces by Jenifer Tidwell

Universal Principles of Design book cover Universal Principles of Design by William Lidwell

Moleskine notebook Moleskine Storyboard Notebook Pocket

Creative Commons License
The Building of Jetrecord by Harry Love is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License. When code, text, or media in this series is not created by me and is not in the public domain I will provide links to their sources from which you can find their respective licenses and terms of use.

]]> http://harrylove.org/2008/10/29/the-building-of-jetrecord-episode-2-tell-me-a-story.html/feed 5 The Building of Jetrecord: Episode 1: The Tabula Rasa of Doom http://harrylove.org/2008/10/15/the-building-of-jetrecord-episode-1-the-tabula-rasa-of-doom.html http://harrylove.org/2008/10/15/the-building-of-jetrecord-episode-1-the-tabula-rasa-of-doom.html#comments Wed, 15 Oct 2008 13:58:34 +0000 Harry Love http://harrylove.org/?p=516

We were out at our family cabin in Bolinas, and he was at the kitchen table close to tears, surrounded by binder paper and pencils and unopened books on birds, immobilized by the hugeness of the task ahead. Then my father sat down beside him, put his arm around my brother’s shoulder, and said, “Bird by bird, buddy. Just take it bird by bird.” –Anne Lamott

I don’t think any of us ever realizes the hugeness of the task until we sit down with our materials and attempt to make sense of it all, even though the whole making-order-out-of-chaos thing is highly overrated in my opinion. Nevertheless, that’s what I’m going to do here in this series. I’m going to take a seemingly simple task–building an online logbook for pilots–expose the underbelly, cut it apart, and then put it all together into a fantastic, cohesive product that everyone will love, including me and you and every pilot you know.

Why? Because I believe we are created to do two things: experience pain and build things. Sometimes these are one and the same. I hate to admit right from the start that this is a task to which I feel compelled, by which I feel repulsed, and about which I feel nonplussed but apparently we’re in a new age of transparency so I’m starting with me, as Michael Jackson would say. I both love and hate computers and projects. And it always happens that about the time I’ve finished a web project I’ve forgotten all about this crummy beginning stage and am strangely excited to do it all over again.

Cue film.

Download (right-click and save) QuickTime MOV (49 Mb) | QuickTime iPod MP4 (7 Mb) | QuickTime SMIL with captions (49 Mb) [Note: you must choose to open the SMIL file with QuickTime]

It Begins Like This

  1. I’m building version 2 of an online logbook for pilots called Jetrecord. This is my attempt to record and share the process.
  2. This is not an exercise (please place your hands inside the yellow circles); it’s the process of building a genuine application that is already live on the web. What you see here is what will be released for version 2. I’m hoping that by sharing something real you’ll be inspired to create your own projects and you’ll see what it’s like for one developer to wade through this stuff.
  3. As far as sharing goes you are free to take the code, the text of this series, and the videos and reuse, repurpose, and remix them under the terms of the Creative Commons Attribution-Share Alike 3.0 United States License. More details are at the end of this post.
  4. My other hope is that we can learn from each other. I am not an expert, as will become more apparent as the series goes on. Please contribute your knowledge in the comments. Can something be improved? Do you have a suggestion or a critique? I want to hear it. Please keep it constructive, though. Shuriken are not allowed.
  5. If you’d like to contact me by email concerning the series, use harry@harrylove.org.

The Scope of the Series

The process of creating a web application from start to finish involves several subjects and my plan is to explore breadth rather than depth. That is, I’m going to talk about whatever will help me complete the project and I’ll mostly concentrate on the places where subjects overlap. If I don’t explain things in enough detail, I apologize. The truth is I may not know enough about a subject to explore it in depth. I’ll try to point you to the places I’m getting my information. Don’t hesitate to speak up if you’d like me to say more about a particular topic. If I have something more to say, something worth creating a new episode for, I may just do it. Otherwise, of course, I’ll point you to my sources.

Let’s Start with Questions, Goals, and Rules

I’m going to start this project the same way I would approach an essay, article, or presentation, by asking questions and then stating goals and rules. You don’t have to do it this way. This is how I do it because it works for me. I’m going to say that just once. It applies to everything I’m going to do from here on out but I don’t want to bore you to death by repeating myself every episode (there’s an important programming principle in there somewhere).

Nose wheel and landing gear assembly

Questions

  • What do I want to build?
    • I want to build a web-based logbook for pilots.
  • Why do I want to build it?
    • I love aviation, data, and the connections made when data cross paths.
    • I am building this because it’s a product that I myself will use.
    • I have surveyed the available logbook software, both desktop- and web-based, and have not seen any that use the same approach to building logbooks that I’m using to build Jetrecord.
    • I believe this is a product that can work in concert with existing desktop- and web-based products.
  • Is this an art project or do I need to consider my audience?
    • It’s both, but I am building this product for public consumption so I need to consider my audience.
  • Who are the primary people groups in my audience?
    • Pilots
    • Air and ground crew
    • Affiliates
    • Aviation buffs
    • Their family and friends
  • Do these people need this software? Why should they care?
    • Pilots must show proof to governing authorities that they have obtained any necessary knowledge and flying experience. Logbooks have been the standard method for recording flying experience for several decades.
    • The second two groups may have business concerns with the logbooks but will otherwise not need a logbook of their own.
    • The last group is important to consider because the entry of each flight will be made public, suitable for sharing with family and friends in the same way that family and friends share news, pictures, and video through blogs.
  • Can I afford to build it?
    • The operating system, programming language, web framework, web server, and database server I am using are all available under open source licenses.
    • I have a computer that is well suited for the purpose of building a web application using this software.
    • I have some good software to edit the code and some to create and edit graphics for the web site.
    • The web application is currently hosted at Joyent using the $125 per month Accelerator option and there is room to grow using the current resource limits; there are both horizontal and vertical scaling options available at Joyent should the application outgrow its resources.
    • My company bank account is free but I may need to switch to a paying account if Jetrecord becomes very popular to the point of making more than a few hundred deposits per month.
    • The merchant account and credit card processing fees per month have been quoted from a reputable business at less than $50 per month.
    • The cost of doing business in Longmont, Colorado as a Sole Proprietor is a small annual fee.
    • I have access to help in preparing my taxes.
  • Can I afford to maintain it and keep it running for years to come?
    • If the current ongoing fees are any indication, the answer is yes. Obviously, in the best case scenario, if Jetrecord suddenly jumps from 1,000 users to 100,000 I will need to upgrade the servers a bit. I may also need additional partners or staff to help manage the workload.
  • Do I have enough domain knowledge to build it?
    • I have enough knowledge about aviation and logbooks to make a good product.
    • I have already built version 1 and it has been well received by the pilots who use it, including both general and commercial pilots.
  • Do I have access to information about the domain?
    • I have access to the FAA’s regulations concerning logbooks through their web site and also via the FAR/AIM book.
    • There are many web sites, magazines, and books that focus on issues concerning pilots and aviation.
  • Do I have access to customers and are they willing to teach me about the domain?
    • I have access to the current users of the product.
    • I am in contact with several pilots through Twitter and myTransponder.
    • I have spoken with several pilots over the phone who have expressed interest in helping me.

Goals

Succinctly and broadly, what is the desired end state? For example, the goal of basketball is to have more points than your opponent at the end of the allotted time for the game.

  • The logbook is the key application, regardless of any related features.
  • It must be as easy as possible to get data into and out of the system both from within the Jetrecord web site and from the developer API.
  • It must be as useful as possible to as many classifications of pilots as possible, but focus on general and commercial aviation.

P-51 Mustang

Mantra

Pilots Aren’t Robots Yet!

Rules

I’m writing some rules for myself that will serve as a guide for the decisions I make. They are written with this project in mind only.

  1. Rules should help us make decisions; this is the only criteria for adding a rule.
  2. Modify or discard any rules that are not helpful.
  3. Use the best design principles we know how to use and spend time researching concepts we are unfamiliar with.
  4. Make forward progress; no product is perfect.
  5. Follow the spirit of Agile methods for software development; remember rule #2 above
  6. Keep documentation in the source code except where sensitive information may compromise security or business secrets.
  7. Documentation is for developers and is an interface into the system; design it well.
  8. Everything should be added to the source control repository unless there is a good reason not to.
  9. Code that can be extracted into a shared library (gem) or plugin should be.
  10. Favor gems, plugins, other libraries, and framework code to writing our own unless there is a good reason not to.
  11. Each feature must begin with a story discussing the feature and its impact, followed by sketches of APIs and GUIs, followed by test coverage, followed by implementation.
  12. Metrics should be built into the project early and often.
  13. Questions drive the need for answers which drive the need to record data, not the other way around.
  14. Build for data access first and GUI display second.
  15. Build for universal access.
  16. Build for progressive enhancement.
  17. Browsers must prove their worth to be included in our support; mainstream use is not proof in and of itself.
  18. See also Matthew Moore’s Ruby on Rails Code Quality Checklist; remember rule #2 above

Coming Up in the Next Episode

Next I’m going to write a brief outline of the basic application. I’m also going to sketch the application on paper and make a list of parts I need to get started. I hope you’ll join me. You can subscribe to the RSS feed in order to be notified when the next episode is up. I have also created a table of contents page for this series. Until next time, cheers and happy flying.

Material You May Find Useful Related to This Episode

Art of the Start book cover The Art of the Start by Guy Kawasaki

Bird by Bird book cover Bird by Bird by Anne Lamott

The Spirit of St. Louis book cover The Spirit of St. Louis by Charles Lindbergh

Building Scalable Web Sites book cover Building Scalable Web Sites by Cal Henderson

Getting Real by 37signals

List of software development philosophies on Wikipedia

Creative Commons License
The Building of Jetrecord by Harry Love is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License. When code, text, or media in this series is not created by me and is not in the public domain I will provide links to their sources from which you can find their respective licenses and terms of use.

]]> http://harrylove.org/2008/10/15/the-building-of-jetrecord-episode-1-the-tabula-rasa-of-doom.html/feed 8 Google Sitemaps with Ruby on Rails, Capistrano, and Cron http://harrylove.org/2008/06/10/google-sitemaps-with-ruby-on-rails-capistrano-and-cron.html http://harrylove.org/2008/06/10/google-sitemaps-with-ruby-on-rails-capistrano-and-cron.html#comments Tue, 10 Jun 2008 23:51:15 +0000 Harry Love http://harrylove.org/?p=374 This is a slight modification of code originally written by Alastair Brunton. I recently implemented this for Jetrecord and since Alastair was so generous, I decided to share the love as well. I have changed Alastair’s code to generate a sitemap index file plus sitemap files for each model, all of them gzipped to save on bandwidth.

I have also added Capistrano code to copy sitemap files from the previous release to the current release so we don’t lose our sitemap files when we deploy a new release.

Remember, Google sitemaps are for publicly available URLs. They’re for pages that you want Google to find and index. If you don’t want Google to find your CIA Operatives records, don’t tell Google about it!

Let’s just go straight to the code. I am going from the top down in my application’s root directory.

app/models/your_model.rb

You must add this code to each model that you want to generate a sitemap for. Here is an example for Airports on Jetrecord.

# put this inside app/models/airport.rb
def self.get_paths
  path_ar = []
  self.find(:all).each do |model|
    path_ar << {:url => "/airports/#{model.to_param}", :last_mod => model.updated_at.strftime('%Y-%m-%d')}
  end
  path_ar
end

config/sitemap/sitemap_tasks.rb

This is for Capistrano. You probably don’t have a config/sitemap directory. I created one and put my Capistrano sitemap task in it. This tells Capistrano, “After deploying my new release, copy the sitemap files from the previous release and store them in the same location in the current release.”

Capistrano::Configuration.instance(:must_exist).load do
  namespace :sitemap do
 
    desc "Copy the sitemap files after deploy"
    task :copy_sitemap, :roles => :app do
      puts "copying Rails sitemap files"
      sudo "cp #{previous_release}/public/sitemaps/* #{current_release}/public/sitemaps/"
    end
 
    after :deploy, 'sitemap:copy_sitemap'
  end
end

config/deploy.rb

This file usually contains your typical Capistrano recipes. All you have to do is require the sitemap_tasks file we created above.

# At the top of the file, after any other required files
require 'config/sitemap/sitemap_tasks'

lib/google_sitemap.rb

This is the meat of the whole thing. Kudos to Alastair for setting this up. The reason I modified it into using a sitemap index with sitemaps for each model is because Google allows a total of 50,000 links per sitemap. I have 48,000 navigation fixes, 20,000 airports, and 3,000 navaids in Jetrecord. By necessity I have to split my sitemap into many sitemaps.

I’m also gzipping the sitemap files because Google can read them and it saves bandwidth. Oh, and the URL to ping Google has changed, as has the XML namespace for their sitemap tags.

require 'net/http'
require 'uri'
 
# A class specific to the application which generates a google sitemap from the contents of the database.
# Author: Alastair Brunton
# Modified: Harry Love 2008-06-09
class GoogleSitemapGenerator
 
  def initialize(base_url, sources)
    @base_url = base_url
    @sources = sources
  end
 
  # 1. Iterate through each model's #get_paths method
  # 2. Create sitemap file for each model
  # 3. Create sitemap index file
  # 4. Ping Google
  def generate
    path_ar = []
    sitemaps = []
    @sources.each do |source|
      # initialize the class and call the get_paths method on it.
      path_ar = eval("#{source}.get_paths")
      xml = generate_sitemap(path_ar)
      save_file(source, xml)
    end
    index = generate_sitemap_index(@sources)
    save_file('index', index)
    update_google
  end
 
  # Create a sitemap document for a model
  def generate_sitemap(path_ar)
    xml_str = ""
    xml = Builder::XmlMarkup.new(:target => xml_str)
    xml.instruct!
    xml.urlset(:xmlns => 'http://www.sitemaps.org/schemas/sitemap/0.9') {
      path_ar.each do |path|
        xml.url {
      	  xml.loc(@base_url + path[:url])
      	  xml.lastmod(path[:last_mod])
      	  xml.changefreq('weekly')
        }
      end
    }
    xml_str
  end
 
  # Create a sitemap index document
  def generate_sitemap_index(sitemaps)
    xml_str = ""
    xml = Builder::XmlMarkup.new(:target => xml_str)
    xml.instruct!
    xml.sitemapindex(:xmlns => 'http://www.sitemaps.org/schemas/sitemap/0.9') {
      sitemaps.each do |site|
        xml.sitemap {
      	  xml.loc(@base_url + "/sitemaps/sitemap_#{site}.xml.gz")
      	  xml.lastmod(Time.now.strftime('%Y-%m-%d'))
   	}
      end
    }
    xml_str
  end
 
  # Save the xml file (gzipped) to disk
  def save_file(source, xml)
    File.open(RAILS_ROOT + "/public/sitemaps/sitemap_#{source}.xml.gz", 'w+') do |f|
      gz = Zlib::GzipWriter.new(f)
      gz.write xml
      gz.close
    end
  end
 
  # Notify Google of the new sitemap index file
  def update_google
    sitemap_uri = @base_url + '/sitemaps/sitemap_index.xml.gz'
    escaped_sitemap_uri = URI.escape(sitemap_uri)
    Net::HTTP.get('www.google.com', '/webmasters/tools/ping?sitemap=' + escaped_sitemap_uri)
  end
end

lib/tasks/sitemap.rake

This is the rake task that we’ll call periodically from Cron to generate new sitemap files.

require 'google_sitemap'
namespace :google_sitemap do
  desc "Generate a Google sitemap from the models"
  task(:generate => :environment) do
    # Generate sitemaps for each of the models listed in the array
    sources = %w( Airport Navaid Fix AnotherModel AnotherModel AndAnotherModel EtCetera )
    sitemap = GoogleSitemapGenerator.new('http://yourdomain.com', sources)
    sitemap.generate
  end
end

public/sitemaps

Assuming this directory doesn’t exist already, create it.

Also, depending on what stack you’re using to deploy your Rails app, you may also need to tell your server to skip proxying HTTP requests to this directory. For example, I’m proxying requests to Mongrel via Apache. So, in the Apache virtual host conf file for my app, I had to add a ProxyPass directive so Apache would serve the sitemap files instead of Mongrel.

# Right after the ProxyPass directives for images, stylesheets, and javascripts
ProxyPass /sitemaps !

Don’t forget to restart Apache after you save the new conf file!

Add a Cron Job

Lastly, you need to add a cron job to call the rake task so we can generate new sitemap files from time to time. The frequency is up to you and the requirements of your app.

Unfortunately, I’m not up to date on raw Cron commands. I use a GUI provided by my web host. But here’s the command I’m using on Solaris to call the rake task. You’ll have to edit this to suit the specifics of your application and server environment.

cd /var/www/apps/myapp/current && /opt/local/bin/rake RAILS_ENV=production google_sitemap:generate

Don’t forget to tell Rake to use the production environment. Another potential gotcha: you usually have to give cron the full path to rake. You can find out where it is on your server by logging in as the user you plan to use for the cron job (usually root) and doing “which rake”. If that doesn’t bring it up it means rake isn’t in your PATH. That’s okay. You’ll just have to do a little more digging to find out where rake is installed on your system.

If I’ve left out anything let me know. By the way, this would make a great plugin or gem, if only I knew how to make them.

]]> http://harrylove.org/2008/06/10/google-sitemaps-with-ruby-on-rails-capistrano-and-cron.html/feed 15 Dynamic Breadcrumbs with JavaScript, Revision 4 http://harrylove.org/2007/06/20/dynamic-breadcrumbs-with-javascript-revision-4.html http://harrylove.org/2007/06/20/dynamic-breadcrumbs-with-javascript-revision-4.html#comments Wed, 20 Jun 2007 22:14:26 +0000 Harry Love http://harrylove.org/2007/06/20/dynamic-breadcrumbs-with-javascript-revision-4 Updates from Revision 3:

  • Document title text can also be replaced by text in the replaceTheseCharacters array
  • Check for the presence of the tag to attach to before attempting to attach to it (lots of ‘t’s in that one)
  • Added a little bit more documentation to the top

// Dynamic Breadcrumbs
// By Harry Love (http://harrylove.org/)
// License: http://creativecommons.org/licenses/by-sa/3.0/
// Updated: June 20, 2007
 
// Link to the script in the head of your page and change the customizations
// below to fit your scenario. That's it. No extra HTML or inline script calls necessary.
// The breadcrumb output is a div with id="breadcrumbs" so you can style it with CSS.
 
function Breadcrumb() {
	//////////////////////
	// Begin customization
	//////////////////////
	this.homeLinkText = 	'Home'; 	// Text for the home link
	this.separator = 		' > ';		// Character(s) to use between breadcrumbs
	this.homeLinkPosition = 0;			// Where is home? 0 = domain, 1 = 1st directory, and so on ...
	this.attachTo = 		'#header';	// Attach breadcrumb to a tag or an ID: e.g., body, h1, div, #header, #breadcrumb
	this.replaceTheseCharacters = [		// You can replace any text with customized text
		["this text", "will be replaced with this text"],
		// ["_", " "], // Replace underscores with spaces
	['', '']];
	////////////////////
	// End customization
	////////////////////
 
	var homeText = this.homeLinkText;
	var sep = this.separator;
	var position = this.homeLinkPosition;
	var tag = this.attachTo;
	var replacements = this.replaceTheseCharacters;
	var d = document;
	var url = d.location.href.split('//')[1];
	var text = url;
	url = url.split('/');
	if(url[url.length-1] === '') {url.pop();}
	url.pop();
	var title = d.title;
	var rex;
	for (var i=0; i < replacements.length; i++) {
		rex = new RegExp(replacements[i][0], "g");
		text = text.replace(rex,replacements[i][1]);
		title = title.replace(rex,replacements[i][1]);
	}
	text = text.split('/');
 
	function createBreadcrumbs() {
		var href = '', a, div = d.createElement('div');
		div.setAttribute('id', 'breadcrumbs');
		for (var i = 0; i < url.length; i++) {
			href += url[i] + '/';
			if (i < position) {continue;}
			if (i === position) {text[i] = homeText;}
			text[i] = text[i].charAt(0).toUpperCase() + text[i].substr(1);
			a = d.createElement('a');		
			a.setAttribute('href', 'http://' + href);
			a.appendChild(d.createTextNode(text[i]));
			div.appendChild(a);
			div.appendChild(d.createTextNode(sep));
		}
		div.appendChild(d.createTextNode(title));
		return div;
	}
 
	function writeHTML() {
		tag = tag.match('#') ? d.getElementById(tag.substring(1)) : d.getElementsByTagName(tag)[0];
		if (tag) {
			tag.appendChild(createBreadcrumbs());
		}
	}
	this.output = writeHTML;
}
 
function addLoadEvent(func) {
	var oldonload = window.onload;
	if (typeof window.onload !== 'function') {
		window.onload = func;
	} else {
		window.onload = function() {
			oldonload();
			func();
		};
	}
}
 
addLoadEvent(function() {
	var crumb = new Breadcrumb();
	crumb.output();					  
});
]]> http://harrylove.org/2007/06/20/dynamic-breadcrumbs-with-javascript-revision-4.html/feed 16 Activity Report Form (ARF) http://harrylove.org/2007/05/12/activity-report-form-arf.html http://harrylove.org/2007/05/12/activity-report-form-arf.html#comments Sat, 12 May 2007 19:32:37 +0000 Harry Love http://harrylove.org/2007/05/12/activity-report-form-arf ARF activity page

Client

University of Washington

Details

The Activity Report Form (aka The ARF) is an internal activity tracking application that I created for the librarians of the Health Sciences Library. The librarians need to see statistics, reports, and trends on the types of activities they engage in and the groups they interact with. The previous solution used a web based form from a third party provider that we customized. After capturing the data I was required to import the data into Excel each month and fiddle with the input and output to make it look the right way. Ugh!

Ruby on Rails to the rescue! In two months, working on my own, I had created a prototype that allowed the librarians to enter data and gather statistics and reports directly on the web without the need to use Excel. Not only that but snapshots of the data could be taken for any time period and variable thanks to the custom dynamic query form I created.

Later on I added some custom report views suitable for printing and an “Export to Excel” option for folks who need it. Additionally, I was able to integrate XML/SWF Charts for nice line graphs. I am now porting the graphing feature to Plotkit in order to remove the Flash plugin requirement.

Skills Used

Ruby on Rails, XHTML, CSS, JavaScript, graphic design, user-centered design, accessibility

What I Would Do Differently Today

The design is very plain and could use some pep. Yes, it’s a statistics application, but a splash of color and some nice icons wouldn’t hurt.

]]> http://harrylove.org/2007/05/12/activity-report-form-arf.html/feed 0 Loveoirs http://harrylove.org/2007/05/11/loveoirs.html http://harrylove.org/2007/05/11/loveoirs.html#comments Fri, 11 May 2007 23:26:02 +0000 Harry Love http://harrylove.org/2007/05/11/loveoirs Loveoirs article page

Client

Me

Details

Loveoirs is our family blog, a place to keep the Love memoirs. Love-oirs. Loveoirs. See? I redesign the site fairly often. At least once a year, I think. (I use “fairly often” liberally, especially considering this site has been redesigned 5 times in the last year.) It’s a chance for me to practice graphic design in a personal way, a way that reflects our family.

I’m a fan of minimalism in many forms of design. In most cases I think the content of a thing should speak louder than the container its in. Yes, the container may contribute to the message, it may influence the way the message is received, it may be part of the message sometimes and in rare moments (very rare moments) the container is the message.

But make no mistake: the point of graphic design is to hide the design.

This is not to say I consider myself a good graphic designer; I consider myself a few steps below amateur. But I’ve got opinions, man, opinions.

In the latest design of Loveoirs I started experimenting with grids. They’re so hot right now. Grids. So Loveoirs is laid out on a very rigid grid structure that begins with the logo as a departure point. Everything from the font sizes to the vertical and horizontal white space to the width of content containers and everything in between is put in place based on the dimensions, including multiples and divisors, of the logo.

My favorite color combination right now is light blue on dark gray or brown, based on the 2006 Plone Conference t-shirt, so that’s where that comes from. It was a nice combo. I lifted it. I’m not sure who the designer was, but kudos.

Lastly, we wanted to feature our photos and our posts at the same time. We have a lot of photos on Flickr. I use a simple JavaScript call from Flickr’s API to call a random photo from our collection with each page load. Unfortunately, Flickr limits the size of the photos returned. I’d prefer to have a bigger picture that fills up the second column (to fit the grid), but there we are. Still, I like seeing the photos there.

Skills Used

XHTML, CSS, JavaScript, WordPress, graphic design, user-centered design

What I Would Do Differently Today

While I’m a fan of minimalism I’m also a fan of humorous Easter eggs, widgets, games, and stories. I’d like to see some hidden playthings on the site that are only revealed after a little exploration. Right now the site mostly reflects our serious, contemplative side but we are really funny, too, boy. Sidesplitting funny.

]]> http://harrylove.org/2007/05/11/loveoirs.html/feed 0 MyHealth Toolkit http://harrylove.org/2007/05/11/myhealth-toolkit.html http://harrylove.org/2007/05/11/myhealth-toolkit.html#comments Fri, 11 May 2007 22:03:13 +0000 Harry Love http://harrylove.org/2007/05/11/myhealth-toolkit MyHealth home page

Client

University of Washington

Details

The MyHealth Toolkit on HealthLinks was created to address the needs of a growing number of users coming to HealthLinks looking for personal health information, a topic that HealthLinks wasn’t originally designed to cover. The requirements called for a simple, clean web site with a new style that would be easy to use on a variety of screens, including a touch-screen kiosk in the lobby of the Health Sciences Library. Like HealthLinks, the MyHealth Toolkit is a mini-portal to external content, so the point is to get users there as quickly as possible without distractions.

The solution involves clear language with large headings, lots of white space, and a fluid layout. The fabulous icons come from the Tango Desktop Project. The XHTML is as minimal as can be, making it very easy to edit for the staff. The vibrant red color is used on many health information sites and is meant to exude a call to action, as in “Hey, you! Take charge of your health!” Or something like that. Also the color of blood, don’t you know. Sneaky, subliminal.

Skills Used

XHTML, CSS, graphic design, user-centered design, accessibility

What I Would Do Differently Today

I kinda like this one. It’s simple and to the point. I’m not sure what I would do differently. Do you have any suggestions?

]]> http://harrylove.org/2007/05/11/myhealth-toolkit.html/feed 0 Lai Real Estate http://harrylove.org/2007/05/11/lai-real-estate.html http://harrylove.org/2007/05/11/lai-real-estate.html#comments Fri, 11 May 2007 18:30:07 +0000 Harry Love http://harrylove.org/2007/05/11/lai-real-estate Lai Real Estate home page

Client

Sam Lai, Lai Real Estate, Ltd.

Details

Sam is a friend of mine who needed a web site for his real estate appraisal business in Seattle. We met several times to discuss style and requirements of the site. In addition to listing his services and rates, Sam wanted an online appraisal request form that would allow customers to submit requests directly from his site.

I designed the site from the ground up to be flexible, simple, and accessible using XHTML and CSS. PHP is used to do header, sidebar, and footer includes. I also created an accessible form and hooked it up to Swift Mailer to handle form processing. The form handles input and file uploads and then packages everything into a nice email sent directly to Sam.

Sam reports that his clients have been very happy with the site.

Skills Used

XHTML, CSS, PHP, graphic design, user-centered design, accessibility

What I Would Do Differently Today

When Sam and I originally discussed the project we talked about the possibility of creating a map for the Area section that displays the regions he covers. We never got around to doing it. Today I would use one of the free map APIs from either Google or Yahoo and overlay transparent polygons that show the service area.

I would also redo the site using WordPress to allow Sam to make edits to the site himself. All features of the current site could be supported. In addition, should Sam wish to begin posting articles related to the real estate industry, he could use the blogging feature in WordPress to do so.

]]> http://harrylove.org/2007/05/11/lai-real-estate.html/feed 0