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:

1. 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').
2. 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:

varhtml=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 functionPakunok::HamlJsTemplate.custom_escape='YourApp.html_escape'# default is nil - built-in# Change the global variable to attach templates toPakunok::HamlJsTemplate.root_variable='Templates'# default is 'JST'# Change the prefix from where to start naming the templatesPakunok::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/