jquery-ui-rails
This gem packages the jQuery UI 1.10.0 assets (JavaScripts, stylesheets, andimages) for the Rails 3.1+ assetpipeline, so you never haveto download a custom package through the webinterface again.
Also check out thejquery-ui-sass-rails gem,which allows you to override theme variables with Sass.
Note: As of version 4.0.5, jquery-ui-rails has dropped its unused dependencyon the jquery-rails
gem. If you get an error "couldn't find file 'jquery'",you may need to explicitly add gem 'jquery-rails'
to your Gemfile.
Usage
In your Gemfile, add:
gem 'jquery-ui-rails'
Require Everything
To require all jQuery UI modules, add the following to your application.js:
//= require jquery.ui.all
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 assetpipeline, so you are good to go! For example, this code will add adatepicker:
$(function() {
$('.datepicker').datepicker();
});
Require Specific Modules
The jQuery UI code weighs 51KB (minified + gzipped) and takes a while toexecute, so for production apps it's recommended to only include the modulesthat 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 yourapplication.js:
//= 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 theother 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.datepicker
//= require jquery.ui.dialog
//= require jquery.ui.menu
//= require jquery.ui.progressbar
//= require jquery.ui.slider
//= require jquery.ui.spinner
//= require jquery.ui.tabs
//= require jquery.ui.tooltip
For all of these, remember to require
their matching CSS files in yourapplication.css as well.
I18n
Datepicker has optional i18n modules for non-US locales, namedjquery.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 notrequired automatically for performancereasons.
Effects
//= require jquery.ui.effect.all
//= require jquery.ui.effect
//= require jquery.ui.effect-blind
//= require jquery.ui.effect-bounce
//= require jquery.ui.effect-clip
//= require jquery.ui.effect-drop
//= require jquery.ui.effect-explode
//= require jquery.ui.effect-fade
//= require jquery.ui.effect-fold
//= require jquery.ui.effect-highlight
//= require jquery.ui.effect-pulsate
//= require jquery.ui.effect-scale
//= require jquery.ui.effect-shake
//= require jquery.ui.effect-slide
//= require jquery.ui.effect-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 automaticallypulled 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.datepicker
*= require jquery.ui.dialog
*= require jquery.ui.menu
*= require jquery.ui.progressbar
*= require jquery.ui.slider
*= require jquery.ui.spinner
*= require jquery.ui.tabs
*= require jquery.ui.tooltip
*/
Contributing
Bug Reports
For bugs in jQuery UI itself, head to the jQuery UI DevelopmentCenter.
For bugs in this gem distribution, use the GitHub issue tracker.
Setup
The jquery-ui-rails
gem should work in Ruby 1.8.7 apps. To run the raketasks, 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 iscontributor-friendlyand has a git submodule containing the official jquery-uirepo. This way it's easy to hack thejQuery 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 donow is refresh your browser, and your changes to jQuery UI are live in yourRails application.
You can send pull requests to thejquery-ui GitHub project straight out ofyour submodule. See also theirGetting Involvedguide.
Testing
As a smoke test, a testapp
application is available in the repository, whichdisplays 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
-
Only the base theme (Smoothness) is included. Once it becomes possible togenerate all themefilesfrom the jQuery UI sources, we can package all the other themes in theThemeRoller gallery.
Perhaps we can also add helper tasks to help developers generate assets fortheir own custom themes or for third-party themes (likeSelene).
If you still want a different theme right now, you could probably downloada custom theme and require the theme CSS after requiring any other jQueryUI CSS files you need, making sure to serve up the theme images correctly.(This is arguably cumbersome, not officially supported by this gem, andadds 1 KB overhead as both the base theme and the custom theme are servedup.)
-
The
jquery.ui.all.js
file is namedjquery-ui.js
in the officialdistribution. We should follow their naming. But jquery-rails provides ajquery-ui.js
asset as well, so until that is removed from thejquery-rails gem (see issue#46), we cannotdistributejquery-ui.js
without risking conflicts.To reduce confusion, as long as there is no
jquery-ui.js
, we also do notdistribute the officialjquery-ui-i18n.js
andjquery-ui.css
. The latteris available asjquery.ui.all.css
however.