package CGI::Test::Form::Widget::Button;
use strict;
use warnings;
##################################################################
# $Id: Button.pm 411 2011-09-26 11:19:30Z nohuhu@nohuhu.org $
# $Name: cgi-test_0-104_t1 $
##################################################################
#
# Copyright (c) 2001, Raphael Manfredi
#
# You may redistribute only under the terms of the Artistic License,
# as specified in the README file that comes with the distribution.
#
use Carp;
#
# This class models a FORM button.
#
use base qw(CGI::Test::Form::Widget);
############################################################
#
# ->new
#
# Creation routine for <BUTTON> elements.
#
############################################################
sub new
{
my $this = bless {}, shift;
my ($node, $form) = @_;
#
# Can't create a CGI::Test::Form::Widget::Button object, only heirs.
#
confess "%s is a deferred class", __PACKAGE__
if ref $this eq __PACKAGE__;
$this->_common_init($form);
#
# We don't keep any reference on the node.
# Analyze the HTML tree to determine some parameters.
#
$this->_init_button($node);
return $this;
}
############################################################
#
# %attr
# %attr_button
#
# Defines which HTML attributes we should look at within the node, and how
# to translate that into class attributes. The %attr_button is specific
# to the <BUTTON> tags.
#
############################################################
my %attr = ('name' => 'name',
'value' => 'value',
'disabled' => 'is_disabled',
);
my %attr_button = (%attr,);
############################################################
#
# ->_init
#
# Per-widget initialization routine, for <INPUT>.
# Parse HTML node to determine our specific parameters.
#
############################################################
sub _init
{
my $this = shift;
my ($node) = shift;
$this->_parse_attr($node, \%attr);
$this->{is_enhanced} = 0;
$this->{is_pressed} = 0;
return;
}
############################################################
#
# ->_init_button
#
# Per-widget initialization routine, for <BUTTON>.
# Parse HTML node to determine our specific parameters.
#
############################################################
sub _init_button
{
my $this = shift;
my ($node) = shift;
$this->_parse_attr($node, \%attr_button);
$this->{is_enhanced} = 1;
$this->{is_pressed} = 0;
return;
}
############################################################
#
# ->_is_successful -- defined
#
# Is the enabled widget "successful", according to W3C's specs?
# Any pressed button is.
#
############################################################
sub _is_successful
{
my $this = shift;
return $this->is_pressed();
}
#
# Attribute access
#
############################################################
sub is_enhanced
{
my $this = shift;
return $this->{is_enhanced};
} # True for <BUTTON> elements
############################################################
sub is_pressed
{
my $this = shift;
return $this->{is_pressed};
}
############################################################
#
# ->press
#
# Press button.
#
# Has immediate effect:
# * If it's a reset button, all widgets are reset to their initial state.
# * If it's a submit button, a GET/POST request is issued.
# * By default, a warning is issued that the action is ignored.
#
# Returns undef if no submit is done, a new CGI::Test::Page otherwise.
#
############################################################
sub press
{
my $this = shift;
#
# Default action: do nothing
# Routine is redefined in heirs when processing required.
#
warn 'ignoring button press: name="%s", value="%s"', $this->name(),
$this->value();
return undef;
}
############################################################
#
# ->set_is_pressed
#
# Press or unpress button.
#
############################################################
sub set_is_pressed
{
my $this = shift;
my ($pressed) = @_;
$this->{is_pressed} = $pressed;
return;
}
############################################################
#
# ->reset_state -- redefined
#
# Called when a "Reset" button is pressed to restore the value the widget
# had upon form entry.
#
############################################################
sub reset_state
{
my $this = shift;
$this->{is_pressed} = 0;
return;
}
############################################################
#
#
# Global widget predicates
#
############################################################
sub is_read_only
{
return 1;
}
#
# Button predicates
#
############################################################
sub is_reset
{
return 0;
}
############################################################
sub is_submit
{
return 0;
}
############################################################
sub is_plain
{
return 0;
}
#
# High-level classification predicates
#
############################################################
sub is_button
{
return 1;
}
1;
=head1 NAME
CGI::Test::Form::Widget::Button - Abstract representation of a button
=head1 SYNOPSIS
# Inherits from CGI::Test::Form::Widget
=head1 DESCRIPTION
This class is the abstract representation of a button, i.e. a submit
button, an image button, a reset button or a plain button.
Pressing a button is achieved by calling C<press()> on it, which returns a
new page, as a C<CGI::Test::Page> object, or C<undef> if pressing had
no round-trip effect.
=head1 INTERFACE
The interface is the same as the one described in L<CGI::Test::Form::Widget>,
with the following additions:
=head2 Attributes
=over 4
=item C<is_pressed>
True when the button is pressed.
=back
=head2 Attribute Setting
=over 4
=item C<press>
Press the button, setting C<is_pressed> to true.
If the button is a reset button (C<is_reset> is true), all widgets
are reset to their initial state, and C<undef> is returned.
If the button is a submit button (C<is_submit> is true), then a GET/POST
request is issued as appropriate and the reply is made available through
a C<CGI::Test::Page> object.
Otherwise, the button pressing is ignored, a warning is issued from the
perspective of the caller, via C<carp>, and C<undef> is returned.
=back
=head2 Widget Classification Predicates
There is an additional set of predicates to distinguish between the various
buttons:
=over 4
=item C<is_plain>
Returns I<true> for a plain button, i.e. a button that has no submit/reset
effects. Usually, those buttons are linked to a script, but C<CGI::Test>
does not support scripting yet.
=item C<is_reset>
Returns I<true> for reset buttons.
=item C<is_submit>
Returns I<true> for submit buttons, whether they are really shown as
buttons or as images. A submit button will cause an HTTP request to be
issued in response to its being pressed.
=back
=head2 Miscellaneous Features
Although documented, those features are more targetted for
internal use...
=over 4
=item C<set_is_pressed> I<flag>
Change the pressed status of the button, to the value of I<flag>.
It does not raise any other side effect, like submitting an HTTP request
if the button is a submit button.
You should probably use the C<press> convenience routine instead of calling
this feature directly.
=back
=head1 AUTHORS
The original author is Raphael Manfredi.
Steven Hilton was long time maintainer of this module.
Current maintainer is Alexander Tokarev F<E<lt>tokarev@cpan.orgE<gt>>.
=head1 SEE ALSO
CGI::Test::Form::Widget(3),
CGI::Test::Form::Widget::Button::Image(3),
CGI::Test::Form::Widget::Button::Plain(3),
CGI::Test::Form::Widget::Button::Reset(3),
CGI::Test::Form::Widget::Button::Submit(3).
=cut