padrino-helpers 0.11.3 → 0.11.4

data/lib/padrino-helpers/form_builder/abstract_form_builder.rb

@@ -1,7 +1,7 @@
 module Padrino
   module Helpers
-    module FormBuilder # @private
-      class AbstractFormBuilder # @private
+    module FormBuilder
+      class AbstractFormBuilder
         attr_accessor :template, :object, :multipart
 
         def initialize(template, object, options={})
@@ -12,37 +12,32 @@ module Padrino
           raise "FormBuilder object must not be a nil value. If there's no object, use a symbol instead! (i.e :user)" unless object
         end
 
-        # f.error_messages
         def error_messages(*params)
           params.unshift object
           @template.error_messages_for(*params)
         end
 
-        # f.error_message_on(field)
         def error_message_on(field, options={})
           @template.error_message_on(object, field, options)
         end
 
-        # f.label :username, :caption => "Nickname"
         def label(field, options={}, &block)
           options.reverse_merge!(:caption => "#{field_human_name(field)}: ")
           @template.label_tag(field_id(field), options, &block)
         end
 
-        # f.hidden_field :session_id, :value => "45"
         def hidden_field(field, options={})
           options.reverse_merge!(:value => field_value(field), :id => field_id(field))
           @template.hidden_field_tag field_name(field), options
         end
 
-        # f.text_field :username, :value => "(blank)", :id => 'username'
         def text_field(field, options={})
           options.reverse_merge!(:value => field_value(field), :id => field_id(field))
           options.merge!(:class => field_error(field, options))
           @template.text_field_tag field_name(field), options
         end
 
-       def number_field(field, options={})
+        def number_field(field, options={})
           options.reverse_merge!(:value => field_value(field), :id => field_id(field))
           options.merge!(:class => field_error(field, options))
           @template.number_field_tag field_name(field), options
@@ -73,35 +68,28 @@ module Padrino
           @template.url_field_tag field_name(field), options
         end
 
-        # f.text_area :summary, :value => "(enter summary)", :id => 'summary'
         def text_area(field, options={})
           options.reverse_merge!(:value => field_value(field), :id => field_id(field))
           options.merge!(:class => field_error(field, options))
           @template.text_area_tag field_name(field), options
         end
 
-        # f.password_field :password, :id => 'password'
         def password_field(field, options={})
           options.reverse_merge!(:value => field_value(field), :id => field_id(field))
           options.merge!(:class => field_error(field, options))
           @template.password_field_tag field_name(field), options
         end
 
-        # f.select :color, :options => ['red', 'green'], :include_blank => true
-        # f.select :color, :collection => @colors, :fields => [:name, :id]
         def select(field, options={})
           options.reverse_merge!(:id => field_id(field), :selected => field_value(field))
           options.merge!(:class => field_error(field, options))
           @template.select_tag field_name(field), options
         end
 
-        # f.check_box_group :color, :options => ['red', 'green', 'blue'], :selected => ['red', 'blue']
-        # f.check_box_group :color, :collection => @colors, :fields => [:name, :id]
         def check_box_group(field, options={})
           selected_values = Array(options[:selected] || field_value(field))
           if options[:collection]
             fields = options[:fields] || [:name, :id]
-            # don't use map!, it will break some orms
             selected_values = selected_values.map{ |v| (v.respond_to?(fields[0]) ? v.send(fields[1]) : v).to_s }
           end
           labeled_group( field, options ) do |variant|
@@ -109,8 +97,6 @@ module Padrino
           end
         end
 
-        # f.radio_button_group :color, :options => ['red', 'green']
-        # f.radio_button_group :color, :collection => @colors, :fields => [:name, :id], :selected => @colors.first
         def radio_button_group(field, options={})
           fields = options[:fields] || [:name, :id]
           selected_value = options[:selected] || field_value(field)
@@ -120,7 +106,6 @@ module Padrino
           end
         end
 
-        # f.check_box :remember_me, :value => 'true', :uncheck_value => '0'
         def check_box(field, options={})
           html = ActiveSupport::SafeBuffer.new
           unchecked_value = options.delete(:uncheck_value) || '0'
@@ -130,14 +115,12 @@ module Padrino
           html << @template.check_box_tag(field_name(field), options)
         end
 
-        # f.radio_button :gender, :value => 'male'
         def radio_button(field, options={})
           options.reverse_merge!(:id => field_id(field, options[:value]))
           options.reverse_merge!(:checked => true) if values_matches_field?(field, options[:value])
           @template.radio_button_tag field_name(field), options
         end
 
-        # f.file_field :photo, :class => 'avatar'
         def file_field(field, options={})
           self.multipart = true
           options.reverse_merge!(:id => field_id(field))
@@ -145,19 +128,18 @@ module Padrino
           @template.file_field_tag field_name(field), options
         end
 
