RJS Helpers

Some helper methods to perform standard JS library tasks from js.erb without having to write actual javascript

Important: This version was made for use with Rails >= 3.1. If you are using Rails 2.3, please take a look at the rails2 branch.

Installation

As a gem

To install rjs_helpers as a gem, run

gem install rjs_helpers

or put this into your Gemfile:

gem 'rjs_helpers'

In this version, RJS helpers is built as a Rails engine, so the necessary helper methods and assets are automatically loaded into your application.

You only have to extend your application.js file to include the necessary javascript:

//= require rjs_helpers

Usage

The plugin consists of two parts:

A Rails helper which is available in application views
A JS helper library which has to be included into your application scripts / layout

The JS file which is part of this plugin uses jQuery to perform its tasks. If your application is using a different framework, feel free to write an own adapter for it.

The Rails helper does not directly generate code for just one library, as jQuery might not be used for all applications. Instead, it will generate calls to an own API which can be found in the included javascript file.

Available Functions

Update, Replace, Append, Prepend

These content update functions always take a selector element and the new content.

The selector element may either be a string/symbol which is passed directly to the JS function or something the dom_id() function would take as well (an instance of ActiveRecord or an Array).

The content may either be a string containing the new content or options for the ActionView render() method.

js_update_element(element, content)

Updates the given element with the given content

js_replace_element(element, content)

Replaces the given element with the new content

js_append_element_to(element, content)

Appends the given content to the given container element

js_prepend_element_to(element, content)

Like append, but at the top of the container element

Removing DOM elements

js_remove_element(element)

Removes the given element from the DOM.

Show, Hide and Toggle

js_show_element(element)

Shows the given element, by default with .show()

js_hide_element(element)

Hides the given element, by default with .hide()

js_toggle_element(element)

Toggles the given element, by default with .toggle()

Various Actions

js_redirect_to(url)

Performs a javascript redirect to the given URL. The argument may be everything that the url_for() function would accept, e.g. [:admin, :users] or "http://www.google.com"

js_scroll_to(element, offset_top = 0)

Scrolls to the given element on the page. The optional second parameter can be used to set a top offset. This is e.g. useful if you have a fixed top navbar (greetings to you, bootstrap).

If :top is given as the first argument, the page will simply scroll to the very top (+ offset).

Examples

= js_update_element @user, :partial => 'user', :object => @user
#=> rjsHelpers.updateElementByDomId('user_123', ...)
#=> jQuery('#user_123').html(...)

= js_update_element [@user, :emails], :partial => 'emails'
#=> rjsHelpers.updateElementByDomId('emails_user_123', ...)
#=> jQuery('#emails_user_123').html(...)

= js_hide_element '#myContainer'
#=> rjsHelpers.hideElement('#myContainer')
#=> jQuery('#myContainer').hide()

= js_replace_element '#willBeOverridden', 'And now for something completely different'
#=> rjsHelpers.replaceElement('#willBeOverridden', 'And now for something completely different')
#=> jQuery('#willBeOverridden').replaceWith('And now for something completely different')

stex/rjs_helpers