CGI::FormBuilder::Field - phpMan

Che Dong
NAME
    CGI::FormBuilder::Field - Base class for FormBuilder fields

SYNOPSIS
        use CGI::FormBuilder::Field;

        # delegated straight from FormBuilder
        my $f = CGI::FormBuilder::Field->new($form, name => 'whatever');

        # attribute functions
        my $n = $f->name;         # name of field
        my $n = "$f";             # stringify to $f->name

        my $t = $f->type;         # auto-type
        my @v = $f->value;        # auto-stickiness
        my @o = $f->options;      # options, aligned and sorted

        my $l = $f->label;        # auto-label
        my $h = $f->tag;          # field XHTML tag (name/type/value)
        my $s = $f->script;       # per-field JS validation script

        my $m = $f->message;      # error message if invalid
        my $m = $f->jsmessage;    # JavaScript error message

        my $r = $f->required;     # required?
        my $k = $f->validate;     # run validation check

        my $v = $f->tag_value;    # value in tag (stickiness handling)
        my $v = $f->cgi_value;    # CGI value if any
        my $v = $f->def_value;    # manually-specified value

        $f->field(opt => 'val');  # FormBuilder field() call

DESCRIPTION
    This module is internally used by FormBuilder to create and maintain
    field information. Usually, you will not want to directly access this
    set of data structures. However, one big exception is if you are going
    to micro-control form rendering. In this case, you will need to access
    the field objects directly.

    To do so, you will want to loop through the fields in order:

        for my $field ($form->field) {

            # $field holds an object stringified to a field name
            if ($field =~ /_date$/) {
                $field->sticky(0);  # clear CGI value
                print "Enter $field here:", $field->tag;
            } else {
                print $field->label, ': ', $field->tag;
            }
        }

    As illustrated, each $field variable actually holds a stringifiable
    object. This means if you print them out, you will get the field name,
    allowing you to check for certain fields. However, since it is an
    object, you can then run accessor methods directly on that object.

    The most useful method is "tag()". It generates the HTML input tag for
    the field, including all option and type handling, and returns a string
    which you can then print out or manipulate appropriately.

    Second to this method is the "script" method, which returns the
    appropriate JavaScript validation routine for that field. This is useful
    at the top of your form rendering, when you are printing out the leading
    "<head>" section of your HTML document. It is called by the $form method
    of the same name.

    The following methods are provided for each $field object.

METHODS
  new($form, %args)
    This creates a new $field object. The first argument must be a reference
    to the top-level $form object, for callbacks. The remaining arguments
    should be hash, of which one "key/value" pair must specify the "name" of
    the field. Normally you should not touch this method. Ever.

  field(%args)
    This is a delegated field call. This is how FormBuilder tweaks its
    fields. Once you have a $field object, you call this method the exact
    same way that you would call the main "field()" method, minus the field
    name. Again you should use the top-level call instead.

  inflate($subref)
    This sets the inflate attribute: subroutine reference used to inflate
    values returned by value() into objects or whatever you want. If no
    parameter, returns the inflate subroutine reference that is set. For
    example:

     use DateTime::Format::Strptime;
     my $date_format = DateTime::Format::Strptime->new(
        pattern   => '%D',    # for MM/DD/YYYY american dates
        locale    => 'en_US',
        time_zone => 'America/Los_Angeles',
     );
     $field->inflate( sub { return $date_format->format_datetime(shift) } );

  invalid
    This returns the opposite value that "validate()" would return, with
    some extra magic that keeps state for form rendering purposes.

  jsfunc()
    Returns the appropriate JavaScript validation code (see above).

  label($str)
    This sets and returns the field's label. If unset, it will be generated
    from the name of the field.

  tag($type)
    Returns an XHTML form input tag (see above). By default it renders the
    tag based on the type set from the top-level field method:

        $form->field(name => 'poetry', type => 'textarea');

    However, if you are doing custom rendering you can override this
    temporarily by passing in the type explicitly. This is usually not
    useful unless you have a custom rendering module that forcibly overrides
    types for certain fields.

  type($type)
    This sets and returns the field's type. If unset, it will automatically
    generate the appropriate field type, depending on the number of options
    and whether multiple values are allowed:

        Field options?
            No = text (done)
            Yes:
                Less than 'selectnum' setting?
                    No = select (done)
                    Yes:
                        Is the 'multiple' option set?
                        Yes = checkbox (done)
                        No:
                            Have just one single option?
                                Yes = checkbox (done)
                                No = radio (done)

    For an example, view the inside guts of this module.

  validate($pattern)
    This returns 1 if the field passes the validation pattern(s) and
    "required" status previously set via required() and (possibly) the
    top-level new() call in FormBuilder. Usually running per-field
    validate() calls is not what you want. Instead, you want to run the one
    on $form, which in turn calls each individual field's and saves some
    temp state.

  value($val)
    This sets the field's value. It also returns the appropriate value: CGI
    if set, otherwise the manual default value. Same as using "field()" to
    retrieve values.

  tag_value()
    This obeys the "sticky" flag to give a different interpretation of CGI
    values. Use this to get the value if generating your own tag. Otherwise,
    ignore it completely.

  cgi_value()
    This always returns the CGI value, regardless of "sticky".

  def_value()
    This always returns the default value, regardless of "sticky".

  tag_name()
    This returns the tag name of the current item. This was added so you
    could subclass, say, "CGI::FormBuilder::Field::select" and change the
    HTML tag to "<b:select>" instead. This is an experimental feature and
    subject to change wildly (suggestions welcome).

  accessors
    In addition to the above methods, accessors are provided for directly
    manipulating values as if from a "field()" call:

        Accessor                Same as...
        ----------------------- -----------------------------------
        $f->force(0|1)          $form->field(force => 0|1)
        $f->options(\@opt)      $form->field(options => \@opt)
        $f->multiple(0|1)       $form->field(multiple => 0|1)
        $f->message($mesg)      $form->field(message => $mesg)
        $f->jsmessage($mesg)    $form->field(jsmessage => $mesg)
        $f->jsclick($code)      $form->field(jsclick => $code)
        $f->sticky(0|1)         $form->field(sticky => 0|1);
        $f->force(0|1)          $form->field(force => 0|1);
        $f->growable(0|1)       $form->field(growable => 0|1);
        $f->other(0|1)          $form->field(other => 0|1);

SEE ALSO
    CGI::FormBuilder

REVISION
    $Id: Field.pm 100 2007-03-02 18:13:13Z nwiger $

AUTHOR
    Copyright (c) Nate Wiger <http://nateware.com>. All Rights Reserved.

    This module is free software; you may copy this under the terms of the
    GNU General Public License, or the Artistic License, copies of which
    should have accompanied your Perl kit.