4.87. value-extended

4.87.1. Summary

Parameters: name

Positional parameters in same order.

The attribute hash reference is passed to the subroutine after the parameters as the last argument. This may mean that there are parameters not shown here.

Must pass named parameter interpolate=1 to cause interpolation.

Invalidates cache: YES

Called Routine:

ASP-like Perl call:

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

 OR

    $Tag->value_extended($name, $ATTRHASH);
    [value-extended name other_named_attributes]

Parameters	Description	Default
name		DEFAULT_VALUE

Attributes	Default
umask	none
interpolate (reparse)	No

Other_Characteristics
Invalidates cache	YES
Container tag	No
Has Subtags	No
Nests	Yes

Tag expansion example:

    [value-extended name]
---
    TODO: (tag result)

ASP-like Perl call:

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

or similarly with positional parameters,

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

4.87.2. Description

Named call example:

   [value-extended
            name=formfield
            outfile=filename*
            umask=octal*
            ascii=1*
            yes="Yes"*
            no="No"*
            joiner="char|string"*
            test="isfile|length|defined"*
            index="N|N..N|*"
            file_contents=1*
            maxsize=length*
            elements=1*
   ]

Expands into the current value of the customer/form input field named by field. If there are multiple elements of that variable, it will return the value at index; by default all joined together with a space.

If the variable is a file variable coming 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.

4.87.2.1. name

Specify which value variable to deal with. If no other parameters are present, then the value of the variable will be returned. If there are multiple elements, then by default they will all be returned joined by a space. If joiner is present, then they will be joined by its value.

In the special case of a file upload, the value returned is the name of the file as passed for upload.

4.87.2.2. joiner

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

4.87.2.3. test

Three tests: isfile returns true if the variable is a file upload. length returns the length. defined returns whether the value has ever been set at all on a form.

4.87.2.4. index

The index of the element to return if not all are wanted. This is useful especially for pre-setting multiple search variables. If set to *, will return all (joined by joiner). If a range, such as 0 .. 2, will return multiple elements.

4.87.2.5. 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, returns nothing.

4.87.2.6. 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.

4.87.2.7. outfile

Names a file to write the contents of a file upload to. It will not accept an absolute file name; the name must be relative to the catalog directory. If you wish to write images or other files that would go to HTML space, you must use the HTTP server's Alias facilities or make a symbolic link.

4.87.2.8. 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) manpage for details.

4.87.2.9. ascii

To do an auto-ASCII translation before writing the outfile, set the ascii parameter to a non-blank, non-zero value. Default is no translation.

4.87.2.10. yes

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

4.87.2.11. no

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