I was getting annoyed at having to remember all the csspath/xpath expressions for a theme I reused in a new project.
So, install_theme now helps each theme folder remember the previously used settings.
gem install install_theme # version 0.7.0+
install_theme path/to/rails_app path/to/template #content_box \
--partial "header:#header h2" \
Now, the next time you apply that same theme to another project you don’t need to mention “#content_box” or use the
install_theme path/to/another_rails_app path/to/template
If you squint your eyes just right, you’ll notice that your original template folder now has an
install_theme.yml file. It contains your original settings. You can imagine for yourself how the rest of the “themes can remember things” magic might work.
Templates “For Ruby on Rails”
If you are a template maker, you can now easily make your HTML template “For Ruby on Rails” by including an
install_theme.yml file. Think of the children.
I changed the order of the first two arguments. In future, the path/to/template will be optional. Why? Imagine if each theme you ever used was cached in
~/.install_theme/themes and you could select a theme from a list or by
--theme theme_name. That seems neat.
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()"
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.
--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?
<% content_for :menu do %> ... <% end %> from any view template
- Create a
_menu.html.erb partial in your controller’s views folder, e.g.
- 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:
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
<%= 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
If you wanted to change the menu for a specific action, then use
content_for in your view:
<% content_for :menu do: %>
<a href="/login">sign in</a>
<a href="/signup">create account</a>
<% end %>
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()"
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') %>
yield(:menu) enables the
content_for helper to override the partials.
render_or_default helper finds the appropriate partial to use (see app/helpers/template_helper.rb for source).
Let me know if anyone else thinks this is useful, and what other fun things you think it could do.