Skip to content

Commit

Permalink
UJS documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
@stefanpenner @josh
stefanpenner authored and josh committed Jan 31, 2010
1 parent e1618b9 commit c493370
Show file tree
Hide file tree
Showing 3 changed files with 78 additions and 33 deletions.
27 changes: 27 additions & 0 deletions actionpack/lib/action_view/helpers/form_helper.rb
View file
Expand Up @@ -225,6 +225,33 @@ module FormHelper
# ...
# <% 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 <tt>params</tt>).
#
# Example:
#
# <% form_for(:post, @post, :remote => true, :html => { :id => 'create-post', :method => :put }) do |f| %>
# ...
# <% end %>
#
# The HTML generated for this would be:
#
# <form action='http://www.example.com' id='create-post' method='post' data-remote='true'>
# <div style='margin:0;padding:0;display:inline'>
# <input name='_method' type='hidden' value='put' />
# </div>
# ...
# </form>
#
# === Customized form builders
#
# You can also build forms using a customized FormBuilder class. Subclass
Expand Down
29 changes: 21 additions & 8 deletions actionpack/lib/action_view/helpers/form_tag_helper.rb
View file
Expand Up @@ -19,6 +19,8 @@ module FormTagHelper
# If "put", "delete", or another verb is used, a hidden input with name <tt>_method</tt>
# is added to simulate the verb over post.
# * A list of parameters to feed to the URL the form will be posted to.
# * <tt>:remote</tt> - 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')
Expand All @@ -30,10 +32,14 @@ module FormTagHelper
# form_tag('/upload', :multipart => true)
# # => <form action="/upload" method="post" enctype="multipart/form-data">
#
# <% form_tag '/posts' do -%>
# <% form_tag('/posts')do -%>
# <div><%= submit_tag 'Save' %></div>
# <% end -%>
# # => <form action="/posts" method="post"><div><input type="submit" name="submit" value="Save" /></div></form>
#
# <% form_tag('/posts', :remote => true) %>
# # => <form action="/posts" method="post" data-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?
Expand Down Expand Up @@ -333,12 +339,13 @@ def radio_button_tag(name, value, checked = false, options = {})
# Creates a submit button with the text <tt>value</tt> as the caption.
#
# ==== Options
# * <tt>:confirm => 'question?'</tt> - 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.
# * <tt>:confirm => 'question?'</tt> - 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.
# * <tt>:disabled</tt> - If true, the user will not be able to use this input.
# * <tt>:disable_with</tt> - Value of this parameter will be used as the value for a disabled version
# of the submit button when the form is submitted.
# * <tt>:disable_with</tt> - 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
Expand All @@ -351,16 +358,22 @@ def radio_button_tag(name, value, checked = false, options = {})
# submit_tag "Save edits", :disabled => true
# # => <input disabled="disabled" name="commit" type="submit" value="Save edits" />
#
#
# submit_tag "Complete sale", :disable_with => "Please wait..."
# # => <input name="commit" onclick="this.disabled=true;this.value='Please wait...';this.form.submit();"
# # => <input name="commit" data-disable-with="Please wait..."
# # type="submit" value="Complete sale" />
#
# submit_tag nil, :class => "form_submit"
# # => <input class="form_submit" name="commit" type="submit" />
#
# submit_tag "Edit", :disable_with => "Editing...", :class => "edit-button"
# # => <input class="edit-button" onclick="this.disabled=true;this.value='Editing...';this.form.submit();"
# # => <input class="edit-button" data-disable_with="Editing..."
# # name="commit" type="submit" value="Edit" />
#
# submit_tag "Save", :confirm => "Are you sure?"
# # => <input name='commit' type='submit' value='Save'
# data-confirm="Are you sure?" />
#
def submit_tag(value = "Save changes", options = {})
options.stringify_keys!

