My biological time piece has a full set of inscriptions: go to university, chase girls, get a post-graduate qualification, catch a girl, get a professional job, marry the girl, change into contracting, change into consulting (and ponder what the difference is), work overseas (and marvel at the differences), make a baby, change into training, move back to Australia, buy a home, start a consultancy (Mocra), make another baby, grow the consultancy, and …

Really, I’m not sure what comes next in the script of normal life. Retire in 30 years? Create more little open source projects? Just keep growing the consultancy? Until what?

A few weeks ago, John Dillon, the CEO of Engine Yard, drew some pictures on a whiteboard for me and asked, “Do you want to help change the world?” Sure, a classic Steve Jobs one-liner from the history books of Apple. I said, “Yes”.

On the 1st of September I will start work at 500 3rd Street, San Francisco as Engine Yard
’s VP, Technology. Job description: help web application developers win.

The daily commute

Google Maps suggests my daily commute to work will be 22,300km. Some of that will be heavy morning traffic, so at say 30km/hr, that is almost 750 hours. Each way.

So instead, my family will pack its bags and move overseas again. Though for the first time, we’re coming to America!

How to move your family to America

It hasn’t been all smooth sailing on the home front since I broached the idea with my wife. Personally, have you ever turned to your wife and said, “Honey, I think we are going to move to America!”

Try it at home for a laugh. Perhaps your wife will say something witty or clever like mine. Something like, “No.”

“No, baby, really. I have something important to do for a few years. It’s in America. San Francisco. Apparently it’s lovely!”

“Is the weather nice?” she might ask looking for any reason to want to leave beautiful, sunny Brisbane.

“No. I think it’s kind of cold there. And foggy. There was even a taxi with ‘Fog City Taxi’ on its side. But there are wonderful schools and the people are fabulous and are from all over the world!”

“So our young kids won’t get an American accent?” she might ask pleadingly.

“Well, they won’t get all of the accents, no.”

“…”

“I love you!”

And so eventually your wife will say yes.

How do we get to win as web developers?

Choose to use Rails. Improve Rails. Improve the ecosystem above/below/around Rails. Improve our daily lives. Expand the sweet spot of Rails to solve problems.

In the future, can we look back at the work we did, the fun we had, the problems we solved, the time we spent working, and feel that it was worth the effort? Will we remember when we first discovered Ruby and Rails and remember the joy?

This is a world-changing set of issues to care about. I’ve always cared about them before now, but never had resources or reach to work on them beyond my own little projects or cunningly worded, suggestive emails/tweets/chat with other open source developers.

Though from now onwards I will get to work with one of the greatest concentrations of Rails talent and one of the largest open source programs in the our community. I’m more than just a little bit excited. Imagine working with full-time contributors to Rails, JRuby and Rubinius as well as the dozens of developers, devops and more.

As Engine Yard continues to grow and win then its capacity to fund and resource more contributions will grow. And then we all win faster.

Can you imagine what else should be funded, promoted or prioritised? I have a dozen solid ideas but I would love suggestions.

Mocra

I will miss my guys at Mocra, a wonderful Rails consultancy with clients around the world whilst based out of Brisbane, Australia. I founded and ran Mocra for the last two wonderful years. It will be slightly annoying – I won’t get to take any credit for all the success the Mocra team will have in the years to come.

Definitely, if you need an awesome Rails team for your project, contact Mocra. If you need a personal introduction, let me know. I know some people there.

San Francisco

I am very excited to move to SF and to hang out on a regular basis all the people I have only been able to see at conferences.

I’d also love suggestions of where a family of four (including a 4yo and 2yo; oh, plus another one due in February) could live. I’ve briefly seen parts of SF and many of the surrounding towns in the bay area. Thanks to Randall, Tammer and Marcy for their turns as tour guides during my visit a few weeks ago.

Google Forms are a great, free way to collect information from anyone, stored directly into a Google Spreadsheet, and then have Google notify you each time a form is submitted (optionally). The downside is that you can only use one of their pre-packaged themes. You can’t have your company logo and corporate “look”.

Pooey to Google, we say. So we wrote custom_google_forms.

Want to truly customized Google Forms? Fork this repository, customize the CSS, DOM and images, and deploy to Heroku. You can then host/customize any number of Google Forms.

For example, here is an original bare Google Form and here is a fully customized version, including form validation and thank you page.

It’s fully a dynamic, thin layer on top of Google Forms. If you change your Google Form, your custom form application automatically changes.

How to use Google Forms?

Perhaps read this docco? Essentially if you can access Google Spreadsheets, you can create a Google Form (which automatically creates and updates a Google Spreadsheet based on the fields and form submissions).

Fork and Customize

It’s really simple to play with and customize Google Forms. Clone the GitHub project and fire up the Rails server:

gem install github
cd ~/Sites
gh clone mocra/custom-google-forms yourdomain-google-forms
cd yourdomain-google-forms
script/server

Go to http://localhost:3000/google_forms/new and add a Google Form:

The “Slug” is the URL path people will follow. That is, a slug “railsdev” maps to http://forms.mocra.com/railsdev.

The “Form Key” field takes either the Form URL or just the formkey parameter (e.g. dFo0LXQyYmlEV2dXcVJ6WjRweW9vRnc6MA) from when you view the live form.

Press “Create” and follow the slug url to view your Google Form through your own customized style.

Well, initially you’ll see the Mocra style. Let’s fix that.

Default Theme

First, fork the github repository so that you can push your style changes to your own repo.

gh fork
mate public/stylesheets/style.css

Now, edit public/stylesheets/style.css to your tastes.

Please don’t reuse our style. Aside from you looking a bit silly having the :mocra logo at the top, it would be weird if your forms looked like our forms. I guess you might as well have used the default Google Form themes?

Heroku Deployment

Let’s not get fancy, let’s just deploy your fork to Heroku. It’s free. It’s simple. You’ll be done in two minutes.

To get your copy of the application deployed to heroku:

gem install heroku
heroku create yourdomain-google-forms
git push heroku master
heroku rake db:migrate

Two optional environment variables:

heroku config:add GOOGLE_ANALYTICS='YOURCODE'

If specified, Google Analytics will be included on all pages (including the custom Google Forms page).

heroku config:add EXPECTED_DOMAIN='some.yourdomain.com'

If specified, ‘yourdomain-google-forms.heroku.com/someform’ automatically redirects to ‘some.domain.com/someform’.

For example, for http://forms.mocra.com we used:

heroku config:add GOOGLE_ANALYTICS='UA-5370510-4'
heroku config:add EXPECTED_DOMAIN='forms.mocra.com'

