Home

Awesome

jquery-ui-rails

Build Status Dependency Status

This gem packages the jQuery UI 1.8.23 assets (JavaScripts, stylesheets, and images) for the Rails 3.1+ asset pipeline, so you never have to download a custom package through the web interface again.

Usage

In your Gemfile, add:

group :assets do
  gem 'jquery-rails'
  gem 'jquery-ui-rails'
end

Require Everything

To require all jQuery UI modules, add the following to your application.js:

//= require jquery
//= require jquery.ui.all

You need to load jquery manually; jquery-ui-rails does not load it for you. Also note that for network performance, it is better to load jQuery library from Public CDN instead of packaging it into your assets. See Loading from Public CDN section.

Also add the jQuery UI CSS to your application.css:

/*
 *= require jquery.ui.all
 */

All images required by jQuery UI are automatically served through the asset pipeline, so you are good to go! For example, this code will add a datepicker:

$(function() {
  $('.datepicker').datepicker();
});

Require Specific Modules

The jQuery UI code weighs 51KB (minified + gzipped) and takes a while to execute, so for production apps it's recommended to only include the modules that your application actually uses. Dependencies are automatically resolved. Simply pick one or more modules from the asset list below.

For example, if you only need the datepicker module, add this to your application.js:

//= require jquery
//= require jquery.ui.datepicker

In your application.css, require the corresponding CSS module:

/*
 *= require jquery.ui.datepicker
 */

JavaScript Assets

UI Core

//= require jquery.ui.core
//= require jquery.ui.widget
//= require jquery.ui.mouse
//= require jquery.ui.position

You usually do not need to require these directly, as they are pulled in by the other JavaScript modules as needed.

Interactions

//= require jquery.ui.draggable
//= require jquery.ui.droppable
//= require jquery.ui.resizable
//= require jquery.ui.selectable
//= require jquery.ui.sortable

For jquery.ui.resizable and jquery.ui.selectable, remember to require their matching CSS files in your application.css as well.

Widgets

//= require jquery.ui.accordion
//= require jquery.ui.autocomplete
//= require jquery.ui.button
//= require jquery.ui.dialog
//= require jquery.ui.slider
//= require jquery.ui.tabs
//= require jquery.ui.datepicker
//= require jquery.ui.progressbar

For all of these, remember to require their matching CSS files in your application.css as well.

I18n

Datepicker has optional i18n modules for non-US locales, named jquery.ui.datepicker-xx[-YY] (list), for example:

//= require jquery.ui.datepicker
//= require jquery.ui.datepicker-pt-BR

Note that you still need to include the main datepicker module. It is not required automatically for performance reasons.

Effects

//= require jquery.effects.all
//= require jquery.effects.core
//= require jquery.effects.blind
//= require jquery.effects.bounce
//= require jquery.effects.clip
//= require jquery.effects.drop
//= require jquery.effects.explode
//= require jquery.effects.fade
//= require jquery.effects.fold
//= require jquery.effects.highlight
//= require jquery.effects.pulsate
//= require jquery.effects.scale
//= require jquery.effects.shake
//= require jquery.effects.slide
//= require jquery.effects.transfer

Stylesheet Assets

UI Core

/*
 *= require jquery.ui.core
 *= require jquery.ui.theme
 */

You might want to require these if you do not use any of the following modules, but still want jQuery UI's basic theming CSS. Otherwise they are automatically pulled in as dependencies.

Interactions

/*
 *= require jquery.ui.resizable
 *= require jquery.ui.selectable
 */

Widgets

/*
 *= require jquery.ui.accordion
 *= require jquery.ui.autocomplete
 *= require jquery.ui.button
 *= require jquery.ui.dialog
 *= require jquery.ui.slider
 *= require jquery.ui.tabs
 *= require jquery.ui.datepicker
 *= require jquery.ui.progressbar
 */

Loading from Public CDN

jQuery and jQuery UI can be found from Public CDNs like Google Hosted Libraries. If you are using most features of these libraries, it is better to load them from Public CDN.

In addition, jQuery UI depends on jQuery, which is not automatically require'd by any jQuery UI JavaScripts in this gem. You should load them manually, and it's better to load them from Public CDN.

jQuery

To load jQuery JavaScript from Public CDN, use Jquery::Rails::JQUERY_VERSION to get the version number in the jquery-rails gem:

<%= javascript_include_tag "//ajax.googleapis.com/ajax/libs/jquery/#{Jquery::Rails::JQUERY_VERSION}/jquery.min.js" %>
<script>window.jQuery || document.write('<scr'+'ipt src="<%= javascript_path("jquery.min.js") %>"></scr'+'ipt>')</script><!-- local fallback -->

jQuery UI

To load jQuery UI JavaScript from Public CDN, use Jquery::Ui::Rails::JQUERY_UI_VERSION to get the version number in this gem:

<%= javascript_include_tag "//ajax.googleapis.com/ajax/libs/jqueryui/#{Jquery::Ui::Rails::JQUERY_UI_VERSION}/jquery-ui.min.js" %>
<script>window.jQuery || document.write('<scr'+'ipt src="<%= javascript_path("jquery.ui.all.js") %>"></scr'+'ipt>')</script><!-- local fallback -->

Contributing

Bug Reports

For bugs in jQuery UI itself, head to the jQuery UI Development Center.

For bugs in this gem distribution, use the GitHub issue tracker. In particular, the asset dependencies between files are set up by this gem, not by the jQuery UI upstream. If you find that a JavaScript or CSS file does not pull in its dependencies correctly, please open an issue!

Setup

The jquery-ui-rails gem should work in Ruby 1.8.7 apps. To run the rake tasks, you need Ruby 1.9 however.

git clone git://github.com/joliss/jquery-ui-rails.git
cd jquery-ui-rails
git submodule update --init
bundle install
bundle exec rake # rebuild assets

Most of the code lives in the Rakefile. Pull requests are more than welcome!

Hacking jQuery UI

The jquery-ui-rails repository is contributor-friendly and has a git submodule containing the official jquery-ui repo. This way it's easy to hack the jQuery UI code:

cd jquery-ui
git checkout master  # or 1-8-stable
... hack-hack-hack ...
bundle exec rake  # rebuild assets based on your changes

Assuming your app's Gemfile points at your jquery-ui-rails checkout (gem 'jquery-ui-rails', :path => '~/path/to/jquery-ui-rails'), all you need to do now is refresh your browser, and your changes to jQuery UI are live in your Rails application.

You can send pull requests to the jquery-ui GitHub project straight out of your submodule. See also their Getting Involved guide.

Testing

As a smoke test, a testapp application is available in the repository, which displays a check mark and a datepicker to make sure the assets load correctly:

cd testapp
bundle install
rails server

Now point your browser at http://localhost:3000/.

Limitations