padrino-helpers 0.10.2 → 0.10.3

data/lib/padrino-helpers/form_helpers.rb

@@ -4,11 +4,26 @@ module Padrino
       ##
       # Constructs a form for object using given or default form_builder
       #
-      # ==== Examples
-      #
+      # @param [Object] object
+      #   The object for which the form is being built.
+      # @param [String] url
+      #   The url this form will submit to.
+      # @param [Hash] settings
+      #   The settings associated with this form. Accepts html options.
+      # @option settings [String] :builder ("StandardFormBuilder")
+      #   The FormBuilder class to use such as StandardFormBuilder.
+      # @param [Proc] block
+      #   The fields and content inside this form.
+      #
+      # @yield [AbstractFormBuilder] The form builder used to compose fields.
+      #
+      # @return [String] The html object-backed form with the specified options and input fields.
+      #
+      # @example
       #   form_for :user, '/register' do |f| ... end
       #   form_for @user, '/register', :id => 'register' do |f| ... end
       #
+      # @api public
       def form_for(object, url, settings={}, &block)
         form_html = capture_html(builder_instance(object, settings), &block)
         form_tag(url, settings) { form_html }
@@ -18,11 +33,20 @@ module Padrino
       # Constructs form fields for an object using given or default form_builder
       # Used within an existing form to allow alternate objects within one form
       #
-      # ==== Examples
+      # @param [Object] object
+      #   The object for which the fields are being built.
+      # @param [Hash] settings
+      #   The settings associated with these fields. Accepts html options.
+      # @param [Proc] block
+      #   The content inside this set of fields.
+      #
+      # @return [String] The html fields with the specified options.
       #
+      # @example
       #   fields_for @user.assignment do |assignment| ... end
       #   fields_for :assignment do |assigment| ... end
       #
+      # @api public
       def fields_for(object, settings={}, &block)
         instance = builder_instance(object, settings)
         fields_html = capture_html(instance, &block)
@@ -33,10 +57,19 @@ module Padrino
       ##
       # Constructs a form without object based on options
       #
-      # ==== Examples
+      # @param [String] url
+      #   The url this form will submit to.
+      # @param [Hash] options
+      #   The html options associated with this form.
+      # @param [Proc] block
+      #   The fields and content inside this form.
+      #
+      # @return [String] The html form with the specified options and input fields.
       #
-      #   form_tag '/register' do ... end
+      # @example
+      #   form_tag '/register', :class => "registration_form" do ... end
       #
+      # @api public
       def form_tag(url, options={}, &block)
         desired_method = options[:method]
         data_method = options.delete(:method) if options[:method].to_s !~ /get|post/i
@@ -55,11 +88,16 @@ module Padrino
       # Only 'get' and 'post' are allowed within browsers;
       # 'put' and 'delete' are just specified using hidden fields with form action still 'put'.
       #
-      # ==== Examples
+      # @param [String] desired_method
+      #   The method this hidden field represents (i.e put or delete))
       #
+      # @return [String] The hidden field representing the +desired_method+ for the form.
+      #
+      # @example
       #   # Generate: <input name="_method" value="delete" />
       #   hidden_form_method_field('delete')
       #
+      # @api semipublic
       def hidden_form_method_field(desired_method)
         return '' if desired_method.blank? || desired_method.to_s =~ /get|post/i
         hidden_field_tag(:_method, :value => desired_method)
@@ -68,10 +106,21 @@ module Padrino
       ##
       # Constructs a field_set to group fields with given options
       #
-      # ==== Examples
+      # @overload field_set_tag(legend=nil, options={}, &block)
+      #   @param [String] legend  The legend caption for the fieldset
+      #   @param [Hash]   options The html options for the fieldset.
+      #   @param [Proc]   block   The content inside the fieldset.
+      # @overload field_set_tag(options={}, &block)
+      #   @param [Hash]   options The html options for the fieldset.
+      #   @param [Proc]   block   The content inside the fieldset.
+      #
+      # @return [String] The html for the fieldset tag based on given +options+.
       #
-      #   field_set_tag("Office", :class => 'office-set')
+      # @example
+      #   field_set_tag(:class => "office-set") { }
+      #   field_set_tag("Office", :class => 'office-set') { }
       #
