Class: Ramaze::Helper::BlueForm::Form

Inherits:
Object
  • Object
show all
Defined in:
lib/ramaze/helper/blue_form.rb

Overview

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.

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Object) initialize(form_values, options)

Constructor method that generates an instance of the Form class.

Parameters:

  • form_values (Object) —

    Object containing the values for each form field.

  • options (Hash) —

    A hash containing any additional form attributes.



163
164
165
166
167
 
# File 'lib/ramaze/helper/blue_form.rb', line 163

def initialize(form_values, options)
  @form_values  = form_values
  @form_args    = options.dup
  @g            = Gestalt.new
end

Instance Attribute Details

- (Object) form_values (readonly)

Returns the value of attribute form_values



153
154
155
 
# File 'lib/ramaze/helper/blue_form.rb', line 153

def form_values
  @form_values
end

- (Object) g (readonly)

Returns the value of attribute g



152
153
154
 
# File 'lib/ramaze/helper/blue_form.rb', line 152

def g
  @g
end

Instance Method Details

- (Object) build(form_errors = {})

Builds the form by generating the opening/closing tags and executing the methods in the block.

Parameters:

  • form_errors (Hash) (defaults to: {}) —

    Hash containing all form errors (if any).



175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/ramaze/helper/blue_form.rb', line 175

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

- (Object) fieldset(&block)

Generate a fieldset tag.

Examples:


form_for(@data, :method => :post) do |f|
  f.fieldset do
    f.legend 'Hello, world!'
  end
end

Parameters:

  • &block (Block) —

    The form elements to display inside the fieldset.



221
222
223
 
# File 'lib/ramaze/helper/blue_form.rb', line 221

def fieldset(&block)
  @g.fieldset(&block)
end

- (Object) input_checkbox(label, name, checked = nil, args = {}) Also known as: checkbox

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

Examples:

form_for(@data, :method => :post) do |f|
  f.input_checkbox 'Remember me', :remember_user
end

Parameters:

  • label (String) —

    The text to display inside the label tag.

  • name (String Symbol) —

    The name of the checkbox.

  • checked (String/Array) (defaults to: nil) —

    String or array that indicates which value(s) should be checked.

  • args (Hash) (defaults to: {}) —

    Any additional HTML attributes along with their values.

Options Hash (args):

  • :id (String/Symbol) —

    The value to use for the ID attribute.

  • :values (Array) —

    An array containing the possible values for the checkboxes.

  • :span_class (String/Symbol) —

    The class to use for the <span> element that's wrapped around the checkbox.

  • :show_value (TrueClass/FalseClass) —

    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.

  • :show_label (TrueClass/FalseClass) —

    When set to true (default) the label for the checkbox will be displayed. Setting this to false will hide it.



357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
 
# File 'lib/ramaze/helper/blue_form.rb', line 357

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

- (Object) input_file(label, name, args = {}) Also known as: file

Generate a field for uploading files.

Examples:


form_for(@data, :method => :post) do |f|
  f.input_file 'Image', :image
end

Parameters:

  • label (String) —

    The text to display inside the label tag.

  • name (String Symbol) —

    The name of the radio tag.

  • args (Hash) (defaults to: {}) —

    Any additional HTML attributes along with their values.



525
526
527
528
529
530
531
532
533
 
# File 'lib/ramaze/helper/blue_form.rb', line 525

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

- (Object) input_hidden(name, value = nil, args = {}) Also known as: hidden

Generate a hidden field. Hidden fields are essentially the same as text fields except that they aren't displayed in the browser.

Examples:


form_for(@data, :method => :post) do |f|
  f.input_hidden :user_id
end

Parameters:

  • name (String Symbol) —

    The name of the hidden field tag.

  • value (String) (defaults to: nil) —

    The value of the hidden field

  • args (Hash) (defaults to: {}) —

    Any additional HTML attributes along with their values.



