From c493370f332715dee0ef795a66e896d7f0471cbe Mon Sep 17 00:00:00 2001 From: Stefan Penner Date: Sun, 31 Jan 2010 16:30:21 -0600 Subject: UJS documentation. --- actionpack/lib/action_view/helpers/form_helper.rb | 27 +++++++++++ .../lib/action_view/helpers/form_tag_helper.rb | 29 ++++++++---- actionpack/lib/action_view/helpers/url_helper.rb | 55 ++++++++++++---------- 3 files changed, 78 insertions(+), 33 deletions(-) (limited to 'actionpack') diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index 54610fdc71..a72357cf3d 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -225,6 +225,33 @@ module ActionView # ... # <% end %> # + # === Unobtrusive JavaScript + # + # Specifying: + # + # :remote => true + # + # in the options hash creates a form that will allow the unobtrusive JavaScript drivers to modify its + # behaviour. The expected default behaviour is an XMLHttpRequest in the background instead of the regular + # POST arrangement, but ultimately the behaviour is the choice of the JavaScript driver implementor. + # 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). + # + # Example: + # + # <% form_for(:post, @post, :remote => true, :html => { :id => 'create-post', :method => :put }) do |f| %> + # ... + # <% end %> + # + # The HTML generated for this would be: + # + #
+ #
+ # + #
+ # ... + #
+ # # === Customized form builders # # You can also build forms using a customized FormBuilder class. Subclass diff --git a/actionpack/lib/action_view/helpers/form_tag_helper.rb b/actionpack/lib/action_view/helpers/form_tag_helper.rb index 81c76e090a..597cf311cb 100644 --- a/actionpack/lib/action_view/helpers/form_tag_helper.rb +++ b/actionpack/lib/action_view/helpers/form_tag_helper.rb @@ -19,6 +19,8 @@ module ActionView # If "put", "delete", or another verb is used, a hidden input with name _method # is added to simulate the verb over post. # * A list of parameters to feed to the URL the form will be posted to. + # * :remote - If set to true, will allow the Unobtrusive JavaScript drivers to control the + # submit behaviour. By default this behaviour is an ajax submit. # # ==== Examples # form_tag('/posts') @@ -30,10 +32,14 @@ module ActionView # form_tag('/upload', :multipart => true) # # =>
# - # <% form_tag '/posts' do -%> + # <% form_tag('/posts')do -%> #
<%= submit_tag 'Save' %>
# <% end -%> # # =>
+ # + # <% form_tag('/posts', :remote => true) %> + # # =>
+ # def form_tag(url_for_options = {}, options = {}, *parameters_for_url, &block) html_options = html_options_for_form(url_for_options, options, *parameters_for_url) if block_given? @@ -333,12 +339,13 @@ module ActionView # Creates a submit button with the text value as the caption. # # ==== Options - # * :confirm => 'question?' - This will add a JavaScript confirm - # prompt with the question specified. If the user accepts, the form is - # processed normally, otherwise no action is taken. + # * :confirm => 'question?' - If present the unobtrusive JavaScript + # drivers will provide a prompt with the question specified. If the user accepts, + # the form is processed normally, otherwise no action is taken. # * :disabled - If true, the user will not be able to use this input. - # * :disable_with - Value of this parameter will be used as the value for a disabled version - # of the submit button when the form is submitted. + # * :disable_with - Value of this parameter will be used as the value for a + # disabled version of the submit button when the form is submitted. This feature is + # provided by the unobtrusive JavaScript driver. # * Any other key creates standard HTML options for the tag. # # ==== Examples @@ -351,16 +358,22 @@ module ActionView # submit_tag "Save edits", :disabled => true # # => # + # # submit_tag "Complete sale", :disable_with => "Please wait..." - # # => # # submit_tag nil, :class => "form_submit" # # => # # submit_tag "Edit", :disable_with => "Editing...", :class => "edit-button" - # # => + # + # submit_tag "Save", :confirm => "Are you sure?" + # # => + # def submit_tag(value = "Save changes", options = {}) options.stringify_keys! diff --git a/actionpack/lib/action_view/helpers/url_helper.rb b/actionpack/lib/action_view/helpers/url_helper.rb index e56bfc7bfd..4301647a2c 100644 --- a/actionpack/lib/action_view/helpers/url_helper.rb +++ b/actionpack/lib/action_view/helpers/url_helper.rb @@ -117,8 +117,8 @@ module ActionView # end # # ==== Options - # * :confirm => 'question?' - This will add a JavaScript confirm - # prompt with the question specified. If the user accepts, the link is + # * :confirm => 'question?' - This will allow the unobtrusive JavaScript + # driver to prompt with the question specified. If the user accepts, the link is # processed normally, otherwise no action is taken. # * :method => symbol of HTTP verb - This modifier will dynamically # create an HTML form and immediately submit the form for processing using @@ -195,18 +195,15 @@ module ActionView # link_to "Nonsense search", searches_path(:foo => "bar", :baz => "quux") # # => Nonsense search # - # The three options specific to +link_to+ (:confirm and :method) are used as follows: + # The two options specific to +link_to+ (:confirm and :method) are used as follows: # # link_to "Visit Other Site", "http://www.rubyonrails.org/", :confirm => "Are you sure?" - # # => Visit Other Site - # - # link_to "Delete Image", @image, :confirm => "Are you sure?", :method => :delete - # # => Delete Image + # # => Visit Other Site + # + # link_to("Destroy", "http://www.example.com", :method => :delete, :confirm => "Are you sure?") + # # => Destroy + + # def link_to(*args, &block) if block_given? options = args.first || {} @@ -256,9 +253,11 @@ module ActionView # There are a few special +html_options+: # * :method - Specifies the anchor name to be appended to the path. # * :disabled - Specifies the anchor name to be appended to the path. - # * :confirm - This will add a JavaScript confirm + # * :confirm - This will use the unobtrusive JavaScript driver to # prompt with the question specified. If the user accepts, the link is # processed normally, otherwise no action is taken. + # * :remote - If set to true, will allow the Unobtrusive JavaScript drivers to control the + # submit behaviour. By default this behaviour is an ajax submit. # # ==== Examples # <%= button_to "New", :action => "new" %> @@ -266,15 +265,27 @@ module ActionView # #
# #
" # - # button_to "Delete Image", { :action => "delete", :id => @image.id }, - # :confirm => "Are you sure?", :method => :delete + # + # <%= button_to "Delete Image", { :action => "delete", :id => @image.id }, + # :confirm => "Are you sure?", :method => :delete %> # # => "
# #
# # - # # + # # # #
# #
" + # + # + # <%= button_to('Destroy', 'http://www.example.com', :confirm => 'Are you sure?', + # :method => "delete", :remote => true, :disable_with => 'loading...') %> + # # => "
+ # #
+ # # + # # + # #
+ # #
" + # # + def button_to(name, options = {}, html_options = {}) html_options = html_options.stringify_keys convert_boolean_attributes!(html_options, %w( disabled )) @@ -567,14 +578,8 @@ module ActionView method, href = html_options.delete("method"), html_options['href'] - if confirm && method - add_confirm_to_attributes!(html_options, confirm) - add_method_to_attributes!(html_options, method) - elsif confirm - add_confirm_to_attributes!(html_options, confirm) - elsif method - add_method_to_attributes!(html_options, method) - end + add_confirm_to_attributes!(html_options, confirm) if confirm + add_method_to_attributes!(html_options, method) if method html_options["data-url"] = options[:url] if options.is_a?(Hash) && options[:url] -- cgit v1.2.3