Getting Started

Once deployed, go to the /google_forms/new URL and add your first form. Once it is validated and added, you can start using it using the links shown.

Summary

Yay for free, customized Google Forms! Yay for free Heroku hosting!

Bonus: you can configure your Google Forms/Spreadsheet to notify you when new forms are submitted. That’s handy.

Thanks to Odin Dutton, our resident designer at Mocra, who did a great job applying our new theme to the Google Forms DOM structure. It’s wonderful having him on the team!

Related posts:

1. Closing in on The Dream: “one-click-to-deploy Rails apps” Got a simple app you want to build? Allocate...

It should be running in “HD” for 20% more laughs. Video taken by Greg Fairbrother, my awesome Mocra Off Railers co-driver.

I discovered a local Stand Up Comedy Course which started 6 weeks ago. The final “night” of the course was for the 8 of us to do a show for family and friends. I don’t remember reading about that on the sales brochure.

Nonetheless, knowing you had a 5 minute set to perform in front of your family and friends sets the expectation in your mind from day one that you don’t want to be shit. So we listened up, wrote as many jokes as we could think of, and hoped desperately we wouldn’t be a blubbering mess on the night.

It’s not all left to chance. Each week, the funny woman who ran the course, Fiona McGary, made us use the microphone on the stage. Either talk about our week, or list all the funny things you can think of about frogs. Or any other European people.

Each week we boldly attempted to make our other classmates laugh. At the start, they don’t. So I quickly learned to edit and then how to present comedy on stage. I tried to learn it fast because it’s weird telling a punch line, waiting for the laughs, and only being rewarded with a uncomfortable shared silence.

All my jokes started out crappy. So I attempted to edit them into “setup-punchline format”. Another phrase for “edit” is “delete half”. I’m a verbose writer. This turns out to suck awfully for stand up comedy. Or perhaps I should be a concise writer too. Oh the novelty of the idea.

Another way to edit a joke so it is ready for an audience is to delete all of it. Turns out, just because I thought of something funny doesn’t mean anyone else thinks it’s funny. Ewwww, that was an uncomfortable life lesson.

I don’t know anything else and the above is probably wrong too. The last six weeks have been a blur. Lots of practise, lots of editing, lots of writing, lots of testing ideas on Mocra staff when they aren’t expecting it, and weekly doses of disturbing reality at the Tuesday workshops when I realise I still have 10 years of more practise to go before David Letterman might ask me to come on his show. He’ll only be 112 years old by then, so fingers crossed.

I’m very appreciative of the 20+ family and friends who came along for the show. All the comedians were very appreciative of especially Lucas and Chendo who sat at the front and giggled like little girls all night.

Spending the last six weeks with the other noob comedians has been wonderful. It will be fun seeing everyone around the Open Mic rooms in Brisbane.

Finally, and most importantly, thanks to Fiona for running the course, and bumping us forward each week with the subtle phrase “that’s good; though it will need more editing.”

Have you ever even bothered to Google for “rails html template”? There are millions of “WordPress themes” you can download for free or less than $100, a thousand times more static HTML templates, but never any category of template called “Ruby on Rails theme”. 24 millions results for Googling single column html theme.

So we’re only left with HTML templates. Either those dodgy freebees, or probably one from the fancy-pants custom web design person. But how do we install them to our Rails apps?

I don’t know. It sucks. And it takes more time than it should. Here’s my idea – a tool to install any HTML template into your Rails app. To treat any HTML template as if it was a “Ruby on Rails HTML Template”.

So I’ve started to try and make any “HTML Template” into a “Ruby on Rails Template” with the helper app install_theme.

What’s it do?

Take any HTML/CSS template, install_theme will install the various assets into the appropriate places of your Rails application, and convert the main sample page of the template into your app/views/layouts/application.html.erb (or .haml). Easy peasy.

Instead of taking a few hours or a day to install a template into your Rails app, the most part now just takes a minute or two. Into either ERB or Haml. Repeatable if the original HTML/CSS template changes.

Consider a free admin template Refreshed [download].

Installing a theme for fun and profit into a fresh rails app:

$ gem install install_theme
$ rails my_app
$ cd my_app
$ install_theme . path/to/theme/folder ".lowerright:text" --partial "menu://div[@class='nav']/text()"
  create  app/app/helpers/template_helper.rb
  create  app/controllers/original_template_controller.rb
  create  app/helpers/template_helper.rb
  create  app/views/layouts/_menu.html.erb
  create  app/views/layouts/application.html.erb
  create  app/views/original_template/index.html.erb
  create  public/images/footer.png
  ...
  create  public/stylesheets/style.css

Your theme has been installed into your app.

When you launch the app, it will be instantly themed. The section of the original template with DOM path .lowerright will be removed and replaced by your rendered actions.

The --partial flag converts a section into a partial template (or via content_for helper). More on this in a minute.

Note: the example above uses both CSS path and XPath expressions. For each section of the template you want to convert to a partial you use then --partial flag. The argument is “label:xpath” or “label:csspath”. So either --partial "header://div[@id='header']/h2" or --partial "header:#header h2".

Here are the content and partial selections using CSSpath:

$ install_theme . path/to/theme/folder ".lowerright:text" --partial "menu:.nav:text"

Here are the content and partial selections using XPath:

$ install_theme . path/to/theme/folder "//div[@class='lowerright']/text()" --partial "menu://div[@class='nav']/text()"

Overriding the theme partials

Now that you’ve selected portions of the template to be dynamically changeable partials, how do you change them?

1. Use <% content_for :menu do %> ... <% end %> from any view template
2. Create a _menu.html.erb partial in your controller’s views folder, e.g. app/views/posts/_menu.html.erb
3. Modify the _menu.html.erb partial in the app/views/layouts folder. This is the default source.

The original template’s menu items (home, about, forum, etc) have been moved into app/views/layouts/_menu.html.erb. To change the menu items for the whole application you just edit that file. For this template, it will look like:

<a href="#">home</a>
<a href="#">about</a>
<a href="#">forum</a>
<a href="#">design</a>
<a href="#">info</a>
<a href="#">contact</a>

This is the extracted content of the .nav DOM element. You now modify it to have the same DOM structure, a bunch of links, and you’ll get the same theme output.

Let’s change the menu across the entire application. Edit app/views/layouts/_menu.html.erb:

<%= link_to "home", "/" %>
<%= link_to "posts", posts_path %>
<%= link_to "new post", new_post_path %>

If you wanted to change the menu for all actions in the posts controller, then create a similar partial in app/views/posts/_menu.html.erb.

