RubyGems - btakita-jelly - Versions diffs - 0.6.0 - Mend

btakita-jelly 0.6.0

Files changed (38) hide show

data/.gitignore +3 -0
data/MIT-LICENSE +21 -0
data/README.markdown +346 -0
data/Rakefile +39 -0
data/VERSION.yml +5 -0
data/generators/jelly/USAGE +11 -0
data/generators/jelly/jelly_generator.rb +12 -0
data/generators/jelly/templates/javascripts/ajax_with_jelly.js +33 -0
data/generators/jelly/templates/javascripts/jelly.js +97 -0
data/generators/jelly/templates/javascripts/jquery/jquery-1.3.2.js +4376 -0
data/generators/jelly/templates/javascripts/jquery/jquery.protify-0.3.js +345 -0
data/install.rb +1 -0
data/jelly.gemspec +77 -0
data/lib/jelly.rb +16 -0
data/lib/jelly/jelly_controller.rb +23 -0
data/lib/jelly/jelly_helper.rb +45 -0
data/spec/controllers/jelly_controller_spec.rb +118 -0
data/spec/helpers/jelly_helper_spec.rb +54 -0
data/spec/rails_root/app/controllers/application_controller.rb +10 -0
data/spec/rails_root/app/helpers/application_helper.rb +3 -0
data/spec/rails_root/config/boot.rb +110 -0
data/spec/rails_root/config/environment.rb +41 -0
data/spec/rails_root/config/environments/development.rb +17 -0
data/spec/rails_root/config/environments/production.rb +28 -0
data/spec/rails_root/config/environments/test.rb +28 -0
data/spec/rails_root/config/initializers/backtrace_silencers.rb +7 -0
data/spec/rails_root/config/initializers/inflections.rb +10 -0
data/spec/rails_root/config/initializers/mime_types.rb +5 -0
data/spec/rails_root/config/initializers/new_rails_defaults.rb +19 -0
data/spec/rails_root/config/initializers/session_store.rb +15 -0
data/spec/rails_root/config/routes.rb +43 -0
data/spec/rails_root/test/performance/browsing_test.rb +9 -0
data/spec/rails_root/test/test_helper.rb +38 -0
data/spec/spec_helper.rb +38 -0
data/spec/spec_suite.rb +3 -0
data/tasks/jelly_tasks.rake +4 -0
data/uninstall.rb +1 -0
metadata +99 -0

data/.gitignore ADDED Viewed

@@ -0,0 +1,3 @@
+.idea
+*.svn
+pkg

data/MIT-LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+Copyright (c) 2009 Pivotal Labs, Inc.
+with contributions by: Brian Takita, Nate Clark, Eric Metens
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown ADDED Viewed

@@ -0,0 +1,346 @@
+Jelly
+=====
+What is Jelly?
+--------------
+Jelly is an unobtrusive Javascript framework for [jQuery](http://jquery.com) and [Rails](http://rubyonrails.org).
+It provides a set of conventions and tools that help you organize your AJAX and client-side code,
+while keeping Javascript out of your views and markup. Jelly is the glue between your Rails controllers
+and jQuery events.
+Jelly encourages and enables unit testing your Javascript code. Using a Javascript testing framework such as [Jasmine](http://github.com/pivotal/jasmine)
+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
+provides a set of Javascript functions to make interacting with Rails easier. It's nothing like RJS.
+**Jelly is NOT a Javascript framework.** Jelly is designed to be used with jQuery and jQuery's event-based
+AJAX framework. Jelly also supports the popular [jQuery ajaxForm](http://malsup.com/jquery/form/) plugin.
+Requirements
+------------
+* Rails 2.3.x
+* jQuery 1.3.x
+Installation
+------------
+Jelly is now available as a gem on on [RubyForge](http://rubyforge.org/projects/pivotalrb/):
+    sudo gem install jelly
+Then, install the required Javascript files to your <code>public/javascripts</code> directory by running the Jelly generator:
+    script/generate jelly
+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'
+Then, in your layouts, add the following to the `<head>` section:
+    <%= javascript_include_tag :jelly, *application_jelly_files %>
+    <%= spread_jelly %>
+The `javascript_include_tag` line will include the required Javascript libraries for jelly. The `:jelly` javascript
+expansion includes the latest version of jQuery. If you already have jQuery included in the page, use the `:only_jelly`
+expansion instead
+The `spread_jelly` line activates the events that you have defined on the current page.
+Basic Usage
+-------------
+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/stories.js, we create a simple Jelly file:
+    Jelly.add("Stories", {
+      index: function() {
+        $('a.clickme').click(function() {
+          alert('Hello world!');
+        });
+      }
+    });
+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 `StoriesController`.
+    Jelly.add("Stories", {
+      index: function() {
+        $('a.clickme').click(function() {
+          alert('Hello world!');
+        });
+      },
+      'new': function() {
+        $('#mydiv').html('<span>Hello World</span>');
+      },
+      show : function() {},
+      all: function() {
+        $('#hidden_stuff').show();
+      }
+    });
+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
+---------------
+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).
+### Simple AJAX example with `$.ajaxWithJelly()` and `jelly_callback`
+The view, new.html.erb:
+    <a href="#" id="create_story_link">create story</a>
+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 { jelly_callback }
+        end
+      end
+    end
+The javascript, pages/stories.js:
+    Jelly.add("Stories", {
+      new: function() {
+        $("#create_story_link").click(function() {
+          $.ajaxWithJelly({
+            url: "/stories",
+            data: {
+              name : 'Untitled Story',
+            }
+          });
+        });
+      },
+      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({
+            url: "/stories",
+            data: {
+              name : 'Untitled Story',
+            }
+          });
+        });
+      },
+      on_create: function(storyListItemHtml) {
+        $("#stories").append(storyListItemHtml);
+      }
+    });
+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
+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.
+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 Firefox or Safari.

