Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

tests + docs

  • Loading branch information...
commit 253f335294d8207e050d3994eaabe2c8c1fca8b6 1 parent da19dfa
Stefan Penner stefanpenner authored
Showing with 90 additions and 62 deletions.
  1. +90 −62 actionpack/lib/action_view/helpers/ajax_helper.rb
152 actionpack/lib/action_view/helpers/ajax_helper.rb
View
@@ -5,23 +5,26 @@ module AjaxHelper
# Rails classes should not be aware of individual JS frameworks
include PrototypeHelper
- # 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.
+ # Returns a form that will allow the unobtrusive JavaScript drivers to submit the
+ # form the dynamic nature of their choice. The default behaviour is an XMLHttpRequest
+ # in the background instead of the regular 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
+ # <tt>params</tt>). The options for specifying the target with <tt>:url</tt> and
+ # defining callbacks is the same as +link_to_remote+.
#
# === Resource
#
# Example:
#
# # Generates:
- # # <form class='edit_post'
- # # id='edit_post_1'
- # # action='/posts/1/edit'
- # # method='post'
- # # data-remote='true'>...</div>
+ # # <form action='/authors'
+ # # data-remote='true'
+ # # class='new_author'
+ # # id='create-author'
+ # # method='post'> ... </form>
# #
- # <% remote_form_for(@post) do |f| %>
+ # <% remote_form_for(@record, {:html => { :id => 'create-author' }}) do |f| %>
# ...
# <% end %>
#
@@ -47,7 +50,10 @@ module AjaxHelper
#
# 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| %>
+ # <% remote_form_for :comment, @comment, :url => post_comment_path(@post, @comment),
+ # :html => { :method => :put,
+ # :class => "edit_comment",
+ # :id => "edit_comment_45" } do |f| %>
# ...
# <% end %>
#
@@ -69,13 +75,14 @@ def remote_form_for(record_or_name_or_array, *args, &proc)
end
alias_method :form_remote_for, :remote_form_for
- # 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 <tt>params</tt>). The options for
- # specifying the target with <tt>:url</tt> and defining callbacks is the same as
- # +link_to_remote+.
+ # Returns a form tag that will allow the unobtrusive JavaScript drivers to submit the
+ # form via the dynamic behaviour of choice. The default behaviour is an XMLHttpRequest
+ # in the background instead of the regular 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
+ # <tt>params</tt>). The options for specifying the target with <tt>:url</tt> 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 <tt>:action</tt>/<tt>:method</tt> options on <tt>:html</tt>.
@@ -83,13 +90,12 @@ def remote_form_for(record_or_name_or_array, *args, &proc)
# Example:
#
# # Generates:
- # # <form action='/some/place'
- # # method='post'
- # # data-remote='true'>...</div>
+ # # <form action="http://www.example.com/fast"
+ # # method="post"
+ # # data-remote="true"
+ # # data-update-success="glass_of_beer">
# #
- # form_remote_tag :html => { :action =>
- # url_for(:controller => "some", :action => "place") }
- # < form data-remote action="/some/place" method="post" >
+ # form_remote_tag(:update => "glass_of_beer", :url => { :action => :fast })
#
# The Hash passed to the <tt>:html</tt> key is equivalent to the options (2nd)
# argument in the FormTagHelper.form_tag method.
@@ -108,7 +114,17 @@ def remote_form_for(record_or_name_or_array, *args, &proc)
# <% form_remote_tag :url => '/posts' do -%>
# <div><%= submit_tag 'Save' %></div>
# <% end -%>
-
+ #
+ # # Generates:
+ # # <form action="http://www.example.com/fast"
+ # # method="post"
+ # # data-remote="true"
+ # # data-update-success="glass_of_beer">Hello world!</form>
+ # #
+ # <% form_remote_tag(:update => "glass_of_beer", :url => { :action => :fast }) do -%>
+ # <% concat "Hello world!" %>
+ # <% end -%>
+ #
def form_remote_tag(options = {}, &block)
html_options = options.delete(:callbacks)
@@ -121,43 +137,40 @@ def form_remote_tag(options = {}, &block)
form_tag(attributes.delete(:action) || attributes.delete("data-url"), attributes, &block)
end
- # Returns a link to a remote action defined by <tt>options[:url]</tt>
- # (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 <tt>options[:update]</tt>.
- # Usually, the result would be a partial prepared by the controller with
- # render :partial.
+ # Returns a link that will allow unobtrusive JavaScript to dynamical adjust its
+ # behaviour. The default behaviour is an XMLHttpRequest in the background instead
+ # of the regular GET arrangement. The result of that request can then be inserted
+ # into a DOM object whose id can be specified with <tt>options[:update]</tt>. Usually,
+ # the result would be a partial prepared by the controller with render :partial.
#
# Examples:
#
- # # Generates:
- # # <a href='/blog/3'
- # # rel='nofollow'
- # # data-remote='true'
- # # data-method='delete' >Delete this post</ a>
+ # # Generates:
+ # # <a href="#"
+ # # data-remote="true"
+ # # data-url="http://www.example.com/whatnot"
+ # # data-method="delete"
+ # # rel="nofollow">Remove Author</a>
# #
- # link_to_remote "Delete this post", :update => "posts",
- # :url => { :action => "destroy", :id => post.id }
+ # link_to_remote("Remove Author", { :url => { :action => "whatnot" },
+ # :method => "delete"})
#
- # # Generates:
- # # <a data-remote='true' href="/mail/list_emails" rel="nofollow" >
- # # <img src='/images/refresh.png'/>
- # # </ a>
- # link_to_remote(image_tag("refresh"), :update => "emails",
- # :url => { :action => "list_emails" })
#
# You can override the generated HTML options by specifying a hash in
# <tt>options[:html]</tt>.
#
- # # Generates:
- # # <a class='destructive'
- # # href='/mail/list_emails'
- # # rel="nofollow"
- # # data-remote='true'>Delete this post</a>
+ # # Generates:
+ # # <a class="fine"
+ # # href="#"
+ # # data-remote="true"
+ # # data-url="http://www.example.com/whatnot"
+ # # data-method="delete"
+ # # rel="nofollow">Remove Author</a>
# #
- # link_to_remote "Delete this post", :update => "posts",
- # :url => post_url(@post), :method => :delete,
- # :html => { :class => "destructive" }
+ # link_to_remote("Remove Author", { :url => { :action => "whatnot" },
+ # :method => "delete",
+ # :html => { :class => "fine" }})
+ #
#
# You can also specify a hash for <tt>options[:update]</tt> to allow for
# easy redirection of output to an other DOM element if a server-side
@@ -210,7 +223,7 @@ def form_remote_tag(options = {}, &block)
# :url => { :action => "undo", :n => word_counter },
# :complete => "undoRequestCompleted(request)"
#
- # The callbacks that may be specified are (in order): (deprecated)
+ # The callbacks that may be specified are (in order):
#
# <tt>:loading</tt>:: Called when the remote document is being
# loaded with data by the browser.
@@ -292,8 +305,8 @@ def form_remote_tag(options = {}, &block)
# # data-method='delete'> Delete this post</a>
# #
# link_to_remote "Delete this post",
- # { :update => "posts", :url => { :action => "destroy", :id => post.id } },
- # :href => url_for(:action => "destroy", :id => post.id)
+ # { :update => "posts", :url => { :action => "destroy", :id => post.id } }
+ #
def link_to_remote(name, options, html_options = {})
attributes = {}
attributes.merge!(:rel => "nofollow") if options[:method] && options[:method].to_s.downcase == "delete"
@@ -310,10 +323,23 @@ def link_to_remote(name, options, html_options = {})
content_tag(:a, name, attributes)
end
- # Creates a button with an onclick event which calls a remote action
- # via XMLHttpRequest
- # The options for specifying the target with :url
- # and defining callbacks is the same as link_to_remote.
+ # Returns an input of type button, which allows the unobtrusive JavaScript driver
+ # to dynamically adjust its behaviour. The default driver behaviour is to call a
+ # remote action via XMLHttpRequest in the background.
+ # The options for specifying the target with :url and defining callbacks is the same
+ # as link_to_remote.
+ #
+ # Example:
+ #
+ # # Generates:
+ # # <input class="fine"
+ # # type="button"
+ # # value="Remote outpost"
+ # # data-remote="true"
+ # # data-url="http://www.example.com/whatnot" />
+ # #
+ # button_to_remote("Remote outpost", { :url => { :action => "whatnot" }}, { :class => "fine" })
+ #
def button_to_remote(name, options = {}, html_options = {})
attributes = html_options.merge!(:type => "button", :value => name)
@@ -330,9 +356,11 @@ def button_to_remote(name, options = {}, html_options = {})
tag(:input, attributes)
end
- # Returns a button input tag with the element name of +name+ and a value (i.e., display text) of +value+
- # that will submit form using XMLHttpRequest in the background instead of a regular POST request that
- # reloads the page.
+ # Returns an input tag of type button, with the element name of +name+ and a value (i.e., display text)
+ # of +value+ which will allow the unobtrusive JavaScript driver to dynamically adjust its behaviour
+ # The default behaviour is to call a remote action via XMLHttpRequest in the background.
+ #
+ # request that reloads the page.
#
# # Create a button that submits to the create action
# #
Please sign in to comment.
Something went wrong with that request. Please try again.