-        # f.submit "Update", :class => 'large'
         def submit(*args)
           options = args[-1].is_a?(Hash) ? args.pop : {}
           caption = args.length >= 1 ? args.shift : "Submit"
           @template.submit_tag caption, options
         end
 
-        # f.image_submit "buttons/submit.png", :class => 'large'
         def image_submit(source, options={})
           @template.image_submit_tag source, options
         end
 
-        # Supports nested fields for a child model within a form
+        ##
+        # Supports nested fields for a child model within a form.
         # f.fields_for :addresses
         # f.fields_for :addresses, address
         # f.fields_for :addresses, @addresses
@@ -166,7 +148,7 @@ module Padrino
           include_index = default_collection.respond_to?(:each)
           nested_options = { :parent => self, :association => child_association }
           nested_objects = instance_or_collection ? Array(instance_or_collection) : Array(default_collection)
-          result = nested_objects.each_with_index.map do |child_instance, index|
+          nested_objects.each_with_index.map do |child_instance, index|
             nested_options[:index] = include_index ? index : nil
             @template.fields_for(child_instance,  { :nested => nested_options }, &block)
           end.join("\n").html_safe
@@ -177,112 +159,133 @@ module Padrino
         end
 
         protected
-          # Returns the known field types for a formbuilder
-          def self.field_types
-            [:hidden_field, :text_field, :text_area, :password_field, :file_field, :radio_button, :check_box, :select]
-          end
+        # Returns the known field types for a Formbuilder.
+        def self.field_types
+          [:hidden_field, :text_field, :text_area, :password_field, :file_field, :radio_button, :check_box, :select]
+        end
 
-          # Returns true if the value matches the value in the field
-          # field_has_value?(:gender, 'male')
-          def values_matches_field?(field, value)
-            value.present? && (field_value(field).to_s == value.to_s || field_value(field).to_s == 'true')
-          end
+        ##
+        # Returns true if the value matches the value in the field.
+        # field_has_value?(:gender, 'male')
+        def values_matches_field?(field, value)
+          value.present? && (field_value(field).to_s == value.to_s || field_value(field).to_s == 'true')
+        end
 
-          # Add a :invalid css class to the field if it contain an error
-          def field_error(field, options)
-            error = @object.errors[field] rescue nil
-            error.blank? ? options[:class] : [options[:class], :invalid].flatten.compact.join(" ")
-          end
+        ##
+        # Add a :invalid css class to the field if it contain an error.
+        #
+        def field_error(field, options)
+          error = @object.errors[field] rescue nil
+          error.blank? ? options[:class] : [options[:class], :invalid].flatten.compact.join(" ")
+        end
 
-          # Returns the human name of the field. Look that use builtin I18n.
-          def field_human_name(field)
-            I18n.translate("#{object_model_name}.attributes.#{field}", :count => 1, :default => field.to_s.humanize, :scope => :models)
-          end
+        ##
+        # Returns the human name of the field. Look that use builtin I18n.
+        #
+        def field_human_name(field)
+          I18n.translate("#{object_model_name}.attributes.#{field}", :count => 1, :default => field.to_s.humanize, :scope => :models)
+        end
 
-          # Returns the name for the given field
-          # field_name(:username) => "user[username]"
-          # field_name(:number) => "user[telephone_attributes][number]"
-          # field_name(:street) => "user[addresses_attributes][0][street]"
-          def field_name(field=nil)
-            result = field_result
-            result << field_name_fragment if nested_form?
-            result << "[#{field}]" unless field.blank?
-            result.flatten.join
-          end
+        ##
+        # Returns the name for the given field.
+        # field_name(:username) => "user[username]"
+        # field_name(:number) => "user[telephone_attributes][number]"
+        # field_name(:street) => "user[addresses_attributes][0][street]"
+        def field_name(field=nil)
+          result = field_result
+          result << field_name_fragment if nested_form?
+          result << "[#{field}]" unless field.blank?
+          result.flatten.join
+        end
 
-          # Returns the id for the given field
-          # field_id(:username) => "user_username"
-          # field_id(:gender, :male) => "user_gender_male"
-          # field_name(:number) => "user_telephone_attributes_number"
-          # field_name(:street) => "user_addresses_attributes_0_street"
-          def field_id(field=nil, value=nil)
-            result = []
-            result << "#{@options[:namespace]}_" if @options[:namespace] && root_form?
-            result << field_result
-            result << field_id_fragment if nested_form?
-            result << "_#{field}" unless field.blank?
-            result << "_#{value}" unless value.blank?
-            result.flatten.join
-          end
+        ##
+        # Returns the id for the given field.
+        # field_id(:username) => "user_username"
+        # field_id(:gender, :male) => "user_gender_male"
+        # field_name(:number) => "user_telephone_attributes_number"
+        # field_name(:street) => "user_addresses_attributes_0_street"
+        def field_id(field=nil, value=nil)
+          result = []
+          result << "#{@options[:namespace]}_" if @options[:namespace] && root_form?
+          result << field_result
+          result << field_id_fragment if nested_form?
+          result << "_#{field}" unless field.blank?
+          result << "_#{value}" unless value.blank?
+          result.flatten.join
+        end
 