+      # @api public
       def field_set_tag(*args, &block)
         options = args.extract_options!
         legend_text = args[0].is_a?(String) ? args.first : nil
@@ -83,30 +132,41 @@ module Padrino
       ##
       # Constructs list html for the errors for a given symbol
       #
-      # ==== Options
-      #
-      # :header_tag:: Used for the header of the error div (default: "h2").
-      # :id:: The id of the error div (default: "errorExplanation").
-      # :class:: The class of the error div (default: "errorExplanation").
-      # :object:: The object (or array of objects) for which to display errors,
-      # if you need to escape the instance variable convention.
-      # :object_name:: The object name to use in the header, or any text that you prefer.
-      # If +:object_name+ is not set, the name of the first object will be used.
-      # :header_message:: 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").
-      # :message:: 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:").
-      #
-      # ==== Examples
-      #
+      # @overload error_messages_for(*objects, options = {})
+      #   @param [Array<Object>]  object   Splat of objects to display errors for.
+      #   @param [Hash]           options  Error message display options.
+      #   @option options [String] :header_tag ("h2")
+      #     Used for the header of the error div
+      #   @option options [String] :id ("errorExplanation")
+      #     The id of the error div.
+      #   @option options [String] :class ("errorExplanation")
+      #     The class of the error div.
+      #   @option options [Array<Object>]  :object
+      #     The object (or array of objects) for which to display errors,
+      #     if you need to escape the instance variable convention.
+      #   @option options [String] :object_name
+      #     The object name to use in the header, or any text that you prefer.
+      #     If +:object_name+ is not set, the name of the first object will be used.
+      #   @option options [String] :header_message ("X errors prohibited this object from being saved")
+      #     The message in the header of the error div.  Pass +nil+ or an empty string
+      #     to avoid the header message altogether.
+      #   @option options [String] :message ("There were problems with the following fields:")
+      #     The explanation message after the header message and before
+      #     the error list.  Pass +nil+ or an empty string to avoid the explanation message
+      #     altogether.
+      #
+      # @return [String] The html section with all errors for the specified +objects+
+      #
+      # @example
       #   error_messages_for :user
       #
+      # @api public
       def error_messages_for(*objects)
         options = objects.extract_options!.symbolize_keys
-        objects = objects.map {|object_name| object_name.is_a?(Symbol) ? instance_variable_get("@#{object_name}") : object_name }.compact
-        count   = objects.inject(0) {|sum, object| sum + object.errors.size }
+        objects = objects.map { |object_name|
+          object_name.is_a?(Symbol) ? instance_variable_get("@#{object_name}") : object_name
+        }.compact
+        count   = objects.inject(0) { |sum, object| sum + object.errors.size }
 
         unless count.zero?
           html = {}
@@ -153,14 +213,20 @@ module Padrino
       ##
       # Returns a string containing the error message attached to the +method+ on the +object+ if one exists.
       #
-      # ==== Options
-      #
-      # :tag::      The tag that enclose your error. (Default 'div')
-      # :prepend::  Text to add before error.
-      # :append::   Text to add after error.
-      #
-      # ==== Examples
-      #
+      # @param [Object] object
+      #   The object to display the error for.
+      # @param [Symbol] field
+      #   The field on the +object+ to display the error for.
+      # @param [Hash] options
+      #   The options to control the error display.
+      # @option options [String] :tag ("div")
+      #   The tag that encloses the error.
+      # @option options [String] :prepend ("")
+      #   The text to prepend before the field error.
+      # @option options [String] :append ("")
+      #   The text to append after the field error.
+      #
+      # @example
       #   # => <span class="error">can't be blank</div>
       #   error_message_on :post, :title
       #   error_message_on @post, :title
@@ -171,6 +237,9 @@ module Padrino
       #   # => <div class="error">This title can't be blank (or it won't work)</div>
       #   error_message_on :post, :title, :prepend => "This title", :append => "(or it won't work)"
       #
+      # @return [String] The html display of an error for a particular +object+ and +field+.
+      #
+      # @api public
       def error_message_on(object, field, options={})
         object = object.is_a?(Symbol) ? instance_variable_get("@#{object}") : object
         error  = object.errors[field] rescue nil
@@ -188,11 +257,22 @@ module Padrino
       ##
       # Constructs a label tag from the given options
       #
