ramaze 2011.01.30 → 2011.07.25

data/lib/ramaze/helper/blue_form.rb

@@ -5,14 +5,17 @@ module Ramaze
   module Helper
     ##
     # == Introduction
-    # 
-    # The BlueForm helper tries to be an even better way to build forms programmatically.
-    # By using a simple block you can quickly create all the required elements for your form.
     #
-    # Since November 2010 the BlueForm helper works different. You can now specify an object as the first
-    # parameter of the form_for() method. This object will be used to retrieve the values of each field.
-    # This means that you can directly pass a database result object to the form and no longer have
-    # to manually specify values. However, you can still specify your own values if you want.
+    # The BlueForm helper tries to be an even better way to build forms
+    # programmatically.  By using a simple block you can quickly create all the
+    # required elements for your form.
+    #
+    # Since November 2010 the BlueForm helper works different. You can now
+    # specify an object as the first parameter of the form_for() method. This
+    # object will be used to retrieve the values of each field. This means that
+    # you can directly pass a database result object to the form and no longer
+    # have to manually specify values. However, you can still specify your own
+    # values if you want.
     #
     # Old behaviour:
     #
@@ -30,10 +33,12 @@ module Ramaze
     #
     # == Form Data
     #
-    # As stated earlier it's possible to pass an object to the form_for() method. What kind of object this is,
-    # a database result object or an OpenStruct object doesn't matter as long as the attributes can be accessed
-    # outside of the object (this can be done using attr_readers). This makes it extremely easy to directly pass
-    # a result object from your favourite ORM. Example:
+    # As stated earlier it's possible to pass an object to the form_for()
+    # method. What kind of object this is, a database result object or an
+    # OpenStruct object doesn't matter as long as the attributes can be accessed
+    # outside of the object (this can be done using attr_readers). This makes it
+    # extremely easy to directly pass a result object from your favourite ORM.
+    # Example:
     #
     #  @data = User[1]
     #
@@ -41,24 +46,27 @@ module Ramaze
     #    f.input_text 'Username', :username
     #  end
     #
-    # If you don't want to use an object you can simply set the first parameter to nil.
+    # If you don't want to use an object you can simply set the first parameter
+    # to nil.
     #
     # == HTML Output
-    # 
-    # The form helper uses Gestalt, Ramaze's custom HTML builder that works somewhat like Erector.
-    # The output is very minimalistic, elements such as legends and fieldsets have to be added manually.
-    # Each combination of a label and input element will be wrapped in <p> tags.
     #
-    # When using the form helper as a block in your templates it's important to remember that the
-    # result is returned and not displayed in the browser directly. When using Etanni this would result in
-    # something like the following:
+    # The form helper uses Gestalt, Ramaze's custom HTML builder that works
+    # somewhat like Erector. The output is very minimalistic, elements such as
+    # legends and fieldsets have to be added manually. Each combination of a
+    # label and input element will be wrapped in <p> tags.
+    #
+    # When using the form helper as a block in your templates it's important to
+    # remember that the result is returned and not displayed in the browser
+    # directly. When using Etanni this would result in something like the
+    # following:
     #
     #  #{
     #    form_for(@result, :method => :post) do |f| do
     #      f.input_text 'Text label', :textname, 'Chunky bacon!'
     #    end
     #  }
-    # 
+    #
     # @example
     #
     #  form_for(@data, :method => :post) do |f|
@@ -67,12 +75,16 @@ module Ramaze
     #
     module BlueForm
       ##
-      # The form method generates the basic structure of the form. It should be called
-      # using a block and it's return value should be manually sent to the browser (since it does not echo the value).
+      # The form method generates the basic structure of the form. It should be
+      # called using a block and it's return value should be manually sent to
+      # the browser (since it does not echo the value).
       #
-      # @param [Object] form_values Object containing the values for each form field.
-      # @param [Hash] options Hash containing any additional form attributes such as the method, action, enctype and so on.
-      # @param [Block] block Block containing the elements of the form such as password fields, textareas and so on. 
+      # @param [Object] form_values Object containing the values for each form
+      #  field.
+      # @param [Hash] options Hash containing any additional form attributes
+      #  such as the method, action, enctype and so on.
+      # @param [Block] block Block containing the elements of the form such as
+      #  password fields, textareas and so on.
       #
       def form_for(form_values, options = {}, &block)
         form = Form.new(form_values, options)
@@ -81,10 +93,12 @@ module Ramaze
       end
 
       ##
