X-Git-Url: http://git.shiar.net/perl/html-form-simple.git/blobdiff_plain/6bef855dc6c753640512d512e5b31e2734484382..061e1dbc2abe6c89b90348e22e5f3455a2b8328d:/lib/HTML/Form/Simple.pm

diff --git a/lib/HTML/Form/Simple.pm b/lib/HTML/Form/Simple.pm
index 5946030..7d02314 100644
--- a/lib/HTML/Form/Simple.pm
+++ b/lib/HTML/Form/Simple.pm
@@ -9,7 +9,8 @@ our $VERSION = '1.00';
 
 
 sub new {
-	bless {}, $_[0];
+	my ($class, $default) = @_;
+	bless {default => $default}, $class;
 }
 
 sub _attr {
@@ -23,6 +24,7 @@ sub _attr {
 
 sub quote {
 	my $self = shift;
+	return ${$_[0]} if ref $_[0] eq 'SCALAR';
 	return XML::Quote::xml_quote_min($_[0]);
 }
 
@@ -35,10 +37,11 @@ sub tag {
 
 	my $return = '<' . $tag;
 
-	# add booleans
+	# add boolean attributes
 	delete $attr->{$_} and $return .= ' '.$_
 		for qw(selected checked disabled readonly);
 
+	# add attributes with (escaped) string values
 	$return .= sprintf ' %s="%s"', $_, $self->quote($attr->{$_})
 		for sort grep { defined $attr->{$_} } keys %$attr;
 
@@ -71,21 +74,37 @@ sub hidden {
 	my $self = shift;
 	my ($name, $value, $attr) = $self->_attr(2, @_);
 
+	if (ref $name eq 'HASH') {
+		my @return = map { $self->hidden($_, $name->{$_}, $attr) } sort keys %$name;
+		return wantarray ? @return : join(defined $, ? $, : '', @return);
+	}
+
+	if (ref $value eq 'ARRAY') {
+		my @return = map { $self->hidden($name, $_, $attr) } @$value;
+		return wantarray ? @return : join(defined $, ? $, : '', @return);
+	}
+
 	$attr->{name } = $name  if defined $name;
 	$attr->{value} = $value if defined $value;
+	$attr->{value} = $self->{default}->{$name}
+		if not defined $attr->{value} and defined $name and defined $self->{default};
 	$attr->{type} = 'hidden' unless defined $attr->{type};
 
 	return $self->tag(input => $attr);
 }
 
-sub input {
+sub text {
 	my $self = shift;
 	my ($name, $value, $attr) = $self->_attr(2, @_);
 
 	$attr->{name } = $name  if defined $name;
 	$attr->{value} = $value if defined $value;
+	$attr->{value} = $self->{default}->{$name}
+		if not defined $attr->{value} and defined $name and defined $self->{default};
 	$attr->{id}   = $attr->{name} unless defined $attr->{id};
 	$attr->{type} = 'text' unless defined $attr->{type} or defined $attr->{rows};
+
+	# textarea does not have value as tag attribute
 	$value = delete $attr->{value} if defined $attr->{rows};
 
 	return defined $attr->{rows} ? sprintf(
@@ -99,24 +118,29 @@ sub select {
 	my $self = shift;
 	my ($name, $rows, $default, $attr) = $self->_attr(3, @_);
 
-	$default = $attr->{value} unless defined $default;
-	delete $attr->{value};  # never a parent attribute
-
 	$attr->{name} = $name;
 	$attr->{id}   = $attr->{name} unless defined $attr->{id};
 	$attr->{type} = 'select' unless defined $attr->{type};
 
+	$default = $attr->{value} unless defined $default;
+	delete $attr->{value};  # never a parent attribute
+	$default = $self->{default}->{$name}
+		if not defined $default and defined $name and defined $self->{default};
+
 	my @options = map { ref $_ ? $_ : {value => $_} } @$rows;
 
 	my @return;
 
 	if ($attr->{type} eq 'select') {
 		delete $attr->{type};
+
+		# select option(s) matching the default value
 		if (defined $default) {
 			for (@options) {
 				$_->{selected} = 1 if defined $_->{value} and $_->{value} eq $default;
 			}
 		}
+
 		@return = (
 			$self->tag(select => $attr),
 			(map { $self->tag(option => $_) } @options),
@@ -124,22 +148,28 @@ sub select {
 		);
 	}
 	else {
+		# set fallback option id from parent id and value
 		if (defined $attr->{id} and $attr->{id} ne '') {
 			defined $_->{id}
 				or defined $_->{value} and $_->{id} = $attr->{id}.'_'.$_->{value}
 					for @options;
 		}
+
+		# put parent label attribute on options
 		if (defined $attr->{label}) {
 			defined $_->{value} and not defined $_->{label}
 				and $_->{label} = $attr->{label}->{$_->{value}}
 					for @options;
 			delete $attr->{label};
 		}
+
+		# check any option matching the default value
 		if (defined $default) {
 			for (@options) {
 				$_->{checked} = 1 if defined $_->{value} and $_->{value} eq $default;
 			}
 		}
+
 		$_ = {%$attr, %$_} for @options;
 		@return = map {
 			my $label = delete $_->{label};
@@ -154,53 +184,77 @@ sub select {
 
 sub radio {
 	my $self = shift;
-	my ($name, $label, $value, $attr) = $self->_attr(3, @_);
+	my ($name, $rows, $label, $default, $attr) = $self->_attr(4, @_);
 
-	if (not defined $value) {
+	# normalize rows array
+	if (not defined $rows) {
 		if (defined $label) {
-			$value = ref $label eq 'ARRAY' ? [1 .. $#$label+1] : [1];
+			# fill up values with numbers to match labels
+			$rows = ref $label eq 'ARRAY' ? [1 .. $#$label+1] : [1];
 		}
 		else {
-			$value = [{}];
+			$rows = [{}];
 		}
 	}
-	elsif (ref $value ne 'ARRAY') {
-		$value = [$value];
+	elsif (ref $rows ne 'ARRAY') {
+		$rows = [$rows];
 	}
 
+	# add labels
 	if (defined $label) {
-		$_ = ref $_ eq 'HASH' ? {%$_} : {value => $_} for @$value;
-		$_->{label} = ref $label eq 'ARRAY' ? shift @$label : $label for @$value;
+		# convert options to hash refs so we can add label attributes
+		$rows = [ map { ref $_ eq 'HASH' ? {%$_} : {value => $_} } @$rows ];
+
+		if (ref $label eq 'ARRAY') {
+			$rows->[$_]->{label} = $label->[$_] for 0 .. $#$rows;
+		} else {
+			$_->{label} = $label for @$rows;
+		}
 	}
 
-	$self->select($name, $value, {%$attr, type => 'radio'});
+	$self->select($name, $rows, $default, {%$attr, type => 'radio'});
 }
 
 sub check {
 	my $self = shift;
 	my ($name, $label, $checked, $attr) = $self->_attr(3, @_);
 
-	my $rows = defined $label ? ref $label eq 'ARRAY' ? $label : [$label] : [{}];
-	ref $_ eq 'HASH' or $_ = {label => $_} for @$rows;
+	# create option rows array from label argument
+	my $rows = defined $label ? ref $label eq 'ARRAY' ? [@$label] : [$label] : [{}];
+	# convert options to hash refs sooner rather than later
+	$_ = ref $_ eq 'HASH' ? {%$_} : {label => $_} for @$rows;
+
+	# parse checked argument
 	if (defined $checked) {
 		if (ref $checked eq 'ARRAY') {
-			$_->{checked} = shift @$checked for @$rows;
-			push @$rows, map { {checked => $_} } @$checked;
+			# each checked row corresponding to an option
+			$rows->[$_]->{checked} = $checked->[$_] for 0 .. $#$rows;
+			# add superfluous rows as new options
+			push @$rows, map { {checked => $_} } @$checked[@$rows .. $#$checked];
 		}
 		else {
+			# a single value for all options
 			$_->{checked} = $checked for @$rows;
 		}
 	}
+
+	# set default option value (argument number)
 	exists $rows->[$_]->{value} or $rows->[$_]->{value} = $_ + 1 for 0 .. $#$rows;
 
+	# set option id without added value if rows were not given as array
+	$rows->[0]->{id} = $attr->{id} || $rows->[0]->{name} || $attr->{name} || $name #XXX: //
+		if ref $label ne 'ARRAY' and defined $rows->[0] and not defined $rows->[0]->{id};
+
 	$self->select($name, $rows, {%$attr, type => 'checkbox'});
 }
 
 1;
 
+__END__
+
 =head1 NAME
 
-HTML::Form::Simple
+HTML::Form::Simple - Generate HTML form elements
 
 =head1 SYNOPSIS
 
@@ -214,7 +268,7 @@ HTML::Form::Simple
 			msg => 'Textarea default', {rows => 4, style => 'background:red'}
 		) ],
 		[ Gender => join ' or ', $input->radio(
-			sex => ['m', 'f']
+			sex => [qw(m f)], [qw(Male Female)]
 		) ],
 		[ Colour => scalar $input->select(
 			favcolour => [qw(Blue Green Red)], 'Green'
@@ -225,3 +279,133 @@ HTML::Form::Simple
 	);
 	say $input->stop; # </form>
 
+=head1 DESCRIPTION
+
+Set up a form object with new().  The HTML for the opening and closing
+C<< <form> >> tags are returned by the start() and stop() methods.
+
+The L<hidden>, L<text>, L<select>, L<radio>, and L<check> methods all
+correspond to various input types.  The first argument is always the mandatory
+name, and a hash ref as the last argument can optionally be provided for
+additional attributes/options.  Everything is properly escaped.
+
+=over
+
+=item C<hidden>
+
+Returns the HTML for a simple C<< <input type="hidden"> >> with specified name
+and value (both are required by HTML specs).
+
+	$input->hidden('name', 'value');
+
+As with all methods, a final hash ref can be given to add further attributes.
+While rarely needed in this case, it can also be used as an override or
+alternative to value and name:
+
+	$input->hidden({name => 'name', value => 'value'})
+
+=item C<text>
+
+The common C<< <input type="text"> >>.
+
+	$input->text('name', 'default');
+
+If the I<rows> option is set, substitutes a similarly set up C<< <textarea> >>:
+
+	$input->text('name', 'default', {rows => 4});
+
+=item C<select>
+
+	$input->select('name', ['option'], 'default');
+
+Provides C<< <select><option> >> dropdown by default, but can also output
+multiple C<< <input> >> tags if a I<type> is provided:
+
+	$input->select('name', ['1'], {type => 'checkbox'});
+
+In scalar context, options are joined together by C<$,> (C<$OUTPUT_FIELD_SEPARATOR>).
+Otherwise a list of tags is returned.
+
+Each option can be given as either a simple string containing its I<value>,
+or a hash ref with custom attributes.
+When there's no parent tag (only C<< <input> >>s), a fourth parameter can
+provide common options which will be inherited by each element.  Otherwise,
+options will apply to either the C<< <select> >> or an C<< <option> >>.
+
+The default value (either as a third scalar parameter, or with the general
+I<value> option) will be matched to the value of each option, and if equal,
+its I<selected> or I<checked> attribute will be set as appropriate.
+
+=item C<radio>
+
+In fact just a shorthand to L<select> with a preset type of I<radio>, but takes
+an additional third argument to easily set the label for each option:
+
+	$input->radio('name', ['option'], ['option label'], 'default');
+
+This would be the same as saying:
+
+	$input->radio(
+		'name',
+		[ {label => 'option label', value => 'option'} ],
+		{value => 'default'}
+	);
+
+=item C<check>
+
+Also a L<select> shorthand, but with a I<checkbox> type.
+Instead of values, the second argument specifies option I<label>s.
+The values by default are set to an auto-incrementing number starting with 1.
+
+Furthermore, the I<checked> status for each option can be specified by a third
+argument.  Either a single boolean value defining all rows, or an array ref
+with the value for each row in order.
+
+	$input->check('name', ['label', 'second option'], [0, 1]);
+
+Or more descriptive but identical:
+
+	$input->check('name', [
+		{label => 'label',         value => 1, checked => 0},
+		{label => 'second option', value => 2, checked => 1},
+	]);
+
+=back
+
+=head1 TODO
+
+=over
+
+=item C<default()> method
+
+	$input->hidden(foo => $input->default('foo'));
+	$hash_ref = $input->default;
+	$input->default('foo') = 'new value';
+	undef $input->default;  # clear all
+		# XXX: does this equal $input->default=undef;?
+	$input->default = {amend => 'stuff'};
+
+=item documentation
+
+Actual descriptions instead of just a synopsis.
+
+=item C<quote> override
+
+Allow custom value quotation function.
+Makes L<XML::Quote|XML::Quote> dependency optional.
+
+=item single checkbox id
+
+Do not add value to single check() by default.
+
+=back
+
+=head1 AUTHOR
+
+Mischa POSLAWSKY <perl@shiar.org>
+
+=head1 LICENSE
+
+This module is free software; you can redistribute it and/or modify it
+under the same L<terms|perlartistic> as Perl itself.
+