Expand Down
55 changes: 30 additions & 25 deletions actionpack/lib/action_view/helpers/url_helper.rb
View file
Expand Up @@ -117,8 +117,8 @@ def url_for(options = {})
# end
#
# ==== Options
# * <tt>:confirm => 'question?'</tt> - This will add a JavaScript confirm
# prompt with the question specified. If the user accepts, the link is
# * <tt>:confirm => 'question?'</tt> - 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.
# * <tt>:method => symbol of HTTP verb</tt> - This modifier will dynamically
# create an HTML form and immediately submit the form for processing using
Expand Down Expand Up @@ -195,18 +195,15 @@ def url_for(options = {})
# link_to "Nonsense search", searches_path(:foo => "bar", :baz => "quux")
# # => <a href="/searches?foo=bar&amp;baz=quux">Nonsense search</a>
#
# The three options specific to +link_to+ (<tt>:confirm</tt> and <tt>:method</tt>) are used as follows:
# The two options specific to +link_to+ (<tt>:confirm</tt> and <tt>:method</tt>) are used as follows:
#
# link_to "Visit Other Site", "http://www.rubyonrails.org/", :confirm => "Are you sure?"
# # => <a href="http://www.rubyonrails.org/" onclick="return confirm('Are you sure?');">Visit Other Site</a>
#
# link_to "Delete Image", @image, :confirm => "Are you sure?", :method => :delete
# # => <a href="/images/9" onclick="if (confirm('Are you sure?')) { var f = document.createElement('form');
# f.style.display = 'none'; this.parentNode.appendChild(f); f.method = 'POST'; f.action = this.href;
# var m = document.createElement('input'); m.setAttribute('type', 'hidden'); m.setAttribute('name', '_method');
# m.setAttribute('value', 'delete');var s = document.createElement('input'); s.setAttribute('type', 'hidden');
# s.setAttribute('name', 'authenticity_token'); s.setAttribute('value', 'Q/ttlxPYZ6R77B+vZ1sBkhj21G2isO9dpE6UtOHBApg=');
# f.appendChild(s)f.appendChild(m);f.submit(); };return false;">Delete Image</a>
# # => <a href="http://www.rubyonrails.org/" data-confirm="Are you sure?"">Visit Other Site</a>
#
# link_to("Destroy", "http://www.example.com", :method => :delete, :confirm => "Are you sure?")
# # => <a href='http://www.example.com' rel="nofollow" data-method="delete" data-confirm="Are you sure?">Destroy</a>

#
def link_to(*args, &block)
if block_given?
options = args.first || {}
Expand Down Expand Up @@ -256,25 +253,39 @@ def link_to(*args, &block)
# There are a few special +html_options+:
# * <tt>:method</tt> - Specifies the anchor name to be appended to the path.
# * <tt>:disabled</tt> - Specifies the anchor name to be appended to the path.
# * <tt>:confirm</tt> - This will add a JavaScript confirm
# * <tt>:confirm</tt> - 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.
# * <tt>:remote</tt> - 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" %>
# # => "<form method="post" action="/controller/new" class="button-to">
# # <div><input value="New" type="submit" /></div>
# # </form>"
#
# 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 %>
# # => "<form method="post" action="/images/delete/1" class="button-to">
# # <div>
# # <input type="hidden" name="_method" value="delete" />
# # <input onclick="return confirm('Are you sure?');"
# # value="Delete" type="submit" />
# # <input data-confirm='Are you sure?' value="Delete" type="submit" />
# # </div>
# # </form>"
#
#
# <%= button_to('Destroy', 'http://www.example.com', :confirm => 'Are you sure?',
# :method => "delete", :remote => true, :disable_with => 'loading...') %>
# # => "<form class='button-to' method='post' action='http://www.example.com' data-remote='true'>
# # <div>
# # <input name='_method' value='delete' type='hidden' />
# # <input value='Destroy' type='submit' disable_with='loading...' data-confirm='Are you sure?' />
# # </div>
# # </form>"
# #

def button_to(name, options = {}, html_options = {})
html_options = html_options.stringify_keys
convert_boolean_attributes!(html_options, %w( disabled ))
Expand Down Expand Up @@ -567,14 +578,8 @@ def convert_options_to_data_attributes(options, html_options)

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]

Expand Down

0 comments on commit c493370

Please sign in to comment.