NAME

Contentment::Form::Widget::TabularChoice - A list of options in tabular form

SYNOPSIS

  my $template = <<'END_OF_TEMPLATE';
  [% form.start %]
  [% form.widgets.choices.render %]
  [% form.end %]
  END_OF_TEMPLATE

  my $form = Contentment::Form->define({
      # ...
      widgets => {
          choices => {
              name    => 'choices',
              class   => 'TabularChoice',
              heading => [ '', qw( Title Description ) ],
              options => [
                  [ 'first_value'  => 'First Value', 'It is the first value!' ],
                  [ 'second_value' => 'Second Value','And the second one.' ],
                  [ 'third_value'  => 'Third Value', 'And a third.' ],
              ],
          },
      },
      # ...
  });

DESCRIPTION

This widget provides a table of choices in your form. Each row will contain a checkbox or a radio button and zero or more columns of additional information. This control provides a validator that makes sure that the options given are match the widget configuration.

The render() method is the preferred way to rendering this control.

CONSTRUCTION

The widget constructor accepts the following options:

name (required)

This is the name of the control.

options (must be present unless "options_sub" is present)

Either this parameter or "options_sub" must be given for every tabular choice control.

This option should be given as an array of row arrays. Each row array's first element is the value that the button on that row should have when checked. (I.e., the first column is the value regardless of the setting of "button_column".) The rest of the elements are the values that should be shown in the other columns of the table. Each row array should have the same length.

options_sub (must be present unless "options" is present)

Either this parameter or "options" must be given for every tabular choice control.

This option should be given as a string naming the fully-qualified name of a function that the control may call to fetch the options. The return value of the subroutine should return an array of row arrays as described under the "options" parameter.

The subroutine will be passed no parameters. This may change in the future, but I can't think what would be feasible/useful to pass at both render and validation time.

required (optional, defaults to "0")

This is a boolean option that decides if the user must make a selection on this control.

Normally, with radio buttons once an option is selected, it cannot be deselected. Therefore, if you set the "multiple" to false, but want a user to be able to choose an undefined value, you may add an option with value "".

This means that you cannot specify the empty string as a proper value for your form.

multiple (optional, defaults to "1")

This option is a boolean that decides whether or not the buttons should be checkboxes or radio buttons. With a true value, checkboxes are used. With a false value, radio buttons are used.

button_column (optional, defaults to "0")

This specifies which column should be used to hold the button. The first column is "0".

You may use negative numbers to place the control column based upon the position of the last column. That is, "-1" is the last column, "-2" is the next to last column, etc.

heading (optional)

This specifies the headings to give each column of the table. If this option is not given, there will be no headings.

The option should be given as a reference to an array. The first index, "0", of the headings is always the heading for the button column, regardless of the setting for "button_column". This array must have the same number of elements as each index of the "options" array or results of the method called as the "option_sub" option.

VALIDATION

The validation for this control works as follows:

1. If the "required" option is set to true, then something must be set. If nothing is set, an error occurs.

2. If the "multiple" option is set to to false, then no more than one option may be set. If multiple options are set, an error occurs.

3. For every option checked with the form, the value of that option must exist in the list of values in the "options" setting or must exist in the list returned by "options_sub".

If validation passes all of these tests, then a value named according to the "name" option will be added to the results. If "multiple" is set, this option will be an array reference containing zero or more elements. If "multiple" is not set, it will be a scalar or undef. Obviously, if "required" is set, then the array reference would contain one or more elements and the scalar couldn't be undef.

Any query parameter set to an empty string will be considered as unset. This allows for controls with "multiple" set to false and "required" set to false to be deselected if an option with an empty string value is supplied. This also means that the empty string is ignored as an option value.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@cpan.org>

LICENSE AND COPYRIGHT

Copyright 2005 Andrew Sterling Hanenkamp <hanenkamp@cpan.org>. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.