Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

CGI::FormBuilder::Field
Internally used to create a FormBuilder field

CGI::FormBuilder::Field - Internally used to create a FormBuilder field


NAME

CGI::FormBuilder::Field - Internally used to create a FormBuilder field


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.

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.

invalid

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

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.

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

the CGI::FormBuilder manpage


REVISION

$Id: Field.pm,v 1.39 2005/04/15 18:33:11 nwiger Exp $


AUTHOR

Copyright (c) 2000-2005 Nathan Wiger <nate@sun.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.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy