How to integrate a HTML theme into your Ruby on Rails application

There are millions of free WordPress themes on the internet but no Rails specific themes. This post shows one approach for integrating HTML/Bootstrap themes into a Rails application.

The solution is HTML/CSS/Bootstrap themes that take care of all the styling, animation and responsive design for you, allowing you to build a professional, custom website that looks brilliant and works on different screen sizes.

There is some work involved in integrating these with your Rails application though it is surprisingly easy, if you follow a methodical approach. With some basic refactoring and moving assets to a directory where Rails can find them, you can easily integrate an existing HTML theme with your Ruby on Rails application and improve your apps instantly.

To get started, google “Free Bootstrap HTML themes” and pick a nice template to use. Keep in mind that more complex templates with animations and responsive design tend to be harder to maintain and integrate because you have to follow the original creators HTML structures and CSS classes. (It can be hard getting your head around the theme classes).

This tutorial should work for any template as they are all based on the same components.

Step 1: Copying the HTML

To start off simple, all we are going to do is copy the index.html file into your application.html.erb file, more specifically, copy the body-tag and its contents. Make sure you leave the original header-tag contents like JavaScript and CSS style sheet imports (the Rails default code created during scaffold). This will work because we are going to import custom CSS and JavaScript somewhere else. Start your Rails server and have a look at your home page. There should be no styling whatsoever (you might have basic Bootstrap styling if you have Bootstrap installed). This is good!

Step 2: Adding CSS Styling

We are going to add one new asset at a time, testing as we go. First, we should add all CSS assets to get some basic styling going. Thankfully, the Rails Asset Pipeline takes care of the assets for us.

• app/assets: This asset folder contains asset specific to your rails application.
• lib/assets: This folder contains your own asset libraries that are shared across applications.
• vender/assets: Put all other assets such as JavaScript plugins or CSS frameworks in this asset folder.

Rails Asset Pipeline

In order to use this Rails feature properly we should take a moment to understand the different asset locations in Rails. There are three different asset folders in Rails, which sounds confusing at first but it is actually really simple.

We will use the first asset folder for all out assets because all of the HTML theme assets are specific to your application. Rails Asset Pipeline concatenates all asset files to create one big JavaScript and CSS file. This reduces the number of browser request for asset fetching. We can define which assets are included in this “master” asset file by importing all required JavaScript and CSS files into the javascript/application.js and stylesheets/application.css files respectively. The benefit of this is that we need only 1 import statement in our application.html.erb file for CSS and JavaScript (as opposed to one import per file).

Adding CSS assets

To add the theme’s CSS to your Rails app, open your HTML theme folder and then copy the contents of the #{theme_name}/css folder (also known as #{theme_name}/stylesheets) into your Rails assets/stylesheets directory. Next, add references to these files to your stylesheets/application.css stylesheet. The asset pipline will use this file to concatenate all CSS files into one massive CSS file. If you are using Sass, the file extension would be application.scss or even application.css.scss.

Example

Say you just added the following style sheets to your assets folder (in reality, there would be many more depending on the size of your theme and styling complexity):

assets/stylesheets/
    main.css
    animation.css
    responsive.css

In this case, add the following lines to your application.css file to link them correctly in Rails:

@import "main"
@import "animation"
@import "responsive"

Some assets have dedicated Ruby gems. So if you see font-awesome, for example, do not include the related style sheets. It is better to add the appropriate gem to your gem file and to use bundler to handle the installation. Font Awesome is very common so if you have the font-awesome.min.css style sheet, simply delete the CSS file and add gem 'font-awesome-rails' to your Gemfile. Similarly, don’t include bootstrap.min.css and use the dedicated bootstrap-rails or bootstrap-sass gem. If you choose not to do this, everything should (in theory) still work as long as you imported the required style sheets.

Restart the Rails server and check out your website. You should have basic styling and your rails app should already look a lot like the HTML theme you selected! Isn’t this great? Major results with so little work. Images and JavaScript related content won’t work just yet, but we will fix that in the next section. <!– Ad Slot 1 –>

Step 3: Add JavaScript files

The process of integrating JavaScript files is very similar to adding CSS files. The syntax used to add files to javascript/application.js is as follows

//=require "main"
//=require "animation"

Note that we can ignore file extensions here and it will work just fine. Restart your rails server to allow Rails to recompile assets and check out your web app. You should now have both CSS styling and JavaScript. At this point your website should look a lot like the HTML theme, with the exception of image assets which will add in the next section.

Step 4: Adding image assets

Copy all your image assets into assets/images making sure to keep the original directory structure as used by your theme. This will make editing image links a lot simpler. Now we have to convert all HTML image links in the application.html.erb view to their Rails equivalent. An image tag in Rail’s default templating engine, ERB, looks like this:

<%= image_tag "logo.png", class: "logo-style", alt: "Alt Text" %>

Follow the instructions in this post to find out more about using regular expression text replacement to replace and convert these tags. The basic steps are shown below. Change the imgs/ string in the match regex to be the start of the images linked in the HTML image tags. Doing this will replace the old path (which was correct in the static HTML theme) with the new Rails path where the Asset Pipeline can find a precompile your image assets.

Basically, we have to perform the following regex replacement. Match this:

<img src="files/(.*)" class="(.*)" alt="(.*)">

and replace it with this:

<%= image_tag "images/", class:"", alt: "" %>

This regex replacement inserts class and alt attributes into all image tags. The regex is not perfect. You can rectify the issue by searching for , class: "" and , alt: "" and replacing them with nothing to get rid of unnecessary attributes.

Once you successfully completed this step, restart your rails server and your HTML theme should be fully functional in your Rails app! Now it’s time to customize the layout file and add the <%= yield %> line in an appropriate spot to display your dynamic views. Your theme’s index file likely contains different sections to showcase the themes CSS and JavaScript features. Remove these sections as desired to change the layout and content of your web app.

Always keep the original theme files because you can refer to them later to reuse building blocks like pricing tables and other theme-specific CSS goodies. You could even create reusable partials for these HTML structures to make using them really simple and DRY.

Conclusion

Let me know what you think in the comments below.