view release on metacpan or  search on metacpan

Wyrd/Input.pm  view on Meta::CPAN

This is the base class for Input objects, which are tracked and affected
by the Apache::Wyrd::Form (Form) objects that enclose them.  The base
Input object is meant to replace, in most cases, the input HTML objects:

=over

=item *

text inputs

=item *

password inputs

=item *

textarea inputs

=item *

hidden inputs

=back

For these, set the type attribute to B<text>, B<password>, B<textarea>,
and B<hidden> respectively.  Another hybrid input is B<plaintext>, which
both shows the text and includes it in the form as a hidden input.  For
other input types, such as radiobuttons, checkboxes, selection sets,
etc., see C<Apache::Wyrd::Input::Set>.

The Input does its work in the C<_format_output> phase.  If given a
type of "foo", it will first attempt to match it to one of the standard
types, then look for a C<startup_foo> method and if it finds it, will call
the method.  This is to allow derived Input objects to initialize
builtins, if needed, without re-implementing the whole _format_output
method.

Any derived startup_foo method should, for completeness, set the _datum
attribute to a Datum object appropriate to the type, put together a
template for the input appropriate to the expected output, and if the
C<Apache::Wyrd::Interfaces::SmartInput> interface is to be used, set the
_smart_type attribute to the appropriate one for the template.  See the
SYNOPSIS for an example startup routine for integer types.

For entry pages to Forms or any other state where the enclosing Form
cannot determine the initial value of an input, the Input will try the
current value it would be getting from a submission now (typically by
using a CGI parameter of the same name), any previous submissions (in
this form sequence) of variables of the same name, and lastly the
"default" value before giving up and initializing to null.

=head2 HTML ATTRIBUTES

=over

=item regular attributes

Most Input objects also accept the attributes of their HTML
counterparts.  For example, B<text>-type Inputs accept name, value,
size, class, id, maxlength, tabindex, accesskey, onchange, onselect,
onblur, etc.  Dev Note: Derived classes should maintain this support by
including conditionals in the template (see the code).

=item description

A description for this input, to be used in error messages.

=item maxlength

Maximum length of the inputted text, applies both to text and textarea
type Inputs.

=item name

Required.  The name of the Input.

=item param

The CGI parameter to use for this Input, if not the B<name>.

=item triggers

The triggers fired (comma separated list) by this input if invalid, if
not B<param> or B<name> (in that order of precedence).

=item width

Width of the item, in pixels.  This is an estimated value based on the
browser in use and assuming default style-sheets for those browsers. 
Meant for really quick-and-dirty formatting.  Applies only to text and
textarea Inputs, or Inputs that somehow make use of the
C<Apache::Wyrd::Interfaces::SmartInput> interface.

=item height

With the same caveats as width, this attribute is the height of the
item, in pixels.  As with width, applies only to textarea attributes or
SmartInputs that implement a height in chars.

=item type

Required.  The type of the Input.

=item flags

=over

=item allow_zero

By default, a value of zero is not considered a valid value, and a value of zero
will trigger an error if the required flag is set.  This flag will allow values
that are mathematically equivalent to zero.  It may become the default behavior
in future versions of this Wyrd.

=item escape

Escape the HTML of the value, so as to avoid HTML parsing errors. 
Default behavior for Inputs who's end-result input tags have this
problem, such as E<lt>input type="text"E<gt>

Wyrd/Input.pm  view on Meta::CPAN

	my ($self) = @_;
	return $self->{'_error_messages'};
}

=pod

=item (scalar) C<_escape> (scalar)

the C<_escape> method is a utility for escaping the data in an HTML
text-type input in order to avoid formatting errors.  The default is to
only escape quotes and ampersands by encoding them as the appropriate
entity.

=cut

sub _escape {
	my ($self, $value) = @_;
	$value =~ s/\&/\&amp;/g;
	$value =~ s/'/\&apos;/g;
	$value =~ s/"/\&quot;/g;
	$value =~ s/</\&lt;/g;
	$value =~ s/>/\&gt;/g;
	$value =~ s/\?:/\?\x00:/g;
	$value =~ s/\!:/\!\x00:/g;
	$value =~ s/\$:/\$\x00:/g;
	return $value;
}