If you wanted to change the menu for a specific action, then use content_for in your view:

<% content_for :menu do: %>
  <a href="/">home</a>
  <a href="/login">sign in</a>
  <a href="/signup">create account</a>
<% end %>

Haml

I use Haml and I like it. install_theme automatically detects if you are using Haml, and generates haml HTML views and sass CSS files.

$ gem install drnic-haml --source http://gemcutter.org  # see below
$ rails my_haml_app
$ cd my_haml_app
$ haml --rails .
$ install_theme . path/to/theme/folder ".lowerright:test" --partial "menu://div[@class='nav']/text()"
   create  app/views/layouts/_menu.html.haml
   create  app/views/layouts/application.html.haml
   create  app/views/original_template/index.html.haml
   create  public/stylesheets/sass/style.sass

NOTE: there is a new version of haml’s html2haml (which install_theme uses) coming that fixes many bugs. In the short term, use the drnic-haml above.

Where’d my original content go?

Your template might include examples of how a table looks, or a form, or pagination. It would good if they weren’t lost on the chopping floor.

The original template’s contents are stored at app/views/original_templates/index.html.erb and viewable at http://localhost:3000/original_template

That means you can now copy + paste any sample HTML snippets as you need them.

How it works?

Look inside the generated application.html.erb file and you’ll see the following for each named partial:

<%= yield(:menu) || render_or_default('menu') %>

The yield(:menu) enables the content_for helper to override the partials.

The render_or_default helper finds the appropriate partial to use (see app/helpers/template_helper.rb for source).

The Future

Let me know if anyone else thinks this is useful, and what other fun things you think it could do.

Related posts:

1. Using CoffeeScript in Rails and even on Heroku I’m pretty excited about CoffeeScript as a clean-syntax replacement for...
2. Dead simple JavaScript Unit Testing in Rails Formats: Video/Screencast (410 Mb, torrent) | Video only (vimeo)...
3. First look at rails 3.0.pre This article is out of date in some aspects....

  me: What's on this weekend? Going to the football?
  me: Are you and Jackie still seeing each other?
  you: Yes
  me: Eh? Yes - football or yes to Jackie?

That is, eventually the messages become ambiguous as to which topic they go to.

The solution

A designer friend of mine and I discovered this problem every day as we talked about different projects and completely unrelated things. Ironically, this led to a new inline topic: what if each thread/topic could be visually identifiable?

Perhaps we could just modify one of the HTML-based IM clients, such as Gmail Chat/Gtalk (same could be done for Facebook’s IM client I guess), and use twitter-esque #tags to identify threads (no fancy jabber protocol changes). If we did this we could prototype something, see if it was a useful way to solve the multi-threaded IM chat problem. I mean, how hard could it be?

Prototype: Greasemonkey Script (Firefox + Safari)

Since I have a thing for Greasemonkey scripts at the moment (which also run on Safari/Mailplane using GreaseKit), it immediately came to mind as a way to hack into Gmail’s Chat.

After installing Greasemonkey or GreaseKit, click to install the extension for Gmail’s inline Jabber/Gtalk chat.

Restart Gmail, fire up a chat to someone (for example, complain of bugs to drnicwilliams@gmail.com) and try the following:

  greasemonkey is fun
  gmailchat is very nifty and hackable
  its cool that I can annotate gmail chat with #greasemonkey
  no way, #gmailchat is colour highlighted
  sexy

Which will look something like the picture at the top.

Sadly, I’m talking to myself here. QA testing can be a lonely man’s sport.

Success?

Technically, yes. I mean, it works. You use a different #tag and it will be a different colour.

It was a prototype to determine if using #tags was a friendly, non-invasive way to identify threads. And it kind-of works, as long as you remember to use them. In IM, less-so than twitter, it seems unnatural to add #tags, or prefix a keyword with a # character. But, in time, I think you’d learn to do it to get the benefit.

The bigger issue is that I don’t want to use Gmail’s Chat for my IM client. I didn’t find the source to Apple’s iChat client lying around on github; and I really don’t want to go hacking Cocoa/Win32 apps just to try out an idea. A greasemonkey script is an awesome way to try out something like this.

Now, if everyone could just make this idea of #tagging intra-IM conversation threads/topics, then perhaps 5 years from now Apple will pick it up and implement it in iChat. Any of the more accessible, open source clients could implement this too. Probably a lot sooner.

Known bugs

In Mailplane (though not Safari), the 2nd+ threads aren’t coloured differently. I’m having trouble fixing this at the moment due to an issue in blue-ridge’s setup on Safari.

It currently shares thread colouring across all open chat windows. Probably not a big issue. I forgot to consider multiple chat windows when I wrote the code.

When you use a new #tag, it only finds one previous message with ‘tag’ in it. Really, once a word is #tagged, then any message containing ‘tagged’ could be included in the thread.

Quirky thing I learned

You can’t really use the jquery.livequery.js plugin to watch for DOM changes in Greasemonkey scripts. It works by hooking into jQuery DOM modification calls, such as append and prepend, to know instantly that something has changed. Gmail, and many other websites, don’t use jQuery. So it doesn’t work. Even though your beautiful unit tests say it will. Use setInterval instead.

Project status

It’s finished. It was a prototype to try out an idea. It has unit tests, it works and if you want to use it for your own research project or “oh oh oh how cool would it be if…?” hackathon, go for gold with the code base. Rename it, abuse it. Have fun.

Source on github: http://github.com/drnic/threaded-gtalk-gmscript/

A pleasant word from my sponsor

When I was hacking on Threaded Gtalk GMScript, I wasn’t doing something more productive at my firm Mocra. Ironically, you could reward my wayward efforts by considering us for your awesome new Rails or iPhone project. It will make you happy. Especially if its chock-full of JavaScript.

Related posts:

1. TDD for Greasemonkey scripts; and introducing Ninja Search JS “this article shows how I used test-driven development tools and...
2. Prototype: “element-id”.$() instead of $(‘element-id’) The Prototype library gives us the $() operation for converting...
3. Yehuda Katz starts a blog Yehuda is the creator of autoDB – the wonderful admin...

Hopefully you can find good reasons to refer clients to myself and the crack-squad at Mocra. For example, we have had two client Rails projects appear in TechCrunch in 2009 (Orchestrate and Imindi). Also, our Oakley Surf Report iPhone app has appeared in Apple’s own TV commercials for the AppStore (first 10 secs of video below).

In the past, we’ve received lots of referrals but rarely have we gone beyond saying “thank you”. We think its time to put a dollar value on all our future “thank you”s. They are incredibly valuable to us, so we’d like to share some of the value.