-      # Manually add a new error to the form_errors key in the flash hash.
-      # The first parameter is the name of the form field and the second parameter is the custom message.
+      # Manually add a new error to the form_errors key in the flash hash. The
+      # first parameter is the name of the form field and the second parameter
+      # is the custom message.
       #
-      # @param [String] name The name of the form field to which the error belongs.
+      # @param [String] name The name of the form field to which the error
+      #  belongs.
       # @param [String] message The custom error message to show.
       #
       def form_error(name, message)
@@ -97,8 +111,8 @@ module Ramaze
       end
 
       ##
-      # Returns the hash containing all existing errors and allows other methods to set
-      # new errors by using this method as if it were a hash.
+      # Returns the hash containing all existing errors and allows other methods
+      # to set new errors by using this method as if it were a hash.
       #
       # @return [Array] All form errors.
       #
@@ -111,7 +125,8 @@ module Ramaze
       end
 
       ##
-      # Retrieve all the form errors for the specified model and add them to the flash hash.
+      # Retrieve all the form errors for the specified model and add them to the
+      # flash hash.
       #
       # @param [Object] obj An object of a model that contains form errors.
       #
@@ -121,16 +136,17 @@ module Ramaze
             if value.respond_to?(:first)
               value = value.first
             end
-            
+
             form_error(key.to_s, value % key)
           end
         end
       end
 
       ##
-      # Main form class that contains all the required methods to generate form specific tags,
-      # such as textareas and select boxes. Do note that this class is not thread-safe so you should
-      # modify it only within one thread of execution.
+      # Main form class that contains all the required methods to generate form
+      # specific tags, such as textareas and select boxes. Do note that this
+      # class is not thread-safe so you should modify it only within one thread
+      # of execution.
       #
       class Form
         attr_reader :g
@@ -139,7 +155,8 @@ module Ramaze
         ##
         # Constructor method that generates an instance of the Form class.
         #
-        # @param [Object] form_values Object containing the values for each form field.
+        # @param [Object] form_values Object containing the values for each form
+        #  field.
         # @param [Hash] options A hash containing any additional form attributes.
         # @return [Object] An instance of the Form class.
         #
@@ -159,15 +176,15 @@ module Ramaze
           # Convert all the keys in form_errors to strings and
           # retrieve the correct values in case
           @form_errors = {}
-          
+
           form_errors.each do |key, value|
             if value.respond_to?(:first)
               value = value.first
             end
-            
+
             @form_errors[key.to_s] = value
           end
-          
+
           @g.form(@form_args) do
             if block_given?
               yield self
@@ -180,7 +197,7 @@ module Ramaze
         #
         # @param [String] text The text to display inside the legend tag.
         # @example
-        # 
+        #
         #   form_for(@data, :method => :post) do |f|
         #     f.legend 'Ramaze rocks!'
         #   end
@@ -188,13 +205,13 @@ module Ramaze
         def legend(text)
           @g.legend(text)
         end
-        
+
         ##
         # Generate a fieldset tag.
         #
         # @param [Block] &block The form elements to display inside the fieldset.
         # @example
-        #  
+        #
         #  form_for(@data, :method => :post) do |f|
         #    f.fieldset do
         #      f.legend 'Hello, world!'
@@ -202,16 +219,18 @@ module Ramaze
         #  end
         #
         def fieldset(&block)
-          @g.fieldset(block)
+          @g.fieldset(&block)
         end
 
         ##
         # Generate an input tag with a type of "text" along with a label tag.
-        # This method also has the alias "text" so feel free to use that one instead of input_text.
-        # 
+        # This method also has the alias "text" so feel free to use that one
+        # instead of input_text.
+        #
         # @param [String] label The text to display inside the label tag.
         # @param [String Symbol] name The name of the text field.
-        # @param [Hash] args Any additional HTML attributes along with their values.
+        # @param [Hash] args Any additional HTML attributes along with their
+        #  values.
         # @example
         #
         #   form_for(@data, :method => :post) do |f|
@@ -236,14 +255,16 @@ module Ramaze
 
         ##
         # Generate an input tag with a type of "password" along with a label.
-        # Password fields are pretty much the same as text fields except that the content of these fields is replaced with dots.
-        # This method has the following alias: "password".
+        # Password fields are pretty much the same as text fields except that
+        # the content of these fields is replaced with dots. This method has the
+        # following alias: "password".
         #
         # @param [String] label The text to display inside the label tag.
         # @param [String Symbol] name The name of the password field.
