Rack::JQueryUI

jQuery-UI CDN script tags and fallback in one neat package.

Build status

Master branch: Build Status

Why?

I get tired of copy and pasting and downloading and moving… jQuery files and script tags etc. This does it for me (along with https://github.com/yb66/rack-jquery), and keeps version management nice 'n' easy.

Usage

Have a look in the examples directory, but here's a snippet.

  • Install it (see below)
  • require 'rack/jquery_ui'.
  • Add use Rack::JQueryUI to your middleware stack.

  • Put this in the head of your layout (the example is Haml but you can use whatever you like)

    = Rack::JQueryUI.cdn env

where env is the Rack env.

Now you have the script tags to Media Temple's CDN in the head (you can also use Google or Microsoft, or Cloudflare, see the docs).

It also adds in a bit of javascript that will load in a locally kept version of jQuery UI, just in case the CDN is unreachable. The script will use the "/js/jquery-ui/1.10.3/jquery-ui.min.js" path (or, instead of 1.10.3, whatever is in Rack::JQueryUI::VERSION). You can change the "/js" bit if you like (see the docs).

That was easy.

Note

You have to have loaded jQuery before using the CDN helper, as jQuery-UI relies on it. I've already mentioned Rack::JQuery which you can use to do this, or load the script however you like. Just remember that it needs to be there.

When the CDN doesn't support the jQuery UI version of the library

I made a mistake and pushed out a version of the library where not all the CDNs supported the version of jQuery UI it was using. Embarrassing.

To stop this happening again I've added more checks, but there's also a choice for the library user. If you've picked a CDN to use, something like this:

%head
  = Rack::JQueryUI.cdn env, :organisation => :microsoft

and it doesn't support the jQuery UI version, then it will silently use the default CDN (usually Media Temple's, but it will change depending on who supports what).

If you'd prefer an exception to be raised you can either do this:

use Rack::JQueryUI, :raise => true

or

%head
  = Rack::JQueryUI.cdn env, :organisation => :microsoft, :raise => true

the second way will always override the first.

Version numbers

This library uses semver to version the library. That means the library version is not an indicator of quality but a way to manage changes. The version of jQuery UI can be found in the lib/rack/jquery_ui/version.rb file, or via the Rack::JQueryUI::JQUERY_UI_VERSION constant.

On top of that, version numbers will also change when new releases of jQuery UI are supported.

  • If jQuery UI makes a major version jump, then this library will make a minor jump. That is because the API for the library has not really changed, but it is possibly a change that will break things.
  • If jQuery UI makes a minor version jump, then so will this library, for the same reason as above.
  • I doubt point releases will be followed, but if so, it will also precipitate a minor jump in this library's version number. That's because even though jQuery UI feel it's a point release, I'm not them, my responsibility is to users of this library and I'll take the cautious approach of making it a minor version number change.

As an example, if the current library version was 1.0.0 and jQuery UI was at 2.0.0 and I made a change that I felt was major and breaking (to the Ruby library), I'd bump Rack::JQueryUI's version to 2.0.0. That the version numbers match between Rack::jQuery_UI and the jQuery UI script is of no significance, it's just coincidental.
If then jQuery UI went to v2.1.0 and I decided to support that, I'd make the changes and bump Rack::JQueryUI's version to 2.1.0. That the version numbers match between Rack::jQuery_UI and the jQuery UI script is of no significance, it's just coincidental.
If then I made a minor change to the library's API that could be breaking I'd bump it to 2.2.0.
If I then added some more instructions I'd bump Rack::JQueryUI's version to 2.2.1.
If then jQuery UI released version 3.0.0, I'd add it to the library, and bump Rack::JQueryUI's version to 2.3.0.

Only one version of jQuery UI will be supported at a time. This is because the fallback script is shipped with the gem and I'd like to keep it as light as possible. It's also a headache to have more than one.

So basically, if you want to use a specific version of jQuery UI, look for the library version that supports it via the Rack::JQueryUI::JQUERY_UI_VERSION constant. Don't rely on the version numbers of this library to tell you anything other than compatibility between versions of this library.

Installation

Add this line to your application's Gemfile:

gem 'rack-jquery_ui'

And then execute:

$ bundle

Or install it yourself as:

$ gem install rack-jquery_ui

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Licence

See the LICENCE.txt file.