The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
HTML-FormStructure-0.04
River stage zero No dependents
++
/ HTML::FormStructure

NAME

HTML::FormStructure - Accessor for HTML FORM definition

SYNOPSIS

  use HTML::FormStructure;
  use CGI;
  $cgi    = CGI->new;
  $option = { form_accessors  => [qw(foo bar baz)], 
              query_accessors => [qw(foo bar baz)], };

  $form = HTML::FormStructure->new(
      &arrayref_of_queries,
      $cgi_object,
      $option
  );

  sub arrayref_of_queries {
      return [{
        name   => 'user_name',
        type   => 'text',
        more   => 6,
        less   => 255,
        column => 1,
      },{
        name   => 'email',
        type   => 'text',
        more   => 1,
        less   => 255,
        be     => [qw(valid_email)],
        column => 1,
      },{
        name    => 'sex',
        type    => 'radio',
        value   => [1,2],
        checked => 1,
        column  => 1,
      },{
        name    => 'birthday',
        type    => 'text',
        be      => [qw(valid_date)],
        more    => 1,
        less    => 255,
        column  => 1,
        consist => [{
            name => 'year',
            type => 'text',
            more => 1,
            less => 4,
            be   => [qw(is_only_number)],
        },{
            name => 'month',
            type => 'text',
            more => 1,
            less => 2,
            be   => [qw(is_only_number)],
        },{
            name => 'day',
            type => 'text',
            more => 1,
            less => 2,
            be   => [qw(is_only_number)],
        }];
      }];
  }

DESCRIPTION

  HTML::FormStructure hold definition of FORM in your script.
  It have the part of generating FORM tags, validating via itself,
  and storeing cgi(apache request)'s parameters.
  You can access this object in the perl souce code or templates.

Form Accessor

action

  $form->action('foo.cgi');
  $form->action; # foo.cgi

method

  $form->method('POST');
  $form->method; # POST

enctype

  $form->enctype('multipart/form-data')
  $form->enctype; # multipart/form-data

r

  # cgi/apache-req alias.
  $form->r->param('query_name');
  $form->r->param('query_name' => $value);

validator

  # validator object
  $form->validator->method($form->r->param('foo'));
  $form->validator(YourValidate::Clsss->new);

Form Method

list_as_array

  # return the query objects as array.
  @queries = $form->list_as_array;

list_as_arrayref

  # return the query objects as arrayref.
  $queries = $form->list_as_array;

have

  # return the query objects that's defined.
  @queries       = $form->have('column');
  @error_queries = $form->have('error');
  # return the query objects that's equal
  @queries = $form->search(type => 'checkbox');

search_like

  # return the query objects that's matched.
  @queries = $form->search(stored => 'foo');

group

  # return that queries objects that's grouped by value.
  @queries = $form->group('scratch');

fetch

  # get the query object via query name.
  $query = $form->fetch('user_name'); # name => 'user_name'

param

  # get the query stored value via query name.
  # it does not return nothing before $form->store_request called.
  $store = $form->param('user_name');

store_request

  # store the value of cgi/apache-req's param as the 'store'.
  $form->store_request;
  $user_name = $form->param('user_name');

consist_query

  # combine all of consist query
  # each value is stored in r->param.
  $form->consist_query

hashref

  # return the key , value of form object.
  $hashref = $form->hashref(name => 'store');

validate

  # validating each query via "more|less|be"
  $form->validate;

error_messages

  # return error message.
  @error = $form->error_messages;

Query Accessor

name

  # query name
  $query->name;
  $query->name('val');

type

  # query type(text|password|file|hidden|radio|checkbox|select|textarea)
  $query->type;
  $query->type('val');

value

  # query value
  $query->value;
  $query->value('val');
  $query->value([1,2,3]);

checked

  # query checked
  $query->type('radio')
  $query->value('val');
  $query->checked('val');
  $query->tag; # <input type="radio" value="val" checked>

selected

  # query selected
  $query->type('selected')
  $query->value(['foo','bar','val']);
  $query->selected('val');
  $query->tag; # <option value="val" selected>

more

  # query min size
  $query->more('100'); # length 100 checked when validation

less

  # query max size
  $query->less('100'); # length 100 checked when validation

be

  # query validate method name or sub
  # called when $form->validate
  $query->be([qw(foo bar baz)]); # function or method named
                                 # foo,bar,and baz needed in the
                                 # current package.
  $query->be([sub { $_ eq 'foo' }]);

consist

  # define structure of consisted when form's query_combine called.
  $query->consist([{
    name => 'zip1',
    type => 'text',
  },{
    name => 'zip2',
    type => 'text',
  }]);
  # When query_combine called
  # default
            for my $q ($query->array_of('consist')) {
                $value .= $self->r->param($q->name);
            }

consistf

  # format of cosisted
  # consist_* have more priority than this accessor
  $query->consistf("%s-%s-%s");

store

  # query store cgi/apache-req's param
  $query->store;
  $query->store($cgi->param($query->name));

storef

  # query stored format
  $query->storef("%D");

column

  # query have column
  $query->column;
  $query->column(1);
  $query->column('column_name');

error

  # return query error(when validate)
  $query->error; # error message
  $query->store_error([qw(err1,err2)]);

tag_label

  # tag label
  $query->tag_label('user name');
  # in the template
  [% query.tag_label %] : [% query.tag %]
  # user name : <input type="text" name="foo">

tag_attr

  # tag attribute
  $query->tag_attrl('size = "10"');
  # in the template
  [% query.tag %]
  # <input type="text" name="foo" size="10">

tag_desc

  # tag description
  $query->tag_desc('only number');
  # in the template
  [% query.tag_label %] : [% query.tag %] *[% query.tag_desc %]
  # user name : <input type="text" name="foo"> * only number

tag_val_label

  # tag label having key
  $query->tag_val_label({ 1 => 'female', 2 => 'male' });
  # in the template
  [% query.tag %]
  # <input type="radio" name="sex" value="1"> female
  # <input type="radio" name="sex" value="2"> male

tag_left_in / tag_right_in

  $query->tag_val_label({ 1 => 'female', 2 => 'male' });
  $query->tag_left_in('<br>');
  $query->tag_right_in('<br>');
  # in the template
  [% query.tag %]
  # <input type="radio" name="sex" value="1"> female<br>
  # <input type="radio" name="sex" value="2"> male<br>

scratch

  # query scratch pad (free space)
  $query->scratch;
  $query->scratch('foo/bar');

Query Method

tag

  # generate query tag
  $query->tag;
  [% query.tag %]

is_checked

  # check query is check(it's type is 'radio/checkbox').
  $query->is_checked;

is_selected

  # check query is selected(it's type is 'select').
  $query->is_selected;

add (alias of add_right)

  # right concat. push if it's arrayref.
  $query->add(tag_attr => 'size ="10" '); # right

add_right

  # right concat. push if it's arrayref.
  $query->add(tag_attr => 'size ="10" ');

add_left

  # left concat. unshift if it's arrayref.
  $query->add(tag_attr => 'size ="10" ');

OPTION

form_accessors

  # additional accessor in the Form Class.

query_accessors

  # additional accessor in the Query Class.

AUTHOR

Naoto Ishikawa <toona@edge.jp>

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

SEE ALSO