require 'set'
module ActionView
module Helpers
# Provides a set of helpers for calling Prototype JavaScript functions,
# including functionality to call remote methods using
# Ajax[http://www.adaptivepath.com/publications/essays/archives/000385.php].
# This means that you can call actions in your controllers without
# reloading the page, but still update certain parts of it using
# injections into the DOM. The common use case is having a form that adds
# a new element to a list without reloading the page.
#
# To be able to use these helpers, you must include the Prototype
# JavaScript framework in your pages. See the documentation for
# ActionView::Helpers::JavaScriptHelper for more information on including
# the necessary JavaScript.
#
# See link_to_remote for documentation of options common to all Ajax
# helpers.
#
# See also ActionView::Helpers::ScriptaculousHelper for helpers which work
# with the Scriptaculous controls and visual effects library.
#
# See JavaScriptGenerator for information on updating multiple elements
# on the page in an Ajax response.
module PrototypeHelper
unless const_defined? :CALLBACKS
CALLBACKS = Set.new([ :uninitialized, :loading, :loaded,
:interactive, :complete, :failure, :success ] +
(100..599).to_a)
AJAX_OPTIONS = Set.new([ :before, :after, :condition, :url,
:asynchronous, :method, :insertion, :position,
:form, :with, :update, :script ]).merge(CALLBACKS)
end
# Returns a link to a remote action defined by options[:url]
# (using the url_for format) that's called in the background using
# XMLHttpRequest. The result of that request can then be inserted into a
# DOM object whose id can be specified with options[:update].
# Usually, the result would be a partial prepared by the controller with
# render :partial.
#
# Examples:
# link_to_remote "Delete this post", :update => "posts",
# :url => { :action => "destroy", :id => post.id }
# link_to_remote(image_tag("refresh"), :update => "emails",
# :url => { :action => "list_emails" })
#
# You can override the generated HTML options by specifying a hash in
# options[:html].
#
# link_to_remote "Delete this post", :update => "posts",
# :url => post_url(@post), :method => :delete,
# :html => { :class => "destructive" }
#
# You can also specify a hash for options[:update] to allow for
# easy redirection of output to an other DOM element if a server-side
# error occurs:
#
# Example:
# link_to_remote "Delete this post",
# :url => { :action => "destroy", :id => post.id },
# :update => { :success => "posts", :failure => "error" }
#
# Optionally, you can use the options[:position] parameter to
# influence how the target DOM element is updated. It must be one of
# :before, :top, :bottom, or :after.
#
# The method used is by default POST. You can also specify GET or you
# can simulate PUT or DELETE over POST. All specified with options[:method]
#
# Example:
# link_to_remote "Destroy", :url => person_url(:id => person), :method => :delete
#
# By default, these remote requests are processed asynchronous during
# which various JavaScript callbacks can be triggered (for progress
# indicators and the likes). All callbacks get access to the
# request object, which holds the underlying XMLHttpRequest.
#
# To access the server response, use request.responseText, to
# find out the HTTP status, use request.status.
#
# Example:
# link_to_remote word,
# :url => { :action => "undo", :n => word_counter },
# :complete => "undoRequestCompleted(request)"
#
# The callbacks that may be specified are (in order):
#
# :loading:: Called when the remote document is being
# loaded with data by the browser.
# :loaded:: Called when the browser has finished loading
# the remote document.
# :interactive:: Called when the user can interact with the
# remote document, even though it has not
# finished loading.
# :success:: Called when the XMLHttpRequest is completed,
# and the HTTP status code is in the 2XX range.
# :failure:: Called when the XMLHttpRequest is completed,
# and the HTTP status code is not in the 2XX
# range.
# :complete:: Called when the XMLHttpRequest is complete
# (fires after success/failure if they are
# present).
#
# You can further refine :success and :failure by
# adding additional callbacks for specific status codes.
#
# Example:
# link_to_remote word,
# :url => { :action => "action" },
# 404 => "alert('Not found...? Wrong URL...?')",
# :failure => "alert('HTTP Error ' + request.status + '!')"
#
# A status code callback overrides the success/failure handlers if
# present.
#
# If you for some reason or another need synchronous processing (that'll
# block the browser while the request is happening), you can specify
# options[:type] = :synchronous.
#
# You can customize further browser side call logic by passing in
# JavaScript code snippets via some optional parameters. In their order
# of use these are:
#
# :confirm:: Adds confirmation dialog.
# :condition:: Perform remote request conditionally
# by this expression. Use this to
# describe browser-side conditions when
# request should not be initiated.
# :before:: Called before request is initiated.
# :after:: Called immediately after request was
# initiated and before :loading.
# :submit:: Specifies the DOM element ID that's used
# as the parent of the form elements. By
# default this is the current form, but
# it could just as well be the ID of a
# table row or any other DOM element.
def link_to_remote(name, options = {}, html_options = nil)
link_to_function(name, remote_function(options), html_options || options.delete(:html))
end
# Periodically calls the specified url (options[:url]) every
# options[:frequency] seconds (default is 10). Usually used to
# update a specified div (options[:update]) with the results
# of the remote call. The options for specifying the target with :url
# and defining callbacks is the same as link_to_remote.
def periodically_call_remote(options = {})
frequency = options[:frequency] || 10 # every ten seconds by default
code = "new PeriodicalExecuter(function() {#{remote_function(options)}}, #{frequency})"
javascript_tag(code)
end
# Returns a form tag that will submit using XMLHttpRequest in the
# background instead of the regular reloading POST arrangement. Even
# though it's using JavaScript to serialize the form elements, the form
# submission will work just like a regular submission as viewed by the
# receiving side (all elements available in params). The options for
# specifying the target with :url and defining callbacks is the same as
# link_to_remote.
#
# A "fall-through" target for browsers that doesn't do JavaScript can be
# specified with the :action/:method options on :html.
#
# Example:
# form_remote_tag :html => { :action =>
# url_for(:controller => "some", :action => "place") }
#
# The Hash passed to the :html key is equivalent to the options (2nd)
# argument in the FormTagHelper.form_tag method.
#
# By default the fall-through action is the same as the one specified in
# the :url (and the default method is :post).
#
# form_remote_tag also takes a block, like form_tag:
# <% form_remote_tag :url => '/posts' do -%>
#
<%= submit_tag 'Save' %>
# <% end -%>
def form_remote_tag(options = {}, &block)
options[:form] = true
options[:html] ||= {}
options[:html][:onsubmit] =
(options[:html][:onsubmit] ? options[:html][:onsubmit] + "; " : "") +
"#{remote_function(options)}; return false;"
form_tag(options[:html].delete(:action) || url_for(options[:url]), options[:html], &block)
end
# Creates a form that will submit using XMLHttpRequest in the background
# instead of the regular reloading POST arrangement and a scope around a
# specific resource that is used as a base for questioning about
# values for the fields.
#
# === Resource
#
# Example:
# <% remote_form_for(@post) do |f| %>
# ...
# <% end %>
#
# This will expand to be the same as:
#
# <% remote_form_for :post, @post, :url => post_path(@post), :html => { :method => :put, :class => "edit_post", :id => "edit_post_45" } do |f| %>
# ...
# <% end %>
#
# === Nested Resource
#
# Example:
# <% remote_form_for([@post, @comment]) do |f| %>
# ...
# <% end %>
#
# This will expand to be the same as:
#
# <% remote_form_for :comment, @comment, :url => post_comment_path(@post, @comment), :html => { :method => :put, :class => "edit_comment", :id => "edit_comment_45" } do |f| %>
# ...
# <% end %>
#
# If you don't need to attach a form to a resource, then check out form_remote_tag.
#
# See FormHelper#form_for for additional semantics.
def remote_form_for(record_or_name_or_array, *args, &proc)
options = args.extract_options!
case record_or_name_or_array
when String, Symbol
object_name = record_or_name_or_array
when Array
object = record_or_name_or_array.last
object_name = ActionController::RecordIdentifier.singular_class_name(object)
apply_form_for_options!(record_or_name_or_array, options)
args.unshift object
else
object = record_or_name_or_array
object_name = ActionController::RecordIdentifier.singular_class_name(record_or_name_or_array)
apply_form_for_options!(object, options)
args.unshift object
end
concat(form_remote_tag(options), proc.binding)
fields_for(object_name, *(args << options), &proc)
concat('', proc.binding)
end
alias_method :form_remote_for, :remote_form_for
# Returns a button input tag that will submit form using XMLHttpRequest
# in the background instead of regular reloading POST arrangement.
# options argument is the same as in form_remote_tag.
def submit_to_remote(name, value, options = {})
options[:with] ||= 'Form.serialize(this.form)'
options[:html] ||= {}
options[:html][:type] = 'button'
options[:html][:onclick] = "#{remote_function(options)}; return false;"
options[:html][:name] = name
options[:html][:value] = value
tag("input", options[:html], false)
end
# Returns 'eval(request.responseText)' which is the JavaScript function
# that form_remote_tag can call in :complete to evaluate a multiple
# update return document using update_element_function calls.
def evaluate_remote_response
"eval(request.responseText)"
end
# Returns the JavaScript needed for a remote function.
# Takes the same arguments as link_to_remote.
#
# Example:
#
def remote_function(options)
javascript_options = options_for_ajax(options)
update = ''
if options[:update] && options[:update].is_a?(Hash)
update = []
update << "success:'#{options[:update][:success]}'" if options[:update][:success]
update << "failure:'#{options[:update][:failure]}'" if options[:update][:failure]
update = '{' + update.join(',') + '}'
elsif options[:update]
update << "'#{options[:update]}'"
end
function = update.empty? ?
"new Ajax.Request(" :
"new Ajax.Updater(#{update}, "
url_options = options[:url]
url_options = url_options.merge(:escape => false) if url_options.is_a?(Hash)
function << "'#{url_for(url_options)}'"
function << ", #{javascript_options})"
function = "#{options[:before]}; #{function}" if options[:before]
function = "#{function}; #{options[:after]}" if options[:after]
function = "if (#{options[:condition]}) { #{function}; }" if options[:condition]
function = "if (confirm('#{escape_javascript(options[:confirm])}')) { #{function}; }" if options[:confirm]
return function
end
# Observes the field with the DOM ID specified by +field_id+ and calls a
# callback when its contents have changed. The default callback is an
# Ajax call. By default the value of the observed field is sent as a
# parameter with the Ajax call.
#
# Required +options+ are either of:
# :url:: +url_for+-style options for the action to call
# when the field has changed.
# :function:: Instead of making a remote call to a URL, you
# can specify a function to be called instead.
#
# Additional options are:
# :frequency:: The frequency (in seconds) at which changes to
# this field will be detected. Not setting this
# option at all or to a value equal to or less than
# zero will use event based observation instead of
# time based observation.
# :update:: Specifies the DOM ID of the element whose
# innerHTML should be updated with the
# XMLHttpRequest response text.
# :with:: A JavaScript expression specifying the parameters
# for the XMLHttpRequest. The default is to send the
# key and value of the observed field. Any custom
# expressions should return a valid URL query string.
# The value of the field is stored in the JavaScript
# variable +value+.
#
# Examples
#
# :with => "'my_custom_key=' + value"
# :with => "'person[name]=' + prompt('New name')"
# :with => "Form.Element.serialize('other-field')"
#
# Finally
# :with => 'name'
# is shorthand for
# :with => "'name=' + value"
# This essentially just changes the key of the parameter.
# :on:: Specifies which event handler to observe. By default,
# it's set to "changed" for text fields and areas and
# "click" for radio buttons and checkboxes. With this,
# you can specify it instead to be "blur" or "focus" or
# any other event.
#
# Additionally, you may specify any of the options documented in
# link_to_remote.
def observe_field(field_id, options = {})
if options[:frequency] && options[:frequency] > 0
build_observer('Form.Element.Observer', field_id, options)
else
build_observer('Form.Element.EventObserver', field_id, options)
end
end
# Observes the form with the DOM ID specified by +form_id+ and calls a
# callback when its contents have changed. The default callback is an
# Ajax call. By default all fields of the observed field are sent as
# parameters with the Ajax call.
#
# The +options+ for +observe_form+ are the same as the options for
# +observe_field+. The JavaScript variable +value+ available to the
# :with option is set to the serialized form by default.
def observe_form(form_id, options = {})
if options[:frequency]
build_observer('Form.Observer', form_id, options)
else
build_observer('Form.EventObserver', form_id, options)
end
end
# All the methods were moved to GeneratorMethods so that
# #include_helpers_from_context has nothing to overwrite.
class JavaScriptGenerator #:nodoc:
def initialize(context, &block) #:nodoc:
@context, @lines = context, []
include_helpers_from_context
@context.instance_exec(self, &block)
end
private
def include_helpers_from_context
@context.extended_by.each do |mod|
extend mod unless mod.name =~ /^ActionView::Helpers/
end
extend GeneratorMethods
end
# JavaScriptGenerator generates blocks of JavaScript code that allow you
# to change the content and presentation of multiple DOM elements. Use
# this in your Ajax response bodies, either in a