view release on metacpan or  search on metacpan

Changes  view on Meta::CPAN

  New FORMBUILDER_DEBUG environment variable
    Setting this has the same effect as using the "debug" option.

  Removal of excess documentation
    Removed all the stub docs from "Field::*" and "Messages::*" to make CPAN
    happy.

VERSION 3.0302
    This is a bugfix release to repair these main items:

        - optgroups bugfix for complex arrays
        - removal of HTML::Entities support due to utf8 issues
        - new es_ES Messages module with better translations
        - a patch from Mark Hedges to enable plugin modules for mailresults()

    The rest of the features remain the same as below.

VERSION 3.03
  Subclassable Fields
    Each field is now rendered by its own class, named for the field type.
    For example, text fields are rendered by
    "CGI::FormBuilder::Field::text". This allows you to create custom field
    types and plugging them in by creating your own
    "CGI::FormBuilder::Field::whatever_you_want" module. Thanks to Peter
    Eichman for his contributions to this scheme.

  Messages Localization
    All messages are now handled in a similar way to field types: They are
    delegated to "CGI::FormBuilder::Messages::locale" where "locale" is the
    appropriate string such as "en_US" or "da_DK". A number of localizations
    are included as part of the standard distribution.

    There are two ways to use these messages: Either the 'auto' messages
    mode or by specifying a specific locale:

        my $form = CGI::FormBuilder->new(messages => 'auto');   # check client
        my $form = CGI::FormBuilder->new(messages => ':da_DK'); # specified

    You can create your own messages by copying "_example.pm" and modifying
    it for your language. When using messages in this way, the HTTP Charset
    is changed to "utf-8".

  Select optgroup support
    By using the "field()" option "optgroups", you can now cause select
    fields to automatically generate optgroup tags:

        $form->field(name => 'browser', options => \@opt, optgroups => 1);

    See the documentation on "optgroups" for more details.

  Data::FormValidator Support
    Thanks to another great patch from Peter Eichman, "Data::FormValidator"
    is supported as a validation option to "new()", just by passing it in as
    an object. See the documentation on "validate" for more information.

  Option sorting by LABELNAME or LABELNUM
    You can now sort options by "LABELNAME" or "LABELNUM", similar to the
    value-based sorting of "NAME" and "NUM". See the documentation for more
    details.

  XHTML Compliance
    Generated code now validates against <http://validator.w3.org>. This
    includes stuff like lowercase "get" and "post" methods, lowercase
    "onchange" and "onsubmit" actions, and so on.

VERSION 3.02
  Multi-Page Form Support
    A new module, "CGI::FormBuilder::Multi", has been added to handle the
    navigation and state of multi-page forms. A multi-page form is actually
    composed of several individual forms, tied together with the special CGI
    param "_page":

        my $multi = CGI::FormBuilder::Multi->new(
                         # first args are hashrefs per-form
                         \%form1_opts,
                         \%form2_opts,
                         \%form3_opts,

                         # remaining options apply to all forms
                         header => 1,
                         method => 'POST',
                    );

        my $form = $multi->form;    # current form

        if ($form->submitted && $form->validate) {

            # you write this
            do_data_update($form->fields);

            # last page?
            if ($multi->page == $multi->pages) {
                print $form->confirm;
                exit;
            }

            $multi->page++;          # next page counter
            $form = $multi->form;    # fetch next page's form
        }
        print $form->render;

    For more details, see CGI::FormBuilder::Multi.

  External Source File
    Inspired by Peter Eichman's "Text::FormBuilder", the new "source" option
    has been added to "new()" which enables the use of an external config
    file to initialize FormBuilder. This file takes the format:

        # sample config file
        method: POST
        header: 1
        submit: Update, Delete

        fields:
            fname:
                label: First Name
                size:  50
                validate: NAME
            lname:
                label: Last Name
                size:  40

Changes  view on Meta::CPAN

    meaning that you can create an entire template engine with something
    like this:

        package My::HTML::Template;

        use CGI::FormBuilder::Template::HTML;
        use base 'CGI::FormBuilder::Template::HTML';

        # new() is inherited

        sub render {
            my $self = shift;
            my $form = shift;   # complete form object

            # do any special actions here

            $self->SUPER::render;
        }

    For more details, see CGI::FormBuilder::Template.

  Message Changes
    All messages were reworded to make them shorter and easier to read. The
    phrase "You must" was removed from all of them. To see the new messages,
    cut-and-paste this code:

        perl -MCGI::FormBuilder::Messages \
             -e 'CGI::FormBuilder::Messages->messages'

    In addition, the "form_submit_default" and "form_reset_default" messages
    were not even being used, and field labels were not being properly
    highlighted on error. These problems have been fixed.

  Autoloaded Fields
    The 2.x feature of "$form->$fieldname()" has been reimplemented, but
    using it requires the "fieldsubs" option:

        my $form = CGI::FormBuilder->new(fields => \@f, fieldsubs => 1);

    Read the docs for some caveats.

  Disabled Form
    Similar to a static form, you can set "disabled => 1" in "new()" or
    "render()" to display a form with grayed-out input boxes. You can also
    set this on a per-field basis using "field()".

  Verbatim HTML Options
    If you want to include HTML in your field options, set "cleanopts" to 0
    in "field()" (for one field) or "new()" (for all fields).

  Compatibility Methods
    For compatibility with other modules, FormBuilder now includes
    "param()", "query_string()", "self_url()", and "script_name()".