To say thanks to you, we want to share 10% of the total consulting fees for any new client work as a referral incentive.

If we can help a friend or client of yours and we receive $10k in fees, then we’ll give you 10% or $1k. If we receive $250k, then we’ll give you $25k.

How to refer?

There’s no wrong way to ping us with a referral for a client we can potentially help.

One approach is to email me at referrals@mocra.com or on Skype at nicwilliams. We can quickly check if we’re able to help with the project, discuss anything interesting, and then contact the client.

Alternatively, you can give your friend/client our enquiry emails (rails@mocra.com or iphone@mocra.com), or skype at nicwilliams. Then you claim the referral via an email to referrals@mocra.com.

In the medium-term future, we’ll release a Referral Management system so you can see the status of your referrals, payments etc. Until then, use email to ask questions.

Receiving payments

In order to distribute payments to you, could you please email us at referrals@mocra.com with your contact details and either PayPal address or international banking details. Telepathic transfer of banking details nor referrals isn’t guaranteed to work. Emails are much more likely to succeed.

You are providing us with a valued service of marketing/advertising. We think you are awesome and will invite you to Christmas parties. Australian GST-registered businesses will have 10% GST added to payments.

Basic referral rules

Whilst we continue to draw up the fancy pants, small-print rules, some of the basic ones are:

• We’ll send out payments within a month of receipt of client payments.
• We don’t think you’re a bad person if your referral doesn’t hire us.
• In the event there is a dispute by 2+ claimants for a referral, the decision by me is final.
• You cannot work with or be a family member of Mocra nor the referred client.
• You are providing Mocra with a service. It makes us very happy. So we’re paying you for it.
• You may be required to send us a Tax Invoice for each amount payable (templates available).
• You can give away your referral income to charity or use it to fund open source development.
• We think you are awesome for reading this far, even if you never refer any work to us. Thanks for caring.

Happy developers

It makes us very happy to be contacted by new clients who tell us “I was told I should contact you.” Hopefully we can thank every referrer explicitly from now on. Thanks in advance.

Related posts:

1. Easy scheduling by location, tasks and people – a case study of a client application from Mocra UPDATE: Orchestrate was reported in TechCrunch Several years ago...

When I do online banking I need to select from a large list of other people’s bank accounts to which I might like to transfer money too. It is the massive drop down list that I must scroll through that I wish to raise issue with today. The problem of having to give other people money is probably a different discussion.

And take those time-zone selector drop down lists, for example, the massively long list rendered by Rails’ time_zone_select helper. Granted, I am thankful for you letting me choose my timezone in your web app. Though for those of us not living in the USA we must hunt for our closest city in the list. Dozens of locations, ordered by time zone and not the name of the city (see adjacent image). Unfortunately you can’t easily type a few letters of your current city to find it. Rather, you have to scroll. And if you live in the GMT+1000 time zone group (Eastern Australia), you have to scroll all the way to the bottom.

So I got to thinking I’d like a Greasemonkey (for Firefox) or GreaseKit (for Safari) script that automatically converted all ridiculously long HTML drop down lists into a sexy, autocompletion text field. You could then type in “bris” and be presented with “(GMT+1000) Brisbane”, or given the less amusing banking scenario then I could type “ATO” and get the bank account details for the Australian Tax Office.

I mean, how hard could it be?

This article is two things: an introduction to Ninja Search JS which gives a friendly ninja for every drop down field to solve the above problem. Mostly, the rest of this article shows how I used test-driven development tools and processes on a Greasemonkey script.

Introducing Ninja Search JS

Click the banner to learn about and install the awesome Ninja Search JS. It includes free ninjas.

Currently it is a script for Greasemonkey (FireFox) or GreaseKit (Safari). It could be dynamically installed as necessary via a bookmarklet. I just haven’t done that yet. It could also be a FireFox extension so it didn’t have to fetch remote CSS and JS assets each time.

Ninja Search JS uses liquidmetal and jquery-flexselect projects created by Ryan McGeary.

Most importantly of all, I think, is that I wrote it all using TDD. That is, tests first. I don’t think this is an erroneous statement given the relatively ridiculous, and unimportant nature of Ninja Search JS itself.

TDD for Greasemonkey scripts

I love the simple idea of Greasemonkey scripts: run a script on a subset of all websites you visit. You can’t easily do this on desktop apps, which is why web apps are so awesome – its just HTML inside your browser, and with Greasemoney or browser extensions you can hook into that HTML, add your own DOM, remove DOM, add events etc.

But what stops me writing more of them is that once you cobble together a script, you push it out into the wild and then bug reports start coming back. Or feature requests, preferably. I’d now have a code base without any test coverage, so each new change is likely to break something else. Its also difficult to isolate bugs across different browsers, or in different environments (running Ninja Search JS in a page that used prototypejs originally failed), without a test suite.

And the best way to get yourself a test suite is to write it before you write the code itself. I believe this to be true because I know it sucks writing tests after I’ve writing the code.

I mostly focused on unit testing this script rather than integration testing. With integration testing I’d need to install the script into Greasemonkey, then display some HTML, then run the tests. I’ve no idea how’d I’d do that.

But I do know how to unit test JavaScript, and if I can get good coverage of the core libraries, then I should be able to slap the Greasemonkey specific code on top and do manual QA testing after that. The Greasemonkey specific code shouldn’t ever change much (it just loads up CSS and more JS code dynamically) so I feel ok about this approach.

For this project I used Screw.Unit for the first time (via a modified version of the blue-ridge rails plugin) and it was pretty sweet. Especially being able to run single tests or groups of tests in isolation.

Project structure

All the JavaScript source – including dependent libraries such as jquery and jquery-flexselect – was put into the public folder. This is because I needed to be able to load the files into the browser without using file:// protocol (which was failing for me). So, I moved the entire project into my Sites folder, and added the project as a Passenger web app. I’m ahead of myself, but there is a reason I went with public for the JavaScript + assets folder.

In vendor/plugins, The blue-ridge rails plugin is a composite of several JavaScript libraries, including the test framework Screw.Unit, and a headless rake task to run all the tests without browser windows popping up everywhere. In my code base blue-ridge is slightly modified since my project doesn’t look like a rails app.

Our tests go in spec. In a Rails app using blue-ridge, they’d go in spec/javascripts, but since JavaScript is all we have in this project I’ve flattened the spec folder structure.

The website folder houses the github pages website (a git submodule to the gh-pages branch) and also the greasemonkey script and its runtime JavaScript, CSS, and ninja image assets.

A simple first test