-        # @param [Hash] args Any additional HTML attributes along with their values.
+        # @param [Hash] args Any additional HTML attributes along with their
+        #  values.
         # @example
-        # 
+        #
         #  form_for(@data, :method => :post) do |f|
         #    f.input_password 'My password', :password
         #  end
@@ -252,11 +273,11 @@ module Ramaze
           # The ID can come from 2 places, id_for and the args hash
           id   = args[:id] ? args[:id] : id_for(name)
           args = args.merge(:type => :password, :name => name, :id => id)
-          
+
           if !args[:value] and @form_values.respond_to?(name)
             args[:value] = @form_values.send(name)
           end
-          
+
           @g.p do
             label_for(id, label, name)
             @g.input(args)
@@ -265,11 +286,12 @@ module Ramaze
         alias password input_password
 
         ##
-        # Generate a submit tag (without a label). A submit tag is a button that once it's clicked
-        # will send the form data to the server.
+        # Generate a submit tag (without a label). A submit tag is a button that
+        # once it's clicked will send the form data to the server.
         #
         # @param [String] value The text to display in the button.
-        # @param [Hash] args Any additional HTML attributes along with their values.
+        # @param [Hash] args Any additional HTML attributes along with their
+        #  values.
         # @example
         #
         #  form_for(@data, :method => :post) do |f|
@@ -287,14 +309,12 @@ module Ramaze
         alias submit input_submit
 
         ##
-        # Generate an input tag with a type of "checkbox". This method will also
-        # generate a hidden field with the same name as the checkbox to ensure
-        # that the data is always submitted.
+        # Generate an input tag with a type of "checkbox".
         #
-        # If you want to have multiple checkboxes you can either use an array or a hash.
-        # In the case of an array the values will also be used as text for each checkbox.
-        # When using a hash the key will be displayed and the value will be the value of the
-        # checkbox. Example:
+        # If you want to have multiple checkboxes you can either use an array or
+        # a hash.  In the case of an array the values will also be used as text
+        # for each checkbox.  When using a hash the key will be displayed and
+        # the value will be the value of the checkbox. Example:
         #
         #  @data = Class.new
         #    attr_reader :gender_arr
@@ -311,25 +331,44 @@ module Ramaze
         #    f.input_checkbox "Gender", :gender_hash
         #  end
         #
-        # @param [String] label The text to display inside the label tag.
-        # @param [String Symbol] name The name of the checkbox.
-        # @param [String] checked String that indicates if (and which) checkbox should be checked.
-        # @param [Hash] args Any additional HTML attributes along with their values.
         # @example
-        #
         #  form_for(@data, :method => :post) do |f|
         #    f.input_checkbox 'Remember me', :remember_user
         #  end
         #
+        # @param [String] label The text to display inside the label tag.
+        # @param [String Symbol] name The name of the checkbox.
+        # @param [String] checked String that indicates if (and which) checkbox
+        #  should be checked.
+        # @param [Hash] args Any additional HTML attributes along with their
+        #  values.
+        # @option args [String/Symbol] :id The value to use for the ID attribute.
+        # @option args [Array] :values An array containing the possible values
+        #  for the checkboxes.
+        # @option args [String/Symbol] :span_class The class to use for the
+        #  <span> element that's wrapped around the checkbox.
+        # @option args [TrueClass/FalseClass] :show_value When set to false the
+        #  value of each checkbox won't be displayed to the right of the
+        #  checkbox. This option is set to true by default.
+        # @option args [TrueClass/FalseClass] :show_label When set to true
+        #  (default) the label for the checkbox will be displayed. Setting this
+        #  to false will hide it.
+        #
         def input_checkbox(label, name, checked = nil, args = {})
           id = args[:id] ? args[:id] : "#{id_for(name)}_0"
 
-          # Get the default value for the checkbox used for the hidden field.
-          if args[:default]
-            default = args[:default]
-            args.delete(:default)
+          # Determine whether or not to show the value of the checkbox
+          if args.key?(:show_value)
+            show_value = args.delete(:show_value)
+          else
+            show_value = true
+          end
+
+          # Determine whether or not to show the label
+          if args.key?(:show_label)
+            show_label = args.delete(:show_label)
           else
-            default = 0
+            show_label = true
           end
 
           # Get the checkbox value from either the args hash or from
