Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Clean graceful degradation and UJS for Rails, using NinjaScript
branch: master

This branch is 16 commits behind LRDesign:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
spec
.document
.gitignore
Gemfile
Gemfile.lock
LICENSE.txt
README.rdoc
Rakefile
VERSION
mizugumo.gemspec

README.rdoc

Mizugumo

Mizugumo is a gem designed to provide Rails with JavaScript and AJAX behavior that is:

  • absolutely seamless

  • completely unobtrusive - no markup whatsoever in your HTML and

  • gracefully-degrading: defaults to fully functional and sensible page-reload behavior when JavaScript is not available.

See a demo running at:

http://mizugumo-demo.lrdesign.com

Or download the code for the demo at:

https://github.com/LRDesign/mizugumo_demo

Mizugumo uses NinjaScript by Judson Lester to provide unobtrusive JS behaviors. For more info, see:

git@github.com:LRDesign/NinjaScript.git

WARNINGS

In the current (early release) version, Mizugumo and NinjaScript have some limitations. Notably, in this version they will clobber the normal rails.js and prevent its behaviors from working. The installer will copy a jQuery-compatible version of rails.js that you should use instead if you depend on Rails' default (semi-obtrusive) approaches to AJAX, link_to with :confirm =>'Are you sure?' and similar things working.

In addition, NinjaScript currently requires jQuery 1.4.2. It is NOT compatible with the current version of jQuery, 1.5. We are eagerly working on a fix.

Features

Mizugumo's main features are:

  • Easy tools for installing NinjaScript

  • A Rails helper to automatically output <form>s instead of <a> tags when link_to is called with a :method other than GET. This allows these links to function as intended for users who lack JavaScript.

  • A default NinjaScript behavior (in your application.js) that automatically converts those forms back into the expected links when JavaScript is available, resulting in transparent usability for JS users.

  • A scaffold generator that builds both both AJAX behavior and standard “page-reload” behavior in the controller and view and adds NinjaScript behaviors to application.js to activate AJAX. Out of the box, your scaffolded controller will function as an AJAX controller when JS is available but will degrade properly when JS is not available.

Installing

Mizugumo is compatible with Rails >= 3.0.0. We have not tested it with any prior versions of Rails. If you use it with an earlier Rails and it works, let us know!

First, add Mizugumo to your gemfile:

gem 'mizugumo'

Second, install Mizugumo files:

rails generate mizugumo:install

Third, link to jQuery and NinjaScript in your application layout, plus the optional ninjascript.css. If using ERB, add these lines:

<%= javascript_include_tag 'jquery-1.4.2.js' %>
<%= javascript_include_tag 'jquery.ninja_script.js' %>
<%= javascript_include_tag 'application.js' %>
<%= stylesheet_link_tag 'ninjascript' %>

If using Haml, add these instead:

= javascript_include_tag 'jquery-1.4.2.js'
= javascript_include_tag 'jquery.ninja_script.js'
= javascript_include_tag 'application.js'
= stylesheet_link_tag 'ninjascript'

NOTE: If you still have javascript_include_tag :defaults, you probably want to remove it. Ninjascript is meant to work with jQuery, and we don't know what happens if you try to run it side-by-side with Prototype.

Graceful degradation of :method => 'delete' (or PUT, or POST) links

Rails' concept of REST runs headlong into the desire to make a site degrade gracefully. Specifically, the link_to() helper, when passed a method other than 'get', outputs a link with a data-method attribute that won't work when JS is absent. To wit: link_to('Delete Item', @item, :method => 'delete') in Rails outputs this:

<a href='/items/1' data-method='delete'>Delete Item</a>

When JS isn't available, this delete link acts as a show link. This is bad, bad, bad. What's worse, Rails' scaffold generator makes these exact links ubiquitous.

When Mizugumo is installed, that same helper instead outputs this:

<form action='/items/1' class="mizugumo_graceful_form">
  <input type='hidden' name='_method' value='delete'>
  <input type='submit' value='Delete Item'>
</form>

This gives the user a button instead of a form … but it works without JS running. Then, to give JS users the behavior the developer intended, Mizugumo appends this to your application.js:

Ninja.behavior({
  '.mizugumo_graceful_form': Ninja.becomesLink
})

This NinjaScript behavior converts that form back into a link. The JS user sees no difference whatsoever, but the link at least works for the non-JS user.

This behavior will work for :method => 'put' and :method => 'post' as well, and it supports links whose content is an image as well; creating an image submit button in the form rather than a text submit button.

WARNING: This cycle won't work if your link has complex content with html structure; for example if you write

link_to('some <b>content</b><img src="foo">and text', @item, :method => 'delete' )

Mizugomo will not be able to preserve all that content through the degraded form. However, we think this is a rare case. If you aren't passing :method to your link_to, mizugumo will ignore it entirely, so you can still create complex GET links.

Scaffold generator

Mizugumo ships with a scaffold generator that builds out-of-the-box AJAX/UJS scaffolds that degrade gracefully in the absence of JavaScript. To use it, add this to config/application.rb:

For ERB views:

config.generators do |g|
  g.scaffold_controller 'mizugumo:scaffold_controller'
  g.template_engine 'mizugumo:erb'
end

For Haml views:

config.generators do |g|
  g.scaffold_controller 'mizugumo:scaffold_controller'
  g.template_engine 'mizugumo:haml'
end

Contributing to Mizugumo

  • Install MizugumoDemo and make sure that its tests still pass with your version of Mizugumo!

  • Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet

  • Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it

  • Fork the project

  • Start a feature/bugfix branch

  • Commit and push until you are happy with your contribution

  • Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.

  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Reporting Bugs

Use the GitHub issue tracker.

Copyright

Copyright © 2011 Evan Dorn and Logical Reality Design. See LICENSE.txt for further details.

Web Development by Logical Reality Design: LRDesign.com

Something went wrong with that request. Please try again.