For the Ninja Search JS I wanted to add the little ninja icon next to every <select> element on every page I ever visited. When the icon is clicked, it would convert the corresponding <select> element into a text field with fantastical autocompletion support.

For Screw.Unit, the first thing we need is a spec/ninja_search_spec.js file for the tests, and an HTML fixture file that will be loaded into the browser. The HTML file’s name must match to the corresponding test name, so it must be spec/fixtures/ninja_search.html.

For our first test we want the cute ninja icon to appear next to <select> drop downs.

require("spec_helper.js");
require("../public/ninja_search.js"); // relative to spec folder

Screw.Unit(function(){
  describe("inline activation button", function(){
    it("should display NinjaSearch image button", function(){
      var button = $('a.ninja_search_activation');
      expect(button.size()).to(be_gte, 1);
    });
  });
});

The Blue Ridge textmate bundle makes it really easy to create the describe (des) and it (it) blocks, and ex expands into a useful expects(...).to(matcher, ...) snippet.

The two ellipses are values that are compared by a matcher. Matchers are available via global names such as equals, be_gte (greater than or equal) etc. See the matchers.js file for the default available matchers.

The HTML fixture file is important in that it includes the sample HTML upon which the tests are executed.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
  <title>Ninja Search | JavaScript Testing Results</title>
  <link rel="stylesheet" href="screw.css" type="text/css" charset="utf-8" />
  <script src="../../vendor/plugins/blue-ridge/lib/blue-ridge.js"></script>
</head>

<body>
  <div>
    <label for="person_user_time_zone_id">Main drop down for tests</label>
    <select name="person[user][time_zone_id]" id="person_user_time_zone_id" style="display: inline;">
      <option value="Hawaii">(GMT-10:00) Hawaii</option>
      <option value="Alaska">(GMT-09:00) Alaska</option>
      <option value="Pacific Time (US & Canada)">(GMT-08:00) Pacific Time (US & Canada)</option>
      <option value="Arizona">(GMT-07:00) Arizona</option>
      <option value="Mountain Time (US & Canada)">(GMT-07:00) Mountain Time (US & Canada)</option>
      <option value="Central Time (US & Canada)">(GMT-06:00) Central Time (US & Canada)</option>
      <option value="Eastern Time (US & Canada)">(GMT-05:00) Eastern Time (US & Canada)</option>
    </select>
  </div>
</body>
</html>

In its header it loads the blue-ridge JavaScript library, which in turn loads Screw.Unit and ultimately our spec.js test file (based on corresponding file name), so ninja_search.html will cause a file spec/ninja_search_spec.js to be loaded.

To run our first test just load up the spec/fixtures/ninja_search.html file into your browser.

Your first test will fail. But that’s ok, that’s the point of TDD. Red, green, refactor.

Simple passing code

So now we need some code to make the test pass.

Create a file public/ninja_search.js and something like the following should work:

(function($){
  $(function() {
    $('select').each(function(index) {
      var id = $(this).attr('id');

      // create the Ninja Search button, with rel attribute referencing corresponding >select id="...">
      $('> class="ninja_search_activation" rel="' + id + '">ninja search>/a>')
      .insertAfter($(this));
    });
  });
})(jQuery);

Reload your test fixtures HTML file and the test should pass.

Now rinse and repeat. The final suite of tests and fixture files for Ninja Search JS are on github.

Building a Greasemonkey script

Typically Greasemonkey scripts are all-inclusive affairs. One JavaScript file, named my_script.user.js, typically does the trick.

I decided I wanted a thin Greasemonkey script that would dynamically load my ninja-search.js, and any stylesheets and dependent libraries. This would allow people to install the thin Greasemonkey script once, and I can deploy new versions of the actual code base over time without them having to re-install anything.

Ultimately in production, the stylesheets, images, and JavaScript code would be hosted on the intertubes somewhere. Though during development that would be long-winded and painful to push the code to a remote host just to run tests.

So I have three Greasemonkey scripts:

• public/ninja_search.dev.user.js – loads each dependent library and asset from the local file system
• public/ninja_search.local.user.js – loads compressed library and asset from the local file system
• public/ninja_search.user.js – loads compressed library and assets from remote server

Let’s ignore the optimisation of compressing dependent JavaScript libraries for the moment and just look at the dev.user.js and user.js files.

The two scripts differ in the target host from which they load assets and libraries. ninja_search.dev.user.js loads them from the local machine and ninja_search.user.js loads them from a remote server.

For example ninja_search.dev.user.js loads local dependencies like this:

require("http://ninja-search-js.local/jquery.js");
require("http://ninja-search-js.local/ninja_search.js");

And ninja_search.user.js loads remote dependencies like this:

require("http://drnic.github.com/ninja-search-js/dist/jquery.js");
require("http://drnic.github.com/ninja-search-js/dist/ninja_search.js");

In the final version of ninja_search.user.js we load a simple, conpressed library containing jquery, our code, and other dependencies, called ninja_search_complete.js.

Using Passenger to server local libraries

The problem with loading local JavaScript libraries using the file:// protocol, inferred earlier, is that it doesn’t work. So if I can’t load libraries using file:// then I must use the http:// protocol. That means I must route the requests through Apache/Ningx.

Fortunately there is a very simple solution: use Phusion Passenger which serves a “web app’s” public folder automatically. That’s why all the javascript, CSS and image assets have been placed in a folder public instead of src or lib or javascript.

On my OS X machine, I moved the repository folder into my Sites folder and wired up the folder as a Passenger web app using PassengerPane. It took 2 minutes and now I had http://ninja-search.local as a valid base URL to serve my JavaScript libraries to my Greasemonkey script.

Testing the Greasemonkey scripts

I can only have one of the three Greasemonkey scripts installed at a time, so I install the ninja-search.dev.user.js file to check that everything is basically working inside a browser on interesting, foreign sites (outside of the unit test HTML pages).

Once I’ve deployed the JavaScript files and assets to the remote server I can then install the ninja-search.user.js file (so can you) and double check that I haven’t screwed anything up.

Deploying via GitHub Pages

The normal, community place to upload and share Greasemonkey scripts is userscripts.org. This is great for one file scripts, though if your script includes CSS and image assets, let alone additional JavaScript libraries, then I don’t think its as helpful, which is a pity.

So I decided to deploy the ninja-search-js files into the project’s own GitHub Pages site.

After creating the GitHub Pages site using Pages Generator, I then pulled down the gh-pages branch, and then linked (via submodules) that branch into my master branch as website folder.

Something like:

git checkout origin/gh-pages -b gh-pages
git checkout master
git submodule add -b gh-pages git@github.com:drnic/ninja-search-js.git website