@@ -337,7 +376,7 @@ module Ramaze
           if !args[:values] and @form_values.respond_to?(name)
             args[:values] = @form_values.send(name)
           end
-          
+
           # That class for each element wrapper (a span tag) can be customized
           # using :span_class => "a_class".
           if args[:span_class]
@@ -346,38 +385,40 @@ module Ramaze
           else
             span_class = "checkbox_wrap"
           end
-          
-          # Get the type from the args hash instead of pre-defining it. Doing so means we can use
-          # this method for the input_radio method.
-          if !args[:type]
-            args[:type] = :checkbox
-          end
-          
-          # Convert the values to an array if it's something we can't use in a loop (e.g. a string).
+
+          # Get the type from the args hash instead of pre-defining it. Doing so
+          # means we can use this method for the input_radio method.
+          args[:type] = :checkbox if !args[:type]
+
+          # Convert the values to an array if it's something we can't use in a loop
+          # (e.g. a string).
           if args[:values].class != Hash and args[:values].class != Array
             args[:values] = [args[:values]]
           end
-          
+
           # Create a checkbox for each value
           if !args[:values].empty?
             @g.p do
               # Let's create the label and the hidden field
-              label_for(id, label, name)
-              self.input_hidden(name, default)
-              
-              # Loop through all the values. Each checkbox will have an ID of "form-NAME-INDEX".
-              # Each name will be NAME followed by [] to indicate it's an array (since multiple values are possible).
+              if show_label === true
+                label_for(id, label, name)
+              end
+
+              # Loop through all the values. Each checkbox will have an ID of
+              # "form-NAME-INDEX". Each name will be NAME followed by [] to
+              # indicate it's an array (since multiple values are possible).
               args[:values].each_with_index do |value, index|
-                id            = args[:id] ? args[:id] : "#{id_for(name)}_#{index}"
-                
+                id = args[:id] ? args[:id] : "#{id_for(name)}_#{index}"
+
                 if args[:type] == :checkbox
                   checkbox_name = "#{name}[]"
                 else
                   checkbox_name = name
                 end
-                
-                # Copy all additional attributes and their values except the values array.
-                opts = args.clone 
+
+                # Copy all additional attributes and their values except the
+                # values array.
+                opts = args.clone
                 opts.delete(:values)
 
                 # Get the value and text to display for each checkbox
@@ -394,17 +435,20 @@ module Ramaze
                 end
 
                 # And we're done, easy wasn't it?
-                opts = opts.merge(:name => checkbox_name, :id => id, :value => checkbox_value)
+                opts = opts.merge(
+                  :name => checkbox_name, :id => id, :value => checkbox_value
+                )
 
                 # Generate the following HTML:
                 #
                 # <span class="#{span_class}">
-                #   <input type="checkbox" name="#{checkbox_name}" id="#{id}" value="#{value}" /> #{value}
+                #   <input type="checkbox" name="#{checkbox_name}" id="#{id}"
+                #   value="#{value}" /> #{value}
                 # </span>
                 #
-                @g.span :class => span_class do
+                @g.span(:class => span_class) do
                   @g.input(opts)
-                  " #{checkbox_text}"
+                  " #{checkbox_text}" if show_value === true
                 end
               end
             end
@@ -413,12 +457,10 @@ module Ramaze
         alias checkbox input_checkbox
 
         ##
-        # Generate an input tag with a type of "radio". This method will also
-        # generate a hidden field with the same name as the radio button to ensure
-        # that the data is always submitted.
+        # Generate an input tag with a type of "radio".
         #
-        # If you want to generate multiple radio buttons you can use an array just like
-        # you can with checkboxes. Example:
+        # If you want to generate multiple radio buttons you can use an array
+        # just like you can with checkboxes. Example:
         #
         #  @data = Class.new
         #    attr_reader :gender_arr
@@ -435,13 +477,16 @@ module Ramaze
         #    f.input_radio "Gender", :gender_hash
         #  end
         #
+        # For more information see the input_checkbox() method.
+        #
         # @param [String] label The text to display inside the label tag.
         # @param [String Symbol] name The name of the radio button.
-        # @param [String] checked String that indicates if (and which) radio button should be checked.
-        # @param [Hash] args Any additional HTML attributes along with their values.
+        # @param [String] checked String that indicates if (and which) radio
+        #  button should be checked.
+        # @param [Hash] args Any additional HTML attributes along with their
+        #  values.
         # @see input_checkbox()
         # @example
