Many popular CSS frameworks and JavaScript libraries are already available as gems. Search RubyGems to see if the assets you’re interested in are already packaged this way. What if the JavaScript library you use isn’t yet available as a gem? Packaging and publishing asset gems is simple. Here’s your chance.

External assets are made available in Rails via Rails engines. When the engine is loaded into your Rails application, the engine’s asset paths are added to your application’s load paths. This makes them available for require in your manifest files. An asset gem is just an absurdly simple engine. As an example, I’ll walk you through the process I recently took for momentjs-rails. The process is wordy, but it’s really pretty simple.

Create Gem Framework

Bundler makes it simple to create the files and folders necessary for creating a gem. Run the following command to create and initialize a Git repository along with several template files for the gem.

1

$ bundle gem momentjs-rails

Versioning

In this case, momentjs-rails is a gem packaged version of the Moment.js library. Its version should track the version of JavaScript library it wraps, which is currently 1.3.0. Open lib/momentjs-rails/version.rb and set the version like so:

1
2
3
4
5

module Momentjs
  module Rails
    VERSION = "1.3.0"
  end
end

In the event that you need to push an update to your gem that does not change the version of the assets it wraps, I would investigate adding a fourth value to the version string (1.3.0.1).

Start Your Engine

Bundler created the gem as a standard Ruby module, but we want it to be a Rails engine. Edit lib/momentjs-rails.rb to subclass Rails::Engine like so:

1
2
3
4
5
6
7
8

require "momentjs-rails/version"

module Momentjs
  module Rails
    class Engine < ::Rails::Engine
    end
  end
end

Yes, the class is empty on purpose. All we’re doing here is declaring the gem as an engine. This will cause rails to add its directories to the load path when the gem is required.

Add The Assets

Download the asset files you want to include in the gem. If availble, I prefer to use the uncompressed, non-minified versions. They’ll actually be readable if you need to dig into them and you can rely on the asset pipeline to minify them in production or on precompilation. In the case of the Moment.js library, I downloaded the release version to my desktop and ran the following commands:

1
2

$ mkdir -p vendor/assets/javascripts
$ cp ~/Downloads/moment.js vendor/assets/javascripts/moment.js

I used the vendor/assets directory here because these aren’t assets I’m maintaining directly. If they were assets I was responsible for maintaining, I would put them in app/assets though the difference is purely semantic.

Complete The Gemspec

The momentjs-rails.gemspec file contains all of the details that describe the gem. Open it up and complete any pending TODOs left by Bundler. I usually set the homepage to the GitHub repository for the gem. Additionally, I removed the gem.executables and gem.test_files lines, as this gem has neither. I also prefer to change the gem.files setting to avoid shelling out to git. I used the following pure-ruby implementation instead:

1

gem.files = Dir["{lib,vendor}/**/*"] + ["MIT-LICENSE", "README.md"]

Railties needs to be declared as a dependency of the gem. Our gem needs Rails 3.1 or greater, but we’ll stop short of 4.0 for now. Use the following setting:

1

gem.add_dependency "railties", "~> 3.1"

Build and Test

Bundler set up some default rake tasks for us that save a few characters when building. Simply run rake build to build the gem.

I haven’t included any specs with this gem. Full-featured engines usually have a dummy Rails application in the test directory that loads the engine and can be used to run tests. While this would work to test the asset gem, I haven’t set this up yet. Instead, I generally do the following:

1
2
3
4
5
6
7
8
9

$ rails new momentjs-test
$ cd momentjs-test
$ echo 'gem "momentjs-rails", :path => "/Absolute/Path/To/Gem/Directory"' >> Gemfile
$ bundle install
$ echo '//= require moment' >> app/assets/javascripts/application.js
$ rails server &
$ curl http://localhost:3000/assets/moment.js
$ fg
<ctrl-c>

That’s quite the little dance, but the curl command should return the contents of the moment.js file if everything is wired up correctly.

README

I included a very simple readme file with the Gem as its sole documentation. I brifely described Moment.js, supplied simple usage instructions, and a word about versioning. See the momentjs-rails readme.

Push To GitHub and RubyGems

Create a GitHub repository for your project, stage all of your commits, commit, and push the code to GitHub.

If you’ve never published a gem on RubyGems before, you’ll need to sign up for an account there. Your account settings will contain an API key that should be copied to ~/.gem/credentials. Once that’s done, publishing your gem is as simple as:

1

$ rake release

This will create a Git tag for this version, and push the built gem to RubyGems.

Thankfully, there’s a mature, simple, and actively maintained solution just a gem away. Simple Navigation handles just about whatever you can throw at it. I was surprised, however, by how hard it was to unearth when I was looking for the solution to my navigational troubles. It’s an elegant solution that deserves more attention.