-      # ==== Examples
+      # @param [String] name
+      #   The name of the field to label.
+      # @param [Hash] options
+      #   The html options for this label.
+      # @option options :caption
+      #   The caption for this label.
+      # @param [Proc] block
+      #   The content to be inserted into the label.
+      #
+      # @return [String] The html for this label with the given +options+.
       #
+      # @example
       #   label_tag :username, :class => 'long-label'
       #   label_tag :username, :class => 'long-label' do ... end
       #
+      # @api public
       def label_tag(name, options={}, &block)
         options.reverse_merge!(:caption => "#{name.to_s.humanize}: ", :for => name)
         caption_text = options.delete(:caption)
@@ -206,36 +286,48 @@ module Padrino
       end
 
       ##
-      # Constructs a hidden field input from the given options
+      # Constructs a text field input from the given options
       #
-      # ==== Examples
+      # @macro [new] input_field_doc
+      #   @param [String] name
+      #     The name of the input field.
+      #   @param [Hash] options
+      #     The html options for the input field.
       #
-      #   hidden_field_tag :session_key, :value => "__secret__"
+      #   @return [String] The html input field based on the +options+ specified
       #
-      def hidden_field_tag(name, options={})
+      # @example
+      #   text_field_tag :username, :class => 'long'
+      #
+      # @api public
+      def text_field_tag(name, options={})
         options.reverse_merge!(:name => name)
-        input_tag(:hidden, options)
+        input_tag(:text, options)
       end
 
       ##
-      # Constructs a text field input from the given options
+      # Constructs a hidden field input from the given options
       #
-      # ==== Examples
+      # @macro input_field_doc
       #
-      #   text_field_tag :username, :class => 'long'
+      # @example
+      #   hidden_field_tag :session_key, :value => "__secret__"
       #
-      def text_field_tag(name, options={})
+      # @api public
+      def hidden_field_tag(name, options={})
         options.reverse_merge!(:name => name)
-        input_tag(:text, options)
+        input_tag(:hidden, options)
       end
 
       ##
       # Constructs a text area input from the given options
       #
-      # ==== Examples
+      # @macro input_field_doc
       #
+      # @example
       #   text_area_tag :username, :class => 'long', :value => "Demo?"
       #
+      # @api public
       def text_area_tag(name, options={})
         options.reverse_merge!(:name => name, :rows => "", :cols => "")
         content_tag(:textarea, options.delete(:value).to_s, options)
@@ -244,20 +336,63 @@ module Padrino
       ##
       # Constructs a password field input from the given options
       #
-      # ==== Examples
+      # @macro input_field_doc
       #
+      # @example
       #   password_field_tag :password, :class => 'long'
       #
+      # @api public
       def password_field_tag(name, options={})
         options.reverse_merge!(:name => name)
         input_tag(:password, options)
       end
 
       ##
-      # Constructs a select from the given options
+      # Constructs a check_box from the given options
       #
-      # ==== Examples
+      # @macro input_field_doc
+      #
+      # @example
+      #   check_box_tag :remember_me, :value => 'Yes'
       #
+      # @api public
+      def check_box_tag(name, options={})
+        options.reverse_merge!(:name => name, :value => '1')
+        input_tag(:checkbox, options)
+      end
+
+      ##
+      # Constructs a radio_button from the given options
+      #
+      # @macro input_field_doc
+      #
+      # @example
+      #   radio_button_tag :remember_me, :value => 'true'
+      #
+      # @api public
+      def radio_button_tag(name, options={})
+        options.reverse_merge!(:name => name)
+        input_tag(:radio, options)
+      end
+
+      ##
+      # Constructs a file field input from the given options
+      #
+      # @macro input_field_doc
+      #
+      # @example
+      #   file_field_tag :photo, :class => 'long'
+      #
+      # @api public
+      def file_field_tag(name, options={})
+        options.reverse_merge!(:name => name)
+        input_tag(:file, options)
+      end
+
+      ##
+      # Constructs a select from the given options
+      #
+      # @example
       #   options = [['caption', 'value'], ['Green', 'green1'], ['Blue', 'blue1'], ['Black', "black1"]]
       #   options = ['option', 'red', 'yellow' ]
       #   select_tag(:favorite_color, :options => ['red', 'yellow'], :selected => 'green1')
