Pakunok - common assets that you need for Rails 3.1

Pakunok contains a set of prepackaged assets that you can easily include into your Rails 3.1 application (using assets pipeline).

You can see all the included assets. (reference those prefixed with pakunok/):

Tested on MRI Ruby 1.9.2.

If you have any questions please contact me @dnagir.

Install

Add it to your Rails application's Gemfile:

gem 'pakunok'

Then bundle install.

Usage

Reference as you normally do with Sprockets. Let's see some examples:

JavaScript-only libraries

You can simply reference plain JS libraries that do not require other assets (CSS, images) like this:

// app/assets/javascripts/application.js

// Include latest jQuery
//= require 'pakunok/jquery'

// Or an older version
//= require 'pakunok/jquery/jquery-1.5.2'

//= require 'pakunok/innershiv'

// jQuery plug-ins do no depend on jQuery to allow using as a separate HTTP resource
//= require 'pakunok/jquery.form'
//= require 'pakunok/jquery.jscrollpane'
//= require 'pakunok/jquery.mousewheel'
//= require 'pakunok/mwheelIntent'

//= require 'pakunok/jquery.validate'
//= require 'pakunok/jquery.validate/additional-methods'

//= require 'pakunok/jquery.viewport'

Libraries with related resources

If the library has a related CSS file, then it can be included into your CSS (or served as a separate file). It is named after the JavaScript library.

/*
 * app/assets/stylesheets/application.css
 *= require 'pakunok/colorpicker'
 *= require 'pakunok/fileuploader'
 *= require 'pakunok/jquery.jscrollpane' 
*/

Precompilation

By default Rails precompiles all the assets of all included libraries. This means that ALL of the assets will be compiled (although you rarely need that).

Please run RAILS_ENV=production bundle exec rake assets:clean assets:precompile && tree public/assets to verify necessary files.

It is recommended to change the default behaviour so that you are not precompiling assets that the application will never use:

# config/application.rb

# Something like this is the Rails default
#config.assets.precompile = [/\w+\.(?!js|css).+/, /application.(css|js)$/]

# Recommended: Explicitly add assets that you use (colorpicker),
#  so that images and styles are available.
config.assets.precompile = [/application.(css|js)$/, /pakunok\/colorpicker/]

# Exclude all pakunok assets from precompilation (it's ok if you don't have direct HTTP request to them)
config.assets.precompile = [/(!pakunok)\w+\.(?!js|css).+/, /application.(css|js)$/]

# Exclude all pakunok assets, but explicitly add ones that you use (colorpicker),
#  so that images and styles are available.
config.assets.precompile = [/(!pakunok)\w+\.(?!js|css).+/, /application.(css|js)$/, /pakunok\/colorpicker/]

Note on JQuery-UI

In many cases you do not need the full jQuery-UI package, so you can do the following:

Bundle pre-packed jQuery UI components that you are going to use on all pages into application.js (eg: require 'pakunok/jquery-ui/pack/dialog').
Serve the other additional components when you need them (as require 'pakunok/jquery-ui/effects').

All the files under pakunok/jquery-ui/* do not automatically include depndencies. This means that you can serve them separately. But if you want to include all the dependencies into a single file, then use pakunok/jquery-ui/pack/*.

HAML for client side templating

Pakunok provides a new templating engine for Rails 3.1 that can be used to produce JavsScript templates.

What you need to do is to use .hamljs extension on a javascript file with the HAML content. It will generate a plain optimised JavaScipt function that you can use on the client.

For example, assuming you have a file app/assets/javascripts/comment.js.hamljs with the content:

.comment
  .text= text
  .author= author

Then you can require comment from the application.js. This gives you access to JST.comment function allowing you to write JavaScript like:

var html = JST.comment({author: 'Dima', text: 'Awesome'});
$("#commit").append(html)

NOTE: HAML-JS is a little bit different from the original HAML for Ruby.

In case pakunok could magically provide a good name for your template function, you can access it as JST['what ever it is!']. The name of the template function is derrived from the file name. Some examples for you:

  file                      => file
  file.js.erb.hamljs        => file
  file-with-dash.hamljs     => fileWithDash
  file_with_underscore      => fileWithUnderscore
  dir/foo_bar               => dir_fooBar
  win\dir\foo_bar           => win_dir_fooBar
  d1/d2/foo_bar.js.a.b.c.d  => d1_d2_fooBar

Yes, it uses one global variable JST to add all the functions but you can change it (see example further).

Pakunok will escape the HTML using simple built-in function. The escaping function is generated inside each template resulting in larger JavaScript code base. It is highly recommended to set it to your own when you have more than a couple of templates.

HAML Configuration options

# Somewhere in your app...
require 'pakunok/haml_js_template'

# Change the escapeHTML function
Pakunok::HamlJsTemplate.custom_escape = 'YourApp.html_escape' # default is nil - built-in

# Change the global variable to attach templates to
Pakunok::HamlJsTemplate.root_variable = 'Templates'  # default is 'JST'

# Change the prefix from where to start naming the templates
Pakunok::HamlJsTemplate.name_prefix = 'javascripts/templates'  # default is 'javascripts/'
# This option will automatically be set to 'backbone/templates/' if back

When option name_prefix is not set and rails-backbone is available then backbone/templates/ is used by default.

Development

Source hosted at GitHub
Report issues and feature requests to GitHub Issues

Pull requests are very welcome! But please write the specs.

To start, clone the repo and then:

bundle install
bundle exec rspec spec/

dnagir / pakunok

readme