-          # Returns the child object if it exists
-          def nested_object_id
-            nested_form? && object.respond_to?(:new_record?) && !object.new_record? && object.id
-          end
+        ##
+        # Returns the child object if it exists.
+        #
+        def nested_object_id
+          nested_form? && object.respond_to?(:new_record?) && !object.new_record? && object.id
+        end
 
-          # Returns true if this form object is nested in a parent form
-          def nested_form?
-            @options[:nested] && @options[:nested][:parent] && @options[:nested][:parent].respond_to?(:object)
-          end
+        ##
+        # Returns true if this form object is nested in a parent form.
+        #
+        def nested_form?
+          @options[:nested] && @options[:nested][:parent] && @options[:nested][:parent].respond_to?(:object)
+        end
 
-          # Returns the value for the object's field
-          # field_value(:username) => "Joey"
-          def field_value(field)
-            @object && @object.respond_to?(field) ? @object.send(field) : ""
-          end
+        ##
+        # Returns the value for the object's field.
+        #
+        def field_value(field)
+          @object && @object.respond_to?(field) ? @object.send(field) : ""
+        end
 
-          # explicit_object is either a symbol or a record
-          # Returns a new record of the type specified in the object
-          def build_object(object_or_symbol)
-            object_or_symbol.is_a?(Symbol) ? @template.instance_variable_get("@#{object_or_symbol}") || object_class(object_or_symbol).new : object_or_symbol
-          end
+        ##
+        # Returns a new record of the type specified in the object
+        #
+        def build_object(object_or_symbol)
+          object_or_symbol.is_a?(Symbol) ? @template.instance_variable_get("@#{object_or_symbol}") || object_class(object_or_symbol).new : object_or_symbol
+        end
 
