Jzip

A Rails gem (and also plugin) for Javascript merging and compression using templates (like SASS)

Introduction

Jzip was created due to the need of simply merging and minifying Javascript files to reduce HTTP requests and file size of my assets. Using sprites for images and SASS for stylesheets only left javascripts not be optimized. AssetPackager almost suited the solution, but I wanted more flexibility in configuration. So with AssetPackager (for minification) and SASS (for merging with templates) as inspiration, I came up with Jzip. At first Jzip was a plugin only, but after refactoring the entire code base, Jzip is also available as a gem hosted on gemcutter.

Installation

Using Jzip as gem in Rails 3

Add Jzip in Gemfile as a gem dependency:


  gem "jzip"

Run the following in your console to install with Bundler:


  bundle install

Using Jzip as gem in Rails 2

Add Jzip in environment.rb as a gem dependency:


  config.gem "jzip"

Run the following in your console:


  sudo rake gems:install

Using Jzip as plugin in Rails 3


  rails plugin install git://github.com/archan937/jzip.git

Note: the following will be created at installation of the plugin:

  • assets/jzip – which is the default template location
  • assets/jzip/defaults.jz – a Jzip template which requires the default Javascript files (Prototype, Scriptaculous and application.js)

Using Jzip as plugin in Rails 2


  script/plugin install git://github.com/archan937/jzip.git

Usage

Including generated Javascript files

Just use the javascript_include_tag helper method (e.g. for the defaults.jz template):


  <%= javascript_include_tag "defaults" %>

Creating Jzip templates / partials

A .jz file (Jzip template or partial) is nothing more than a common .js file in which you can require other files for merging. You can do this by simply adding the following:


  //= require < path_to_file or path_to_template or path_to_partial or predefined_set >

Just like in Rails views and in SASS, Jzip has partials of which the output file will not be created in the target directory. The path to the Javascript file or Jzip template or partial has to be relative to the Jzip template / partial itself. Please note that specifying a preleading / in the path will be interpreted by Jzip as RAILS_ROOT/public/javascripts (which is very handy).

Other than the path to a Javascript file, you can also refer to a predefined set of Javascripts sources. At the moment, only defaults is available for the Prototype and Scriptaculous libs and application.js which are shipped with a Rails application. Any suggestions for other predefined sets are welcome.

The following instructs Jzip to merge the Prototype and Scriptaculous libraries with three custom Javascript files into public/javascripts/foo.js:

Note: template is located in assets/jzip/foo.jz


  //= require shared/top_up
  //= require /defaults
  //= require builder/module
  //= require builder/model_browser

Please see http://github.com/archan937/jzip/tree/master/test/javascripts/assets/jzip/ for a complete assets directory example.

Registering template locations

You probably already have guessed that the default location for Jzip templates is RAILS_ROOT/assets/jzip. I can imagine that you would have choosen another location. So fortunately, the Jzip engine offers you to that piece of freedom. All you have to do is put the following in your environment.rb file:


  Jzip::Engine.add_template_location < your_own_template_location(s) >

This comes in very handy when building a Rails plugin that uses Jzip because you don’t want to copy your all Jzip templates to RAILS_ROOT/assets/jzip. So let’s say your plugin is called betty, all you have to do is put the following in it’s init.rb file:


  Jzip::Engine.add_template_location RAILS_ROOT + "vendor/plugins/betty/assets/jzip"

Now isn’t that a piece cake? Not only can you pass a string containing the template location, you can also pass an array of strings (containing multiple locations) or a hash (which also specifies the output directory):

  • string – target directory will be public/javascripts

  RAILS_ROOT + "/lib/jzip
  • array – target directory will be public/javascripts

  [RAILS_ROOT + "/some/path/jzip", RAILS_ROOT + "/vendor/plugins/foo/assets/jzip"]
  • hash – target directory will be public/javascripts/betty

  {RAILS_ROOT + "/vendor/plugins/betty/assets/jzip" => RAILS_ROOT + "/public/javascripts/betty"}

Compile options

Finally, Jzip has some options that you can configure in the environment.rb file:

  • :minify – Minify the merged Javascript file using the JSMin library (default: true when in production environment)
  • :always_update – Merge (and minify when specified) the Jzip templates on every page request when outdated (default: true when not in production environment)
  • :log_level – Which is used for logging, you can pass through the regular Rails log levels (:error, :info and :debug) and even :console which puts the output in your console (default: nil)

You can specify a Jzip option by putting the following in your environment.rb file:


  Jzip::Engine.options[:minify]        = false
  Jzip::Engine.options[:always_update] = true
  Jzip::Engine.options[:log_level]     = :console

In the Rails console

You can run the following commands in the Rails console (with ./script/console):

  • Jzip::Assets.install_defaults – which installs assets/jzip/defaults.jz (see “Using Jzip as plugin” for more information)
  • Jzip::Engine.compile_javascript_files – which instructs Jzip to compile the Javascript files (this is automatically called at every request)

Contact me

For support, remarks and requests please mail me at [email protected].

Credit

This Rails engine is inspired by:

AssetPackager
http://github.com/sbecker/asset_packager/tree/master

SASS
http://sass-lang.com

Also, the Jzip engine makes use of the Ruby JavaScript Minifier created by Douglas Crockford
http://www.crockford.com/javascript/jsmin.html

Contributors

Mark Mulder – @bitterzoet – http://ikbenbitterzoet.com

ToDo’s

None.

License

Copyright © 2010 Paul Engel, released under the MIT license

http://holder.nl – http://codehero.es – http://gettopup.com – http://twitter.com/archan937 – [email protected]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.