VERSION 3.01
    This was a bugfix release, including the following changes:

        - fixed major problems with keepextras, including a reversed ismember test
        - added debug messages to keepextras and changed a few other debugs
        - added patch from Peter Eichman to fix scalar $field->tag and $field->tag_value
        - converted most all XHTML generation methods to only returning scalars
        - fixed the columns option which was totally broken for radio buttons
        - added a feature to plop in {border => 0} in columns as well
        - added the 2.x 'override' alias for field() 'force' which was missing
        - also added a 'defaults' alias for field() 'value' for CGI.pm happiness
        - more tests since there were way too many bugs

    In addition there were many documentation updates and changes.

VERSION 3.00
  Internals
    The internals have been completely rewritten, nearly from the ground up.
    All of the major functions have been split into methods, and objects
    have been created for the form, fields, messages, CGI params, and so on.
    Several new sub-modules have been created, including:

        CGI::FormBuilder::Field
        CGI::FormBuilder::Messages
        CGI::FormBuilder::Template
        CGI::FormBuilder::Template::HTML
        CGI::FormBuilder::Template::Text
        CGI::FormBuilder::Template::TT2

    Many of these modules can be subclassed and overridden if desired. In
    addition, the template engine has been rewritten to allow "plugging in"
    of additional template modules, simply by specifying the name of the
    module to the 'template' option in new().

    For more details, see the man pages for the individual modules above.

  Style Sheets
    Stylesheets are now generated if the "stylesheet" option is specified to
    FormBuilder. This can either be 1 to turn it on, or a full path to a
    style sheet to include. When used, all tags are then output with a
    "class" attribute, named "styleclass" plus the name of the tag:

        my $form = CGI::FormBuilder->new(
                        fields => [qw/name email/],
                        styleclass => 'myFB',   # default is "fb_"
                        stylesheet => 1,        # turn on style
                   );
                
        print $form->render;

        # HTML will include
        #   <input class="myFBname" id="name" name="name" type="text" />
        #   <input class="myFBemail" id="email" name="email" type="text" />

  Compliant XHTML
    The output should be fully-compliant XHTML finally. Really. Maybe.

  Attributes and Field Objects
    Individual accessors have been added for every attribute that
    FormBuilder maintains. For example, here's a snippet of code to
    demonstrate:

        if ($form->stylesheet) {
            # loop thru fields, changing class
            for ($form->fields) {
                next if /_date$/;   # skip fields named "XXX_date"

                # each field is a stringifiable object with accessors
                if ($_->options) {
                    # has options
                    $_->class('my_opt_style');
                } else {
                    # plain text box
                    $_->class('my_text_style');
                }
            }
        }

    This code checks to see if the "stylesheet" property has been set on the
    main $form. If so, then it loops thru all the fields, skipping those
    named "XXX_date". Of the remaining fields, those that have options have
    their "class" attribute changed to "my_opt_style", and those without
    options have it set to "my_text_style".

    In addition, you can individually render every part of the form
    yourself. by calling the appropriate method. For example:

        print $form->header;      # just the header
        print $form->script;      # opening JavaScript
        print $form->title;       # form title
        print $form->start;       # opening <form> tag
        for ($form->fields) {
            print $_->label;      # each field's human label
            print $_->tag;        # each field's <input> tag
        }
        print $form->end;         # closing </form> tag

    For a complete list of accessors, see the documentation for both
    CGI::FormBuilder and CGI::FormBuilder::Field.

  Messages
    Many messages have been reworded, and several new messages were added to
    make it easier to customize individual text. In addition, you can now
    specify messages to individual fields:

        $form->field(name => 'email',
                     message => 'Please enter a valid email address');

    For more details, see "CGI::FormBuilder::Messages".

  HTML::Entities encoding
    HTML character encoding is now dispatched to "HTML::Entities", if
    available. This can be downloaded as part of the "HTML::Parser" module
    set on CPAN.

  Documentation