diff options
Diffstat (limited to 'actionpack/lib/action_view/helpers')
10 files changed, 103 insertions, 88 deletions
diff --git a/actionpack/lib/action_view/helpers/active_record_helper.rb b/actionpack/lib/action_view/helpers/active_record_helper.rb index 7569cc381d..f3f204cc97 100644 --- a/actionpack/lib/action_view/helpers/active_record_helper.rb +++ b/actionpack/lib/action_view/helpers/active_record_helper.rb @@ -8,47 +8,55 @@ module ActionView end module Helpers - # The Active Record Helper makes it easier to create forms for records kept in instance variables. The most far-reaching is the form + # The Active Record Helper makes it easier to create forms for records kept in instance variables. The most far-reaching is the +form+ # method that creates a complete form for all the basic content types of the record (not associations or aggregations, though). This # is a great way of making the record quickly available for editing, but likely to prove lackluster for a complicated real-world form. - # In that case, it's better to use the input method and the specialized form methods in link:classes/ActionView/Helpers/FormHelper.html + # In that case, it's better to use the +input+ method and the specialized +form+ methods in link:classes/ActionView/Helpers/FormHelper.html module ActiveRecordHelper - # Returns a default input tag for the type of object returned by the method. For example, let's say you have a model - # that has an attribute +title+ of type VARCHAR column, and this instance holds "Hello World": - # input("post", "title") => - # <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" /> + # Returns a default input tag for the type of object returned by the method. For example, if <tt>@post</tt> + # has an attribute +title+ mapped to a +VARCHAR+ column that holds "Hello World": + # + # input("post", "title") + # # => <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" /> def input(record_name, method, options = {}) InstanceTag.new(record_name, method, self).to_tag(options) end - # Returns an entire form with all needed input tags for a specified Active Record object. For example, let's say you - # have a table model <tt>Post</tt> with attributes named <tt>title</tt> of type <tt>VARCHAR</tt> and <tt>body</tt> of type <tt>TEXT</tt>: + # Returns an entire form with all needed input tags for a specified Active Record object. For example, if <tt>@post</tt> + # has attributes named +title+ of type +VARCHAR+ and +body+ of type +TEXT+ then + # # form("post") - # That line would yield a form like the following: - # <form action='/post/create' method='post'> - # <p> - # <label for="post_title">Title</label><br /> - # <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" /> - # </p> - # <p> - # <label for="post_body">Body</label><br /> - # <textarea cols="40" id="post_body" name="post[body]" rows="20"> - # </textarea> - # </p> - # <input type='submit' value='Create' /> - # </form> + # + # would yield a form like the following (modulus formatting): + # + # <form action='/posts/create' method='post'> + # <p> + # <label for="post_title">Title</label><br /> + # <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" /> + # </p> + # <p> + # <label for="post_body">Body</label><br /> + # <textarea cols="40" id="post_body" name="post[body]" rows="20"></textarea> + # </p> + # <input name="commit" type="submit" value="Create" /> + # </form> # # It's possible to specialize the form builder by using a different action name and by supplying another - # block renderer. For example, let's say you have a model <tt>Entry</tt> with an attribute <tt>message</tt> of type <tt>VARCHAR</tt>: + # block renderer. For example, if <tt>@entry</tt> has an attribute +message+ of type +VARCHAR+ then + # + # form("entry", + # :action => "sign", + # :input_block => Proc.new { |record, column| + # "#{column.human_name}: #{input(record, column.name)}<br />" + # }) # - # form("entry", :action => "sign", :input_block => - # Proc.new { |record, column| "#{column.human_name}: #{input(record, column.name)}<br />" }) => + # would yield a form like the following (modulus formatting): # - # <form action='/post/sign' method='post'> - # Message: - # <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" /><br /> - # <input type='submit' value='Sign' /> - # </form> + # <form action="/entries/sign" method="post"> + # Message: + # <input id="entry_message" name="entry[message]" size="30" type="text" /><br /> + # <input name="commit" type="submit" value="Sign" /> + # </form> # # It's also possible to add additional content to the form by giving it a block, such as: # @@ -59,11 +67,11 @@ module ActionView # # The following options are available: # - # * <tt>action</tt> - the action used when submitting the form (default: create if a new record, otherwise update) - # * <tt>input_block</tt> - specialize the output using a different block, see above - # * <tt>method</tt> - the method used when submitting the form (default: post) - # * <tt>multipart</tt> - whether to change the enctype of the form to multipart/form-date, used when uploading a file (default: false) - # * <tt>submit_value</tt> - the text of the submit button (default: Create if a new record, otherwise Update) + # * <tt>:action</tt> - The action used when submitting the form (default: +create+ if a new record, otherwise +update+). + # * <tt>:input_block</tt> - Specialize the output using a different block, see above. + # * <tt>:method</tt> - The method used when submitting the form (default: +post+). + # * <tt>:multipart</tt> - Whether to change the enctype of the form to "multipart/form-data", used when uploading a file (default: +false+). + # * <tt>:submit_value</tt> - The text of the submit button (default: "Create" if a new record, otherwise "Update"). def form(record_name, options = {}) record = instance_variable_get("@#{record_name}") @@ -84,17 +92,16 @@ module ActionView # Returns a string containing the error message attached to the +method+ on the +object+ if one exists. # This error message is wrapped in a <tt>DIV</tt> tag, which can be extended to include a +prepend_text+ and/or +append_text+ # (to properly explain the error), and a +css_class+ to style it accordingly. +object+ should either be the name of an instance variable or - # the actual object. As an example, let's say you have a model - # +post+ that has an error message on the +title+ attribute: + # the actual object. As an example, let's say you have a model <tt>@post</tt> that has an error message on the +title+ attribute: # - # <%= error_message_on "post", "title" %> => - # <div class="formError">can't be empty</div> + # <%= error_message_on "post", "title" %> + # # => <div class="formError">can't be empty</div> # - # <%= error_message_on @post, "title" %> => - # <div class="formError">can't be empty</div> + # <%= error_message_on @post, "title" %> + # # => <div class="formError">can't be empty</div> # - # <%= error_message_on "post", "title", "Title simply ", " (or it won't work).", "inputError" %> => - # <div class="inputError">Title simply can't be empty (or it won't work).</div> + # <%= error_message_on "post", "title", "Title simply ", " (or it won't work).", "inputError" %> + # # => <div class="inputError">Title simply can't be empty (or it won't work).</div> def error_message_on(object, method, prepend_text = "", append_text = "", css_class = "formError") if (obj = (object.respond_to?(:errors) ? object : instance_variable_get("@#{object}"))) && (errors = obj.errors.on(method)) @@ -110,30 +117,37 @@ module ActionView # # This <tt>DIV</tt> can be tailored by the following options: # - # * <tt>header_tag</tt> - Used for the header of the error div (default: h2) - # * <tt>id</tt> - The id of the error div (default: errorExplanation) - # * <tt>class</tt> - The class of the error div (default: errorExplanation) - # * <tt>object</tt> - The object (or array of objects) for which to display errors, if you need to escape the instance variable convention - # * <tt>object_name</tt> - The object name to use in the header, or any text that you prefer. If <tt>object_name</tt> is not set, the name of the first object will be used. - # * <tt>header_message</tt> - The message in the header of the error div. Pass +nil+ or an empty string to avoid the header message altogether. (default: X errors prohibited this object from being saved) - # * <tt>message</tt> - The explanation message after the header message and before the error list. Pass +nil+ or an empty string to avoid the explanation message altogether. (default: There were problems with the following fields:) + # * <tt>:header_tag</tt> - Used for the header of the error div (default: "h2"). + # * <tt>:id</tt> - The id of the error div (default: "errorExplanation"). + # * <tt>:class</tt> - The class of the error div (default: "errorExplanation"). + # * <tt>:object</tt> - The object (or array of objects) for which to display errors, + # if you need to escape the instance variable convention. + # * <tt>:object_name</tt> - The object name to use in the header, or any text that you prefer. + # If <tt>:object_name</tt> is not set, the name of the first object will be used. + # * <tt>:header_message</tt> - The message in the header of the error div. Pass +nil+ + # or an empty string to avoid the header message altogether. (Default: "X errors + # prohibited this object from being saved"). + # * <tt>:message</tt> - The explanation message after the header message and before + # the error list. Pass +nil+ or an empty string to avoid the explanation message + # altogether. (Default: "There were problems with the following fields:"). # - # To specify the display for one object, you simply provide its name as a parameter. For example, for the +User+ model: + # To specify the display for one object, you simply provide its name as a parameter. + # For example, for the <tt>@user</tt> model: # # error_messages_for 'user' # - # To specify more than one object, you simply list them; optionally, you can add an extra +object_name+ parameter, which - # will be the name used in the header message. + # To specify more than one object, you simply list them; optionally, you can add an extra <tt>:object_name</tt> parameter, which + # will be the name used in the header message: # # error_messages_for 'user_common', 'user', :object_name => 'user' # - # If the objects cannot be located as instance variables, you can add an extra +object+ paremeter which gives the actual - # object (or array of objects to use) + # If the objects cannot be located as instance variables, you can add an extra <tt>:object</tt> paremeter which gives the actual + # object (or array of objects to use): # # error_messages_for 'user', :object => @question.user # # NOTE: This is a pre-packaged presentation of the errors with embedded strings and a certain HTML structure. If what - # you need is significantly different from the default presentation, it makes plenty of sense to access the object.errors + # you need is significantly different from the default presentation, it makes plenty of sense to access the <tt>object.errors</tt> # instance yourself and set it up. View the source of this method to see how easy it is. def error_messages_for(*params) options = params.extract_options!.symbolize_keys diff --git a/actionpack/lib/action_view/helpers/asset_tag_helper.rb b/actionpack/lib/action_view/helpers/asset_tag_helper.rb index 0cce96b184..dfc7e2b3ed 100644 --- a/actionpack/lib/action_view/helpers/asset_tag_helper.rb +++ b/actionpack/lib/action_view/helpers/asset_tag_helper.rb @@ -164,7 +164,7 @@ module ActionView # current page or you can pass the full path relative to your document # root. To include the Prototype and Scriptaculous javascript libraries in # your application, pass <tt>:defaults</tt> as the source. When using - # :defaults, if an <tt>application.js</tt> file exists in your public + # <tt>:defaults</tt>, if an application.js file exists in your public # javascripts directory, it will be included as well. You can modify the # html attributes of the script tag by passing a hash as the last argument. # @@ -332,7 +332,7 @@ module ActionView # <link href="/stylesheets/random.styles" media="screen" rel="stylesheet" type="text/css" /> # <link href="/css/stylish.css" media="screen" rel="stylesheet" type="text/css" /> # - # You can also include all styles in the stylesheet directory using :all as the source: + # You can also include all styles in the stylesheet directory using <tt>:all</tt> as the source: # # stylesheet_link_tag :all # => # <link href="/stylesheets/style1.css" media="screen" rel="stylesheet" type="text/css" /> diff --git a/actionpack/lib/action_view/helpers/date_helper.rb b/actionpack/lib/action_view/helpers/date_helper.rb index 9f7790d0f9..cbd390421a 100755 --- a/actionpack/lib/action_view/helpers/date_helper.rb +++ b/actionpack/lib/action_view/helpers/date_helper.rb @@ -104,17 +104,17 @@ module ActionView # Returns a set of select tags (one for year, month, and day) pre-selected for accessing a specified date-based attribute (identified by # +method+) on an object assigned to the template (identified by +object+). It's possible to tailor the selects through the +options+ hash, - # which accepts all the keys that each of the individual select builders do (like :use_month_numbers for select_month) as well as a range of + # which accepts all the keys that each of the individual select builders do (like <tt>:use_month_numbers</tt> for select_month) as well as a range of # discard options. The discard options are <tt>:discard_year</tt>, <tt>:discard_month</tt> and <tt>:discard_day</tt>. Set to true, they'll # drop the respective select. Discarding the month select will also automatically discard the day select. It's also possible to explicitly # set the order of the tags using the <tt>:order</tt> option with an array of symbols <tt>:year</tt>, <tt>:month</tt> and <tt>:day</tt> in # the desired order. Symbols may be omitted and the respective select is not included. # - # Pass the <tt>:default</tt> option to set the default date. Use a Time object or a Hash of :year, :month, :day, :hour, :minute, and :second. + # Pass the <tt>:default</tt> option to set the default date. Use a Time object or a Hash of <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>, <tt>:hour</tt>, <tt>:minute</tt>, and <tt>:second</tt>. # - # Passing :disabled => true as part of the +options+ will make elements inaccessible for change. + # Passing <tt>:disabled => true</tt> as part of the +options+ will make elements inaccessible for change. # - # If anything is passed in the html_options hash it will be applied to every select tag in the set. + # If anything is passed in the +html_options+ hash it will be applied to every select tag in the set. # # NOTE: Discarded selects will default to 1. So if no month select is available, January will be assumed. # diff --git a/actionpack/lib/action_view/helpers/form_helper.rb b/actionpack/lib/action_view/helpers/form_helper.rb index 65f4fb6e45..63c5fd57aa 100644 --- a/actionpack/lib/action_view/helpers/form_helper.rb +++ b/actionpack/lib/action_view/helpers/form_helper.rb @@ -108,7 +108,7 @@ module ActionView # Note: This also works for the methods in FormOptionHelper and DateHelper that are designed to work with an object as base, # like FormOptionHelper#collection_select and DateHelper#datetime_select. # - # HTML attributes for the form tag can be given as :html => {...}. For example: + # HTML attributes for the form tag can be given as <tt>:html => {...}</tt>. For example: # # <% form_for :person, @person, :html => {:id => 'person_form'} do |f| %> # ... diff --git a/actionpack/lib/action_view/helpers/form_options_helper.rb b/actionpack/lib/action_view/helpers/form_options_helper.rb index 5b026245da..bf65fe5574 100644 --- a/actionpack/lib/action_view/helpers/form_options_helper.rb +++ b/actionpack/lib/action_view/helpers/form_options_helper.rb @@ -93,8 +93,8 @@ module ActionView # This allows the user to submit a form page more than once with the expected results of creating multiple records. # In addition, this allows a single partial to be used to generate form inputs for both edit and create forms. # - # By default, post.person_id is the selected option. Specify :selected => value to use a different selection - # or :selected => nil to leave all options unselected. + # By default, <tt>post.person_id</tt> is the selected option. Specify <tt>:selected => value</tt> to use a different selection + # or <tt>:selected => nil</tt> to leave all options unselected. def select(object, method, choices, options = {}, html_options = {}) InstanceTag.new(object, method, self, nil, options.delete(:object)).to_select_tag(choices, options, html_options) end diff --git a/actionpack/lib/action_view/helpers/form_tag_helper.rb b/actionpack/lib/action_view/helpers/form_tag_helper.rb index 0544ed3ded..f37b428b80 100644 --- a/actionpack/lib/action_view/helpers/form_tag_helper.rb +++ b/actionpack/lib/action_view/helpers/form_tag_helper.rb @@ -341,8 +341,9 @@ module ActionView # 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" disable_with="Editing..." name="commit" type="submit" value="Edit" /> + # submit_tag "Edit", :disable_with => "Editing...", :class => "edit-button" + # # => <input class="edit-button" onclick="this.disabled=true;this.value='Editing...';this.form.submit();" + # # name="commit" type="submit" value="Edit" /> def submit_tag(value = "Save changes", options = {}) options.stringify_keys! diff --git a/actionpack/lib/action_view/helpers/prototype_helper.rb b/actionpack/lib/action_view/helpers/prototype_helper.rb index 81938ac8e3..908728c0e6 100644 --- a/actionpack/lib/action_view/helpers/prototype_helper.rb +++ b/actionpack/lib/action_view/helpers/prototype_helper.rb @@ -255,10 +255,10 @@ module ActionView link_to_function(name, remote_function(options), html_options || options.delete(:html)) end - # Periodically calls the specified url (<tt>options[:url]</tt>) every + # Periodically calls the specified url (<tt>options[:url]</tt>) every # <tt>options[:frequency]</tt> seconds (default is 10). Usually used to - # update a specified div (<tt>options[:update]</tt>) with the results - # of the remote call. The options for specifying the target with :url + # update a specified div (<tt>options[:update]</tt>) with the results + # of the remote call. The options for specifying the target with <tt>:url</tt> # and defining callbacks is the same as link_to_remote. # Examples: # # Call get_averages and put its results in 'avg' every 10 seconds @@ -291,11 +291,11 @@ module ActionView # 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 :url and defining callbacks is the same as - # link_to_remote. + # 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 :action/:method options on :html. + # specified with the <tt>:action</tt>/<tt>:method</tt> options on <tt>:html</tt>. # # Example: # # Generates: @@ -304,11 +304,11 @@ module ActionView # form_remote_tag :html => { :action => # url_for(:controller => "some", :action => "place") } # - # The Hash passed to the :html key is equivalent to the options (2nd) + # The Hash passed to the <tt>:html</tt> 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). + # the <tt>:url</tt> (and the default method is <tt>:post</tt>). # # form_remote_tag also takes a block, like form_tag: # # Generates: @@ -422,8 +422,8 @@ module ActionView end # Returns '<tt>eval(request.responseText)</tt>' 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. + # that +form_remote_tag+ can call in <tt>:complete</tt> to evaluate a multiple + # update return document using +update_element_function+ calls. def evaluate_remote_response "eval(request.responseText)" end diff --git a/actionpack/lib/action_view/helpers/sanitize_helper.rb b/actionpack/lib/action_view/helpers/sanitize_helper.rb index 47fbe3a27a..3129ff414e 100644 --- a/actionpack/lib/action_view/helpers/sanitize_helper.rb +++ b/actionpack/lib/action_view/helpers/sanitize_helper.rb @@ -10,7 +10,7 @@ module ActionView base.extend(ClassMethods) end - # This #sanitize helper will html encode all tags and strip all attributes that aren't specifically allowed. + # This +sanitize+ helper will html encode all tags and strip all attributes that aren't specifically allowed. # It also strips href/src tags with invalid protocols, like javascript: especially. It does its best to counter any # tricks that hackers may use, like throwing in unicode/ascii/hex values to get past the javascript: filters. Check out # the extensive test suite. @@ -18,7 +18,7 @@ module ActionView # <%= sanitize @article.body %> # # You can add or remove tags/attributes if you want to customize it a bit. See ActionView::Base for full docs on the - # available options. You can add tags/attributes for single uses of #sanitize by passing either the :attributes or :tags options: + # available options. You can add tags/attributes for single uses of +sanitize+ by passing either the <tt>:attributes</tt> or <tt>:tags</tt> options: # # Normal Use # diff --git a/actionpack/lib/action_view/helpers/scriptaculous_helper.rb b/actionpack/lib/action_view/helpers/scriptaculous_helper.rb index 60e285b722..12b4cfd3f8 100644 --- a/actionpack/lib/action_view/helpers/scriptaculous_helper.rb +++ b/actionpack/lib/action_view/helpers/scriptaculous_helper.rb @@ -35,8 +35,8 @@ module ActionView # This would fade the element that was dropped on the drop receiving # element. # - # For toggling visual effects, you can use :toggle_appear, :toggle_slide, and - # :toggle_blind which will alternate between appear/fade, slidedown/slideup, and + # For toggling visual effects, you can use <tt>:toggle_appear</tt>, <tt>:toggle_slide</tt>, and + # <tt>:toggle_blind</tt> which will alternate between appear/fade, slidedown/slideup, and # blinddown/blindup respectively. # # You can change the behaviour with various options, see diff --git a/actionpack/lib/action_view/helpers/url_helper.rb b/actionpack/lib/action_view/helpers/url_helper.rb index 4a951f2c88..6d27494213 100644 --- a/actionpack/lib/action_view/helpers/url_helper.rb +++ b/actionpack/lib/action_view/helpers/url_helper.rb @@ -16,7 +16,7 @@ module ActionView # instead of the fully qualified URL like http://example.com/controller/action. # # When called from a view, url_for returns an HTML escaped url. If you - # need an unescaped url, pass :escape => false in the +options+. + # need an unescaped url, pass <tt>:escape => false</tt> in the +options+. # # ==== Options # * <tt>:anchor</tt> -- specifies the anchor name to be appended to the path. @@ -25,8 +25,8 @@ module ActionView # is currently not recommended since it breaks caching. # * <tt>:host</tt> -- overrides the default (current) host if provided # * <tt>:protocol</tt> -- overrides the default (current) protocol if provided - # * <tt>:user</tt> -- Inline HTTP authentication (only plucked out if :password is also present) - # * <tt>:password</tt> -- Inline HTTP authentication (only plucked out if :user is also present) + # * <tt>:user</tt> -- Inline HTTP authentication (only plucked out if <tt>:password</tt> is also present) + # * <tt>:password</tt> -- Inline HTTP authentication (only plucked out if <tt>:user</tt> is also present) # * <tt>:escape</tt> -- Determines whether the returned URL will be HTML escaped or not (<tt>true</tt> by default) # # ==== Relying on named routes @@ -102,21 +102,21 @@ module ActionView # create an HTML form and immediately submit the form for processing using # the HTTP verb specified. Useful for having links perform a POST operation # in dangerous actions like deleting a record (which search bots can follow - # while spidering your site). Supported verbs are :post, :delete and :put. + # while spidering your site). Supported verbs are <tt>:post</tt>, <tt>:delete</tt> and <tt>:put</tt>. # Note that if the user has JavaScript disabled, the request will fall back # to using GET. If you are relying on the POST behavior, you should check # for it in your controller's action by using the request object's methods - # for post?, delete? or put?. + # for <tt>post?</tt>, <tt>delete?</tt> or <tt>put?</tt>. # * The +html_options+ will accept a hash of html attributes for the link tag. # # Note that if the user has JavaScript disabled, the request will fall back - # to using GET. If :href=>'#' is used and the user has JavaScript disabled + # to using GET. If <tt>:href => '#'</tt> is used and the user has JavaScript disabled # clicking the link will have no effect. If you are relying on the POST # behavior, your should check for it in your controller's action by using the - # request object's methods for post?, delete? or put?. + # request object's methods for <tt>post?</tt>, <tt>delete?</tt> or <tt>put?</tt>. # # You can mix and match the +html_options+ with the exception of - # :popup and :method which will raise an ActionView::ActionViewError + # <tt>:popup</tt> and <tt>:method</tt> which will raise an ActionView::ActionViewError # exception. # # ==== Examples |