vendor/rails/actionpack/lib/action_view/helpers/scriptaculous_helper.rb

   1 require 'action_view/helpers/javascript_helper'
   2 require 'active_support/json'
   3
   4 module ActionView
   5   module Helpers
   6     # Provides a set of helpers for calling Scriptaculous JavaScript
   7     # functions, including those which create Ajax controls and visual effects.
   8     #
   9     # To be able to use these helpers, you must include the Prototype
  10     # JavaScript framework and the Scriptaculous JavaScript library in your
  11     # pages. See the documentation for ActionView::Helpers::JavaScriptHelper
  12     # for more information on including the necessary JavaScript.
  13     #
  14     # The Scriptaculous helpers' behavior can be tweaked with various options.
  15     # See the documentation at http://script.aculo.us for more information on
  16     # using these helpers in your application.
  17     module ScriptaculousHelper
  18       unless const_defined? :TOGGLE_EFFECTS
  19         TOGGLE_EFFECTS = [:toggle_appear, :toggle_slide, :toggle_blind]
  20       end
  21
  22       # Returns a JavaScript snippet to be used on the Ajax callbacks for
  23       # starting visual effects.
  24       #
  25       # Example:
  26       #   <%= link_to_remote "Reload", :update => "posts",
  27       #         :url => { :action => "reload" },
  28       #         :complete => visual_effect(:highlight, "posts", :duration => 0.5)
  29       #
  30       # If no +element_id+ is given, it assumes "element" which should be a local
  31       # variable in the generated JavaScript execution context. This can be
  32       # used for example with +drop_receiving_element+:
  33       #
  34       #   <%= drop_receiving_element (...), :loading => visual_effect(:fade) %>
  35       #
  36       # This would fade the element that was dropped on the drop receiving
  37       # element.
  38       #
  39       # For toggling visual effects, you can use <tt>:toggle_appear</tt>, <tt>:toggle_slide</tt>, and
  40       # <tt>:toggle_blind</tt> which will alternate between appear/fade, slidedown/slideup, and
  41       # blinddown/blindup respectively.
  42       #
  43       # You can change the behaviour with various options, see
  44       # http://script.aculo.us for more documentation.
  45       def visual_effect(name, element_id = false, js_options = {})
  46         element = element_id ? element_id.to_json : "element"
  47
  48         js_options[:queue] = if js_options[:queue].is_a?(Hash)
  49           '{' + js_options[:queue].map {|k, v| k == :limit ? "#{k}:#{v}" : "#{k}:'#{v}'" }.join(',') + '}'
  50         elsif js_options[:queue]
  51           "'#{js_options[:queue]}'"
  52         end if js_options[:queue]
  53
  54         [:endcolor, :direction, :startcolor, :scaleMode, :restorecolor].each do |option|
  55           js_options[option] = "'#{js_options[option]}'" if js_options[option]
  56         end
  57
  58         if TOGGLE_EFFECTS.include? name.to_sym
  59           "Effect.toggle(#{element},'#{name.to_s.gsub(/^toggle_/,'')}',#{options_for_javascript(js_options)});"
  60         else
  61           "new Effect.#{name.to_s.camelize}(#{element},#{options_for_javascript(js_options)});"
  62         end
  63       end
  64
  65       # Makes the element with the DOM ID specified by +element_id+ sortable
  66       # by drag-and-drop and make an Ajax call whenever the sort order has
  67       # changed. By default, the action called gets the serialized sortable
  68       # element as parameters.
  69       #
  70       # Example:
  71       #
  72       #   <%= sortable_element("my_list", :url => { :action => "order" }) %>
  73       #
  74       # In the example, the action gets a "my_list" array parameter
  75       # containing the values of the ids of elements the sortable consists
  76       # of, in the current order.
  77       #
  78       # Important: For this to work, the sortable elements must have id
  79       # attributes in the form "string_identifier". For example, "item_1". Only
  80       # the identifier part of the id attribute will be serialized.
  81       #
  82       # Additional +options+ are:
  83       #
  84       # * <tt>:format</tt> - A regular expression to determine what to send as the
  85       #   serialized id to the server (the default is <tt>/^[^_]*_(.*)$/</tt>).
  86       #
  87       # * <tt>:constraint</tt> - Whether to constrain the dragging to either
  88       #   <tt>:horizontal</tt> or <tt>:vertical</tt> (or false to make it unconstrained).
  89       #
  90       # * <tt>:overlap</tt> - Calculate the item overlap in the <tt>:horizontal</tt>
  91       #   or <tt>:vertical</tt> direction.
  92       #
  93       # * <tt>:tag</tt> - Which children of the container element to treat as
  94       #   sortable (default is <tt>li</tt>).
  95       #
  96       # * <tt>:containment</tt> - Takes an element or array of elements to treat as
  97       #   potential drop targets (defaults to the original target element).
  98       #
  99       # * <tt>:only</tt> - A CSS class name or array of class names used to filter
 100       #   out child elements as candidates.
 101       #
 102       # * <tt>:scroll</tt> - Determines whether to scroll the list during drag
 103       #   operations if the list runs past the visual border.
 104       #
 105       # * <tt>:tree</tt> - Determines whether to treat nested lists as part of the
 106       #   main sortable list. This means that you can create multi-layer lists,
 107       #   and not only sort items at the same level, but drag and sort items
 108       #   between levels.
 109       #
 110       # * <tt>:hoverclass</tt> - If set, the Droppable will have this additional CSS class
 111       #   when an accepted Draggable is hovered over it.
 112       #
 113       # * <tt>:handle</tt> - Sets whether the element should only be draggable by an
 114       #   embedded handle. The value may be a string referencing a CSS class value
 115       #   (as of script.aculo.us V1.5). The first child/grandchild/etc. element
 116       #   found within the element that has this CSS class value will be used as
 117       #   the handle.
 118       #
 119       # * <tt>:ghosting</tt> - Clones the element and drags the clone, leaving
 120       #   the original in place until the clone is dropped (default is <tt>false</tt>).
 121       #
 122       # * <tt>:dropOnEmpty</tt> - If true the Sortable container will be made into
 123       #   a Droppable, that can receive a Draggable (as according to the containment
 124       #   rules) as a child element when there are no more elements inside (default
 125       #   is <tt>false</tt>).
 126       #
 127       # * <tt>:onChange</tt> - Called whenever the sort order changes while dragging. When
 128       #   dragging from one Sortable to another, the callback is called once on each
 129       #   Sortable. Gets the affected element as its parameter.
 130       #
 131       # * <tt>:onUpdate</tt> - Called when the drag ends and the Sortable's order is
 132       #   changed in any way. When dragging from one Sortable to another, the callback
 133       #   is called once on each Sortable. Gets the container as its parameter.
 134       #
 135       # See http://script.aculo.us for more documentation.
 136       def sortable_element(element_id, options = {})
 137         javascript_tag(sortable_element_js(element_id, options).chop!)
 138       end
 139
 140       def sortable_element_js(element_id, options = {}) #:nodoc:
 141         options[:with]     ||= "Sortable.serialize(#{element_id.to_json})"
 142         options[:onUpdate] ||= "function(){" + remote_function(options) + "}"
 143         options.delete_if { |key, value| PrototypeHelper::AJAX_OPTIONS.include?(key) }
 144
 145         [:tag, :overlap, :constraint, :handle].each do |option|
 146           options[option] = "'#{options[option]}'" if options[option]
 147         end
 148
 149         options[:containment] = array_or_string_for_javascript(options[:containment]) if options[:containment]
 150         options[:only] = array_or_string_for_javascript(options[:only]) if options[:only]
 151
 152         %(Sortable.create(#{element_id.to_json}, #{options_for_javascript(options)});)
 153       end
 154
 155       # Makes the element with the DOM ID specified by +element_id+ draggable.
 156       #
 157       # Example:
 158       #   <%= draggable_element("my_image", :revert => true)
 159       #
 160       # You can change the behaviour with various options, see
 161       # http://script.aculo.us for more documentation.
 162       def draggable_element(element_id, options = {})
 163         javascript_tag(draggable_element_js(element_id, options).chop!)
 164       end
 165
 166       def draggable_element_js(element_id, options = {}) #:nodoc:
 167         %(new Draggable(#{element_id.to_json}, #{options_for_javascript(options)});)
 168       end
 169
 170       # Makes the element with the DOM ID specified by +element_id+ receive
 171       # dropped draggable elements (created by +draggable_element+).
 172       # and make an AJAX call. By default, the action called gets the DOM ID
 173       # of the element as parameter.
 174       #
 175       # Example:
 176       #   <%= drop_receiving_element("my_cart", :url =>
 177       #     { :controller => "cart", :action => "add" }) %>
 178       #
 179       # You can change the behaviour with various options, see
 180       # http://script.aculo.us for more documentation.
 181       #
 182       # Some of these +options+ include:
 183       # * <tt>:accept</tt> - Set this to a string or an array of strings describing the
 184       #   allowable CSS classes that the +draggable_element+ must have in order
 185       #   to be accepted by this +drop_receiving_element+.
 186       #
 187       # * <tt>:confirm</tt> - Adds a confirmation dialog. Example:
 188       #
 189       #     :confirm => "Are you sure you want to do this?"
 190       #
 191       # * <tt>:hoverclass</tt> - If set, the +drop_receiving_element+ will have
 192       #   this additional CSS class when an accepted +draggable_element+ is
 193       #   hovered over it.
 194       #
 195       # * <tt>:onDrop</tt> - Called when a +draggable_element+ is dropped onto
 196       #   this element. Override this callback with a JavaScript expression to
 197       #   change the default drop behaviour. Example:
 198       #
 199       #     :onDrop => "function(draggable_element, droppable_element, event) { alert('I like bananas') }"
 200       #
 201       #   This callback gets three parameters: The Draggable element, the Droppable
 202       #   element and the Event object. You can extract additional information about
 203       #   the drop - like if the Ctrl or Shift keys were pressed - from the Event object.
 204       #
 205       # * <tt>:with</tt> - A JavaScript expression specifying the parameters for
 206       #   the XMLHttpRequest. Any expressions should return a valid URL query string.
 207       def drop_receiving_element(element_id, options = {})
 208         javascript_tag(drop_receiving_element_js(element_id, options).chop!)
 209       end
 210
 211       def drop_receiving_element_js(element_id, options = {}) #:nodoc:
 212         options[:with]     ||= "'id=' + encodeURIComponent(element.id)"
 213         options[:onDrop]   ||= "function(element){" + remote_function(options) + "}"
 214         options.delete_if { |key, value| PrototypeHelper::AJAX_OPTIONS.include?(key) }
 215
 216         options[:accept] = array_or_string_for_javascript(options[:accept]) if options[:accept]
 217         options[:hoverclass] = "'#{options[:hoverclass]}'" if options[:hoverclass]
 218
 219         # Confirmation happens during the onDrop callback, so it can be removed from the options
 220         options.delete(:confirm) if options[:confirm]
 221
 222         %(Droppables.add(#{element_id.to_json}, #{options_for_javascript(options)});)
 223       end
 224     end
 225   end
 226 end