krjs

= KRJS - Keat's RJS

RJS is a great Ruby DSL to write javascript. However, its so tempting to write RJS directly in the views, and soon the views would contain substantial controller knowledge (e.g. link_to_remote, link_to, etc)

KRJS attempts to solve that problem by allowing dynamic inclusion of AJAX calls on HTML elements. When a controller defines a method (based on naming convention) that handles a client-side event, the rendering engine will do the wiring automatically - when the event happens, an AJAX call will be made to the controller's method which would ideally reply with RJS and update portions of the document.

KRJS could potentially use behavior/selector style javascript instead of modifying elements itself - See http://www.lukeredpath.co.uk/index.php/2006/06/06/introducing-unobtrusive-javascript-for-rails and http://www.vivabit.com/bollocks/2006/02/09/rails-is-the-devil-in-your-client-side-shoulder.

== Examples

To see it in action, create a blank controller and a index.rhtml file: ./script/generate controller Sample index

In your view (app/views/sample/index.rhtml) write: <%= form_tag({:action => 'submit'}, {:id => 'form'}) %> <%= text_field 'account', 'login', :id => 'account-new-login' %>
<%= submit_tag 'Login' %> <%= end_form_tag %>

In your controller (app/controllers/sample_controller.rb), write: class SampleController < ApplicationController def on_form_submit render :update do |page| page.insert_html :after, params[:dom_id], CGI.escapeHTML(params.inspect) end end end

Go to your browser, load the page and click on the submit button. The form should be submitted via ajax (not a fullpage refresh) and rjs code should update the page, right after the form (submit button)

You can also try adding this method to the controller: def on_account_login_blur render :update do |page| page.insert_html :after, params[:dom_id], CGI.escapeHTML(params.inspect) end end

View the page again, type in something in the textfield, press the TAB key (to lose focus on the input field). An AJAX call should be made to your controller, and the respective RJS will update the page.

== Explanation

Controller#on_XX_YY means the controller receives ajax requests when event "onYY" of element XX occurs. e.g. if YY is "focus", then the ajax request is sent during "onfocus" even of XX field. Controller#on_XX_YY_ZZ means the controller receives ajax requests when field XX is modified - changes are polled every ZZ seconds instead of waiting for event to occur. Note: if YY is 'form' or 'submit', XX is considered as a DOM ID for a form instead of a field. This impacts the :with parameter. i.e. for a field, the value is submitted; for a form, the whole form is submitted

== Installation

Go to your RAILS_ROOT directory and execute: ./script/plugin install http://choonkeat.svnrepository.com/svn/rails-plugins/krjs

== Testing

To test, go to your RAILS_ROOT directory and execute (1 line): PLUGIN=krjs rake test:plugins

To be sure you test only KRJS, do it on a clean RAILS directory: $ rails test_directory $ cd test_directory $ script/plugin install
http://choonkeat.svnrepository.com/svn/rails-plugins/krjs $ PLUGIN=krjs rake test:plugins

== License

KRJS is released under the MIT license.

== Author

Chew Choon Keat http://blog.yanime.org/

12 June 2006