e16935ea87ea8a145f4a10a3363b775d5cd7d5b7
1 require 'action_view/helpers/javascript_helper'
2 require 'active_support/json'
6 # Provides a set of helpers for calling Scriptaculous JavaScript
7 # functions, including those which create Ajax controls and visual effects.
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.
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]
22 # Returns a JavaScript snippet to be used on the Ajax callbacks for
23 # starting visual effects.
26 # <%= link_to_remote "Reload", :update => "posts",
27 # :url => { :action => "reload" },
28 # :complete => visual_effect(:highlight, "posts", :duration => 0.5)
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+:
34 # <%= drop_receiving_element (...), :loading => visual_effect(:fade) %>
36 # This would fade the element that was dropped on the drop receiving
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.
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"
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]
54 [:endcolor, :direction, :startcolor, :scaleMode, :restorecolor].each
do |option
|
55 js_options
[option
] = "'#{js_options[option]}'" if js_options
[option
]
58 if TOGGLE_EFFECTS
.include? name
.to_sym
59 "Effect.toggle(#{element},'#{name.to_s.gsub(/^toggle_/,'')}',#{options_for_javascript(js_options)});"
61 "new Effect.#{name.to_s.camelize}(#{element},#{options_for_javascript(js_options)});"
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.
72 # <%= sortable_element("my_list", :url => { :action => "order" }) %>
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.
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.
82 # Additional +options+ are:
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>).
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).
90 # * <tt>:overlap</tt> - Calculate the item overlap in the <tt>:horizontal</tt>
91 # or <tt>:vertical</tt> direction.
93 # * <tt>:tag</tt> - Which children of the container element to treat as
94 # sortable (default is <tt>li</tt>).
96 # * <tt>:containment</tt> - Takes an element or array of elements to treat as
97 # potential drop targets (defaults to the original target element).
99 # * <tt>:only</tt> - A CSS class name or array of class names used to filter
100 # out child elements as candidates.
102 # * <tt>:scroll</tt> - Determines whether to scroll the list during drag
103 # operations if the list runs past the visual border.
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
110 # * <tt>:hoverclass</tt> - If set, the Droppable will have this additional CSS class
111 # when an accepted Draggable is hovered over it.
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
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>).
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>).
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.
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.
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
!)
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
) }
145 [:tag, :overlap, :constraint, :handle].each
do |option
|
146 options
[option
] = "'#{options[option]}'" if options
[option
]
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]
152 %(Sortable.create(#{element_id.to_json}, #{options_for_javascript(options)});)
155 # Makes the element with the DOM ID specified by +element_id+ draggable.
158 # <%= draggable_element("my_image", :revert => true)
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!)
166 def draggable_element_js(element_id, options = {}) #:nodoc:
167 %(new Draggable(#{element_id.to_json}, #{options_for_javascript(options)});)
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.
176 # <%= drop_receiving_element("my_cart", :url =>
177 # { :controller => "cart", :action => "add" }) %>
179 # You can change the behaviour with various options, see
180 # http://script.aculo.us for more documentation.
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+.
187 # * <tt>:confirm</tt> - Adds a confirmation dialog. Example:
189 # :confirm => "Are you sure you want to do this?"
191 # * <tt>:hoverclass</tt> - If set, the +drop_receiving_element+ will have
192 # this additional CSS class when an accepted +draggable_element+ is
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:
199 # :onDrop => "function(draggable_element, droppable_element, event) { alert('I like bananas') }"
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.
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!)
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) }
216 options[:accept] = array_or_string_for_javascript(options[:accept]) if options[:accept]
217 options[:hoverclass] = "'#{options[:hoverclass]}'" if options[:hoverclass]
219 # Confirmation happens during the onDrop callback, so it can be removed from the options
220 options.delete(:confirm) if options[:confirm]
222 %(Droppables.add(#{element_id.to_json}, #{options_for_javascript(options)});)