Add WrapBootstrap Theme to Rails Project

Some tips and suggestions for adding a WrapBootstrap theme to a Rails project. The following are my notes after integrating the cleverAdmin theme into a Rails 4 project that was already using Bootstrap 3.

I purchased a couple themes before choosing one and noticed that each theme has its own file structure so I’ve tried to keep these tips general. If you’re lucky, you’ll choose a theme that has documentation. (I didn’t.)

Turns out the whole process wasn’t that bad if you have a decent understanding of the Rails asset pipeline.

Tip 1

Unpack the theme’s files in a location separate from the Rails project. Commit to yourself that you’re not going to modify these files. You’re going to want to have a complete original copy as a reference. Plus you’re not going to want all of the files in your asset pipeline.

Tip 2

Understand your starting point. This will make sure you avoid problems from multiple inclusions. For example, my Rails 4 project was already using the following gems:

Hit F12, use Firebug or some other tool (or go old-school and just view the source in the browser) to see which Javascript and stylesheet files are already being included.

Tip 3

The files from the theme belong under vendor/assets. From the Rails guidelines:

app/assets is for assets that are owned by the application, such as custom images, JavaScript files or stylesheets.

lib/assets is for your own libraries’ code that doesn’t really fit into the scope of the application or those libraries which are shared across applications.

vendor/assets is for assets that are owned by outside entities, such as code for JavaScript plugins and CSS frameworks.

And to make sure the theme’s files are easily identifiable and there aren’t any filename conflicts, create subdirectories. I used the label clever and ended up with:
vendor/assets/stylesheets/clever
vendor/assets/javascripts/clever
vendor/assets/images/clever

As you’re copying the theme’s files into the vendor/asset directories, make sure you’re not creating duplicates of the files you identified in Tip 2. (Seriously, pay attention. This will create issues that are a bear to track down.)

And be sure not to copy over anything that isn’t needed as an asset. For example, don’t copy over the example HTML pages or any documentation.

Tip 4

If you put the assets in a subdirectory under vendor/assets, this subdirectory will need to be added to any references to the theme’s assets. For example, in application.css or url() statements in stylesheets.

Tip 5

Chances are your theme uses some third-party font libraries like Font Awesome or Glyphicons. If you don’t already have a vendor/assets/fonts directory, here’s a great straightforward guide to getting that set-up. My personal choice was to install the font libraries separately and before the theme. This way, if I decide to remove or change the theme, I still have the fonts.

Tip 6

Don’t forget to add the necessary lines to app/assets/stylesheets/application.css and app/assets/javascripts/application.js

If you’re lucky your theme has documentation but it may still take a little detective work and trial and error to figure out. A good place to look is the source of the theme’s example pages.

To get started, the cleverAdmin theme needed:

(Climbing up on my soap box … ) This is a great example of why you shouldn’t use //= require_tree . and *= require_tree . Think of all the unnecessary and confusing theme files that would be picked-up.

Tip 7

Make sure all of the above is taken care of and there are no errors before you start modifying any of the theme’s files. Things are going to look a little odd since the asset paths are probably wrong but this way you know you haven’t introduced any problems.

Tip 8

Unless your theme is Rails-ready, you’re going to need to update the theme’s stylesheets to use the correct asset path. A quick grep for "url(" of the stylesheet files will let you know what you’re in for.

The exact way you reset the paths will depend on the file type you’re editing and your set-up. I prefer to skip the helper methods and add the correct path directly.

For example, this:
     url("../img/select.png")
becomes this:
     url("/assets/clever/select.png")

If you used one, don’t forget to add the vendor/assets subdirectory in the path.

Tip 9

When was the last time anyone used a theme without making a few changes?

Might as well set-up an easy way to make modifications and ensure any edits you make are saved in your source control. vendor/assets is now in my git repository.

For example, I created a directory vendor/assets/stylesheets/clever/less for the theme’s Less source files. As I adjust the colors/etc, I compile the Less files into a new file clever_style.css. This file is now included in application.css instead of clever/style.min.css.

Other Thoughts

  • I had no (none, zip, zilch) problems pre-compiling the assets and running the Rails app in a production environment. Makes me suspicious. Nothing’s that simple so if (when) I find any compiler issues, I’ll update this post.
  • After all this, I’m still not sold on the idea of using a third-party theme. Just for fun, I created a branch and deleted the theme to see how much clean-up there would be and it wasn’t bad so it stays for now. This is a big reason for using a subdirectory and separating out the font libraries.

Was this helpful? Have another tip or suggestion? Please leave a comment.