.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CGI::Test::Form 3pm" .TH CGI::Test::Form 3pm "2022-06-10" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CGI::Test::Form \- Querying interface to CGI form widgets .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& my $form = $page\->forms\->[0]; # first form in CGI::Test::Page \& \& # \& # Querying interface, to access form widgets \& # \& \& my @buttons = $form\->button_list; # \->buttons would give list ref \& my $radio_listref = $form\->radios; # \->radios_list would give list \& \& my $passwd_widget = $form\->input_by_name("password"); \& my ($login, $passwd) = $form\->input_by_name(qw(login password)); \& \& my @menus = $form\->widgets_matching(sub { $_[0]\->is_menu }); \& my @menus = $form\->menu_list; # same as line above \& \& my $rg = $form\->radio_groups; # a CGI::Test::Form::Group or undef \& \& # \& #
attributes, as defined by HTML 4.0 \& # \& \& my $encoding = $form\->enctype; \& my $action = $form\->action; \& my $method = $form\->method; \& my $name = $form\->name; \& my $accept = $form\->accept; \& my $accept_charset = $form\->accept_charset; \& \& # \& # Miscellaneous \& # \& \& # Low\-level, direct calls normally not needed \& $form\->reset; \& my $new_page = $form\->submit; \& \& # Very low\-level access \& my $html_tree = $form\->tree; # HTML::Element form tree \& my $page = $form\->page; # Page containing this form \& \& # \& # Garbage collection \-\- needed to break circular references \& # \& \& $form\->delete; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \f(CW\*(C`CGI::Test::Form\*(C'\fR class provides an interface to the content of the \s-1CGI\s0 forms. Instances are automatically created by \f(CW\*(C`CGI::Test\*(C'\fR when it analyzes an \s-1HTML\s0 output from a \s-1GET/POST\s0 request and encounters such beasts. .PP This class is really the basis of the \f(CW\*(C`CGI::Test\*(C'\fR testing abilities: it provides the necessary routines to query the \s-1CGI\s0 widgets present in the form: buttons, input areas, menus, etc... Queries can be made by type, and by name. There is also an interface to specifically access groupped widgets like checkboxes and radio buttons. .PP All widgets returned by the queries are polymorphic objects, heirs of \&\f(CW\*(C`CGI::Test::Form::Widget\*(C'\fR. If the querying interface can be compared to the human eye, enabling you to locate a particular graphical item on the browser screen, the widget interface can be compared to the mouse and keyboard, allowing you to interact with the located graphical components. Please refer to CGI::Test::Form::Widget for interaction details. .PP Apart from the widget querying interface, this class also offers a few services to other \f(CW\*(C`CGI::Test\*(C'\fR components, like handling of \fIreset\fR and \&\fIsubmit\fR actions, which need not be used directly in practice. .PP Finally, it provides inspection of the <\s-1FORM\s0> tag attributes (encoding type, action, etc...) and, if you really need it, to the \s-1HTML\s0 tree of the all <\s-1FORM\s0> content. This interface is based on the \f(CW\*(C`HTML::Element\*(C'\fR class, which represents a tree node. The tree is shared with other \&\f(CW\*(C`CGI::Test\*(C'\fR components, it is not a private copy. See HTML::Element if you are not already familiar with it. .PP If memory is a problem, you must be aware that circular references are used almost everywhere within \f(CW\*(C`CGI::Test\*(C'\fR. Because Perl's garbage collector cannot reclaim objects that are part of such a reference loop, you must explicitely call the \fIdelete\fR method on \f(CW\*(C`CGI::Test::Form\*(C'\fR. Simply forgetting about the reference to that object is not enough. Don't bother with it if your regression test scripts die quickly. .SH "INTERFACE" .IX Header "INTERFACE" The interface is mostly a querying interface. Most of the routines return widget objects, via lists or list references. See CGI::Test::Form::Widget for details about the interface provided by widget objects, and the classification. .PP The order of the widgets returned lists is the same as the order the widgets appear in the \s-1HTML\s0 representation. .SS "Type Querying Interface" .IX Subsection "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. .PP The \fIItem Polymorphic Type\fR 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 \f(CW\*(C`CGI::Test::Form::\*(C'\fR in front of them to get the real type. .PP .Vb 10 \& 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 .Ve .PP For instance: .PP .Vb 2 \& my @widgets = @{$form\->widgets}; # heavy style \& my @widgets = $form\->widget_list; # light style .Ve .PP 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 \f(CW\*(C`widget_list\*(C'\fR (which lists \fIall\fR widgets), in the \f(CW\*(C`button_list\*(C'\fR and in the \f(CW\*(C`submit_list\*(C'\fR. .SS "Name Querying Interface" .IX Subsection "Name Querying Interface" Those routine take a name or a list of names, and return the widgets whose parameter name is \fBexactly\fR the given name (string comparison). You may query all widgets, or a particular class, like all buttons, or all input fields. .PP There are two groups of routines: .IP "\(bu" 4 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: .Sp .Vb 3 \& my @hidden = $form\->hidden_by_name("foo", "bar"); \& my ($context) = $form\->hidden_by_name("context"); \& my $context = $form\->hidden_by_name("context"); .Ve .Sp When no widget (of that particular type) bearing the requested name is found, \&\f(CW\*(C`undef\*(C'\fR is returned for that particular slot, so don't blindly make method calls on each returned value. .Sp We shall call that group of query routines the \fBby-name\fR group. .IP "\(bu" 4 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. .Sp .Vb 1 \& my @hidden = $form\->hidden_named("foo"); .Ve .Sp Don't assume that only radios and checkboxes can have multiple instances bearing the same name. .Sp We shall call that group of query routines the \fBall-named\fR group. .PP The available routines are listed in the table below. Note that \fIby-name\fR queries are singular, because there is at most one returned widget per name asked, whereas \fIall-named\fR queries are plural, where possible. .PP The \fIItem Polymorphic Type\fR 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 \f(CW\*(C`CGI::Test::Form::\*(C'\fR in front of them to get the real type. .PP .Vb 10 \& 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 .Ve .SS "Match Querying Interface" .IX Subsection "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: .PP .Vb 1 \& my @matching = $form\->widgets_matching(sub {code}, $arg); .Ve .PP and the callback is invoked as: .PP .Vb 1 \& callback($widget, $arg); .Ve .PP 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. .PP Each matching routine returns a list of matching widgets. Using the \f(CW$arg\fR parameter is optional, and should be avoided unless you have no other choice, so as to be as stateless as possible. .PP 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 \f(CW\*(C`CGI::Test::Form::\*(C'\fR to get the real type. .PP .Vb 10 \& 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 .Ve .PP For instance: .PP .Vb 4 \& my @menus = $form\->widgets_matching(sub { $_[0]\->is_menu }); \& my @color = $form\->widgets_matching( \& sub { $_[0]\->is_menu && $_[0]\->name eq "color" } \& ); .Ve .PP is an inefficient way of saying: .PP .Vb 2 \& my @menus = $form\->menu_list; \& my @color = $form\->menus_matching(sub { $_[0]\->name eq "color" }); .Ve .PP and the latter can further be rewritten as: .PP .Vb 1 \& my @color = $form\->menus_named("color"); .Ve .SS "Form Interface" .IX Subsection "Form Interface" This provides an interface to get at the attributes of the <\s-1FORM\s0> tag. For instance: .PP .Vb 1 \& my $enctype = $form\->enctype; .Ve .PP to get at the encoding type of that particular form. The following attributes are available: .PP .Vb 6 \& accept \& accept_charset \& action \& enctype \& method \& name .Ve .PP as defined by \s-1HTML 4.0.\s0 .SS "Group Querying Interface" .IX Subsection "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). .PP All radio buttons and checkboxes defined in a form are automatically inserted into a group of their own, which is an instance of the \&\f(CW\*(C`CGI::Test::Form::Group\*(C'\fR class. This class contains all the defined groups for a particular kind. The routines: .PP .Vb 2 \& checkbox_groups \& radio_groups .Ve .PP give you access to the \f(CW\*(C`CGI::Test::Form::Group\*(C'\fR container. Both routines may return \f(CW\*(C`undef\*(C'\fR when there is no checkbox or radio button in the form. See CGI::Test::Form::Group for its querying interface. .SS "Memory Cleanup" .IX Subsection "Memory Cleanup" You \fBmust\fR call the \fIdelete\fR method to break the circular references if you wish to dispose of the object. .SS "Internal Interface" .IX Subsection "Internal Interface" The following routines are available internally: .IP "reset" 4 .IX Item "reset" Reset the form state, restoring all the controls to the value they had upon entry. .IP "submit" 4 .IX Item "submit" Submit the form, returning a \f(CW\*(C`CGI::Test::Page\*(C'\fR reply. .SH "AUTHORS" .IX Header "AUTHORS" The original author is Raphael Manfredi. .PP Steven Hilton was long time maintainer of this module. .PP Current maintainer is Alexander Tokarev \fI\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBCGI::Test\fR\|(3), \fBCGI::Test::Form::Widget\fR\|(3), \fBCGI::Test::Form::Group\fR\|(3), \&\fBCGI::Test::Page\fR\|(3), \fBHTML::Element\fR\|(3).