-           # Returns the object's models name
-          #   => user_assignment
-          def object_model_name(explicit_object=object)
-            explicit_object.is_a?(Symbol) ? explicit_object : explicit_object.class.to_s.underscore.gsub(/\//, '_')
-          end
+        ##
+        # Returns the object's models name.
+        #
+        def object_model_name(explicit_object=object)
+          explicit_object.is_a?(Symbol) ? explicit_object : explicit_object.class.to_s.underscore.gsub(/\//, '_')
+        end
 
-          # Returns the class type for the given object
-          def object_class(explicit_object)
-            explicit_object.is_a?(Symbol) ? explicit_object.to_s.camelize.constantize : explicit_object.class
-          end
+        ##
+        # Returns the class type for the given object.
+        #
+        def object_class(explicit_object)
+          explicit_object.is_a?(Symbol) ? explicit_object.to_s.camelize.constantize : explicit_object.class
+        end
 
-          # Returns true if this form is the top-level (not nested)
-          def root_form?
-            !nested_form?
-          end
+        ##
+        # Returns true if this form is the top-level (not nested).
+        #
+        def root_form?
+          !nested_form?
+        end
 
-          # Builds a group of labels for radios or checkboxes
-          def labeled_group(field, options={})
-            options.reverse_merge!(:id => field_id(field), :selected => field_value(field))
-            options.merge!(:class => field_error(field, options))
-            variants = case
-            when options[:options]
-              options[:options].map{ |caption, value| [caption.to_s, (value||caption).to_s] }
-            when options[:collection]
-              fields = options[:fields] || [:name, :id]
-              options[:collection].map{ |variant| [variant.send(fields.first).to_s, variant.send(fields.last).to_s] }
-            else
-              []
-            end
-            variants.inject(''.html_safe) do |html, variant|
-              variant[2] = "#{field_id(field)}_#{variant[1]}"
-              html << @template.label_tag("#{field_name(field)}[]", :for => variant[2], :caption => "#{yield(variant)} #{variant[0]}")
-            end
+        ##
+        # Builds a group of labels for radios or checkboxes.
+        #
+        def labeled_group(field, options={})
+          options.reverse_merge!(:id => field_id(field), :selected => field_value(field))
+          options.merge!(:class => field_error(field, options))
+          variants = case
+          when options[:options]
+            options[:options].map{ |caption, value| [caption.to_s, (value||caption).to_s] }
+          when options[:collection]
+            fields = options[:fields] || [:name, :id]
+            options[:collection].map{ |variant| [variant.send(fields.first).to_s, variant.send(fields.last).to_s] }
+          else
+            []
+          end
+          variants.inject(''.html_safe) do |html, variant|
+            variant[2] = "#{field_id(field)}_#{variant[1]}"
+            html << @template.label_tag("#{field_name(field)}[]", :for => variant[2], :caption => "#{yield(variant)} #{variant[0]}")
           end
+        end
 
         private
+
         def field_result
           result = []
           result << object_model_name if root_form?
@@ -308,7 +311,7 @@ module Padrino
             :attributes_name => "#{@options[:nested][:association]}_attributes"
           }
         end
-      end # AbstractFormBuilder
-    end # FormBuilder
-  end # Helpers
-end # Padrino
+      end
+    end
+  end
+end

data/lib/padrino-helpers/form_builder/standard_form_builder.rb

@@ -2,9 +2,8 @@ require File.expand_path(File.dirname(__FILE__) + '/abstract_form_builder') unle
 
 module Padrino
   module Helpers
-    module FormBuilder # @private
-      class StandardFormBuilder < AbstractFormBuilder # @private
-
+    module FormBuilder
+      class StandardFormBuilder < AbstractFormBuilder
         ##
         # StandardFormBuilder
         #
@@ -26,18 +25,16 @@ module Padrino
           EOF
         end
 
-        # submit_block("Update")
         def submit_block(caption, options={})
           submit_html = self.submit(caption, options)
           @template.content_tag(:p, submit_html)
         end
 
-        # image_submit_block("submit.png")
         def image_submit_block(source, options={})
           submit_html = self.image_submit(source, options)
           @template.content_tag(:p, submit_html)
         end
-      end # StandardFormBuilder
-    end # FormBuilder
-  end # Helpers
-end # Padrino
+      end
+    end
+  end
+end

data/lib/padrino-helpers/form_helpers.rb

@@ -7,16 +7,16 @@ module Padrino
     #
     module FormHelpers
       ##
-      # Constructs a form for object using given or default form_builder
+      # Constructs a form for object using given or default form_builder.
       #
       # @param [Object] object
       #   The object for which the form is being built.
-      # @param [String] url
+      # @param [String] URL
       #   The url this form will submit to.
       # @param [Hash] settings
       #   The settings associated with this form.
       #   Accepts a :namespace option that will be prepended to the id attributes of the form's elements.
-      #   Also accepts html options.
+      #   Also accepts HTML options.
       # @option settings [String] :builder ("StandardFormBuilder")
       #   The FormBuilder class to use such as StandardFormBuilder.
       # @param [Proc] block
@@ -30,7 +30,6 @@ module Padrino
       #   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)
         instance = builder_instance(object, settings)
         html = capture_html(instance, &block)
@@ -40,13 +39,13 @@ module Padrino
       end
 
       ##
-      # Constructs form fields for an object using given or default form_builder
-      # Used within an existing form to allow alternate objects within one form
+      # Constructs form fields for an object using given or default form_builder.
+      # Used within an existing form to allow alternate objects within one form.
       #
       # @param [Object] object
       #   The object for which the fields are being built.
       # @param [Hash] settings
-      #   The settings associated with these fields. Accepts html options.
+      #   The settings associated with these fields. Accepts HTML options.
       # @param [Proc] block
       #   The content inside this set of fields.
       #
@@ -56,7 +55,6 @@ module Padrino
       #   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)
@@ -65,21 +63,20 @@ module Padrino
       end
 
       ##
-      # Constructs a form without object based on options
+      # Constructs a form without object based on options.
       #
       # @param [String] url
-      #   The url this form will submit to.
+      #   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.
+      # @return [String] The HTML form with the specified options and input fields.
       #
       # @example
       #   form_tag '/register', :class => "registration_form" do ... end
       #
-      # @api public
       def form_tag(url, options={}, &block)
         desired_method = options[:method].to_s
         options.delete(:method) unless desired_method =~ /get|post/i
@@ -99,12 +96,12 @@ module Padrino
       end
 
       ##
-      # Returns the hidden method field for 'put' and 'delete' forms
+      # Returns the hidden method field for 'put' and 'delete' forms.
       # Only 'get' and 'post' are allowed within browsers;
       # 'put' and 'delete' are just specified using hidden fields with form action still 'put'.
       #
       # @param [String] desired_method
-      #   The method this hidden field represents (i.e put or delete))
+      #   The method this hidden field represents (i.e put or delete).
       #
       # @return [String] The hidden field representing the +desired_method+ for the form.
       #
@@ -112,14 +109,13 @@ module Padrino
       #   # Generate: <input name="_method" value="delete" />
       #   hidden_form_method_field('delete')
       #
-      # @api semipublic
       def hidden_form_method_field(desired_method)
         return ActiveSupport::SafeBuffer.new if desired_method.blank? || desired_method.to_s =~ /get|post/i
         hidden_field_tag(:_method, :value => desired_method)
       end
 
       ##
-      # Constructs a field_set to group fields with given options
+      # Constructs a field_set to group fields with given options.
       #
       # @overload field_set_tag(legend=nil, options={}, &block)
       #   @param [String] legend  The legend caption for the fieldset
@@ -135,7 +131,6 @@ module Padrino
       #   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
@@ -145,13 +140,13 @@ module Padrino
       end
 
       ##
-      # Constructs list html for the errors for a given symbol
+      # Constructs list HTML for the errors for a given symbol.
       #
       # @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
+      #     Used for the header of the error div.
       #   @option options [String] :id ("field-errors")
       #     The id of the error div.
       #   @option options [String] :class ("field-errors")
@@ -163,7 +158,7 @@ module Padrino
       #     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
+      #     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
@@ -175,7 +170,6 @@ module Padrino
       # @example
       #   error_messages_for :user
       #
-      # @api public
       def error_messages_for(*objects)
         options = objects.extract_options!.symbolize_keys
         objects = objects.map { |object_name|
@@ -194,19 +188,19 @@ module Padrino
             end
           end
 
-          options[:object_name] ||= objects.first.class
+          options[:object_name] ||= objects.first.class.to_s.underscore.gsub(/\//, ' ')
 
           I18n.with_options :locale => options[:locale], :scope => [:models, :errors, :template] do |locale|
             header_message = if options.include?(:header_message)
               options[:header_message]
             else
-              object_name = options[:object_name].to_s.underscore.gsub(/\//, ' ')
+              object_name = options[:object_name]
               object_name = I18n.t(:name, :default => object_name.humanize, :scope => [:models, object_name], :count => 1)
               locale.t :header, :count => count, :model => object_name
             end
             message = options.include?(:message) ? options[:message] : locale.t(:body)
             error_messages = objects.map { |object|
-              object_name = options[:object_name].to_s.underscore.gsub(/\//, ' ')
+              object_name = options[:object_name]
               object.errors.map { |f, msg|
                 field = I18n.t(f, :default => f.to_s.humanize, :scope => [:models, object_name, :attributes])
                 content_tag(:li, "%s %s" % [field, msg])
@@ -226,7 +220,8 @@ module Padrino
       end
 
       ##
-      # Returns a string containing the error message attached to the +method+ on the +object+ if one exists.
+      # Returns a string containing the error message attached to the
+      # +method+ on the +object+ if one exists.
       #
       # @param [Object] object
       #   The object to display the error for.
@@ -262,7 +257,7 @@ module Padrino
           I18n.t("ohm.errors.messages.#{error[0]}", :default => error[0].to_s)
         else
           # Array(error).first is necessary because some ORMs
-          # give us an array others directly a value
+          # give us an array others directly a value.
           Array(error)[0]
         end
 
@@ -277,7 +272,7 @@ module Padrino
       end
 
       ##
-      # Constructs a label tag from the given options
+      # Constructs a label tag from the given options.
       #
       # @param [String] name
       #   The name of the field to label.
@@ -294,7 +289,6 @@ module Padrino
       #   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).html_safe
@@ -309,7 +303,7 @@ module Padrino
       end
 
       ##
-      # Creates a text field input with the given name and options
+      # Creates a text field input with the given name and options.
       #
       # @macro [new] text_field
       #   @param [Symbol] name
@@ -338,22 +332,22 @@ module Padrino
       #   @option options [Boolean] :spellcheck
       #     Specifies whether or not the field should have it's spelling and grammar checked for errors.
       #   @option options [Boolean] :draggable
-      #     Specifies whether or not the field is draggable. (true, false, :auto)
+      #     Specifies whether or not the field is draggable. (true, false, :auto).
       #   @option options [String] :pattern
       #     Specifies the regular expression pattern that the field's value is checked against.
       #   @option options [Symbol] :autocomplete
-      #     Specifies whether or not the field should have autocomplete enabled. (:on, :off)
+      #     Specifies whether or not the field should have autocomplete enabled. (:on, :off).
       #   @option options [Boolean] :autofocus
       #     Specifies whether or not the field should automatically get focus when the page loads.
       #   @option options [Boolean] :required
-      #     Specifies whether or not the field is required to be completeled before the form is submitted.
+      #     Specifies whether or not the field is required to be completed before the form is submitted.
       #   @option options [Boolean] :readonly
       #     Specifies whether or not the field is read only.
       #   @option options [Boolean] :disabled
       #     Specifies whether or not the field is disabled.
       #
       #   @return [String]
-      #     Generated HTML with specified +options+
+      #     Generated HTML with specified +options+.
       #
       # @example
       #   text_field_tag :first_name, :maxlength => 40, :required => true
@@ -365,13 +359,12 @@ module Padrino
       #   text_field_tag :username, :placeholder => 'Your Username'
       #   # => <input name="username" placeholder="Your Username" type="text" />
       #
-      # @api public
       def text_field_tag(name, options={})
         input_tag(:text, options.reverse_merge!(:name => name))
       end
 
       ##
-      # Creates a number field input with the given name and options
+      # Creates a number field input with the given name and options.
       #
       # @macro [new] number_field
       #   @param [Symbol] name
@@ -400,11 +393,11 @@ module Padrino
       #   @option options [Boolean] :spellcheck
       #     Specifies whether or not the field should have it's spelling and grammar checked for errors.
       #   @option options [Boolean] :draggable
-      #     Specifies whether or not the field is draggable. (true, false, :auto)
+      #     Specifies whether or not the field is draggable. (true, false, :auto).
       #   @option options [String] :pattern
       #     Specifies the regular expression pattern that the field's value is checked against.
       #   @option options [Symbol] :autocomplete
-      #     Specifies whether or not the field should have autocomplete enabled. (:on, :off)
+      #     Specifies whether or not the field should have autocomplete enabled. (:on, :off).
       #   @option options [Boolean] :autofocus
       #     Specifies whether or not the field should automatically get focus when the page loads.
       #   @option options [Boolean] :required
@@ -415,11 +408,11 @@ module Padrino
       #     Specifies whether or not the field is disabled.
       #
       #   @return [String]
-      #     Generated HTML with specified +options+
+      #     Generated HTML with specified +options+.
       #
       # @example
-      #   number_field_tag :quanity, :class => 'numeric'
-      #   # => <input name="quanity" class="numeric" type="number" />
+      #   number_field_tag :quantity, :class => 'numeric'
+      #   # => <input name="quantity" class="numeric" type="number" />
       #
       #   number_field_tag :zip_code, :pattern => /[0-9]{5}/
       #   # => <input name="zip_code" pattern="[0-9]{5}" type="number" />
@@ -430,13 +423,12 @@ module Padrino
       #   number_field_tag :age, :min => 18, :max => 120, :step => 1
       #   # => <input name="age" min="18" max="120" step="1" type="number" />
       #
-      # @api public
       def number_field_tag(name, options={})
         input_tag(:number, options.reverse_merge(:name => name))
       end
 
       ##
-      # Creates a telephone field input with the given name and options
+      # Creates a telephone field input with the given name and options.
       #
       # @macro text_field
       #
@@ -452,14 +444,13 @@ module Padrino
       #  # => <input name="work_phone" tabindex="2" type="tel" />
       #  # => <input name="home_phone" tabindex="3" type="tel" />
       #
-      # @api public
       def telephone_field_tag(name, options={})
         input_tag(:tel, options.reverse_merge(:name => name))
       end
       alias_method :phone_field_tag, :telephone_field_tag
 
       ##
-      # Creates an email field input with the given name and options
+      # Creates an email field input with the given name and options.
       #
       # @macro text_field
       #
@@ -470,13 +461,12 @@ module Padrino
       #   email_field_tag :email, :value => 'padrinorb@gmail.com', :readonly => true
       #   # => <input name="email" value="padrinorb@gmail.com" readonly type="email" />
       #
-      # @api public
       def email_field_tag(name, options={})
         input_tag(:email, options.reverse_merge(:name => name))
       end
 
       ##
-      # Creates a search field input with the given name and options
+      # Creates a search field input with the given name and options.
       #
       # @macro text_field
       #
@@ -493,13 +483,12 @@ module Padrino
       #  search_field_tag :search, :autofocus => true
       #  # => <input name="search" autofocus type="search" />
       #
-      # @api public
       def search_field_tag(name, options={})
         input_tag(:search, options.reverse_merge(:name => name))
       end
 
       ##
-      # Creates a url field input with the given name and options
+      # Creates a URL field input with the given name and options.
       #
       # @macro text_field
       #
@@ -510,43 +499,34 @@ module Padrino
       #  url_field_tag :home_page, :class => 'string url'
       #  <input name="home_page" class="string url", type="url" />
       #
-      # @api public
       def url_field_tag(name, options={})
         input_tag(:url, options.reverse_merge(:name => name))
       end
 
       ##
-      # Constructs a hidden field input from the given options
-      #
-      # @macro text_field
+      # Constructs a hidden field input from the given options.
       #
       # @example
       #   hidden_field_tag :session_key, :value => "__secret__"
       #
-      # @api public
       def hidden_field_tag(name, options={})
         options.reverse_merge!(:name => name)
         input_tag(:hidden, options)
       end
 
       ##
-      # Constructs a text area input from the given options
-      #
-      # @macro text_field
+      # Constructs a text area input from the given options.
       #
       # @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)
       end
 
       ##
-      # Constructs a password field input from the given options
-      #
-      # @macro text_field
+      # Constructs a password field input from the given options.
       #
       # @example
       #   password_field_tag :password, :class => 'long'
@@ -558,37 +538,29 @@ module Padrino
       end
 
       ##
-      # Constructs a check_box from the given options
-      #
-      # @macro text_field
+      # Constructs a check_box from the given options.
       #
       # @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 text_field
+      # Constructs a radio_button from the given options.
       #
       # @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 text_field
+      # Constructs a file field input from the given options.
       #
       # @example
       #   file_field_tag :photo, :class => 'long'
@@ -601,7 +573,7 @@ module Padrino
       end
 
       ##
-      # Constructs a select from the given options
+      # Constructs a select from the given options.
       #
       # @example
       #   options = [['caption', 'value'], ['Green', 'green1'], ['Blue', 'blue1'], ['Black', "black1"]]
@@ -638,9 +610,8 @@ module Padrino
       # @option options [Boolean] :multiple (false)
       #   Allow multiple options to be selected at once.
       #
-      # @return [String] The html input field based on the +options+ specified
+      # @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)
@@ -657,7 +628,7 @@ module Padrino
       end
 
       ##
-      # Constructs a button input from the given options
+      # Constructs a button input from the given options.
       #
       # @param [String] caption
       #   The caption for the button.
@@ -669,14 +640,13 @@ module Padrino
       # @example
       #   button_tag "Cancel", :class => 'clear'
       #
-      # @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
+      # Constructs a submit button from the given options.
       #
       # @param [String] caption (defaults to: +Submit+)
       #   The caption for the submit button.
@@ -689,7 +659,6 @@ module Padrino
       #   submit_tag "Create", :class => 'success'
       #   submit_tag :class => 'btn'
       #
-      # @api public
       def submit_tag(*args)
         options = args[-1].is_a?(Hash) ? args.pop : {}
         caption = args.length >= 1 ? args.shift : "Submit"
@@ -697,7 +666,8 @@ module Padrino
         input_tag(:submit, options)
       end
 
-      # Constructs a submit button from the given options
+      ##
+      # Constructs a submit button from the given options.
       #
       # @param [String] source
       #   The source image path for the button.
@@ -709,12 +679,12 @@ module Padrino
       # @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
 
+      ##
       # Constructs a hidden field containing a CSRF token.
       #
       # @param [String] token
@@ -725,17 +695,28 @@ module Padrino
       # @example
       #   csrf_token_field
       #
-      # @api public
       def csrf_token_field(token = nil)
-        if defined? session
-          token ||= (session[:csrf] ||= SecureRandom.hex(32))
-        end
+        hidden_field_tag csrf_param, :value => csrf_token
+      end
 
-        hidden_field_tag :authenticity_token, :value => token
+      ##
+      # Constructs meta tags `csrf-param` and `csrf-token` with the name of the
+      # cross-site request forgery protection parameter and token, respectively.
+      #
+      # @return [String] The meta tags with the CSRF token and the param your app expects it in.
+      #
+      # @example
+      #   csrf_meta_tags
+      #
+      def csrf_meta_tags
+        if is_protected_from_csrf?
+          meta_tag(csrf_param, :name => 'csrf-param') <<
+          meta_tag(csrf_token, :name => 'csrf-token')
+        end
       end
 
       ##
-      # Creates a form containing a single button that submits to the url.
+      # Creates a form containing a single button that submits to the URL.
       #
       # @overload button_to(name, url, options={})
       #   @param [String]  caption  The text caption.
@@ -752,6 +733,8 @@ module Padrino
       #   Instructs ujs handler to handle the submit as ajax.
       # @option options [Symbol] :method
       #   Instructs ujs handler to use different http method (i.e :post, :delete).
+      # @option options [Hash] :submit_options
+      #   Hash of any options, that you want to pass to submit_tag (i.e :id, :class)
       #
       # @return [String] Form and button html with specified +options+.
       #
@@ -763,22 +746,22 @@ module Padrino
       #   #   <input type="submit" value="Delete" />
       #   # </form>
       #
-      # @api public
       def button_to(*args, &block)
         name, url = args[0], args[1]
         options   = args.extract_options!
         options['data-remote'] = 'true' if options.delete(:remote)
+        submit_options = options.delete(:submit_options) || {}
         if block_given?
           form_tag(url, options, &block)
         else
           form_tag(url, options.merge!(:not_concat => true)) do
-            submit_tag(name)
+            submit_tag(name, submit_options)
           end
         end
       end
 
       ##
-      # Constructs a range tag from the given options
+      # Constructs a range tag from the given options.
       #
       # @example
       #   range_field_tag('ranger_with_min_max', :min => 1, :max => 50)
@@ -789,14 +772,13 @@ module Padrino
       # @param [Hash] options
       #   The html options for the range field.
       # @option options [Integer] :min
-      #  The min range of the range field
+      #  The min range of the range field.
       # @option options [Integer] :max
-      #  The max range of the range field
+      #  The max range of the range field.
       # @option options [range] :range
-      #  The range, in lieu of :min and :max.  See examples for details
+      #  The range, in lieu of :min and :max.  See examples for details.
       # @return [String] The html range field
       #
-      # @api public
       def range_field_tag(name, options = {})
         options.reverse_merge!(:name => name)
         if range = options.delete(:range)
@@ -807,116 +789,131 @@ module Padrino
 
       protected
 
-        ##
-        # 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
+      ##
+      # Returns an array of option items for a select field based on the given collection.
+      #
+      # @param [Array] fields
+      #   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
 
-        #
-        # 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, disabled|
-            value ||= caption
-            disabled ||= false
-            content_tag(:option, caption, :value => value, :selected => option_is_selected?(value, caption, selected_value), :disabled => disabled)
-          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, disabled|
+          value ||= caption
+          disabled ||= false
+          content_tag(:option, caption, :value => value, :selected => option_is_selected?(value, caption, selected_value), :disabled => disabled)
         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|
-              # Hash format:
-              # {:first => [1,2,3], :second => [4,5,6]}
-              # or:
-              # {:first => [[1,2,3], {:disabled => true}], :second => [4,5,6]}
-              attributes_hash = value.last.is_a?(Hash) ? value.pop : nil
-              disabled ||=  attributes_hash && attributes_hash.include?(:disabled) ? attributes_hash[:disabled] : false
-              content_tag :optgroup, options_for_select(value, selected), :label => key, :disabled => disabled
-            end
-          elsif collection.is_a?(Array)
-            # Array format:
-            # ["Option Label", [:option1, :option2, ...]]
+      ##
+      # 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|
+            # Hash format:
+            # {:first => [1,2,3], :second => [4,5,6]}
             # or:
-            # ["Option Label", [:option1, :option2, ...], true]
-            # the last item tells if it is disabled or not. This is keeps it backwards compatible.
-            collection.map do |optgroup|
-              disabled ||= optgroup.count > 2 ? optgroup.pop : false
-              content_tag :optgroup, options_for_select(optgroup.last, selected), :label => optgroup.first, :disabled => disabled
-            end
+            # {:first => [[1,2,3], {:disabled => true}], :second => [4,5,6]}
+            attributes_hash = value.last.is_a?(Hash) ? value.pop : nil
+            disabled ||=  attributes_hash && attributes_hash.include?(:disabled) ? attributes_hash[:disabled] : false
+            content_tag :optgroup, options_for_select(value, selected), :label => key, :disabled => disabled
           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 => '')
+        elsif collection.is_a?(Array)
+          # Array format:
+          # ["Option Label", [:option1, :option2, ...]]
+          # or:
+          # ["Option Label", [:option1, :option2, ...], true]
+          # the last item tells if it is disabled or not. This is keeps it backwards compatible.
+          collection.map do |optgroup|
+            disabled ||= optgroup.count > 2 ? optgroup.pop : false
+            content_tag :optgroup, options_for_select(optgroup.last, selected), :label => optgroup.first, :disabled => disabled
           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'
-          configured_builder = "Padrino::Helpers::FormBuilder::#{configured_builder}".constantize if configured_builder.is_a?(String)
-          configured_builder
+      ##
+      # 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
 
-        ##
-        # 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)
-        end
+      ##
+      # Returns whether the application is being protected from CSRF. Defaults to true.
+      #
+      def is_protected_from_csrf?
+        defined?(settings) ? settings.protect_from_csrf : true
+      end
 
-        ##
-        # 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)
-          end
-        end
+      ##
+      # Returns the current CSRF token (based on the session). If it doesn't exist,
+      # it will create one and assign it to the session's `csrf` key.
+      #
+      def csrf_token
+        session[:csrf] ||= SecureRandom.hex(32) if defined?(session)
+      end
+
+      ##
+      # Returns the param/field name in which your CSRF token should be expected by your
+      # controllers. Defaults to `authenticity_token`.
+      #
+      # Set this in your application with `set :csrf_param, :something_else`.
+      #
+      def csrf_param
+        defined?(settings) && settings.respond_to?(:csrf_param) ?
+          settings.csrf_param : :authenticity_token
+      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
+      #
+      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'
+        configured_builder = "Padrino::Helpers::FormBuilder::#{configured_builder}".constantize if configured_builder.is_a?(String)
+        configured_builder
+      end
+
+      ##
+      # Returns an initialized builder instance for the given object and settings.
+      #
+      # @example
+      #   builder_instance(@account, :nested => { ... }) => <FormBuilder>
+      #
+      def builder_instance(object, settings={})
+         builder_class = configured_form_builder_class(settings.delete(:builder))
+         builder_class.new(self, object, settings)
+      end
 
-        ##
-        # Returns whether the application is being protected from csrf
-        #
-        def is_protected_from_csrf?
-          return true unless defined? app
-          return true unless app.respond_to?(:protect_from_csrf)
-          return true if app.protect_from_csrf == nil
-          app.protect_from_csrf
+      ##
+      # 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
+      #
+      def option_is_selected?(value, caption, selected_values)
+        Array(selected_values).any? do |selected|
+          [value.to_s, caption.to_s].include?(selected.to_s)
         end
-    end # FormHelpers
-  end # Helpers
-end # Padrino
+      end
+    end
+  end
+end