CGI::Test::Form::Widget - Ancestor of all form widget classes
# Deferred class, only heirs can be created
The CGI::Test::Form::Widget class is deferred. It is an abstract representation of a <FORM> widget, i.e. a graphical control element like a popup menu or a submit button.
CGI::Test::Form::Widget
Here is an outline of the class hierarchy tree, with the leading CGI::Test::Form:: string stripped for readability, and a trailing * indicating deferred classes:
CGI::Test::Form::
*
Widget* . Widget::Box* . . Widget::Box::Check . . Widget::Box::Radio . Widget::Button* . . Widget::Button::Plain . . Widget::Button::Submit . . Widget::Button::Image . . Widget::Button::Reset . Widget::Hidden . Widget::Input* . . Widget::Input::Text_Area . . Widget::Input::Text_Field . . Widget::Input::File . . Widget::Input::Password . Widget::Menu* . . Widget::Menu::List . . Widget::Menu::Popup
Only leaf nodes are concrete classes, and there is one such class for each known control type that can appear in the <FORM> element.
Those classes are constructed as needed by CGI::Test. They are the programmatic artefacts which can be used to manipulate those graphical elements, on which you would otherwise click and fill within a browser.
CGI::Test
This is the interface defined at the CGI::Test::Form::Widget level, and which is therefore common to all classes in the hierarchy. Each subclass may naturally add further specific features.
It is very important to stick to using common widget features when writing a matching callback for the widgets_matching routine in CGI::Test::Form, or you run the risk of getting a runtime error since Perl is not statically typed.
widgets_matching
CGI::Test::Form
form
The CGI::Test::Form to which this widget belongs.
gui_type
A human readable description of the widget, as it would appear on a GUI, like "popup menu" or "radio button". Meant for logging only, not to determine the object type.
name
The CGI parameter name.
value
The current CGI parameter value.
set_value
Change the value attribute to new_value. The widget must not be is_read_only nor is_disabled.
is_read_only
is_disabled
Those predicates may be used to determine whether it is possible to change the value of a widget from the user interface.
When true, the widget is disabled, i.e. not available for editing. It would typically appear as being grayed out within a browser.
This predicate is not architecturally defined: a widget may or may not be marked as disabled in HTML via a suitable attribute.
is_mutable
Test whether widget can change value. Returns false when the widget is_read_only or is_disabled.
When the optional warn_flag is true, carp is called to emit a warning from the perspective of the caller.
carp
When false, the value parameter can be changed with set_value. This is an architecturally defined predicate, i.e. its value depends only on the widget type.
Those predicates may be used to determine the overall widget type. The classification is rather high level and only helps determining the kind of calls that may be used on a given widget object.
is_box
Returns true for radio buttons and checkboxes.
is_button
Returns true for all buttons that are not boxes.
is_file
Returns true for a file upload widget, which allows file selection.
is_hidden
Returns true for hidden fields, which have no graphical representation by definition.
is_input
Returns true for all input fields, where the user can type text.
is_menu
Returns true for popup menus and scrolling lists.
Although documented, those features are more targetted for internal use...
delete
Breaks circular references. This is normally done by the delete routine on the enclosing form.
is_submitable
Returns true when the name/value tupple of this widget need to be part of the submitted parameters. The rules for determining the submitable nature of a widget vary depending on the widget type.
reset_state
Reset the widget's value to the one it had initially. Invoked internally when a reset button is pressed.
submit_tuples
For submitable widgets, return the list of (name => value) tupples that should be part of the submitted data. Widgets like scrolling list may return more than one tuple.
This routine is invoked to compute the parameter list that must be sent back when pressing a submit button.
The original author is Raphael Manfredi.
Steven Hilton was long time maintainer of this module.
Current maintainer is Alexander Tokarev <tokarev@cpan.org>.
CGI::Test::Form(3), CGI::Test::Form::Widget::Box(3), CGI::Test::Form::Widget::Button(3), CGI::Test::Form::Widget::Input(3), CGI::Test::Form::Widget::Hidden(3), CGI::Test::Form::Widget::Menu(3).
To install CGI::Test, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::Test
CPAN shell
perl -MCPAN -e shell install CGI::Test
For more information on module installation, please visit the detailed CPAN module installation guide.