=pod

=item (scalar) C<_escape> (scalar)

the C<_unescape> method reverse-mirrors the C<_escape> method exactly.

=cut

sub _unescape {
	my ($self, $value) = @_;
	$value =~ s/\&amp;/\&/g;
	$value =~ s/\&apos;/'/g;
	$value =~ s/\&quot;/"/g;
	$value =~ s/\&lt;/</g;
	$value =~ s/\&gt;/>/g;
	$value =~ s/\?\x00:/\?:/g;
	$value =~ s/\!\x00:/\!:/g;
	$value =~ s/\$\x00:/\$:/g;
	return $value;
}

=pod

=item (scalar) C<_template_foo> (scalar)

the C<_template> methods should provide an
C<Apache::Wyrd::Interfaces::Setter>-style template for a given input.
Built-in templates are text, textarea, password

=cut

sub _template_text {
	return '<input type="text" name="$:param" value="$:value"?:size{ size="$:size"}?:class{ class="$:class"}?:style{ style="$:style"}?:id{ id="$:id"}?:maxlength{ maxlength="$:maxlength"}?:tabindex{ tabindex="$:tabindex"}?:accesskey{ accesskey="$:tabinde...
}

sub _template_textarea {
	return '<textarea name="$:param"?:cols{ cols="$:cols"}?:rows{ rows="$:rows"}?:wrap{ wrap="$:wrap"}?:id{ id="$:id"}?:class{ class="$:class"}?:style{ style="$:style"}?:tabindex{ tabindex="$:tabindex"}?:accesskey{ accesskey="$:accesskey"}?:onblur{ onbl...
}

sub _template_password {
	return '<input type="password" name="$:param" value="$:value"?:size{ size="$:size"}?:id{ id="$:id"}?:maxlength{ maxlength="$:maxlength"}?:class{ class="$:class"}?:style{ style="$:style"}?:tabindex{ tabindex="$:tabindex"}?:accesskey{ accesskey="$:tab...
}

sub _template_hidden {
	return '<input type="hidden" name="$:param" value="$:value">';
}

=pod

=back

=head1 BUGS/CAVEATS/RESERVED METHODS

Reserves the C<_format_output> and C<_generate_output> methods.  Also
reserves the C<final_output> method.

=cut

sub _format_output {
	my ($self) = @_;
	$self->{'value'} ||= undef;#value will be set by the end if not earlier
	$self->{'_error_messages'} ||= [];
	my $name = $self->{'name'};
	$self->{'param'} ||= $name;
	my $type = $self->{'type'};
	$self->_parse_options;
	#primitives are overriden by instances of Apache::Wyrd::Input
	my %params = (
		#default params
		strict => ($self->_flags->{strict} || undef),
		not_null => ($self->_flags->not_null || $self->_flags->required || undef),
		options => $self->{'options'}
	);
	if ($self->_flags->readonly) {
		$self->{'readonly'} = 'true';
	}
	$self->{'_template'} = $self->{'_data'};
	if ($name eq '') {
		$self->_raise_exception('All Inputs must have a name')
	} elsif ($type eq '') {
		$self->_raise_exception('All Inputs must have a type')
	} elsif ($self->can('_setup_' . $type)) {
		my $result = eval('$self->_setup_' . $type);
		if ($@) {
			$self->_raise_exception($@);
		}
	#send the datums the "value" for defaults.
	} elsif ($type eq 'text') {
		$self->_flags->escape(1);
		my $max_length =  $self->{'maxlength'};
		if ($max_length and ($max_length < 255)) {
			$params{'length'} = $max_length;
			$self->{'_datum'} ||= (Apache::Wyrd::Datum::Char->new($self->{'value'}, \%params));
		} else {
			$self->{'_datum'} ||= (Apache::Wyrd::Datum::Text->new($self->{'value'}, \%params));
		};
		$self->{'_template'} ||= $self->_template_text;
	} elsif ($type eq 'textarea') {
		$self->_flags->escape(1);
		$self->{'value'} ||= $self->_data;#value may be enclosed in a textarea input
		$self->{'_datum'} ||= Apache::Wyrd::Datum::Text->new($self->{'value'}, \%params);