/ 
HTML-Widget-1.03
River stage one • 6 direct dependents • 6 total dependents
/ HTML::Widget

NAME

HTML::Widget - HTML Widget And Validation Framework

SYNOPSIS

use HTML::Widget;

# Create a widget
my $w = HTML::Widget->new('widget')->method('get')->action('/');

# Add some elements
$w->element( 'Textfield', 'age' )->label('Age')->size(3);
$w->element( 'Textfield', 'name' )->label('Name')->size(60);
$w->element( 'Submit', 'ok' )->value('OK');

# Add some constraints
$w->constraint( 'Integer', 'age' )->message('No integer.');
$w->constraint( 'Not_Integer', 'name' )->message('Integer.');
$w->constraint( 'All', 'age', 'name' )->message('Missing value.');

# Add some filters
$w->filter('Whitespace');

# Process
my $result = $w->process;
my $result = $w->process($query);


# Check validation results
my @valid_fields   = $result->valid;
my $is_valid       = $result->valid('foo');
my @invalid_fields = $result->have_errors;
my $is_invalid     = $result->has_errors('foo');;

# CGI.pm-compatible! (read-only)
my $value  = $result->param('foo');
my @params = $result->param;

# Catalyst::Request-compatible
my $value = $result->params->{foo};
my @params = keys %{ $result->params };


# Merge widgets (constraints and elements will be appended)
$widget->merge($other_widget);


# Embed widgets (as fieldset)
$widget->embed($other_widget);


# Complete xml result
[% result %]
[% result.as_xml %]


# Iterate over elements
<form action="/foo" method="get">
[% FOREACH element = result.elements %]
    [% element.field_xml %]
    [% element.error_xml %]
[% END %]
</form>


# Iterate over validation errors
[% FOREACH element = result.have_errors %]
    <p>
    [% element %]:<br/>
    <ul>
    [% FOREACH error = result.errors(element) %]
        <li>
            [% error.name %]: [% error.message %] ([% error.type %])
        </li>
    [% END %]
    </ul>
    </p>
[% END %]

<p><ul>
[% FOREACH element = result.have_errors %]
    [% IF result.error( element, 'Integer' ) %]
        <li>[% element %] has to be an integer.</li>
    [% END %]
[% END %]
</ul></p>

[% FOREACH error = result.errors %]
    <li>[% error.name %]: [% error.message %] ([% error.type %])</li>
[% END %]


# XML output looks like this (easy to theme with css)
<form action="/foo/bar" id="widget" method="post">
    <fieldset>
        <label for="widget_age" id="widget_age_label"
          class="labels_with_errors">
            Age
            <span class="label_comments" id="widget_age_comment">
                (Required)
            </span>
            <span class="fields_with_errors">
                <input id="widget_age" name="age" size="3" type="text"
                  value="24" class="Textfield" />
            </span>
        </label>
        <span class="error_messages" id="widget_age_errors">
            <span class="Regex_errors" id="widget_age_error_Regex">
                Contains digit characters.
            </span>
        </span>
        <label for="widget_name" id="widget_name_label">
            Name
            <input id="widget_name" name="name" size="60" type="text"
              value="sri" class="Textfield" />
            <span class="error_messages" id="widget_name_errors"></span>
        </label>
        <input id="widget_ok" name="ok" type="submit" value="OK" />
    </fieldset>
</form>

DESCRIPTION

Create easy to maintain HTML widgets!

Everything is optional, use validation only or just generate forms, you can embed and merge them later.

The API was designed similar to other popular modules like Data::FormValidator and FormValidator::Simple, HTML::FillInForm is also built in (and much faster).

This Module is very powerful, don't misuse it as a template system!

METHODS

new

$self->action($action)

Contains the form action.

$self->const($tag)

$self->container($tag)

Contains the container tag to use. Defaults to form.

$self->constraint( $type, @names )

Returns a HTML::Widget::Constraint object.

$self->elem( $type, $name )

$self->element( $type, $name )

Returns a HTML::Widget::Element object.

$self->embed(@widgets)

Embed another widget. Note that this will change data in the embedded widgets!

$self->empty_errors(1)

Create spans for errors even when there's no errors.. (For AJAX validation validation)

$self->enctype($enctype)

Contains the form encoding type.

$self->filter( $type, @names )

Returns a HTML::Widget::Filter object.

$self->id($id)

Contains the widget id.

$self->indi($indicator)

$self->indicator($indicator)

Contains the submitted form indicator.

$self->legend($legend)

Contains the legend name for this widget.

$self->merge(@widget)

Merge in another widget.

$self->method($method)

Contains the form method.

$self->result( $query, $uploads )

$self->process( $query, $uploads )

Returns a HTML::Widget::Result object.

$self->query($query)

Contains the query object to use for validation input.

$self->strict($strict)

Only consider parameters that pass at least one constraint valid.

$self->subcontainer($tag)

Contains the subcontainer tag to use. Defaults to fieldset.

$self->uploads($uploads)

Contains a arrayref of Apache2::Upload compatible objects.

SEE ALSO

Catalyst

AUTHOR

Sebastian Riedel, sri@oook.de

LICENSE

This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.