-        # 
         #  form_for(@data, :method => :post) do |f|
         #    f.input_radio 'Gender', :gender
         #  end
@@ -449,21 +494,22 @@ module Ramaze
         def input_radio(label, name, checked = nil, args = {})
           # Force a type of "radio"
           args[:type] = :radio
-          
+
           if !args[:span_class]
             args[:span_class] = "radio_wrap"
           end
-          
+
           self.input_checkbox(label, name, checked, args)
         end
         alias radio input_radio
 
         ##
         # Generate a field for uploading files.
-        # 
+        #
         # @param [String] label The text to display inside the label tag.
         # @param [String Symbol] name The name of the radio tag.
-        # @param [Hash] args Any additional HTML attributes along with their values.
+        # @param [Hash] args Any additional HTML attributes along with their
+        #  values.
         # @example
         #
         #  form_for(@data, :method => :post) do |f|
@@ -482,21 +528,22 @@ module Ramaze
         alias file input_file
 
         ##
-        # Generate a hidden field. Hidden fields are essentially the same as text fields
-        # except that they aren't displayed in the browser.
+        # Generate a hidden field. Hidden fields are essentially the same as
+        # text fields except that they aren't displayed in the browser.
         #
         # @param [String Symbol] name The name of the hidden field tag.
         # @param [String] value The value of the hidden field
-        # @param [Hash] args Any additional HTML attributes along with their values.
+        # @param [Hash] args Any additional HTML attributes along with their
+        #  values.
         # @example
         #
         #  form_for(@data, :method => :post) do |f|
         #    f.input_hidden :user_id
         #  end
-        # 
+        #
         def input_hidden(name, value = nil, args = {})
           args = args.merge(:type => :hidden, :name => name)
-          
+
           if !value and @form_values.respond_to?(name)
             args[:value] = @form_values.send(name)
           else
@@ -512,7 +559,8 @@ module Ramaze
         #
         # @param [String] label The text to display inside the label tag.
         # @param [String Symbol] name The name of the textarea.
-        # @param [Hash] args Any additional HTML attributes along with their values.
+        # @param [Hash] args Any additional HTML attributes along with their
+        #  values.
         # @example
         #
         #  form_for(@data, :method => :post) do |f|
@@ -521,7 +569,7 @@ module Ramaze
         #
         def textarea(label, name, args = {})
           id = args[:id] ? args[:id] : id_for(name)
-          
+
           # Get the value of the textarea
           if !args[:value] and @form_values.respond_to?(name)
             value = @form_values.send(name)
@@ -529,7 +577,7 @@ module Ramaze
             value = args[:value]
             args.delete(:value)
           end
-          
+
           args = args.merge(:name => name, :id => id)
 
           @g.p do
@@ -540,7 +588,7 @@ module Ramaze
 
         ##
         # Generate a select tag along with the option tags and a label.
-        # 
+        #
         # @param [String] label The text to display inside the label tag.
         # @param [String Symbol] name The name of the select tag.
         # @param [Hash] args Hash containing additional HTML attributes.
@@ -553,7 +601,7 @@ module Ramaze
         def select(label, name, args = {})
           id              = args[:id] ? args[:id] : id_for(name)
           multiple, size  = args.values_at(:multiple, :size)
-          
+
           # Get all the values
           if !args[:values] and @form_values.respond_to?(name)
             values = @form_values.send(name)
@@ -561,7 +609,7 @@ module Ramaze
             values = args[:values]
             args.delete(:values)
           end
-          
+
           args[:multiple] = 'multiple' if multiple
           args[:size]     = (size || values.count || 1).to_i
           args[:name]     = multiple ? "#{name}[]" : name
@@ -578,11 +626,11 @@ module Ramaze
               values.each do |value, o_name|
                 o_name ||= value
                 o_args = {:value => value}
-                
+
                 if has_selected and selected.include?(value)
                   o_args[:selected] = 'selected'
                 end
-                
+
                 @g.option(o_args){ o_name }
               end
             end
@@ -590,7 +638,8 @@ module Ramaze
         end
 
         ##
-        # Method used for converting the results of the BlueForm helper to a string
+        # Method used for converting the results of the BlueForm helper to a
+        # string
         #
         # @return [String] The form output
         #
@@ -628,7 +677,7 @@ module Ramaze
             "form_#{field_name}".downcase.gsub(/-/, '_')
           end
         end
-      end
-    end
-  end
-end
+      end # Form
+    end # BlueForm
+  end # Helper
+end # Ramaze