NAME

CGI::Form::Table - create a table of form inputs

VERSION

version 0.161

 $Id: /my/cs/projects/formtable/trunk/lib/CGI/Form/Table.pm 27835 2006-11-11T04:18:20.685136Z rjbs  $

SYNOPSIS

 use CGI::Form::Table;

 my $form = CGI::Form::Table->new(
   prefix  => 'employee',
   columns => [qw(lname fname job age)]
 );

 print $form->as_html;
 print $form->javascript;

DESCRIPTION

This module simplifies the creation of an HTML table containing form inputs. The table can be extended to include extra rows, and these rows can be removed. Each has a unique name, and on form submission the inputs are effectively serialized.

CGI::Form::Table::Reader will use the CGI module to produce a data structure based on the parameters submitted by a form of this type.

METHODS

CGI::Form::Table->new(%arg)

This method constructs a new form. The only required arguments are columns, which names the columns that will be in the form table, and prefix, which gives the unique prefix for input fields.

If given, initial_rows specifies how many rows should initially be in the form.

Instead of initial_rows, you can pass initial_values, a reference to an array of hashes providing values for the columns of each row. For example:

 my $table = CGI::Form::Table->new(
  prefix  => "charsheet",
  columns => [ qw(ability score) ],
  initial_values => [
   { ability => 'Str', score => '18/00' },
   { ability => 'Cha', score => '11'    }
  ]
 );

column_header, if passed, is a hash of text strings to use as column headers. The keys are column names. Columns without column_header entries are headed by their names.

Another argument, column_content, may be passed. It must contain a hashref, with entries providing subs to produce initial content. The subs are passed the form object, the row number, and the name of the column. For example, to add a reminder of the current row in the middle of each row, you might create a form like this:

 my $form = CGI::Form::Table->new(
   prefix  => 'simpleform',
   columns => [qw(one two reminder three four)],
   column_content => {
     reminder => sub { $_[1] }
   }
 );

This can be useful for forms that require SELECT elements or other complicated parts. (The JavaScript will just copy the column value when new rows are added, updating the name attribute.)

$form->as_html

This returns HTML representing the form object. JavaScript is required to make the form expandible/shrinkable; see the javascript method. ("SEE ALSO")

$form->column_header($column_name)

This method returns the text that should be used as the column header in the table output. If no header was given in the initialization of the form, the column name is returned verbatim. (No checking is done to ensure that the named column actually exists.)

$form->cell_content($row, $column_name)

This method returns the text (HTML) that should appear in the given row and column. If no column_content entry was given for the column, a basic input element is generated.

$form->cell_value($row, $column_name)

This method returns the default value for the given row and column, taken from the initial_values passed to the initializer.

$class->javascript

This method returns JavaScript that will make the handlers for the HTML buttons work. This code has been (poorly) tested in Firefox, MSIE, and WebKit-based browsers.

SEE ALSO

• http://rjbs.manxome.org/hacks/js/plusminus.html

• CGI::Form::Table::Reader

AUTHOR

Ricardo SIGNES, <rjbs@cpan.org>

BUGS

Please report any bugs or feature requests through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT

Copyright 2004 Ricardo SIGNES, All Rights Reserved.

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