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

jelly 0.5.7 → 0.5.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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