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.



166
167
168
169
170
 
# 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

Instance Attribute Details

- (Object) form_values (readonly)

Returns the value of attribute form_values



156
157
158
 
# File 'lib/ramaze/helper/blue_form.rb', line 156

def form_values
  @form_values
end

- (Object) g (readonly)

Returns the value of attribute g



155
156
157
 
# File 'lib/ramaze/helper/blue_form.rb', line 155

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



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
 
# 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

- (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 (Proc) —

    The form elements to display inside the fieldset.



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

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

- (String) id_for(field_name) (private)

Generate a value for an ID tag based on the field's name.

Parameters:

  • field_name (String) —

    The name of the field.

Returns:

  • (String) —

    The ID for the specified field name.



673
674
675
676
677
678
679
 
# 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

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



355
356
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
 
# 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

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



522
523
524
525
526
527
528
529
530
 
# 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

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



546
547
548
549
550
551
552
553
554
555
556
 
# File 'lib/ramaze/helper/blue_form.rb', line 546

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.



271
272
273
274
275
276
277
278
279
280
281
282
283
284
 
# 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

- (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()


498
499
500
501
502
503
504
505
506
507
 
# 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

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



299
300
301
302
303
304
305
306
 
# 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

- (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) label_for(id, value, name) (private)

Generate a label based on the id and value.

Parameters:

  • id (String) —

    The ID to which the label belongs.

  • value (String) —

    The text to display inside the label tag.

  • name (String) —

    The name of the field to which the label belongs.



659
660
661
662
663
664
665
 
# 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

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



207
208
209
 
# File 'lib/ramaze/helper/blue_form.rb', line 207

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.



601
602
603
604
605
606
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
 
# 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

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



571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
 
# 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

- (String) to_s

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

Returns:

  • (String) —

    The form output



646
647
648
 
# File 'lib/ramaze/helper/blue_form.rb', line 646

def to_s
  @g.to_s
end