550
551
552
553
554
555
556
557
558
559
560
 
# File 'lib/ramaze/helper/blue_form.rb', line 550

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
    args[:value] = value
  end

  @g.input(args)
end

- (Object) input_password(label, name, args = {}) Also known as: password

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".

Examples:


form_for(@data, :method => :post) do |f|
  f.input_password 'My password', :password
end

Parameters:

  • label (String) —

    The text to display inside the label tag.

  • name (String Symbol) —

    The name of the password field.

  • args (Hash) (defaults to: {}) —

    Any additional HTML attributes along with their values.



272
273
274
275
276
277
278
279
280
281
282
283
284
285
 
# File 'lib/ramaze/helper/blue_form.rb', line 272

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

- (Object) input_radio(label, name, checked = nil, args = {}) Also known as: radio

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.

Examples:

form_for(@data, :method => :post) do |f|
  f.input_radio 'Gender', :gender
end

Parameters:

  • label (String) —

    The text to display inside the label tag.

  • name (String Symbol) —

    The name of the radio button.

  • checked (String) (defaults to: nil) —

    String that indicates if (and which) radio button should be checked.

  • args (Hash) (defaults to: {}) —

    Any additional HTML attributes along with their values.

See Also:

  • input_checkbox()


500
501
502
503
504
505
506
507
508
509
 
# File 'lib/ramaze/helper/blue_form.rb', line 500

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

- (Object) input_submit(value = nil, args = {}) Also known as: submit

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.

Examples:


form_for(@data, :method => :post) do |f|
  f.input_submit 'Save'
end

Parameters:

  • value (String) (defaults to: nil) —

    The text to display in the button.

  • args (Hash) (defaults to: {}) —

    Any additional HTML attributes along with their values.



301
302
303
304
305
306
307
308
 
# File 'lib/ramaze/helper/blue_form.rb', line 301

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

- (Object) input_text(label, name, args = {}) Also known as: text

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.

Examples:


form_for(@data, :method => :post) do |f|
  f.input_text 'Username', :username
end

Parameters:

  • label (String) —

    The text to display inside the label tag.

  • name (String Symbol) —

    The name of the text field.

  • args (Hash) (defaults to: {}) —

    Any additional HTML attributes along with their values.



240
241
242
243
244
245
246
247
248
249
250
251
252
253
 
# 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

- (Object) legend(text)

Generate a <legend> tag.

Examples:


form_for(@data, :method => :post) do |f|
  f.legend 'Ramaze rocks!'
end

Parameters:

  • text (String) —

    The text to display inside the legend tag.



205
206
207
 
# File 'lib/ramaze/helper/blue_form.rb', line 205

def legend(text)
  @g.legend(text)
end

- (Object) select(label, name, args = {})

Generate a select tag along with the option tags and a label.

Examples:


form_for(@data, :method => :post) do |f|
  f.select 'Country', :country_list
end

Parameters:

  • label (String) —

    The text to display inside the label tag.

  • name (String Symbol) —

    The name of the select tag.

  • args (Hash) (defaults to: {}) —

    Hash containing additional HTML attributes.



607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
 
# File 'lib/ramaze/helper/blue_form.rb', line 607

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

- (Object) textarea(label, name, args = {})

Generate a text area.

Examples:


form_for(@data, :method => :post) do |f|
  f.textarea 'Description', :description
end

Parameters:

  • label (String) —

    The text to display inside the label tag.

  • name (String Symbol) —

    The name of the textarea.

  • args (Hash) (defaults to: {}) —

    Any additional HTML attributes along with their values.



576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
 
# File 'lib/ramaze/helper/blue_form.rb', line 576

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

- (String) to_s

Method used for converting the results of the BlueForm helper to a string

Returns:

  • (String) —

    The form output



652
653
654
 
# File 'lib/ramaze/helper/blue_form.rb', line 652

def to_s
  @g.to_s
end