Dr Nic

Install any HTML theme/template into your Rails app

theme applied and menu update

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].

refreshed theme

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"

refreshed theme - identifying partials

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()"

refreshed theme - identifying partials

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. Instant new Rails applications with the App Scrolls When I start a new project I want to start...
  2. Using CoffeeScript in Rails and even on Heroku I’m pretty excited about CoffeeScript as a clean-syntax replacement for...
  3. Dead simple JavaScript Unit Testing in Rails Formats: Video/Screencast (410 Mb, torrent) | Video only (vimeo)...
  4. First look at rails 3.0.pre This article is out of date in some aspects....
  5. Rails themes can remember things I was getting annoyed at having to remember all the...

41 Responses to “Install any HTML theme/template into your Rails app”

  1. Robert Boyd says:

    that is pretty ninja. thanks nic.

  2. Good stuff. I was just about to waste a day importing a template from a current project I have.

  3. Mark Coleman says:

    That is utterly brilliant! And a haml option too!
    I wish I knew about it last week; on the other hand, I know that it will come in very handy next week :)
    I’ve also been finding compass very handy for handling designs, I’ll have to get my head around how to use them both.

  4. [...] This post was mentioned on Twitter by Ruby Reflector. Ruby Reflector said: Top Ruby Article: Install any HTML theme/template into your Rails app: So we're only left.. http://bit.ly/VaPkW [...]

  5. [...] See the article here: Dr Nic ’s Install any HTML theme/template into your Rails app [...]

  6. +1 for usefulness. Great idea.

  7. [...] Shared Dr Nic ’s Install any HTML theme/template into your Rails app. [...]

  8. [...] Install any HTML theme/template into your Rails app – Dr. Nic goes public about the install_theme project. [...]

  9. brainopia says:

    Very useful, thanks. It would be nice if it could export themes from remote sources.

  10. Guoliang Cao says:

    This is brilliant. Thanks.

    I can imagine that people will fork this away and make it integrated with their work flow.

  11. [...] Interactivity in Web Design: A Beginners Guide Desizn Tech Life is beautiful: Flash vs. HTML5 Dr Nic s Install any HTML theme/template into your Rails app Firefox Chrome * 10 Years of Virtual Machine Performance (Semi) Demystified Engine Experience [...]

  12. [...] Dr Nic ’s Install any HTML theme/template into your Rails app Really interesting stuff from Dr. Nic. [...]

  13. This is a fantastic idea, but I couldn’t get this link to work:

    http://localhost:3000/original_templates

    It would have been pretty impressive if that had worked.

  14. Amar Daxini says:

    very much useful ,and nice idea

  15. Dr Nic says:

    @Giles – sorry, the url was wrong. Thanks for spotting that. It should be http://localhost:3000/original_template (no trailing s). I’ve updated the post above.

  16. Dr Nic says:

    The post has been updated to reverse the order of the first two arguments (path/to/rails/app and path/to/template) in line with 0.7.0 release.

  17. [...] original here: Dr Nic 's Install any HTML theme/template into your Rails app SHARETHIS.addEntry({ title: "Dr Nic 's Install any HTML theme/template into your Rails app", [...]

  18. Rick Bradley says:

    I feel like somehow this is one medium step away from producing an hquery lovechild that would be truly bad-ass.

  19. [...] See original here: Dr Nic 's Install any HTML theme/template into your Rails app [...]

  20. Nic, that’s downright extraordinary, I had no idea there was a bug there. I was kidding. I meant that I would be impressed if the link worked because I was reading it late at night, clicked it – blind moron instinct – and then wondered why I got a routing error. Ah yes, because that link’s to localhost and I haven’t installed anything. I meant I would be impressed if it worked because I clicked it without setting anything up or even thinking for a split-second, and for **that** to work would be magic. Anyway, I guess the angels of bug detection guided my hand.

  21. Dr Nic says:

    @giles – that is stunning. Jedi instincts. Damn.

  22. insane.dreamer says:

    Brillant! Extremely useful. Thank you.

  23. Dr Nic says:

    As of 0.8.0 you now use /text() or :text at the end of path expression to replace the inner HTML of a selected DOM node. Without this suffix, you will replace the selected node itself.

    There is now also a --action posts/show flag: the extracted main content of the themed page is stored as app/views/posts/show.html.erb (or .haml).

  24. Jeff Owens says:

    Hmm, getting hpricot error when running install_theme command. I’m rolling on snow leopard and can load and use hpricot gem just fine from irb. Using Rails 2.3.4. Any suggestions?

    install_theme . themes/refreshed/ “.lowerright:text” –partial “menu://div[@class='nav']/text()”

    /usr/local/lib/ruby/gems/1.8/gems/install_theme-0.8.0/lib/install_theme.rb:126:in `convert_file_to_layout’: undefined method `Hpricot’ for # (NoMethodError)

  25. Dr Nic says:

    @Jeff – Doh. I was playing with a nokogiri implementation and forgot to restore the require statement. I didn’t notice the bug when I used it because I use haml, which loads hpricot. Thanks for the notice. v0.8.1 released with fix.

  26. [...] Dr Nic ’s Install any HTML theme/template into your Rails app [...]

  27. [...] Dr Nic ’s Install any HTML theme/template into your Rails app – October 21st ( tags: rails theme templates html template rubyonrails design plugin ) [...]

  28. James White says:

    I just recently started learning RoR and have been wondering how one would go about installing a theme from Themeforest into a RoR application. This was great! Thanks!

    On another note, I think there is an untapped market for these kinds of tutorials over at nettuts/themeforest. Their tutorials are predominantly PHP based and not super helpful for those trying to break into RoR. You might want to consider turning this into a screencast and submitting it. It would be an easy $150-$200 and I think the community would really benefit from a splash of RoR. Not to mention it would probably help sell a TON more themeforest themes.

  29. Andrew says:

    I’m new to rails and I can’t figure out *exactly* how to use this.

    The example provided is: install_theme path/to/rails_app path/to/template content_path

    And while I understand the path-to-rails and path-to-template, I don’t know what content_path means?

    Thanks in advance…

  30. Dr Nic says:

    @Andrew content_path is a csspath/xpath to the “body” of the template, which will be replaced with <% yield %>

  31. Grant says:

    Dr Nic,

    I watched your comedy on Youtube, its hilarious. But, its probably more applicable to south Africa where I am from. You need to literally shove baggage down the front to your shirt or it disappears.

    On another note. I am having this error on a hosting server that wont let me install install_theme.

    ERROR: Error installing install_theme:
    rubigen requires thoughtbot-shoulda (>= 2.10.2, runtime)

    Would you know how to solve it? I am at a loss. I install shoulda gem but it still gives me the same error.

    Thanks for the great solution. Use in on my development servers all the time, although I am still new to rails and ruby.

  32. Dr Nic says:

    I’ve fixed rubigen now in 1.5.4 so that error should go. Sorry about that.

  33. Mahesh says:

    It seems that the error is still occurring on version 1.5.4. I can find the plugin on github, but I can’t find the thoughtbot-shoulda gem.

  34. Dr Nic says:

    The thoughtbot-shoulda gem is no longer being mentioned in the code. Can you post a stdout dump of your “gem install rubigen” output to the Issues tracker? That’d be great, thanks!

  35. [...] the original: Dr Nic’s Install any HTML theme/template into your Rails app Tags: goodidea, nicedesign, [...]

  36. Phenomenal work! Thanks Dr. Nic. This worked perfectly as described. It took me a few minutes to figure out the correct params and to modify my template accordingly, but that’s to be expected, and I’m very happy with the results.

    I’ll be in Sydney for WebDU in a couple of weeks, any chance you may make an appearance?

  37. Grant says:

    Dr Nic,

    I love what you have done with install theme. I have tried it a few times and it works well. I need to ask though, is there a cms that you can suggest that you use your install them with that does not require too much modification to get the theme to work?

    Thanks for all the hard work.

  38. This is so awsome :-)

    @Grant: I’d use Radiant
    @Dr Nic: Would be easy to generate Radiant Layouts with this

  39. Owen Dall says:

    Hey Nic,

    Would love to adapt to Hobo. Great work!

    -Owen Dall