With Simple Navigation, the application’s entire navigational structure is contained in a single configuration file. The configration is specified in a simple DSL that allows for multiple levels of navigation. You can render the entire structure, with appropriate sub menus with a call to render_navigation or you can render each level explicitly with calls to render_navigation :level => 2. There is, of course, support for configuring the exact classes, elements, and ids used in the HTML.

Active item tracking can be done automatically, which works surprisingly well in basic cases. Alternatively, you can supply a regular expression or proc to determin which item should be tracked as active. If your navigation has more than one level, then the parent of an active item will also be marked as active.

The project wiki has good documentation for most features. There are a lot of options, but the configration is still easily understood. For instance, here’s a chunk of the configuration for my current project. The navigation features a static top bar with any applicable secondary menu rendered as tabs below. The entire ‘Admin’ menu is visible only to users who are administrators.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

SimpleNavigation::Configuration.run do |navigation|
  navigation.autogenerate_item_ids = false
  navigation.selected_class = 'active'

  navigation.items do |primary|
    primary.item :schedule, 'Schedule', schedules_path
    primary.item :admin, 'Admin', admin_root_path, :if => Proc.new { current_user.administrator? } do |admin|
      admin.item :admin_shifts, 'Shifts', admin_shifts_path, :highlights_on => /admin\/?$|admin\/shifts/i
      admin.item :admin_responsibilities, 'Responsibilities', admin_responsibilities_path, :highlights_on => :subpath
      admin.item :admin_locations, 'Locations', admin_locations_path, :highlights_on => :subpath
      admin.item :admin_holiday_schedules, 'Holidays', admin_holiday_schedules_path, :highlights_on => :subpath
      admin.item :admin_users, 'Users', admin_users_path, :highlights_on => :subpath
      admin.dom_class = 'tabs span16'
    end
    primary.item :preferences, 'Preferences', preferences_path
    primary.item :help, 'Help', help_path
    primary.dom_class = 'nav'
  end
end

Check out Simple Navigation for use in your Rails projects. It’s simple, powerful, and DRY.

Simplest: Homebrew built MacVim

Homebrew is my favorite OS X package manager. If you’re not familiar with Homebrew, you should check it out. You can use Homebrew to install MacVim, which includes both a GUI and console version of Vim 7.3. Passing a simple flag to brew install will instruct homebrew to setup the necessary symlinks to replace the system console Vim with the version provided by MacVim.

1
2
3
4

$ brew install macvim --override-system-vim

# If you need the app bundle linked in /Applications...
$ brew linkapps

Note: Please see the caveat below concerning building Vim

Simple: Homebrew built Vim

If you don’t want the version of Vim shipped with MacVim, you can build Vim directly from source, also using Homebrew. Homebrew does not include a formula for Vim in its official repository as that would be counter to its (occasionally broken) rule to not provide system duplicates. There’s a formula in the homebrew-alt repository that will get the job done in just a few short steps, however.

1
2
3
4
5
6
7
8
9
10
11
12

# mercurial required - install if you don't already have it.
$ brew install mercurial

# install Vim from homebrew-alt
$ brew install https://raw.github.com/adamv/homebrew-alt/master/duplicates/vim.rb

# if /usr/bin is before /usr/local/bin in your $PATH,
# hide the system Vim so the new version is found first
$ sudo mv /usr/bin/vim /usr/bin/vim72

# should return /usr/local/bin/vim
$ which vim

Note: Please see the caveat below concerning building Vim

Without Homebrew

If you’re interested in Vim, I’m guessing you’re also fully capable of using a package manager, but if you want to do this quickly and without involving Homebrew and without running afoul of the caveat below, you can download and install the MacVim app bundle and setup an alias to point to its version of Vim. Assuming you have MacVim installed to /Applications/, you can add the folowing to ~/.bash_profile or other appropriate configuration file.

1

$ alias vim="/Applications/MacVim.app/Contents/MacOS/Vim"

Caveat: Locally Built Vim

If you build Vim locally via Homebrew or any other method and you use RVM or rbenv to manage multiple rubies, you should be sure to switch to the system installed Ruby when building Vim and any compiled plugins (such as Command-T). If you build Vim against one Ruby and Command-T against another, the penalty will be a SegFault when launching Vim. In that case, rebuild both against a consistent Ruby.

Specific Versions For Everything!

