noble (3) CGI::FormBuilder::Field.3pm.gz

Provided by: libcgi-formbuilder-perl_3.10-6_all bug

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.