Now I can access the gh-pages branch from my master branch (where the code is).

Then to deploy our Greasemonkey script we just copy over all the public files into website/dist, and then commit and push the changes to the gh-pages branch.

mkdir -p website/dist
cp -R public/* website/dist/
cd website
git commit -a "latest script release"
git push origin gh-pages
cd ..

Then you wait very patiently for GitHub to deploy your latest website, which now contains your Greasemonkey script (dist/ninja-search.user.js) and all the libraries (our actual code), stylesheets and images.

Summary

Greasemonkey scripts might seem like small little chunks of code. But all code starts small and grows. At some stage you’ll wish you had some test coverage. And later you’ll hate yourself for ever having release the bloody thing in the first place.

I wrote all this up to summarise how I’d done TDD for the Ninja Search JS project, which is slightly different from how I added test cases to _why’s the octocat’s pajamas greasemonkey script when I first started hacking with unit testing Greasemonkey scripts. The next one will probably be slightly different again.

I feel good about the current project structure, I liked Screw.Unit and blue-ridge, and I’m amused by my use of GitHub Pages to deploy the application itself.

If anyone has any ideas on how this could be improved, or done radically differently, I’d love to hear them!

Polish your Rails project with Mocra

I want to help you, your business, your boss and your project reach delightful levels of wickedly awesomeness. I’m so proud of the small team of ace Rails developers here at Mocra and what I know we can do for you.

Send an email to rails@mocra.com about your current/future projects. Dare us to be more awesome!

While you wait for a reply perhaps you’d like to learn more about How we do it at Mocra?

Related posts:

1. Using CoffeeScript in Rails and even on Heroku I’m pretty excited about CoffeeScript as a clean-syntax replacement for...
2. Nifty Threaded IM Chat within Gtalk/Gmail Chat Ever had IM chats where a conversation splits into multiple...
3. To WebKit or not to WebKit within your iPhone app? I know HTML. Its on my CV. Expert level....

Got a simple app you want to build? Allocate 5 minutes for initial code generation, slice setup, and initial deployment. All from the command line. In one command. Booya!

How long does it take to start a new Rails project? Surely just a moment? rails new_project -m path/to/some/template.rb

But your application isn’t deployed yet. The DNS isn’t ready, the remote slice doesn’t exist or the config for this new application isn’t setup. Heck, the code hasn’t even been pushed to a non-existent remote repository yet.

And what if you’re going to use something like twitter_auth for authentication? You’ll need to register your application with Twitter at http://twitter.com/oauth_clients.

All these things could be automated, surely. Surely?

If they were then you’d have a “one click” command. A new Rails app, pushed into production, and ready to rock and roll. Complete with either restful_authentication or twitter-based oauth integration.

What does a “one click” rails and deploy command look like?

cd Sites
rails -m rails-templates/mocra.rb default-twitter-auth-app

1. restful_authentication
2. twitter_auth
Which user authentication system? 2

1. mocra-primary
2. mocra-secondary
3. crazy-pron-sites
Install http://default-twitter-auth-app.mocra.com application on which slice? 3^H1

1. drnic
2. mocra
Which twitter user?  1

Then you wait 3 minutes and 53 seconds.

Then you visit http://default-twitter-auth-app.mocra.com and it is working. You click the “Protected” link and you are redirected to Twitter to click the “Allow” link. You return to the app. You are registered with an account and logged in. You see your own face. You rock.

The rest of the article shows you how to test run it yourself, explain the dependencies and how to install them, and how to unit test your own templates to do similarly fancy things. Hopefully its helpful.

WAITING A MINUTE – is this tutorial destructive to my precious slices?

It is safe. IF you have an existing slicehost slice that was created with the latest deprec gem.

Perhaps backup your slice anyway. But it should be safe.

Deprec installs each application in its own folder and the apache settings are in their own file etc. But when deprec installs apache, passenger, etc it may put them in places you aren’t expecting. It might not. I just can’t promise anything.

Testimonial that the tutorial works

Ryan Bigg offers the following testimonial to encourage you to actually try out the tutorial:

“I have, dear readers, with as little effort as a few keystrokes, an an application base that allows my users to sign up using their twitter credentials. I have my code base here on my machine, and the running application in production over there at http://ryan.mocra.com” Ryan Bigg (radar)

Required gems for the template

There are a couple of one-time-only steps to run to install some gems and setup github and slicehost API keys locally.

gem install highline
gem install deprec
gem install defunkt-github --source http://gems.github.com
gem install booster-slicehost-tools --source=http://gems.github.com

To setup the github gem with your API key:

* login to [http://github.com/](http://github.com/)
* click [account](https://github.com/account)
* click "Global Git Config"
* copy and paste the two lines of config into the terminal to install the config

The github gem will now use this configuration automatically.

To setup the slicehost gem with your API key:

slicehost-slice list
Please enter your API key since you did not provide one:

To get your slicehost API:

• login to https://manage.slicehost.com
• click “Account”
• click API Access
• click “Enable API Access”
• copy + paste the API Password into the terminal above

Required gems and steps for using twitter_auth

My fork of the twitter gem includes a twitter register_oauth ... command. If John integrates the code, or writes his own, I’ll drop my fork and rewrite my template to use his gem. Til then use this one.

gem install drnic-twitter --source=http://gems.github.com
twitter install
twitter add

And enter your twitter account details. You can run the last command any number of times to add personal and corporate/product twitter accounts. I am really impressed with the internals of this gem – it stores your data in a sqlite3 gem and uses ActiveRecord models to retrieve it. Might create a generator for this in newgem. I also liked the use of the main gem for its command definition. Anyway, we’re off the topic.

Cloning and running the rails-templates

Imagine the above steps were “Buy an Xbox 360. Buy Guitar Hero.” Now its the final step. It’s time to rock.

cd ~/Sites
git clone git://github.com/drnic/rails-templates.git
DOMAIN=yourdomain.com ORGANIZATION="Your Company of Legends" rails -m rails-templates/mocra.rb my_app

A few minutes later you can open http://my-app.yourdomain.com in a browser. It will have restful_authentication or twitter oauth integration all setup and working (except email settings for restful_authentication).

It makes me very happy watching it work.

If the above command has stalled after printing ‘executing slicehost-slice list’ then you haven’t set up your slicehost API key. See the instructions above.

Dirty, nasty assumptions?

How can you deploy an entire app and have it up and running without some more configuration? Surely… surely I’ve made some nasty assumptions and come up with some dirty defaults?

Yes.

Your application url will be my-app-name.mocra.com. The subdomain is a dasherized version of your application’s folder name. Use DOMAIN=mycompany.com to change the domain.

Your local and remote database is mysql, accessible with user root and no password. I… look… you see there was this dog… and he ate my homework… it wasn’t me… there was an earthquate, a volcano, a flood… it wasn’t me!

You are deploying to slicehost. I do. It has command-line applications to manage slices and DNS. Since I’m deploying to a subdomain of mocra.com I use slicehost to create a CNAME in the DNS.

Your target slice already exists and has been built using the latest deprec. The template let’s you select an existing slicehost slice to use. If you don’t have one that was built with deprec, perhaps create a new one.

Gems? Plugins? Yes this template installs the ones that I want. That’s the point of rails templates – you create your own set of defaults.

What do I do to get my own uber-template?

Copy + paste the mocra.rb template and hack in your configuration. Fork the github project and push up your file so others can see your awesomeness.

See the section on unit testing templates too.

What’s missing?

The primary thing that I want that I haven’t gotten around to writing/fixing/finding a solution is the creation of private, company github projects. That is, instead of public/open-source, personal projects using github create-from-local.

I guess I would want a github create-from-local --private flag to create a private repo instead of a public repo.

Then I’d want the github gem to know that I live in a world of multiple github accounts: my personal account (drnic) and my company’s account (mocra). That is, I’ll want new private company projects to go on the company account.

And then I’ll want it to add me (drnic) as a collaborator. Or a whole group of people.

Since the github gem currently derives its user + API token information from your global git config (git config --get github.user), instead of a nice external sqlite3 database like the twitter gem, I’m not sure what the best/correct data structure would be to add multiple user support to the github gem.

Or perhaps the github create-from-local mechanism should be extracted out of the github gem all together into a github-admin gem which would have multiple users, create public/private repos, add collaborators etc. Yeah, that might be better.

Want a default application theme?

The template will attempt to invoke a generator app_layout if it can find it. Watch the railscast on generators for an example of how to create a local generator and he gives an example of creating a default application theme generator. That’s why all the railscasts applications look the same!

Bonus section: unit testing a Rails template

If you look in the rails-templates project you cloned you’ll see a spec folder. There is a mock template_runner.rb which is used by the spec/mocra/template_spec.rb. This way I can stub out calls to command-line tools like slicehost-slice list and twitter register_oauth and check that the template installs the correct plugins, creates the correct files, etc without actually installing or creating anything.

More importantly its a lot bloody faster to run than the full template.

If you’re creating Rails templates with interesting logic in them then writing some unit tests for your template might be a helpful idea to save time.

Related posts:

1. Using CoffeeScript in Rails and even on Heroku I’m pretty excited about CoffeeScript as a clean-syntax replacement for...
2. Dead simple JavaScript Unit Testing in Rails Formats: Video/Screencast (410 Mb, torrent) | Video only (vimeo)...
3. First look at rails 3.0.pre This article is out of date in some aspects....

Imagine yourself and a posse of like-minded Ruby hackers on a country retreat with zero internet for a weekend of fun. You’ll laugh, hack, learn, cry (well, you probably won’t cry… but you know… it felt poetic) and most likely play a crap-load of guitar hero. [manifesto]

In chronological order, the first RailsCamps in Australia were in the states: New South Wales, Victoria, New South Wales, and South Australia.

This time, between May 15th and 18th, it’s in Queensland. God’s Country. The Sunshine State. Home of Steve Irwin (deceased), Sir Joh Bjelke-Petersen (deceased), Greg Norman (expat), Keith Urban (expat), and Kristy Hinze (marrying ex-Silicon Graphics/ex-Netscape billionaire Jim Clark; expat). So its a pretty famous and popular place to come from.

Book your tickets now for RailsCamp #5.

• Date: May 15-18 2009
• Cost: $164
• Where: Koonjewarre Retreat Centre, Gold Coast Hinterland, Queensland
• Airport: Gold Coast Airport, Coolangatta
• Website for bookings: http://railscampau.github.com/

Foreigners and RailsCamp.au

There is no official foreigners policy. More generally, there aren’t too many policies on anything for RailsCamps. Its noteworthy that we’re a country founded 200 years ago on Britain’s primary export in the 1800s: shoplifters. So we’ll accept just about anyone. If you can get through Customs and Quarantine into our country, then we’ll let you come to RailsCamp.

Since RailsCamp.au starts just after RailsConf finishes, it would seem like an idea back-to-back “working” holiday. If you arrive early into Brisbane we’ll find you some office space to hang out in, or we’ll point you in the direction of some places to go touristing.

RailsCamp tickets sell out faster than RailsConf tickets, so decide fast.

Related posts:

1. I Still Call Australia Home On the 25th of September I’m doing a one-day workshop...
2. Railsconf – the sessions I’ll be attending http://myconfplan.com/conferences/RailsConf2007/users/drnic This is a new site called MyConfPlan, built...

Its almost Christmas time and that means presents.

It also means that sometime between today and December 25th you need to go out and buy other people some presents because you haven’t done it yet.

But there’s someone else special in your life that deserves an Xmas gift this year. That special someone is your open source projects.

You might think, “But, Dr Nic, what do I get for the open source project that already has everything? What gift would my open source projects possible appreciate?”

Its true – this year has been a boon for open source. You probably migrated your projects from SVN to Git this year. Specifically, you probably clicked the “create a new one” link on your GitHub home page a lot this year: either to migrate your old projects to github or start new ones. Lots of new ones.

And now that your code is on github, your README file is rendered beautifully on the home page, so you were more inclined to rename it to README.markdown or README.textile and thusforthly fill it full of education information about your projects.

More people would then instantaneously figure out what the f@#$ your project actually does, thus more people used it, thus more people wrote patches or forked your code and sent Pull Requests.

All round, in 2008, I bet your open source projects had a sweet year.

Nonetheless, it is Christmas time and you should now get them a present. Something they wouldn’t get for themselves. Something you wouldn’t have done for them except for the free loving spirit of Christmas.

The Gift for all Open Source projects

A website.

Oh sure, github renders your README.markdown file. Yeah, yeah, github gives you a wiki for your project. Sure, sure, Google Groups let you communicate with your co-developers and users. Certainly, you don’t need a website for your project.

That’s why its a Christmas gift. You’re going to do it because you care.

Websites sell your project. READMEs and Wikis educate. The project website will sell it and make people want to use your stuff.

A website could have a blog with an RSS/atom feed. Then you could post updates about your project. People could subscribe and also leave comments. Oh the novelty.

And if it only took 5 minutes to get all this setup – the website code, the blog engine, the RSS feed, the comments, and published to its own hosted server – then that would just be oh so sweet.

So we’re going to do some craft for our Xmas present. A little DIY project, if you will. You’ll need a few things that you’ll find around your house, a command-line interface, and a beer or perhaps some port or sherry. Christmas cake is good too.

The commands below take about 5 minutes to execute and you’ll have a sweet website for your project, setup on GitHub Pages, just like the macruby-tmbundle and jekyll_generator sites, and the sample image above.

Jekyll and GitHub Pages

Jekyll, by Tom Preston-Werner, is one of several static website generators. All your website content will be written in textile or markdown, rendered against some HTML layouts, and published on a website somewhere. We’re going to use GitHub Pages because they are new and shiny, and free, and I’ve written some sake tasks (below) to make it all easy peasy to get up and running.

There are a bunch of reasons we’re going to use Jekyll to render our website:

One, textile and markdown are much nicer to write/edit text than HTML.

Two, Jekyll is “blog enabled”. That is, some of your pages will be specifically “blog post” pages, and elsewhere in your layout you can programmatically list them. Like a blog. Yeah.

Three, GitHub Pages automatically supports Jekyll but no other static-website generators. This saves you from having to manually render your HTML from your Textile/Markdown pages before pushing the site to the remove server.

Four, I wrote a stand-alone generator to create a Jekyll website for any project. It is preconfigured with Disqus for comments, including badges for latest comments etc.

Living with a Jekyll

Jekyll comes as a RubyGem:

sudo gem source -a http://gems.github.com/
sudo gem install mojombo-jekyll

You can either read the Jekyll README and create your project website by hand (and then skip below to Living with GitHub Page).

Alternately, you can cheat and use a generator.

jekyll_generator

For the last few years, newgem has come with the ability to create a website for your project. For the jekyll_generator I decided to go with a separate generator so that any project – rubygem, rails plugin, javascript project, etc – can easily use it.

sudo gem install jekyll_generator
cd path/to/project
jekyll_generator website --title "Project Name"
cd website
jekyll
open _site/index.html

The final steps performs the local rendering of your website (jekyll) and then on OS X it opens the rendered website into your browser. Otherwise, manually open the index.html from the _site folder.

Currently the generator assumes that your project is already in a git repository that is hosted on github (specifically that you’ve added the github project as the origin remote).

Living with GitHub Pages

GitHub recently released GitHub Pages as a place for you to publish a personal website and websites for each of your projects. Instead of requiring you to rsync or “rake website” your way to publishing glory, you just use git.

Specifically, you put your website in a branch called “gh-pages”. When you push commits in that branch to github it will automatically refresh your website. No rsyncing required. Also, it will run your website through Jekyll.

So much delicious magic.

Except our website is not currently in another branch. Its in master. In a folder called website. Where it should be.

But the boffins at github say we need to move our shit across to a branch called gh-pages, and who are we to argue.

I personally will never be doing this migration manually. I figured it out once and slapped it into a sake task. It moves all the content in your website folder into this branch, and replaces it with a submodule link so you can access the website from your master branch. Didn't follow that? No, me neither. Let's just run the sake task and move on with our lives, and eat fresh prawns and Christmas pudding.

Sake tasks to get started with GitHub Pages

To install them from scratch (initial blog post):

sudo gem install sake
cd /tmp
git clone git://github.com/drnic/sake-tasks.git
cd sake-tasks
rake install:all

You can toss away the repo after installing the sake tasks.

You now have some tasks to manage github:pages:

sake github:pages:migrate_website   # Migrates an existing website folder into a gh-pages branch, and links back as submodule
sake github:pages:setup             # Creates the gh-pages branch, and links to it as 'website' as submodule

Since we've already created the website above, we're going to use the first task to migrate this folder into the required gh-pages branch.

sake github:pages:migrate_website

Um, and your done.

Note, if sake crashes and burns in your project it might be that you don't have a Rakefile. Try, "touch Rakefile" and rerun the sake command.

In 1-10 minutes your fancy new site will appear at http://username.github.com/projectname. It even has a complimentary first blog post. You might want to change it to something useful.

You can now update your website via your website folder, commit changes and they automatically appear, automatically rendered via Jekyll, on your website.

Disqus for comments

Since your new website is static text there is no way to support comments on the blog posts. I've bundled into the theme's layouts the access code for Disqus. Like the image above, each blog post has Disqus comments at the bottom, and the sidebar shows the latest comments from all your blog posts.

You need to create a Disqus account, and create a project with the same name as your github project name. For example, if jekyll_generator is the project name on github, then make it the name on Disqus.

In my example above, my github project name was jekyll_generator but I couldn't use underscores on Disqus, so it is jekyll-generator. Fortunately, the generator templates already know this, and have converted your underscored name to hyphens already.

You can skip the "Choose your platform to install" steps as this is all done by the generator templates.

If you reload your project's website it should have Disqus badges on the sidebar, and the posts should have comment boxes.

Lighthouse for tickets

Lighthouse offers free access for open source projects to track their bugs. After you've created your Lighthouse project, you need to change the TODO values in _layouts/default.html and _layouts/post.html to your Lighthouse project number.

Updating your website

Your website now appears within your project source under the website folder. Though if you change it, add new posts, etc, you won't be able to commit the changes back normally. The contents of the website folder are effectively another git repository.

To commit changes to your website, go into the website folder and proceed normally:

project(master) $ cd website
project/website(gh-pages) $ git commit -m "some changes"
project/website(gh-pages) $ git push origin gh-pages
project/website(gh-pages) $ cd ..
project(master) $

Now your submodule may be dirty and need updating:

git submodule update --init

Not sure what this is all about.

Summary

A website is a great way to show that your pride and joy isn't ignored by new visitors and reminds existing users just how awesome the project is, and by clever association, how awesome you are.

A sexy website has to be even better.

Jekyll is great, and the Github Pages concept seems fun. Perhaps it wouldn't be necessary if the Github Wiki content was available as its own git repo, or if you could theme your project's source browser like a diry MySpace page.

Hopefully the sake tasks make migration of any existing websites to the Github Pages system easy peasy, and hopefully the jekyll_generator is useful for any new projects.

Hopefully.

Merry Christmas.

Related posts:

1. Hacking someone’s gem with github and gemcutter Ever used a rubygem, found a bug, and just...
2. Future proofing your Ruby code. Ruby 1.9.1 is coming. Bugger. I’m a Ruby monogamist. I use the Ruby...
3. newgem 1.0.0 all thanks to Cucumber The New Gem Generator (newgem) was exciting, moderately revolutionary, and...