pivotal-honkster-jelly

Jelly

INSTALLATION

If you haven't already, add GitHub to your gem sources:

gem sources -a http://gems.github.com

Then run:

sudo gem install pivotal-jelly

GETTING STARTED

In your environment.rb in the Rails::Initializer.run block, be sure to require jelly:

config.gem "jelly"

Then install the required JavaScript files by running this command in your Rails project:

script/generate jelly

Then, in your layout, add the following:

<%= javascript_include_tag :jelly, *application_jelly_files %>
<%= spread_jelly %>

This will include the required JavaScripts for jelly and activate the current page. The :jelly javascript expansion includes jQuery. If you already have jQuery included in the page, use the :only_jelly expansion instead.

EXAMPLE USAGE

Assuming you have controller named fun with an action called index and that you have a layout called fun.html.erb that is already setup as described above. In your fun index view (index.html.erb), put:

<h1>Your page's 'index' function did not run. Jelly is not configured correctly.</h1>
<span class="all">Your page's 'all' function did not run. Jelly is not configured correctly.</span>

Then, in public/javascripts/pages/fun.js, put:

Jelly.add("Fun", {
  all: function() {
    $('span.all').text("I am displayed on every action in this controller.");
  },
  index: function() {
    $('h1').text("Welcome to the index page.");
  }
});

Now goto /fun/index and see Jelly in action!

AJAX CALLBACKS WITH JELLY

You can trigger callbacks on the page object from Rails with the jelly_callback method. Adding to the index.html.erb file from above:

<a href="#" id="jelly_ajax_link">Click me for Jelly Ajax Action</a>
<span id="jelly_callback_element">This gets filled in by the Jelly Ajax callback</span>

And update your controller:

class FunController < ApplicationController
  def index
  end

  def ajax_action
    jelly_callback do
      [
        render(:partial => 'fun_partial'),
        "second_parameter"
      ]
    end
  end
end

Update your page object in fun.js:

Jelly.add("Fun", {
  all: function() {
    $('title').text("Hello!  Isn't this fun?");
  },
  index: function() {
    $('h1').text("Welcome to the index page.");
    $("#jelly_ajax_link").click(function() {
      $.ajaxWithJelly({
        type: "GET",
        url: "/fun/ajax_action"
      });
    });
  },
  on_ajax_action: function(html, second_parameter) {
    $('#jelly_callback_element').html(html);
  }
});

And finally, make the partial _fun_partial.html.erb and just put "Hello from the server!" in it, then visit your page and watch the ajax callbacks in action.

The jelly_callback method takes an optional parameter for the name of the callback, and the provided block can return either one parameter, or an array of parameters.

DEVELOPMENT

To run ruby tests, run rake spec. To run JavaScript tests, open jelly/spec/jasmine_runner.html in a web browser.