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.
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()"
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:
Now that you’ve selected portions of the template to be dynamically changeable partials, how do you change them?
Use <% content_for :menu do %> ... <% end %> from any view template
Create a _menu.html.erb partial in your controller’s views folder, e.g. app/views/posts/_menu.html.erb
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:
Ever had IM chats where a conversation splits into multiple topics? You’ll be able to follow along, intelligently piecing together which-message-goes-with-which-topic, until the following scenario inevitably occurs:
me: What's on this weekend? Going to the football?
me: Are you and Jackie still seeing each other?
me: Eh? Yes - football or yes to Jackie?
That is, eventually the messages become ambiguous as to which topic they go to.
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.
Restart Gmail, fire up a chat to someone (for example, complain of bugs to firstname.lastname@example.org) 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
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.
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.
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.
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.
There’s only so many hours in the day and only so many technologies people can be awesome at. So sometimes there are projects that developers can’t do themselves. Either the scope is too big, the timeframe to urgent, or it falls outside their areas of expertise. Or you’ve already got yourself a sexy job and you just don’t need the work. If this situation ever happens to you I would love for you to ask me if I can help with the work you can’t do or don’t want.
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 email@example.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.
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.
In order to distribute payments to you, could you please email us at firstname.lastname@example.org 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.
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.
“this article shows how I used test-driven development tools and processes on a Greasemonkey script.” Though it also includes free ninjas.
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.
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.
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.
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.
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">
<link rel="stylesheet" href="screw.css" type="text/css" charset="utf-8" />
<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>
To run our first test just load up the spec/fixtures/ninja_search.html file into your browser.
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.
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
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).
Deploying via GitHub Pages
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.
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/
git commit -a "latest script release"
git push origin gh-pages
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.
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 email@example.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?
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?
rails -m rails-templates/mocra.rb default-twitter-auth-app
Which user authentication system? 2
Install http://default-twitter-auth-app.mocra.com application on which slice? 3^H1
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.
* 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:
Please enter your API key since you did not provide one:
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.
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.
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
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?
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.
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.