@@ -273,6 +408,28 @@ module Padrino
       #   grouped_options = {'Friends' => ['Yoda',['Obiwan',1]],'Enemies' => ['Palpatine',['Darth Vader',3]]}
       #   select_tag(:color, :grouped_options => [['warm',['red','yellow']],['cool',['blue', 'purple']]])
       #
+      # @param [String] name
+      #   The name of the input field.
+      # @param [Hash] options
+      #   The html options for the input field.
+      # @option options [Array<String, Array>] :options
+      #  Explicit options to display in the select. Can be strings or string tuples.
+      # @option options [Array<Array>] :grouped_options
+      #   List of options for each group in the select. See examples for details.
+      # @option options [Array<Object>] :collection
+      #   Collection of objects used as options in the select.
+      # @option options [Array<Symbol>] :fields
+      #   The attributes used as "label" and "value" for each +collection+ object.
+      # @option options [String] :selected (nil)
+      #   The option value initially selected.
+      # @option options [Boolean] :include_blank (false)
+      #   Include a blank option in the select.
+      # @option options [Boolean] :multiple (false)
+      #   Allow multiple options to be selected at once.
+      #
+      # @return [String] The html input field based on the +options+ specified
+      #
+      # @api public
       def select_tag(name, options={})
         options.reverse_merge!(:name => name)
         collection, fields = options.delete(:collection), options.delete(:fields)
@@ -289,133 +446,122 @@ module Padrino
       end
 
       ##
-      # Constructs a check_box from the given options
-      #
-      # ==== Examples
-      #
-      #   check_box_tag :remember_me, :value => 'Yes'
-      #
-      def check_box_tag(name, options={})
-        options.reverse_merge!(:name => name, :value => '1')
-        input_tag(:checkbox, options)
-      end
-
-      ##
-      # Constructs a radio_button from the given options
-      #
-      # ==== Examples
-      #
-      #   radio_button_tag :remember_me, :value => 'true'
+      # Constructs a button input from the given options
       #
-      def radio_button_tag(name, options={})
-        options.reverse_merge!(:name => name)
-        input_tag(:radio, options)
-      end
-
-      ##
-      # Constructs a file field input from the given options
+      # @param [String] caption
+      #   The caption for the button.
+      # @param [Hash] options
+      #   The html options for the input field.
       #
-      # ==== Examples
+      # @return [String] The html button based on the +options+ specified.
       #
-      #   file_field_tag :photo, :class => 'long'
+      # @example
+      #   button_tag "Cancel", :class => 'clear'
       #
-      def file_field_tag(name, options={})
-        options.reverse_merge!(:name => name)
-        input_tag(:file, options)
+      # @api public
+      def button_tag(caption, options = {})
+        options.reverse_merge!(:value => caption)
+        input_tag(:button, options)
       end
 
       ##
       # Constructs a submit button from the given options
       #
-      # ==== Examples
+      # @param [String] caption
+      #   The caption for the submit button.
+      # @param [Hash] options
+      #   The html options for the input field.
       #
+      # @return [String] The html submit button based on the +options+ specified.
+      #
+      # @example
       #   submit_tag "Create", :class => 'success'
       #
+      # @api public
       def submit_tag(caption="Submit", options={})
         options.reverse_merge!(:value => caption)
         input_tag(:submit, options)
       end
 
-      ##
-      # Constructs a button input from the given options
-      #
-      # ==== Examples
-      #
-      #   button_tag "Cancel", :class => 'clear'
-      #
-      def button_tag(caption, options = {})
-        options.reverse_merge!(:value => caption)
-        input_tag(:button, options)
-      end
-
       # Constructs a submit button from the given options
       #
-      # ==== Examples
+      # @param [String] source
+      #   The source image path for the button.
+      # @param [Hash] options
+      #   The html options for the input field.
+      #
+      # @return [String] The html image button based on the +options+ specified.
       #
+      # @example
       #   submit_tag "Create", :class => 'success'
       #
+      # @api public
       def image_submit_tag(source, options={})
         options.reverse_merge!(:src => image_path(source))
         input_tag(:image, options)
       end
 
