error

Manage form variable error checking for the Interchange submit form processing action.

Summary

[error name]

Parameter	Description	Default
name	The name of the form variable.	None
all	Display all error messages.	No
auto	Preset some parameter values.	No
class	CSS class name used only if auto is true	None
extra	Extra list_container HTML tag parameters, only used if auto is true	None
filter	Run the error message(s) through the specified filter(s) prior to returning the value.	None
footer	Footer value used at the end of the output if all is true.	None
header	Header value used at the start of the output if all is true.	None
joiner	Character used to join multiple error messages.	See below
keep	Don't delete the error messages after display.	No
list_container	Default list container HTML tag, used if auto is true	ul
overwrite	Overwrite any error messages with the new message set with the set parameter instead of appending.	No
required	Specifies that this is a required field, for formatting purposes.	No
set	Raise an error against the named form variable. Will append to any existing messages unless overwrite is true.	None
show_error	Return the error message text.	None
show_label	Causes the field label to be included as part of the error message.	No
show_var	Includes the name of the variable, in which the error was found, as part of the error message.	No
std_label	Label string for error message.	None
style	CSS style value(s) used only if auto is true	None
text	Optional string in which to embed the error message(s).	None
hide	Suppress any output text that would ordinarily be returned from this tag. (This universal parameter was introduced with Interchange version 5.5.2.)	No

Examples

Perl example

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

or similarly with positional parameters:

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

Description

The [error] tag is designed to manage form variable checking for the Interchange submit form processing action. It works in conjunction with the definition, set in mv_order_profile. and can generate error messages in any format you desire.

If the variable in question passes its order profile checks then it will output a label. By default, bold text will be used if the item is required or normal text if not (as controlled by the require parameter).

If the variable fails one or more of its order checks then the error message will be substituted into a template and the error cleared from the user's session.

You can use the following to show a list of errors, without clearing the list at the same time:

[if type=explicit compare="[error all=1 show_var=1 keep=1]"]
There were errors in your form submission.
 
<blockquote>
[error all=1 keep=1 show_error=1 show_label=1 joiner=" "]
</blockquote>
[/if]

You can also use the [if errors] test to check for individual form field errors:

[if errors fname]
Please enter your first name.
[/if]

Parameters

name

The name of the form variable.

all

all=1 means display all error messages, not just the one referred to by name. The default is only display the error message assigned to name.

auto

Setting this parameter true will cause the following parameters to be set, as follows:

all will be set to true.
show_error will be set true.
std_label will be set false.
show_var will be set true unless overridden.
joiner will be set to "<li>" unless overridden.
text will be set to "%s".
list_container will be set to "ul" unless overridden.
header will be set as follows:
- "<" followed by the list_container (see above).
- "class="class"", if the class parameter has a value.
- "style="style"", if the style parameter has a value.
- "extra", if the extra parameter has a value.
- ">" followed by the joiner.
footer will be set to "</list_container>" unless overridden.

class

CSS class name used only if auto is true.

extra

Extra list_container HTML tag parameters, only used if auto is true.

filter

Setting filter="filter1 filter2" modifies the returned error message(s) by running the text through the specified filter(s).

See the filters category for a list of standard filters.

footer

Footer value used at the end of the output if all is true.

header

Header value used at the start of the output if all is true.

joiner

Character used to join multiple error messages. The default is "<li>" if auto is true, otherwise the default is "\n" (a newline).

keep

If set true then this tag will not delete the error message(s) after use.

list_container

Default list container HTML tag, used if auto is true.

overwrite

Overwrite any existing error messages, with the value specified using the set parameter, instead of appending the new message.

required

Specifies that this is a required field for, formatting purposes. In the std_label format, it means the field will be emboldened. If you specify your own label string, it will insert HTML anywhere you have {REQUIRED: HTML}, but only when the field is required.

set

This is used to raise an error against a named form variable. This could be useful in a custom, non-profile-based, form checking routine.

[error name="email" set="Invalid email address"]

The message will be appended to any existing messages (using "AND" as the message separator) unless the overwrite parameter is set true.

show_error

show_error=1 means return the error message text, otherwise just the number of errors found is returned.

show_label

show_label=1 causes the field label, set by a previous [error] tag's std_label attribute, to be included as part of the error message, like this:

First name: blank

If no std_label was set, the variable name will be used instead. This can also be used in combination with show_var to show both the label and the variable name.

show_var

show_var=1 includes the name of the variable, in which the error was found, as part of the error message, like this:

email: 'bob#nothing,net' not a valid email address

std_label

If supplied, this parameter's value will be stored in the user's session for possible use in a subsequent call to [error show_label=1].

A return value will be built in the following manner:

A return value will be initialised from one of the following sources, which will be checked for a value in the following order:

This tag's text parameter (if supplied).
The MV_ERROR_STD_LABEL Variable (if defined).

The following default:

{LABEL} (%s)
[else]{REQUIRED }{LABEL}{REQUIRED }[/else]

The "mv_contrast" class name can be overridden by setting the "CSS_CONTRAST" Variable.

Availability

Interchange versions prior to 5.5.0 used the following default instead of the one shown above:

{LABEL} (%s)
[else]{REQUIRED }{LABEL}{REQUIRED }[/else]

If a "{LABEL}" placeholder is present in the initialised return text then it will be replaced with this "std_label" parameter's value.
If a "{REQUIRED xxxx}" placeholder is present in the initialised return text then, and the required parameter is set true then the "xxxx parameter value will be output.
The return value will be split depending upon whether an error was found, as follows:
- If an error was found, and an "[else]...[/else]" block is is present in the return text, then the "[else]" block will be stripped from the text.
- If no error was found, and an "[else]...[/else]" block is is present in the return, text then the "[else]" block's content will be used as the return value.
The "%s" token will be replaced with the error message. If no "%s" token is found then the error message will be appended to the end of the return text.

style

CSS style value(s) used only if auto is true.

text

Optional string in which to embed the returned error message(s).

See the "std_label" parameter.