RubyGems - jelly - Versions diffs - 0.5.7 → 0.5.8 - Mend

jelly 0.5.7 → 0.5.8

Files changed (5) hide show

data/README.markdown +224 -39
data/VERSION.yml +3 -2
data/generators/jelly/templates/javascripts/jelly.js +2 -2
data/jelly.gemspec +14 -13
metadata +11 -11

data/README.markdown CHANGED Viewed

@@ -12,6 +12,14 @@ Jelly encourages and enables unit testing your Javascript code. Using a Javascri
 or [Screw Unit](http://github.com/nathansobo/screw-unit), Jelly allows you to test AJAX and client-side
 events independently from your Rails app.
+Key Benefits
+------------
+* [Unobtrusive Javascript](http://en.wikipedia.org/wiki/Unobtrusive_JavaScript). Your Javascript code remains completely
+separate from your markup.
+* [Test Driven Development](http://en.wikipedia.org/wiki/Test-driven_development). Jelly blends well with the Javascript testing framework
+[Jasmine](http://github.com/pivotal/jasmine) and allows you to test-drive your ajaxy and client-side code.
+* Familiar conventions. Jelly follows the conventions of Ruby on Rails, making it simple for developers to organize and keep track of their Javascript code.
 What Jelly is NOT
 -----------------
 **Jelly is NOT a Javascript generator.** With Jelly, you're writing pure Javascript to define your AJAX browser events. Jelly simply
@@ -41,7 +49,7 @@ Getting Started
 Be sure to require <code>jelly</code> when your application loads. This can be done in your `environment.rb` in the `Rails::Initializer.run` block:
-    config.gem "jelly"
+    config.gem 'jelly'
 Then, in your layouts, add the following to the `<head>` section:
@@ -54,16 +62,16 @@ expansion instead
 The `spread_jelly` line activates the events that you have defined on the current page.
-Usage
+Basic Usage
 -------------
-Jelly maps page-specific Javascript functions to Rails Actions and Controllers. For example: FunController#index will
+Jelly maps page-specific Javascript functions to Rails Actions and Controllers. For example: StoriesController#index will
 activate the `index` function in the `Fun` Jelly object. Jelly uses jQuery's `$(document).ready()` to execute the
 page-specifc function when the page has loaded. Let's look at some code:
-In `public/javascripts/pages/fun.js`, I write a simple Jelly file:
+In public/javascripts/pages/stories.js, we create a simple Jelly file:
-    Jelly.add("Fun", {
+    Jelly.add("Stories", {
       index: function() {
         $('a.clickme').click(function() {
@@ -73,11 +81,11 @@ In `public/javascripts/pages/fun.js`, I write a simple Jelly file:
     });
-Jelly will automatically execute the `index` function when the Rails app runs the `FunController#index` action. Lets
+Jelly will automatically execute the `index` function when the Rails app runs the `StoriesController#index` action. Lets
 continue the example by adding more Javascript functions that map to the `new` and `show` Rails actions. We can also
-specify an `all` function, which will be executed on all actions in the `FunController`.
+specify an `all` function, which will be executed on all actions in the `StoriesController`.
-    Jelly.add("Fun", {
+    Jelly.add("Stories", {
       index: function() {
         $('a.clickme').click(function() {
@@ -100,62 +108,239 @@ specify an `all` function, which will be executed on all actions in the `FunCont
 Notice the slightly different syntax for `new`. This is because `new` is a reserved word in Javascript.
 Create a separate file in `public/javascripts/pages` for each of your controllers as you use Jelly throughout your application.
+Common Components
+-----------------
+Often you will want to mix common Javascript components on many pages throughout your application, not just in the namespace
+of a single Controller. Jelly Components allow you to organize common Javascript code, and invoke it on arbitrary pages
+within your application.
+Jelly Components are simply Javascript classes with (at least) an `init` function. Here's an example of a `SearchBox` component that
+activates an autocompleter on a search box on every page.
+in public/javascripts/components/search_box.js:
+    SearchBox = {
+      init: function(){
+        $("#search_box").autocompleter({
+          url : '/search'
+        });
+      }
+    };
+To attach the SearchBox component to the page and automatically call the `init` function when the page is ready, we use the `attach_javascript_component`
+method in our view. This can be done either in your layout (for components to attach to all pages), or in your view using
+`content_for`.
+in the `<head>` tag of the layout:
+    <%= attach_javascript_component('SearchBox') %>
+or in a view:
+    <% content_for :javascript do -%>
+      <%= attach_javascript_component('SearchBox') %>
+    <% end -%>
+Components always get initialized **after** the page-specific Javascript functions.
 AJAX 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:
+Jelly adds an `$.ajaxWithJelly()` function to the jQuery namespace which is a simple wrapper for jQuery's `$.ajax()`.
+When you use `$.ajaxWithJelly()` to create an ajax event, Jelly automatically adds an onSuccess handler to your ajax
+call that invokes the Jelly framework after receiving the ajax response.
+Jelly's convention relies on the Controller to specify the javascript callback after an ajax request. We can invoke Jelly
+in response to a javascript request with the `jelly_callback` method.
+This example assumes that you have working knowledge of jQuery's `$.ajax()` function. If not, [read up on it here](http://docs.jquery.com/Ajax).
-    <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>
+### Simple AJAX example with `$.ajaxWithJelly()` and `jelly_callback`
-And update your controller:
+The view, new.html.erb:
-    class FunController < ApplicationController
-      def index
+    <a href="#" id="create_story_link">create story</a>
+The controller, stories_controller.rb
+    class StoriesController < ApplicationController
+      def new
       end
-      def ajax_action
-        jelly_callback do
-          [
-            render(:partial => 'fun_partial'),
-            "second_parameter"
-          ]
+      def create
+        Story.create!(params[:story])
+        respond_to do |format|
+          format.html
+          format.js { jelly_callback }
         end
       end
     end
-Update your page object in `fun.js`:
+The javascript, pages/stories.js:
-    Jelly.add("Fun", {
-      all: function() {
-        $('title').text("Hello!  Isn't this fun?");
+    Jelly.add("Stories", {
+      new: function() {
+        $("#create_story_link").click(function() {
+          $.ajaxWithJelly({
+            url: "/stories",
+            data: {
+              name : 'Untitled Story',
+            }
+          });
+        });
       },
-      index: function() {
-        $('h1').text("Welcome to the index page.");
-        $("#jelly_ajax_link").click(function() {
+      on_create: function() {
+        alert('Your story has been created!');
+      }
+    });
+The example above attaches an ajax event to the "create story" link, and when clicked, jQuery will fire a ajax POST request to
+the create action of our controller. The controller then responds with `jelly_callback`, and by default invokes the
+javascript function named `on_create` in the Stories javascript file.
+### Passing parameters to the Jelly callback target
+If we wanted to make the creation of the story a bit more interesting, we can send back a html fragment of the
+new story that has been created, and pass it as a parameter to `on_create` so it can be added to the page. Let's see how that might look:
+The view, new.html.erb:
+    <a href="#" id="create_story_link">create story</a>
+    <ul id="stories">
+      <li>First Story</li>
+    </ul>
+The controller, stories_controller.rb
+    class StoriesController < ApplicationController
+      def new
+      end
+      def create
+        Story.create!(params[:story])
+        respond_to do |format|
+          format.html
+          format.js do
+            jelly_callback do
+              render :partial => 'story_list_item'
+            end
+          end
+        end
+      end
+    end
+The javascript, pages/stories.js:
+    Jelly.add("Stories", {
+      new: function() {
+        $("#create_story_link").click(function() {
           $.ajaxWithJelly({
-            type: "GET",
-            url: "/fun/ajax_action"
+            url: "/stories",
+            data: {
+              name : 'Untitled Story',
+            }
           });
         });
       },
-      on_ajax_action: function(html, second_parameter) {
-        $('#jelly_callback_element').html(html);
+      on_create: function(storyListItemHtml) {
+        $("#stories").append(storyListItemHtml);
       }
     });
-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` function accepts a block which is evaluated in the context of the view layer, which allows you to
+render partials and use Rails Helpers as you normally would. You can pass as many parameters as you want to the javascript
+callback by passing an array to the `jelly_callback` block:
+### Passing multiple parameters to the Jelly callback target
+in the controller, stories_controller.rb:
+    def create
+      @story = Story.create!(params[:story])
+      respond_to do |format|
+        format.html
+        format.js do
+          jelly_callback do
+            [ render(:partial => 'story_list_item'), @story.id, "Nice looking story, smart guy" ]
+          end
+        end
+      end
+    end
+in the javascript, pages/stories.js:
+    on_create: function(storyListItemHtml, storyId, message) {
+      $(storyListItemHtml).attr('id', storyId).appendTo($("#stories"));
+      alert(message);
+    },
+### Specifying custom callback functions in jelly_callback
-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.
+As we have seen above, by default, `jelly_callback` invokes the javascript function by prepending `on_` to the Rails
+action name. The `jelly_callback` method can take an optional parameter for the name of the callback to allow more fine-grained
+client-side behaviors depending on the server-side response.
-DEVELOPMENT
------------
+in the controller, stories_controller.rb
+    def create
+      begin
+        Story.create!(params[:story])
+        respond_to do |format|
+          format.html
+          format.js do
+            jelly_callback('successful_create') do
+              render :partial => 'story_list_item'
+            end
+          end
+        end
+      rescue
+        respond_to do |format|
+          format.html
+          format.js do
+            jelly_callback('failed_create')
+          end
+        end
+      end
+    end
+in the javascript, pages/stories.js:
+    on_successful_create: function(storyListItemHtml) {
+      $("#stories").append(storyListItemHtml);
+    },
+    on_failed_create: function() {
+      alert('Oops, there was a problem creating your story!);
+    }
+### Callbacks to Jelly Components
+By default, ajax callbacks functions are scoped to the current Jelly page. But if you want, you can also direct ajax
+callbacks to functions on Jelly components or other Javascript objects in your application. To
+do this, send an `:on` paremeter to `jelly_callback`, for example.
+in the controller:
+    respond_to do |format|
+      format.js do
+        jelly_callback('successful_create', :on => 'CommonHandler') do
+          render :partial => 'story_list_item'
+        end
+      end
+    end
+This will call `CommonHandler.on_successful_create()` with the response.
+Jelly Development
+-----------------
 Track Jelly's development roadmap on [Jelly's Pivotal Tracker project](http://www.pivotaltracker.com/projects/30454)
 To run ruby tests, run `rake spec`.
-To run Javascript tests, open `jelly/spec/jasmine_runner.html` in a web browser.
+To run Javascript tests, open `jelly/spec/jasmine_runner.html` in Firefox or Safari.

data/VERSION.yml CHANGED Viewed

@@ -1,4 +1,5 @@
 ---
-:patch: 7
-:major: 0
 :minor: 5
+:patch: 8
+:build:
+:major: 0

data/generators/jelly/templates/javascripts/jelly.js CHANGED Viewed

@@ -48,14 +48,14 @@ Jelly.initComponents = function() {
 Jelly.notifyObservers = function(params) {
   var context = params.on ? eval(params.on) : page;
   if(context[params.method]) {
-    context[params.method].apply(params, params.arguments);
+    context[params.method].apply(context, params.arguments);
   }
   $.protify(page.components).each(function(componentAndArgs) {
     var component = componentAndArgs[0];
     if(component[params.method]) {
       component[params.method].apply(component, params.arguments);
     }
-  });
+  });
 };
 Jelly.Page = function(name) {

data/jelly.gemspec CHANGED Viewed

@@ -1,15 +1,15 @@
 # Generated by jeweler
-# DO NOT EDIT THIS FILE
-# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
 # -*- encoding: utf-8 -*-
 Gem::Specification.new do |s|
   s.name = %q{jelly}
-  s.version = "0.5.7"
+  s.version = "0.5.8"
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Pivotal Labs, Inc"]
-  s.date = %q{2009-10-08}
+  s.date = %q{2009-10-28}
   s.description = %q{Jelly provides a set of tools and conventions for creating rich ajax/javascript web applications with jQuery and Ruby on Rails.}
   s.email = %q{opensource@pivotallabs.com}
   s.extra_rdoc_files = [
@@ -43,23 +43,23 @@ Gem::Specification.new do |s|
   s.summary = %q{a sweet unobtrusive javascript framework for jQuery and Rails}
   s.test_files = [
     "spec/controllers/jelly_controller_spec.rb",
-     "spec/spec_helper.rb",
+     "spec/helpers/jelly_helper_spec.rb",
      "spec/rails_root/app/controllers/application_controller.rb",
      "spec/rails_root/app/helpers/application_helper.rb",
+     "spec/rails_root/config/boot.rb",
      "spec/rails_root/config/environment.rb",
-     "spec/rails_root/config/initializers/new_rails_defaults.rb",
-     "spec/rails_root/config/initializers/mime_types.rb",
-     "spec/rails_root/config/initializers/session_store.rb",
-     "spec/rails_root/config/initializers/backtrace_silencers.rb",
-     "spec/rails_root/config/initializers/inflections.rb",
+     "spec/rails_root/config/environments/development.rb",
      "spec/rails_root/config/environments/production.rb",
      "spec/rails_root/config/environments/test.rb",
-     "spec/rails_root/config/environments/development.rb",
+     "spec/rails_root/config/initializers/backtrace_silencers.rb",
+     "spec/rails_root/config/initializers/inflections.rb",
+     "spec/rails_root/config/initializers/mime_types.rb",
+     "spec/rails_root/config/initializers/new_rails_defaults.rb",
+     "spec/rails_root/config/initializers/session_store.rb",
      "spec/rails_root/config/routes.rb",
-     "spec/rails_root/config/boot.rb",
      "spec/rails_root/test/performance/browsing_test.rb",
      "spec/rails_root/test/test_helper.rb",
-     "spec/helpers/jelly_helper_spec.rb"
+     "spec/spec_helper.rb"
   ]
   if s.respond_to? :specification_version then
@@ -75,3 +75,4 @@ Gem::Specification.new do |s|
     s.add_dependency(%q<rails>, [">= 2.3.0"])
   end
 end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jelly
 version: !ruby/object:Gem::Version
-  version: 0.5.7
+  version: 0.5.8
 platform: ruby
 authors:
 - Pivotal Labs, Inc
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
-date: 2009-10-08 00:00:00 -07:00
+date: 2009-10-28 00:00:00 -07:00
 default_executable:
 dependencies:
 - !ruby/object:Gem::Dependency
@@ -80,20 +80,20 @@ specification_version: 3
 summary: a sweet unobtrusive javascript framework for jQuery and Rails
 test_files:
 - spec/controllers/jelly_controller_spec.rb
-- spec/spec_helper.rb
+- spec/helpers/jelly_helper_spec.rb
 - spec/rails_root/app/controllers/application_controller.rb
 - spec/rails_root/app/helpers/application_helper.rb
+- spec/rails_root/config/boot.rb
 - spec/rails_root/config/environment.rb
-- spec/rails_root/config/initializers/new_rails_defaults.rb
-- spec/rails_root/config/initializers/mime_types.rb
-- spec/rails_root/config/initializers/session_store.rb
-- spec/rails_root/config/initializers/backtrace_silencers.rb
-- spec/rails_root/config/initializers/inflections.rb
+- spec/rails_root/config/environments/development.rb
 - spec/rails_root/config/environments/production.rb
 - spec/rails_root/config/environments/test.rb
-- spec/rails_root/config/environments/development.rb
+- spec/rails_root/config/initializers/backtrace_silencers.rb
+- spec/rails_root/config/initializers/inflections.rb
+- spec/rails_root/config/initializers/mime_types.rb
+- spec/rails_root/config/initializers/new_rails_defaults.rb
+- spec/rails_root/config/initializers/session_store.rb
 - spec/rails_root/config/routes.rb
-- spec/rails_root/config/boot.rb
 - spec/rails_root/test/performance/browsing_test.rb
 - spec/rails_root/test/test_helper.rb
-- spec/helpers/jelly_helper_spec.rb
+- spec/spec_helper.rb