From 253f335294d8207e050d3994eaabe2c8c1fca8b6 Mon Sep 17 00:00:00 2001 From: Stefan Penner Date: Tue, 26 Jan 2010 00:50:26 -0600 Subject: tests + docs --- actionpack/lib/action_view/helpers/ajax_helper.rb | 152 +++++++++++++--------- 1 file changed, 90 insertions(+), 62 deletions(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_view/helpers/ajax_helper.rb b/actionpack/lib/action_view/helpers/ajax_helper.rb index 343bd78bbd..445e59d3a5 100644 --- a/actionpack/lib/action_view/helpers/ajax_helper.rb +++ b/actionpack/lib/action_view/helpers/ajax_helper.rb @@ -5,23 +5,26 @@ module ActionView # 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 + # params). The options for specifying the target with :url and + # defining callbacks is the same as +link_to_remote+. # # === Resource # # Example: # # # Generates: - # #
... + # # ...
# # - # <% remote_form_for(@post) do |f| %> + # <% remote_form_for(@record, {:html => { :id => 'create-author' }}) do |f| %> # ... # <% end %> # @@ -47,7 +50,10 @@ module ActionView # # 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 @@ module ActionView 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 params). The options for - # specifying the target with :url 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 + # 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. @@ -83,13 +90,12 @@ module ActionView # Example: # # # Generates: - # #
... + # # # # - # 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 :html key is equivalent to the options (2nd) # argument in the FormTagHelper.form_tag method. @@ -108,7 +114,17 @@ module ActionView # <% form_remote_tag :url => '/posts' do -%> #
<%= submit_tag 'Save' %>
# <% end -%> - + # + # # Generates: + # # Hello world!
+ # # + # <% 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 @@ module ActionView form_tag(attributes.delete(:action) || attributes.delete("data-url"), attributes, &block) 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. + # 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 options[:update]. Usually, + # the result would be a partial prepared by the controller with render :partial. # # Examples: # - # # Generates: - # # Delete this post + # # Generates: + # # Remove Author # # - # 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: - # # - # # - # # - # 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]. # - # # Generates: - # # Delete this post + # # Generates: + # # Remove Author # # - # 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 options[:update] to allow for # easy redirection of output to an other DOM element if a server-side @@ -210,7 +223,7 @@ module ActionView # :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): # # :loading:: Called when the remote document is being # loaded with data by the browser. @@ -292,8 +305,8 @@ module ActionView # # data-method='delete'> Delete this post # # # 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 @@ module ActionView 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: + # # + # # + # 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 @@ module ActionView 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 # # -- cgit v1.2.3