Developers in the first camp routinely lock gems down to specific versions ('3.1.0') They argue that this ensures all developers and all deployment environments run the same version of the project’s dependencies. While this is true for direct dependencies listed in the Gemfile, it is not true for the dependencies of those dependencies. This position shows a fundamental misunderstanding of how bundler works. The complete versioning picture is maintained by bundler in Gemfile.lock, which is generated when bundle install is run for the first time. Subsequent runs of bundle install install only the exact versions listed in Gemfile.lock. This is why it’s critical that Gemfile.lock be checked into source control. It’s Gemfile.lock – and not Gemfile – that provides complete consistency across deployments.

This is important: the Gemfile.lock makes your application a single package of both your own code and the third-party code it ran the last time you know for sure that everything worked. Specifying exact versions of the third-party code you depend on in your Gemfile would not provide the same guarantee, because gems usually declare a range of versions for their dependencies.

Pessimistic Version Constraints for All!

Some developers lean on the use of the pessimistic version constraint (~>). In fact, the rubygems web interface encourages this explicitly on every gem page. In the absence of an existing version that breaks compatibility I find this unnecessary as well.

The pessimistic constraint is typically used to lock a gem to a specific major.minor version while allowing the patch level to increase. For instance, '~> 3.1.0' would lock the gem to version 3.1.x. The effectiveness of this approach depends on gem authors strictly following a rational or semantic versioning policy. Even well-meaning gem maintainers accidentally introduce breaking changes or performance regressions in patch number releases. A patch level release may also take new versions (major, minor, or patch level) of its dependencies which may cause issues with a different direct dependency in your gemfile.

Regardless of the constraints used in the Gemfile, the developer must still exercise caution when updating the bundle. It’s unclear to me what advantage using pessimistic version constraints by default offers.

Promiscuous Gemfiles

I opt to leave my gems unconstrained by default. Updating gems in the application bundle is done with bundle update <gemname> and will change Gemfile.lock. This is a conscious operation and is undertaken with care. If the project’s test suite or QA plan fail then it’s appropriate to add a version constraint to the offending gem or update the application to remedy the incompatibility.

I will leverage a pessimistic version constraint when, for instance, maintaining a rails 2.3.x project. The '~> 2.3.14' constraint would allow the project to update to newer security fixes while not introducing changes I know to be breaking from the 3.x releases. I will use an exact version constraint if, for example, a gem introduces breaking changes in a patch number release. The result is a less noisy Gemfile where all of the version constraints are immediately obvious and usually documented with appropriate comments.

The introduction of bundler 1.1 (currently at release candidate 3), adds the command bundle outdated which is a boon to this approach. bundle outdated returns a list of gems that would be updated if bundle update were run with no arguments. This allows me to easily see which gems have been updated and investigate the changes before running bundle update. It’s important to note that bundle outdated will not show you versions that don’t meet the constraints specified in your gemfile. If you have a gem specified with the constraint '~>2.0.0' and the maintainer releases version 2.1 bundle outdated won’t alert you to this. When paired with an unconstrained Gemfile, bundle outdated can help developers keep up with changes to dependencies that might prove useful in their project.

Conclusion

Unnecessary constraints make updating gems a hassle, particularly as your project ages or new versions of your dependencies and their dependencies are released. If you alter a constraint to pick up a new version of a direct dependency, you may find that bundle update fails until you alter additional constraints. This hoop jumping can be avoided by removing all but the strictly necessary constraints and employing bundle update with care.

Fortunately, with a little work we can use the External Tools configuration in RubyMine to invoke PeepOpen.

1. With RubyMine closed, navigate to your /Applications folder and rename the RubyMine app bundle (i.e. RubyMine 3.2.3) to RubyMine. I tried numerous escape sequences when configuring the external tool to avoid this, but none of them worked.

2. Launch RubyMine, open preferences, and navigate to the “External Tools” section under IDE Settings. Add a new external tool. Name it, group it, and describe it however you wish. Make sure you turn off the console option. Set the program to open and the parameters to peepopen://$ProjectFileDir$?editor=RubyMine. My configuration looks like this. Apply these changes to save the new command.

3. Go to the KeyMap settings in RubyMine and search for the command you just created. Add a keyboard shortcut of your choosing. I used command-t, just as I had in MacVim and TextMate.

4. Be sure to apply all changes before exiting the preferences. Load up a project and give it a shot!

Notes

• The editor= line in the parameter tells PeepOpen which application it should send the file to. The space in the RubyMine app bundle name was causing this to fail. I tried numerous ways of escaping this before giving up and renaming the bundle. I’ve always been annoyed by it, anyway.

• I had some issues with the $ProjectFileDir$ macro in my project. $Projectpath$ and $SourcePath$ were also incorrectly mapped. I fixed this by adding/removing some random items under the Project Structure settings, but it’s not clear why this was necessary.

• You probably want to open your PeepOpen preferences and set it to exclude the .idea directory by adding that path to “Directories to Ignore”.