Ruby on Rails | Screencasts | Download | Documentation | Weblog | Community | Source

Ticket #7722: extend_scriptaculous_helper_docs.diff

File extend_scriptaculous_helper_docs.diff, 10.1 kB (added by jeremymcanally, 1 year ago)

  • actionpack/lib/action_view/helpers/scriptaculous_helper.rb

    old new  
    22 
    33module ActionView 
    44  module Helpers 
    5     # Provides a set of helpers for calling Scriptaculous JavaScript  
    6     # functions, including those which create Ajax controls and visual effects. 
    7     # 
    8     # To be able to use these helpers, you must include the Prototype  
     5    # Scriptaculous[http://script.aculo.us] is a JavaScript library that provides a set of functions 
     6    # for creating Ajax controls and visual effects.  This helper provides a  
     7    # set of methods for calling these Scriptaculous functions using Ruby code 
     8    # to generate the JavaScript. 
     9    #  
     10    # === Usage 
     11    # To be able to use these helpers, you must first include the Prototype  
    912    # JavaScript framework and the Scriptaculous JavaScript library in your  
    10     # pages. See the documentation for ActionView::Helpers::JavaScriptHelper 
    11     # for more information on including the necessary JavaScript. 
     13    # pages.  
    1214    # 
    13     # The Scriptaculous helpers' behavior can be tweaked with various options. 
    14     # See the documentation at http://script.aculo.us for more information on 
    15     # using these helpers in your application. 
     15    #  <%=  
     16    #    javascript_include_tag 'prototype' 
     17    #    javascript_include_tag 'scriptaculous' 
     18    #  %> 
     19    # 
     20    # (See the documentation for ActionView::Helpers::JavaScriptHelper 
     21    # for more information on including this and other JavaScript files) 
     22    # 
     23    # Once those are included, you are able to use Ruby to generate Scriptaculous 
     24    # calls.  For example, let's say you wanted to highlight a shopping cart's total 
     25    # after an item had been added to it over Ajax.  You could do something like this: 
     26    #  
     27    #  <%=  
     28    #      # Generates: <a href="#" onclick="new Ajax.Updater('total', '/testing/add_to_cart', {asynchronous:true,  
     29    #      # evalScripts:true, onComplete:function(request){new Effect.Highlight(&quot;total&quot;,{duration:0.75});}});  
     30    #      # return false;">Add to cart</a> 
     31    #      link_to_remote "Add to cart", :update => "total",  
     32    #          :url => { :action => "add_to_cart" },  
     33    #          :complete => visual_effect(:highlight, "total", :duration => 0.75)  
     34    #  %> 
     35    # 
     36    # The visual_effect method allows you to use various visual effects built-in to Scriptaculous 
     37    # (in this case, a faint, fading highlight); see the visual_effect method's documentation for more information. 
     38    # 
     39    # ScriptaculousHelper's behavior can be tweaked using the +js_options+ parameter. 
     40    # See the documentation at http://script.aculo.us for more information. 
    1641    module ScriptaculousHelper 
    1742      unless const_defined? :TOGGLE_EFFECTS 
    1843        TOGGLE_EFFECTS = [:toggle_appear, :toggle_slide, :toggle_blind] 
    1944      end 
    2045       
    21       # Returns a JavaScript snippet to be used on the Ajax callbacks for 
    22       # starting visual effects. 
     46      # The Scriptaculous visual effects library has a number of effects built-in, such as changing opacity, highlighting, 
     47      # pulsating, fading out, and so on (see the documentation[http://wiki.script.aculo.us/scriptaculous/show/VisualEffects] for 
     48      # the visual effects for more information).  The visual_effect method allow you to use these visual effects in Ajax callbacks 
     49      # by returning a JavaScript snippet to be used as the callback. 
    2350      # 
    2451      # Example: 
    25       #   <%= link_to_remote "Reload", :update => "posts",  
     52      #   <%=  
     53      #      # Generates: <a href="#" onclick="new Ajax.Updater('posts', '/mycontroller/reload',  
     54      #      # {asynchronous:true, evalScripts:true, onComplete:function(request){new Effect.Highlight(&quot;posts&quot;, 
     55      #      # {duration:0.5});}}); return false;">Reload</a> 
     56      #      link_to_remote "Reload", :update => "posts",  
    2657      #         :url => { :action => "reload" },  
    27       #         :complete => visual_effect(:highlight, "posts", :duration => 0.5) 
     58      #         :complete => visual_effect(:highlight, "posts", :duration => 0.5)  
     59      #    %> 
    2860      # 
    29       # If no element_id is given, it assumes "element" which should be a local 
     61      # If no +element_id+ is given, it assumes +element+ which should be a local 
    3062      # variable in the generated JavaScript execution context. This can be  
    3163      # used for example with drop_receiving_element: 
    3264      # 
    …… 
    3567      # This would fade the element that was dropped on the drop receiving  
    3668      # element. 
    3769      # 
    38       # For toggling visual effects, you can use :toggle_appear, :toggle_slide, and 
    39       # :toggle_blind which will alternate between appear/fade, slidedown/slideup, and 
    40       # blinddown/blindup respectively. 
     70      # For toggling visual effects, you can use <tt>:toggle_appear</tt>, <tt>:toggle_slide</tt>, and 
     71      # <tt>:toggle_blind</tt> in the +js_options+ parameter which will alternate between appear/fade, slidedown/slideup, and 
     72      # blinddown/blindup, respectively. 
    4173      # 
    42       # You can change the behaviour with various options, see 
     74      # You can change the behaviour with various options; see 
    4375      # http://script.aculo.us for more documentation. 
    4476      def visual_effect(name, element_id = false, js_options = {}) 
    4577        element = element_id ? element_id.to_json : "element" 
    …… 
    5789        end 
    5890      end 
    5991       
    60       # Makes the element with the DOM ID specified by +element_id+ sortable 
    61       # by drag-and-drop and make an Ajax call whenever the sort order has 
    62       # changed. By default, the action called gets the serialized sortable 
     92      # Scriptaculous allows you to make container elements (for example, <ul>) sortable.   
     93      # The sortable_elements makes the element with the DOM ID specified by +element_id+ sortable 
     94      # by drag-and-drop; it will also make an Ajax call whenever the sort order has 
     95      # changed. By default, the action called gets the JSON serialized sortable 
    6396      # element as parameters. 
    6497      # 
    6598      # Example: 
    66       #   <%= sortable_element("my_list", :url => { :action => "order" }) %> 
     99      #   <%=  
     100      #     # Generates: Sortable.create("my_list", {onUpdate:function(){ 
     101      #     # new Ajax.Request('/testing/order', {asynchronous:true, evalScripts:true, parameters:Sortable.serialize("my_list")})}}) 
     102      #     sortable_element("my_list", :url => { :action => "order" })  
     103      #   %> 
    67104      # 
    68       # In the example, the action gets a "my_list" array parameter  
     105      # In the example, the action gets a +my_list+ array parameter  
    69106      # containing the values of the ids of elements the sortable consists  
    70107      # of, in the current order. 
    71108      # 
    72       # Important: For this to work, the sortable elements must have id 
    73       # attributes in the form "string_identifier". For example, "item_1". Only 
    74       # the identifier part of the id attribute will be serialized. 
     109      # <b>Important:</b> For this to work, the sortable elements must have +id+ 
     110      # attributes in the form "string_identifier" (for example, "item_1"). Only 
     111      # the identifier part of the +id+ attribute will be serialized. 
    75112      # 
    76       # 
    77       # You can change the behaviour with various options, see 
     113      # You can change the behaviour with various options; see 
    78114      # http://script.aculo.us for more documentation. 
    79115      def sortable_element(element_id, options = {}) 
    80116        javascript_tag(sortable_element_js(element_id, options).chop!) 
    …… 
    95131        %(Sortable.create(#{element_id.to_json}, #{options_for_javascript(options)});) 
    96132      end 
    97133 
    98       # Makes the element with the DOM ID specified by +element_id+ draggable. 
     134      # Scriptaculous allows you to easily create interfaces with drag and drop functionality; the 
     135      # draggable_element method makes the element with the DOM ID specified by +element_id+ draggable. 
    99136      # 
    100137      # Example: 
    101       #   <%= draggable_element("my_image", :revert => true) 
     138      #   <%= 
     139      #      # Generates: new Draggable("my_image", {revert:true})  
     140      #      draggable_element("my_image", :revert => true)  
     141      #   %> 
    102142      #  
    103       # You can change the behaviour with various options, see 
     143      # You can change the behaviour with various option; see 
    104144      # http://script.aculo.us for more documentation. 
    105145      def draggable_element(element_id, options = {}) 
    106146        javascript_tag(draggable_element_js(element_id, options).chop!) 
    …… 
    110150        %(new Draggable(#{element_id.to_json}, #{options_for_javascript(options)});) 
    111151      end 
    112152 
    113       # Makes the element with the DOM ID specified by +element_id+ receive 
    114       # dropped draggable elements (created by draggable_element). 
    115       # and make an AJAX call  By default, the action called gets the DOM ID  
    116       # of the element as parameter. 
     153      # Scriptaculous allows you to easily create interfaces with drag and drop functionality; the 
     154      # drop_receiving_element method makes the element with the DOM ID specified by +element_id+ receive 
     155      # dropped draggable elements (created by draggable_element). It will also make an Ajax call when the item 
     156      # is dropped.  By default, the action called gets the DOM ID of the element as parameter. 
    117157      # 
    118158      # Example: 
    119       #   <%= drop_receiving_element("my_cart", :url =>  
    120       #     { :controller => "cart", :action => "add" }) %> 
     159      #   <%=  
     160      #      # Generates: Droppables.add("my_cart", {onDrop:function(element){ 
     161      #      # new Ajax.Request('/cart/add', {asynchronous:true, evalScripts:true,  
     162      #      # parameters:'id=' + encodeURIComponent(element.id)})}}) 
     163      #      drop_receiving_element("my_cart", :url =>  
     164      #        { :controller => "cart", :action => "add" })  
     165      #   %> 
    121166      # 
    122       # You can change the behaviour with various options, see 
     167      # You can change the behaviour with various options; see 
    123168      # http://script.aculo.us for more documentation. 
    124169      def drop_receiving_element(element_id, options = {}) 
    125170        javascript_tag(drop_receiving_element_js(element_id, options).chop!)