[Catalyst] [Announce] HTML::Widget 1.0 released!

[Sebastian Riedel]

HTML::Widget is a new elegant way to handle HTML form generation and  
validation.

     http://search.cpan.org/dist/HTML-Widget/
     http://search.cpan.org/dist/Catalyst-Plugin-HTML-Widget/

     http://search.cpan.org/src/SRI/HTML-Widget-1.01/examples/big.pl
     http://search.cpan.org/src/SRI/HTML-Widget-1.01/examples/simple.css


Here are some examples:


     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>


There is also a Catalyst plugin to make it even easier. :)


     use Catalyst qw/HTML::Widget;

     $c->widget('foo')->method('get')->action('/foo/action');   #  
will initialize a new widget

     $c->widget('foo')->element( 'Textfield', 'age' )->label('Age')- 
 >size(3);
     $c->widget('foo')->element( 'Textfield', 'name' )->label('Name')- 
 >size(60);
     $c->widget('foo')->element( 'Submit', 'ok' )->value('OK');

     $c->widget('foo')->constraint( 'Integer', 'age' )->message('No  
integer.');
     $c->widget('foo')->constraint( 'All', 'age', 'name' )
         ->message('Missing value.');

     $c->widget( HTML::Widget->new('foo') );   # will also initialize  
a new widget

     $c->widget('foo')->indicator('some_field');    # this field will  
indicate a submitted form

     my $result = $c->widget('foo')->process;
     my $result = $c->widget('foo')->process($query);

     my $result = $c->widget_result('foo');      #  with query params


Btw. The most frequently asked question so far was "Can i use the  
form validation stuff without form generation?", the answer is "YES!!!".

And PLEASE, don't misuse HTML::Widget as a template system, i know  
it's very powerful but not that powerful. :)


--
sebastian