-      ##
-      # Returns an array of option items for a select field based on the given collection
-      # fields is an array containing the fields to display from each item in the collection
-      #
-      def options_from_collection(collection, fields)
-        collection.map { |item| [ item.send(fields.first), item.send(fields.last) ] }
-      end
+      protected
 
-      #
-      # Returns the options tags for a select based on the given option items
-      #
-      def options_for_select(option_items, selected_value=nil)
-        return '' if option_items.blank?
-        option_items.map do |caption, value|
-          value ||= caption
-          content_tag(:option, caption, :value => value, :selected => option_is_selected?(value, caption, selected_value))
+        ##
+        # Returns an array of option items for a select field based on the given collection
+        # fields is an array containing the fields to display from each item in the collection
+        #
+        def options_from_collection(collection, fields)
+          collection.map { |item| [ item.send(fields.first), item.send(fields.last) ] }
         end
-      end
 
-      #
-      # Returns the optgroups with options tags for a select based on the given :grouped_options items
-      #
-      def grouped_options_for_select(collection,selected=nil,prompt=false)
-        if collection.is_a?(Hash)
-          collection.map do |key, value|
-            content_tag :optgroup, :label => key do
-              options_for_select(value, selected)
-            end
+        #
+        # Returns the options tags for a select based on the given option items
+        #
+        def options_for_select(option_items, selected_value=nil)
+          return '' if option_items.blank?
+          option_items.map do |caption, value|
+            value ||= caption
+            content_tag(:option, caption, :value => value, :selected => option_is_selected?(value, caption, selected_value))
           end
-        elsif collection.is_a?(Array)
-          collection.map do |optgroup|
-            content_tag :optgroup, :label => optgroup.first do
-              options_for_select(optgroup.last, selected)
+        end
+
+        #
+        # Returns the optgroups with options tags for a select based on the given :grouped_options items
+        #
+        def grouped_options_for_select(collection, selected=nil, prompt=false)
+          if collection.is_a?(Hash)
+            collection.map do |key, value|
+              content_tag :optgroup, :label => key do
+                options_for_select(value, selected)
+              end
+            end
+          elsif collection.is_a?(Array)
+            collection.map do |optgroup|
+              content_tag :optgroup, :label => optgroup.first do
+                options_for_select(optgroup.last, selected)
+              end
             end
           end
         end
-      end
 
-      #
-      # Returns the blank option serving as a prompt if passed
-      #
-      def blank_option(prompt)
-        return unless prompt
-        case prompt
-          when String then content_tag(:option, prompt,       :value => '')
-          when Array  then content_tag(:option, prompt.first, :value => prompt.last)
-          else             content_tag(:option, '',           :value => '')
+        #
+        # Returns the blank option serving as a prompt if passed
+        #
+        def blank_option(prompt)
+          return unless prompt
+          case prompt
+            when String then content_tag(:option, prompt,       :value => '')
+            when Array  then content_tag(:option, prompt.first, :value => prompt.last)
+            else             content_tag(:option, '',           :value => '')
+          end
         end
-      end
 
       private
         ##
         # Returns the FormBuilder class to use based on all available setting sources
         # If explicitly defined, returns that, otherwise returns defaults.
         #
+        # @example
         #   configured_form_builder_class(nil) => StandardFormBuilder
         #
+        # @api private
         def configured_form_builder_class(explicit_builder=nil)
           default_builder    = self.respond_to?(:settings) && self.settings.default_builder
           configured_builder = explicit_builder || default_builder || 'StandardFormBuilder'
@@ -426,8 +572,10 @@ module Padrino
         ##
         # Returns an initialized builder instance for the given object and settings
         #
+        # @example
         #   builder_instance(@account, :nested => { ... }) => <FormBuilder>
         #
+        # @api private
         def builder_instance(object, settings={})
            builder_class = configured_form_builder_class(settings.delete(:builder))
            builder_class.new(self, object, settings)
@@ -436,6 +584,11 @@ module Padrino
         ##
         # Returns whether the option should be selected or not
         #
+        # @example
+        #   option_is_selected?("red", "Red", ["red", "blue"])   => true
+        #   option_is_selected?("red", "Red", ["green", "blue"]) => false
+        #
+        # @api private
         def option_is_selected?(value, caption, selected_values)
           Array(selected_values).any? do |selected|
             [value.to_s, caption.to_s].include?(selected.to_s)