data/Rakefile ADDED Viewed

@@ -0,0 +1,39 @@
+require 'spec/version'
+require 'spec/rake/spectask'
+require 'rake/rdoctask'
+desc 'Default: run specs'
+task :default => :spec
+desc 'Test the jelly plugin with Rspec.'
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.libs << 'lib'
+  t.libs << 'spec'
+  t.pattern = 'spec/**/*_spec.rb'
+  t.verbose = true
+end
+desc 'Generate documentation for the jelly plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Jelly.'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = ENV["GEM_PREFIX"] ? "#{ENV["GEM_PREFIX"]}-jelly" : "jelly"
+    gemspec.summary = "a sweet unobtrusive javascript framework for jQuery and Rails"
+    gemspec.description = "Jelly provides a set of tools and conventions for creating rich ajax/javascript web applications with jQuery and Ruby on Rails."
+    gemspec.email = "opensource@pivotallabs.com"
+    gemspec.homepage = "http://github.com/pivotal/jelly"
+    gemspec.authors = ["Pivotal Labs, Inc"]
+    gemspec.files.exclude 'spec/**/*'
+    gemspec.add_dependency('rails', '>= 2.3.0')
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install jeweler"
+end

data/VERSION.yml ADDED Viewed

@@ -0,0 +1,5 @@
+---
+:build:
+:patch: 0
+:major: 0
+:minor: 6

data/generators/jelly/USAGE ADDED Viewed

@@ -0,0 +1,11 @@
+Description:
+    Creates 'jelly.js' and dependent jQuery libraries
+Example:
+    ./script/generate jelly
+    This will create:
+        public/javascripts/jelly.js
+        public/javascripts/jquery-1.3.2.js
+        public/javascripts/jquery.protify-0.3.js

data/generators/jelly/jelly_generator.rb ADDED Viewed

@@ -0,0 +1,12 @@
+class JellyGenerator < Rails::Generator::Base
+  def manifest
+    record do |m|
+      m.file 'javascripts/jelly.js', "public/javascripts/jelly.js"
+      m.file 'javascripts/ajax_with_jelly.js', "public/javascripts/ajax_with_jelly.js"
+      m.directory('public/javascripts/jquery')
+      m.file 'javascripts/jquery/jquery-1.3.2.js', "public/javascripts/jquery/jquery-1.3.2.js"
+      m.file 'javascripts/jquery/jquery.protify-0.3.js', "public/javascripts/jquery/jquery.protify-0.3.js"
+      m.directory('public/javascripts/pages')
+    end
+  end
+end

data/generators/jelly/templates/javascripts/ajax_with_jelly.js ADDED Viewed

@@ -0,0 +1,33 @@
+if(!window.Jelly) Jelly = new Object();
+(Jelly.defineAjaxWithJellyFunctions = function($) {
+  $.ajaxWithJelly = function(params) {
+    $.ajax($.ajaxWithJelly.params(params));
+  };
+  if ($.fn.ajaxForm) {
+    $.fn.ajaxFormWithJelly = function(params) {
+      this.ajaxForm($.ajaxWithJelly.params(params));
+    };
+  }
+  $.ajaxWithJelly.params = function(otherParams) {
+    otherParams = otherParams || {};
+    if (otherParams.type && otherParams.type != "GET") {
+      otherParams['data'] = $.extend(otherParams['data'], {
+        authenticity_token: window._token
+      });
+    }
+    return $.extend({
+      dataType: 'json',
+      cache: false,
+      success : $.ajaxWithJelly.onSuccess
+    }, otherParams);
+  };
+  $.ajaxWithJelly.onSuccess = function(json) {
+    Jelly.notifyObservers(json);
+    return true;
+  };
+})(jQuery);