view release on metacpan or  search on metacpan

Wyrd/Input.pm  view on Meta::CPAN

=cut

sub null_ok {
	my ($self) = @_;
	return undef;
}

=pod

=item (void) C<set> (varies)

set accepts a value, which is converted to the appropriate type
(arrayref, scalar, etc.) to safely pass the next test, which is the
B<_check_param> internal method.  If B<_check_param> returns a null
result, it is assumed to have failed and the appropriate error calls are
made, setting error flags in the parent via the parent's
B<register_errors> and B<register_error_messages>.

In the parent, B<register_errors> is assumed to process the triggers and
register that at least one error has occurred in submitting it's inputs.
B<register_error_messages> is called separately, as there may not be a
one-to-one correspondence between what the Input should warn the user
about and what it considers an error.

The no_fail flag prevents the errors from registering at all, while the
quiet flag will suppress only the error messages.

However, pass or fail, a call to the _datum object will occur with the
B<set> call, and presumably, the Datum class will know how to deal with
that.  For it's own purposes, however, the value will be temporarily
stored by the Input, and HTML esacaped if the B<escape> flag is set.

=cut

sub set {
	my ($self, $value) = @_;
	$value = $self->_unescape($value) if ($self->_flags->escape);
	#convert value to appropriate type
	$value = [$value] if ((ref($value) ne 'ARRAY') and ($self->{'_multiple'}));
	$value = shift(@{$value}) if ((ref($value) eq 'ARRAY') and not($self->{'_multiple'}));
	my $result = $self->_check_param($value); #check params and set error values
	unless ($result) {
		$self->_warn("Failed to set the datum object for " . $self->{'name'} . " to the value $value");
		unless ($self->_flags->no_fail) {
			$self->{'_parent'}->register_errors($self);
			$self->{'_parent'}->register_error_messages($self) unless ($self->_flags->quiet);
		}
	}
	$self->{'_datum'}->set($value);
	#set the value anyway, since it will need to be stored temporarily and,
	#presumeably, an impossible value will not be rendered as set by the
	#browser on the form at all.
	$value = $self->{'_datum'}->get($value);
	$self->{'value'}=$value unless ($self->_flags->reset);
}

=pod

=item (void) C<_parse_options> (void)

_parse_options looks to the B<options> attribute, which may be explicit
as a comma/whitespace delineated list or built up by sub-objects (see
C<Apache::Wyrd::Input::Opt>) in order to determine what options to give
to the datum object.  If this value is already a hashref or arrayref, it
does no further processing.  Otherwise it attempts to separate the words
of the options attribute, using an optional regexp under the "delimiter"
attribute.

=cut

sub _parse_options {
	#prepare options for Apache::Wyrd::Datum
	my ($self) = @_;
	$self->{options} = {} unless ($self->{'options'} or $self->{'hash_options'});
	my $self_options = $self->{'options'};
	my $delimiter = $self->{'delimiter'};
	return undef if (ref($self_options) =~ /HASH|ARRAY/);
	if (ref($self_options)) {
		$self->_raise_exception("Don't understand why options are a " 
			. ref($self_options));
	} elsif ($self->{'hash_options'}) {
		my %hash = token_parse($self->{'hash_options'}, $delimiter);
		$self->{'options'} = \%hash;
	} else {
		my @options = token_parse($self->{options}, $delimiter);
		$self->{'options'} = \@options;
	}
}

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

the B<_check_param> method itself, by default, calls the B<check> method
of the underlying Datum instance.  Datum returns two values, the first
indicating pass/fail for defined/undefined and the second indicating
what the default error message is.  Authors producing Datum objects
created to support the Input should pay special attention to this, as
this is where useful error messages can be generated, rather than the
default "Invalid data in <param-name>".  _check_param also adds the
parameter/name as a token to the error register so it can be tracked by
the parent.

A shorthand for adding this method to an item is the description
attribute, which will be prepended to the error string if an error
occurs.

the values stored in the _errors and _error_messages registers can be
accessed read_only through the errors and error_messages methods, as
demonstrated by the Form object.

=cut

sub _check_param {
	my ($self, $value) = @_;
	#use the datum as the checker
	my ($ok, $errstr) = ($self->{'_datum'}->check($value));
	return 1 if ($ok);
	$errstr ||= ($self->{'error_message'} || 'Invalid data.');
	$errstr = $self->description . ": $errstr" if ($self->description);
	$self->{'_error_messages'} = [@{$self->{'_error_messages'}}, $errstr];
	$self->{'_errors'} ||= $self->triggers;
	return;