view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    
            my $form = $c->stash->{form};
            my $user = $c->stash->{user};
    
            if ( $form->submitted_and_valid ) {
    
                $form->model->update( $user );
    
                $c->res->redirect( $c->uri_for( "/user/$id" ) );
                return;
            }
    
            $form->model->default_values( $user )
                if ! $form->submitted;
    
        }

    Note: Because "process" is automatically called for you by the Catalyst
    controller; if you make any modifications to the form within your
    action method, such as adding or changing elements, adding constraints,
    etc; you must call "process" again yourself before using
    "submitted_and_valid", any of the methods listed under "SUBMITTED FORM
    VALUES AND ERRORS" or "MODIFYING A SUBMITTED FORM", or rendering the
    form.

    Here's an example of a config file to create a basic login form (all
    examples here are YAML, but you can use any format supported by
    Config::Any), you can also create forms directly in your perl code,
    rather than using an external config file.

        ---
        action: /login
        indicator: submit
        auto_fieldset: 1
    
        elements:
          - type: Text
            name: user
            constraints:
              - Required
    
          - type: Password
            name: pass
            constraints:
              - Required
    
          - type: Submit
            name: submit
    
        constraints:
          - SingleValue

DESCRIPTION

    HTML::FormFu is a HTML form framework which aims to be as easy as
    possible to use for basic web forms, but with the power and flexibility
    to do anything else you might want to do (as long as it involves
    forms).

    You can configure almost any part of formfu's behaviour and output. By
    default formfu renders "XHTML 1.0 Strict" compliant markup, with as
    little extra markup as possible, but with sufficient CSS class names to
    allow for a wide-range of output styles to be generated by changing
    only the CSS.

    All methods listed below (except "new") can either be called as a
    normal method on your $form object, or as an option in your config
    file. Examples will mainly be shown in YAML config syntax.

    This documentation follows the convention that method arguments
    surrounded by square brackets [] are optional, and all other arguments
    are required.

BUILDING A FORM

 new

    Arguments: [\%options]

    Return Value: $form

    Create a new HTML::FormFu object.

    Any method which can be called on the HTML::FormFu object may instead
    be passed as an argument to "new".

        my $form = HTML::FormFu->new({
            action        => '/search',
            method        => 'GET',
            auto_fieldset => 1,
        });

 load_config_file

    Arguments: $filename

    Arguments: \@filenames

    Return Value: $form

    Accepts a filename or list of file names, whose filetypes should be of
    any format recognized by Config::Any.

    The content of each config file is passed to "populate", and so are
    added to the form.

    "load_config_file" may be called in a config file itself, so as to
    allow common settings to be kept in a single config file which may be
    loaded by any form.

        ---
        load_config_file:
          - file1
          - file2

    YAML multiple documents within a single file. The document start marker
    is a line containing 3 dashes. Multiple documents will be applied in
    order, just as if multiple filenames had been given.

    In the following example, multiple documents are taken advantage of to
    load another config file after the elements are added. (If this were a

README  view on Meta::CPAN

    Return Value: $model

 model_config

    Arguments: \%config

MODIFYING A SUBMITTED FORM

 add_valid

    Arguments: $name, $value

    Return Value: $value

    The provided value replaces any current value for the named field. This
    value will be returned in subsequent calls to "params" and "param" and
    the named field will be included in calculations for "valid".

 clear_errors

    Deletes all errors from a submitted form.

RENDERING A FORM

 render

    Return Value: $string

    You must call "process" once after building the form, and before
    calling "render".

 start

    Return Value: $string

    Returns the form start tag, and any output of "form_error_message" and
    "javascript".

 end

    Return Value: $string

    Returns the form end tag.

 hidden_fields

    Return Value: $string

    Returns all hidden form fields.

PLUGIN SYSTEM

    HTML::FormFu provides a plugin-system that allows plugins to be easily
    added to a form or element, to change the default behaviour or output.

    See HTML::FormFu::Plugin for details.

ADVANCED CUSTOMISATION

    By default, formfu renders "XHTML 1.0 Strict" compliant markup, with as
    little extra markup as possible. Many hooks are provided to add
    programatically-generated CSS class names, to allow for a wide-range of
    output styles to be generated by changing only the CSS.

    Basic customisation of the markup is possible via the layout and
    multi_layout methods. This allows you to reorder the position of
    various parts of each field - such as the label, comment, error
    messages and the input tag - as well as inserting any other arbitrary
    tags you may wish.

    If this is not sufficient, you can make completely personalise the
    markup by telling HTML::FormFu to use an external rendering engine,
    such as Template Toolkit or Template::Alloy. See "render_method" and
    "tt_module" for details.

    Even if you set HTML::FormFu to use Template::Toolkit to render, the
    forms, HTML::FormFu can still be used in conjunction with whichever
    other templating system you prefer to use for your own page layouts,
    whether it's HTML::Template: <TMPL_VAR form>, Petal: <form
    tal:replace="form"></form> or Template::Magic: <!-- {form} -->.

    As of HTML::FormFu v1.00, TT is no longer listed a required
    prerequisite - so you'll need to install it manually if you with to use
    the template files.

 render_method

    Default Value: string

    Can be set to tt to generate the form with external template files.

    To customise the markup, you'll need a copy of the template files,
    local to your application. See "Installing the TT templates" in
    HTML::FormFu::Manual::Cookbook for further details.

    You can customise the markup for a single element by setting that
    element's "render_method" to tt, while the rest of the form uses the
    default string render-method. Note though, that if you try setting the
    form or a Block's "render_method" to tt, and then set a child element's
    "render_method" to string, that setting will be ignored, and the child
    elements will still use the tt render-method.

        ---
        elements:
          - name: foo
            render_method: tt
            filename: custom_field
    
          - name: bar
    
        # in this example, 'foo' will use a custom template,
        # while bar will use the default 'string' rendering method

    This method is a special 'inherited accessor', which means it can be
    set on the form, a block element or a single element. When the value is
    read, if no value is defined it automatically traverses the element's
    hierarchy of parents, through any block elements and up to the form,
    searching for a defined value.

    Is an inheriting accessor.