Type Querying Interface¶

There are two groups or routines: one group returns expanded lists, the other returns list references. They are listed in the table below.

The Item Polymorphic Type column refers to the polymorphic dynamic type of items held within the list: each item is guaranteed to at least be of that type, but can be a descendant. Types are listed in the abridged form, and you have to prepend the string "CGI::Test::Form::" in front of them to get the real type.

 Expanded List  List Reference  Item Polymorphic Type
 -------------  --------------  ----------------------
 button_list    buttons         Widget::Button
 checkbox_list  checkboxes      Widget::Box::Check
 hidden_list    hidden          Widget::Hidden
 input_list     inputs          Widget::Input
 menu_list      menus           Widget::Menu
 radio_list     radios          Widget::Box::Radio
 submit_list    submits         Widget::Button::Submit
 widget_list    widgets         Widget

For instance:

    my @widgets = @{$form->widgets};     # heavy style
    my @widgets = $form->widget_list;    # light style

A given widget may appear in several lists, i.e.the above do not form a partition over the widget set. For instance, a submit button would appear in the "widget_list" (which lists all widgets), in the "button_list" and in the "submit_list".

Name Querying Interface¶

Those routine take a name or a list of names, and return the widgets whose parameter name is exactly the given name (string comparison). You may query all widgets, or a particular class, like all buttons, or all input fields.

There are two groups of routines:

• One group allows for multiple name queries, and returns a list of widgets, one entry for each listed name. Some widgets like radio buttons may have multiple instances bearing the same name, and in that case only one is returned. When querying for one name, you are allowed to use scalar context:

      my  @hidden   = $form->hidden_by_name("foo", "bar");
      my ($context) = $form->hidden_by_name("context");
      my  $context  = $form->hidden_by_name("context");
      

  When no widget (of that particular type) bearing the requested name is found, "undef" is returned for that particular slot, so don't blindly make method calls on each returned value.

  We shall call that group of query routines the by-name group.

• The other group allows for a single name query, but returns a list of all the widgets (of some particular type when not querying the whole widget list) bearing that name.

      my @hidden = $form->hidden_named("foo");
      

  Don't assume that only radios and checkboxes can have multiple instances bearing the same name.

  We shall call that group of query routines the all-named group.

The available routines are listed in the table below. Note that by-name queries are singular, because there is at most one returned widget per name asked, whereas all-named queries are plural, where possible.

The Item Polymorphic Type column refers to the polymorphic dynamic type of items held within the list: each defined item is guaranteed to at least be of that type, but can be a descendant. Types are listed in the abridged form, and you have to prepend the string "CGI::Test::Form::" in front of them to get the real type.

 By-Name Queries   All-Named Queries  Item Polymorphic Type
 ----------------  -----------------  ----------------------
 button_by_name    buttons_named      Widget::Button
 checkbox_by_name  checkboxes_named   Widget::Box::Check
 hidden_by_name    hidden_named       Widget::Hidden
 input_by_name     inputs_named       Widget::Input
 menu_by_name      menus_named        Widget::Menu
 radio_by_name     radios_named       Widget::Box::Radio
 submit_by_name    submits_named      Widget::Button::Submit
 widget_by_name    widgets_named      Widget

Match Querying Interface¶

This is a general interface, which invokes a matching callback on each widget of a particular category. The signature of the matching routines is:

    my @matching = $form->widgets_matching(sub {code}, $arg);

and the callback is invoked as:

    callback($widget, $arg);

A widget is kept if, and only if, the callback returns true. Be sure to write your callback so that is only uses calls that apply to the particular widget. When you know you're matching on menu widgets, you can call menu-specific features, but should you use that same callback for buttons, you would get a runtime error.

Each matching routine returns a list of matching widgets. Using the $arg parameter is optional, and should be avoided unless you have no other choice, so as to be as stateless as possible.

The following table lists the available matching routines, along with the polymorphic widget type to be expected in the callback. As usual, you must prepend the string "CGI::Test::Form::" to get the real type.

 Matching Routine     Item Polymorphic Type
 -------------------  ---------------------
 buttons_matching     Widget::Button
 checkboxes_matching  Widget::Box::Check
 hidden_matching      Widget::Hidden
 inputs_matching      Widget::Input
 menus_matching       Widget::Menu
 radios_matching      Widget::Box::Radio
 submits_matching     Widget::Button::Submit
 widgets_matching     Widget

For instance:

    my @menus = $form->widgets_matching(sub { $_[0]->is_menu });
    my @color = $form->widgets_matching(
        sub { $_[0]->is_menu && $_[0]->name eq "color" }
    );

is an inefficient way of saying:

    my @menus = $form->menu_list;
    my @color = $form->menus_matching(sub { $_[0]->name eq "color" });

and the latter can further be rewritten as:

    my @color = $form->menus_named("color");

Form Interface¶

This provides an interface to get at the attributes of the <FORM> tag. For instance:

    my $enctype = $form->enctype;

to get at the encoding type of that particular form. The following attributes are available:

    accept
    accept_charset
    action
    enctype
    method
    name

as defined by HTML 4.0.

Group Querying Interface¶

There are two kinds of widgets that are architecturally groupped, meaning more that one instance of that widget can bear the same name: radio buttons and checkboxes (although you may have a single standalone checkbox).

All radio buttons and checkboxes defined in a form are automatically inserted into a group of their own, which is an instance of the "CGI::Test::Form::Group" class. This class contains all the defined groups for a particular kind. The routines:

    checkbox_groups
    radio_groups

give you access to the "CGI::Test::Form::Group" container. Both routines may return "undef" when there is no checkbox or radio button in the form. See CGI::Test::Form::Group for its querying interface.

Memory Cleanup¶

You must call the delete method to break the circular references if you wish to dispose of the object.

Internal Interface¶

The following routines are available internally:

reset

Reset the form state, restoring all the controls to the value they had upon entry.

submit

Submit the form, returning a "CGI::Test::Page" reply.