class Ramaze::Helper::BlueForm::Form
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.
Attributes
Public Class Methods
Constructor method that generates an instance of the Form class.
@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.
# File lib/ramaze/helper/blue_form.rb, line 166 def initialize(form_values, options) @form_values = form_values @form_args = options.dup @g = Gestalt.new end
Public Instance Methods
Builds the form by generating the opening/closing tags and executing the methods in the block.
@param [Hash] form_errors Hash containing all form errors (if any).
# File lib/ramaze/helper/blue_form.rb, line 178 def build(form_errors = {}) # 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 end end end
Generate a fieldset tag.
@param [Proc] block The form elements to display inside the fieldset. @example
form_for(@data, :method => :post) do |f| f.fieldset do f.legend 'Hello, world!' end end
# File lib/ramaze/helper/blue_form.rb, line 222 def fieldset(&block) @g.fieldset(&block) end
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:
@data = Class.new attr_reader :gender_arr attr_reader :gender_hash def initialize @gender_arr = ['male', 'female'] @gender_hash = {"Male" => "male", "Female" => "female"} end end.new form_for(@data, :method => :post) do |f| f.input_checkbox "Gender", :gender_arr f.input_checkbox "Gender", :gender_hash end
@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/Array] checked String or array that indicates which
value(s) 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.
# File lib/ramaze/helper/blue_form.rb, line 355 def input_checkbox(label, name, checked = nil, args = {}) id = args[:id] ? args[:id] : "#{id_for(name)}_0" # 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 show_label = true end # Get the checkbox value from either the args hash or from # the form object (as specified in the form_for() method). 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] span_class = args[:span_class] args.delete(:span_class) 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. 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 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}" 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 opts.delete(:values) # Get the value and text to display for each checkbox if value.class == Array checkbox_text = value[0] checkbox_value = value[1] else checkbox_text = checkbox_value = value end # Let's see if the current item is checked if checked.class == Array if checked.include?(checkbox_value) opts[:checked] = 'checked' end else if checkbox_value == checked opts[:checked] = 'checked' end end # And we're done, easy wasn't it? 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} # </span> # @g.span(:class => span_class) do @g.input(opts) " #{checkbox_text}" if show_value === true end end end end end
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.
@example
form_for(@data, :method => :post) do |f| f.input_file 'Image', :image end
# File lib/ramaze/helper/blue_form.rb, line 522 def input_file(label, name, args = {}) id = args[:id] ? args[:id] : id_for(name) args = args.merge(:type => :file, :name => name, :id => id) @g.p do label_for(id, label, name) @g.input(args) end end
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”.
@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.
@example
form_for(@data, :method => :post) do |f| f.input_password 'My password', :password end
# File lib/ramaze/helper/blue_form.rb, line 271 def input_password(label, name, args = {}) # 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) end end
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:
@data = Class.new attr_reader :gender_arr attr_reader :gender_hash def initialize @gender_arr = ['male', 'female'] @gender_hash = {"Male" => "male", "Female" => "female"} end end.new form_for(@data, :method => :post) do |f| f.input_radio "Gender", :gender_arr 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.
@see #input_checkbox() @example
form_for(@data, :method => :post) do |f| f.input_radio 'Gender', :gender end
# File lib/ramaze/helper/blue_form.rb, line 498 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
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.
@example
form_for(@data, :method => :post) do |f| f.input_submit 'Save' end
# File lib/ramaze/helper/blue_form.rb, line 299 def input_submit(value = nil, args = {}) args = args.merge(:type => :submit) args[:value] = value unless value.nil? @g.p do @g.input(args) end 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.
@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.
@example
form_for(@data, :method => :post) do |f| f.input_text 'Username', :username end
# File lib/ramaze/helper/blue_form.rb, line 240 def input_text(label, name, args = {}) # 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 => :text, :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) end end
Generate a `<legend>` tag.
@param [String] text The text to display inside the legend tag. @example
form_for(@data, :method => :post) do |f| f.legend 'Ramaze rocks!' end
# File lib/ramaze/helper/blue_form.rb, line 207 def legend(text) @g.legend(text) end
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. @example
form_for(@data, :method => :post) do |f| f.select 'Country', :country_list end
# File lib/ramaze/helper/blue_form.rb, line 601 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) else 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 args = args.merge(:id => id) # Retrieve the selected value has_selected, selected = args.key?(:selected), args[:selected] selected = [selected] if !selected.is_a?(Array) args.delete(:selected) @g.p do label_for(id, label, name) @g.select args do 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 end end
Generate a text area.
@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.
@example
form_for(@data, :method => :post) do |f| f.textarea 'Description', :description end
# File lib/ramaze/helper/blue_form.rb, line 571 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) else value = args[:value] args.delete(:value) end args = args.merge(:name => name, :id => id) @g.p do label_for(id, label, name) @g.textarea(args){ value } end end
Method used for converting the results of the BlueForm helper to a string
@return [String] The form output
# File lib/ramaze/helper/blue_form.rb, line 646 def to_s @g.to_s end
Private Instance Methods
Generate a value for an ID tag based on the field's name.
@param [String] field_name The name of the field. @return [String] The ID for the specified field name.
# File lib/ramaze/helper/blue_form.rb, line 673 def id_for(field_name) if name = @form_args[:name] "#{name}_#{field_name}".downcase.gsub(/-/, '_') else "form_#{field_name}".downcase.gsub(/-/, '_') end end
Generate a label based on the id and value.
@param [String] id The ID to which the label belongs. @param [String] value The text to display inside the label tag. @param [String] name The name of the field to which the label belongs.
# File lib/ramaze/helper/blue_form.rb, line 659 def label_for(id, value, name) if error = @form_errors.delete(name.to_s) @g.label("#{value} ", :for => id){ @g.span(:class => :error){ error } } else @g.label(value, :for => id) end end