Index: actionpack/lib/action_view/helpers/scriptaculous_helper.rb =================================================================== --- actionpack/lib/action_view/helpers/scriptaculous_helper.rb (revision 7118) +++ actionpack/lib/action_view/helpers/scriptaculous_helper.rb (working copy) @@ -2,31 +2,63 @@ module ActionView module Helpers - # Provides a set of helpers for calling Scriptaculous JavaScript - # functions, including those which create Ajax controls and visual effects. - # - # To be able to use these helpers, you must include the Prototype + # Scriptaculous[http://script.aculo.us] is a JavaScript library that provides a set of functions + # for creating Ajax controls and visual effects. This helper provides a + # set of methods for calling these Scriptaculous functions using Ruby code + # to generate the JavaScript. + # + # === Usage + # To be able to use these helpers, you must first include the Prototype # JavaScript framework and the Scriptaculous JavaScript library in your - # pages. See the documentation for ActionView::Helpers::JavaScriptHelper - # for more information on including the necessary JavaScript. + # pages. # - # The Scriptaculous helpers' behavior can be tweaked with various options. - # See the documentation at http://script.aculo.us for more information on - # using these helpers in your application. + # <%= + # javascript_include_tag 'prototype' + # javascript_include_tag 'scriptaculous' + # %> + # + # (See the documentation for ActionView::Helpers::JavaScriptHelper + # for more information on including this and other JavaScript files) + # + # Once those are included, you are able to use Ruby to generate Scriptaculous + # calls. For example, let's say you wanted to highlight a shopping cart's total + # after an item had been added to it over Ajax. You could do something like this: + # + # <%= + # # Generates: Add to cart + # link_to_remote "Add to cart", :update => "total", + # :url => { :action => "add_to_cart" }, + # :complete => visual_effect(:highlight, "total", :duration => 0.75) + # %> + # + # The visual_effect method allows you to use various visual effects built-in to Scriptaculous + # (in this case, a faint, fading highlight); see the visual_effect method's documentation for more information. + # + # ScriptaculousHelper's behavior can be tweaked using the +js_options+ parameter. + # See the documentation at http://script.aculo.us for more information. module ScriptaculousHelper unless const_defined? :TOGGLE_EFFECTS TOGGLE_EFFECTS = [:toggle_appear, :toggle_slide, :toggle_blind] end - # Returns a JavaScript snippet to be used on the Ajax callbacks for - # starting visual effects. + # The Scriptaculous visual effects library has a number of effects built-in, such as changing opacity, highlighting, + # pulsating, fading out, and so on (see the documentation[http://wiki.script.aculo.us/scriptaculous/show/VisualEffects] for + # the visual effects for more information). The visual_effect method allow you to use these visual effects in Ajax callbacks + # by returning a JavaScript snippet to be used as the callback. # # Example: - # <%= link_to_remote "Reload", :update => "posts", + # <%= + # # Generates: Reload + # link_to_remote "Reload", :update => "posts", # :url => { :action => "reload" }, - # :complete => visual_effect(:highlight, "posts", :duration => 0.5) + # :complete => visual_effect(:highlight, "posts", :duration => 0.5) + # %> # - # If no element_id is given, it assumes "element" which should be a local + # If no +element_id+ is given, it assumes +element+ which should be a local # variable in the generated JavaScript execution context. This can be # used for example with drop_receiving_element: # @@ -35,11 +67,11 @@ # This would fade the element that was dropped on the drop receiving # element. # - # For toggling visual effects, you can use :toggle_appear, :toggle_slide, and - # :toggle_blind which will alternate between appear/fade, slidedown/slideup, and - # blinddown/blindup respectively. + # For toggling visual effects, you can use :toggle_appear, :toggle_slide, and + # :toggle_blind in the +js_options+ parameter which will alternate between appear/fade, slidedown/slideup, and + # blinddown/blindup, respectively. # - # You can change the behaviour with various options, see + # You can change the behaviour with various options; see # http://script.aculo.us for more documentation. def visual_effect(name, element_id = false, js_options = {}) element = element_id ? element_id.to_json : "element" @@ -57,24 +89,47 @@ end end - # Makes the element with the DOM ID specified by +element_id+ sortable - # by drag-and-drop and make an Ajax call whenever the sort order has - # changed. By default, the action called gets the serialized sortable + # Scriptaculous allows you to make container elements (for example,