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.
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.
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:
gem 'less-rails-bootstrap', '~> 3.0'
The files from the theme belong under
vendor/assets. From the Rails guidelines:
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.
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:
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.
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
url() statements in stylesheets.
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.
Don’t forget to add the necessary lines to
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:
//= require clever/core.min
//= require clever/custom.min
*= require clever/style.min
(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.
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.
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
"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:
If you used one, don’t forget to add the
vendor/assets subdirectory in the path.
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
- 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.