value-extended

Expands into the current value of the named form input value. If there are multiple elements in the variable then it will return the value(s) at the specified index(es) within the variable.

Summary

[value-extended name]

Parameter	Description	Default
name	The name of the form variable being examined.	None
ascii	auto-ASCII translation before writing the outfile.	No
elements	Return a list of form variable index numbers	No
file_contents	Returns the contents of an uploaded file.	None
filter	Modify the value list before returning.	None
index	The index of the element to return if not all are wanted.	*
joiner	The character or string that will join the elements of the array	Space (" ").
maxsize	The maximum file size allowed, in bytes.	None
no	The value that will be returned if a test is false or a file write fails.	See below
outfile	The name of a file to to which an uploaded file should be saved.	None
test	Perform one of three tests on the value (see below).	None
umask	Permission mask (in octal) to apply to the uploaded file's permission bits.	None
yes	The value that will be returned if a test is false or a file write fails.	See below
interpolate	Process any Interchange tags found in the text output from this tag.	No

Examples

Perl example

$Tag->value_extended({
name => $name,
});

or similarly with positional parameters:

$Tag->value_extended($name, $attribute_hash_reference);

Description

Expands into the current value of the named form input value. If there are multiple elements in the variable then it will return the value(s) at the specified index(es) within the variable.

By default, all of the elements in the named form input value will be returned, joined together with either the joiner value, or a space.

If the variable contains data originating from a "multipart/form-data" file upload, then the contents of that upload can be returned to the page, or optionally written to the outfile.

Parameters

name

Specify the name of the form input value this tag should be dealing with.

If no other parameters are present then the value of the named form variable will be returned. If there are multiple elements then they will all be returned, joined with the joiner value (or with a space if no joiner value is provided).

If the variable contains data originating from a "multipart/form-data" file upload, then the name of the uploaded file will be returned.

ascii

To do an auto-ASCII translation before writing the outfile, set the ascii parameter to a non-blank, non-zero value. The default is to not perform any translation.

elements

If set true then a list of index numbers for the named form input value will be returned, separated with a space. For instance, if the named value contains "foo\0bar\0baz" then the three elements will be translated into a list of index numbers and returned as "0 1 2".

file_contents

Returns the contents of a file upload if set to a non-blank, non-zero value. If the variable is not a file then nothing will be returned.

filter

Setting filter="filter1 filter2" will run the return value(s) through the specified filter(s).

This parameter does not have any effect on the value returned when using the file_contents parameter, nor does it have any effect when the test or outfile parameters are used.

Unlike the [value] and [cgi] tags etc., the filter modifications will not be written back to the named variable. There is therefore no need for a "keep" parameter switch.

See the filters category for a list of standard filters.

index

The index of the element to return if you want all of the values. This is especially useful for pre-setting multiple search parameters. If set to "*", or not set at all, then all elements will be returned (joined by the joiner parameter's value, or its default). If a range, such as "0..2" is specified then multiple elements will be returned, as per the specified index range.

joiner

The character or string that will join the elements of the array. Will accept string literals such as "\n" and "\r" etc.

maxsize

The maximum file size allowed, in bytes. If a file of greater size than maxsize is uploaded, the tag will return false and an error will be logged.

no

The value that will be returned if a test is false, or if a file write fails. Defaults to an empty string.

outfile

Names a file to which the contents of an uploaded file should be written. This parameter will not accept an absolute file name; the name must be relative to the website's home directory, as specified using the Catalog directive.

If you want to write images, or other files that would go to HTML space, then you must use the HTTP server's Alias facilities, or make a symbolic link.

test

Three tests are available, as follows:

"isfile" returns true if the named variable is a file upload.
"length" returns the length of the named variable.
"defined" returns whether the named variable was passed along with the form.

Returns the value of the yes parameter if the test passes, or the value of the no parameter if the test fails. See the yes and no parameter documentation to find their default value.

umask

Permission mask (in octal) to apply to the uploaded file's permission bits. You may want to set this to make a file world-readable, or to keep it from being group-readable. See the UNIX chmod(1) manual page for details.

yes

The value that will be returned if a test is true or a file is written successfully. Defaults to 1 for tests, and an empty string for file uploads.