Name

error — display and manipulate errors stored in session

ATTRIBUTES

Attribute Pos. Req. Default Description
name Yes Yes default Name of the error, usually corresponds to the name of a input field in which the error ocurred.
overwrite No Overwrite existing error messages for the specified name? If this option is unset, the new error text will be appended with the word " AND ".
set Error text to set.
keep Yes Preserve the error after display? (The error is otherwise automatically deleted as soon as you retrieve its value.)
auto
all Yes if auto is enabled Display all error messages instead of just one pointed to by name?
show_error Yes if auto is enabled Show actual error messages instead of just reporting their count?
std_label
show_var Yes if auto is enabled Include error name in the display?
joiner <li> if auto is enabled, a newline (\n) otherwise Join element to use if multiple errors are to be displayed at once, such as when all is enabled.
text Optional string in which the actual error message should be embedded. If the literal %s is present in the string, it will be substituted for the message. Otherwise the error text is just appended.
header
footer
list_container ul Default list container HTML tag (applicable only if auto is enabled).
class None CSS class name (applicable only if auto is enabled).
style None CSS style value (applicable only if auto is enabled).
extra None Extra HTML attributes (applicable only if auto is enabled).
show_label No
filter
required No Used for display purposes, as a hint to std_label. Enabling this attribute allows the label to be printed differently for required form fields. In the default label template, this means bold text, but in your custom labels the behavior is, of course, arbitrary.
interpolate     0 interpolate output?
hide     0 Hide the tag return value?

DESCRIPTION

The [error] tag was designed to report meaningful error messages to the users, should an error occur in the processing action (such as missing or invalid field values entered).

It can work in conjunction with the definitions set in a profile, and can generate error messages in any format you desire.

Error conditions can also be tested with the [if] conditional:

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

BEHAVIOR

This tag appears to be affected by, or affects, the following:
Catalog Variables: MV_ERROR_STD_LABEL, CSS_CONTRAST

EXAMPLES

Example: Automatic error display

The following will simply display all accumulated session errors. (Note that after display, session errors will be cleared and will not show up on subsequent page accesses).

<ul>
[error auto=1]
</ul>

Example: Trigger an error

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

Example: Show all errors

[error all=1 show_error=1]

Example: Clear all errors

[tmp clear_errors][error all=1 comment="Clear errors"][/tmp]

NOTES

AVAILABILITY

error is available in Interchange versions:

4.6.0-5.7.0 (git-head)

SOURCE

Interchange 5.7.0:

Source: code/SystemTag/error.coretag
Lines: 162


# Copyright 2002-2007 Interchange Development Group and others
# 
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.  See the LICENSE file for details.
# 
# $Id: error.coretag,v 1.11 2009-02-10 12:16:49 thunder Exp $

### This is in package Vend::Interpolate, and may make reference
### to variables in that module
UserTag error               Order        name
UserTag error               addAttr
UserTag error               PosNumber    1
UserTag error               Version      $Revision: 1.11 $
UserTag error               Routine      <<EOR
sub set_error {
my ($error, $var, $opt) = @_;
$var = 'default' unless $var;
$opt = { keep => 1 } if ! $opt;
my $ref = $Vend::Session->{errors};
if($ref->{$var} and ! $opt->{overwrite}) {
  $ref->{$var} .= errmsg(" AND ");
}
else {
  $ref->{$var} = '';
}

$ref->{$var} .= $error;
return tag_error($var, $opt);
}

sub tag_error {
my($var, $opt) = @_;
$Vend::Session->{errors} = {}
  unless defined $Vend::Session->{errors};
if($opt->{set}) {
  $opt->{keep} = 1 unless defined $opt->{keep};
  my $error = delete $opt->{set};
  if($opt->{param}) {
    $opt->{param} = [ $opt->{param} ] unless ref($opt->{param}) eq 'ARRAY';
    $error = sprintf($error, @{$opt->{param}});
  }
  return set_error($error, $var, $opt);
}
unless(defined $opt->{filter}) {
  $opt->{filter} = 'encode_entities';
}
my $err_ref = $Vend::Session->{errors};
my $text;
my @errors;
my $found_error = '';

if($opt->{auto}) {
  $opt->{all} = 1;
  $opt->{show_error} = 1;
  $opt->{std_label} = 0;
  $opt->{show_var} = 1
    unless defined $opt->{show_var};
  $opt->{joiner} = '<li>'
    unless length $opt->{joiner};
  $opt->{text} ||= '%s';
  $opt->{list_container} ||= 'ul';
  my $out = '';
  $out .= "<$opt->{list_container}";
  for(qw/ class style extra /) {
    next unless $opt->{$_};
    if($_ eq 'extra') {
      $out .= ' ' . $opt->{$_};
    }
    else {
      $out .= ' ' . qq{$_="$opt->{$_}"};
    }
  }
  $out .= '>';
  $out .= $opt->{joiner};
  $opt->{header} ||= $out;
  $opt->{footer} ||= "</$opt->{list_container}>";
}

$text = $opt->{text} if $opt->{text};

#::logDebug("tag_error: var=$var text=$text opt=" . ::uneval($opt));
#::logDebug("tag_error: var=$var text=$text");
if($opt->{all}) {
  $opt->{joiner} = "\n" unless defined $opt->{joiner};
  for(sort keys %$err_ref) {
    my $err = $err_ref->{$_};
    delete $err_ref->{$_} unless $opt->{keep};
    next unless $err;
    $found_error++;
    my $string = '';
    if ($opt->{show_label}) {
      if ($string = $Vend::Session->{errorlabels}{$_}) {
        $string =~ s/[:\s]+$//;
        $string .= " ($_)" if $opt->{show_var};
        $string .= ": ";
      } else {
        # Use the variable name unless Locale has a default label.
        my $label = errmsg("error_label_${_}");
        $label = $_ if $label eq "error_label_${_}";
        $string .= "($label): ";
      }
    } else {
      $string .= "$_: " if $opt->{show_var};
    }
    $string .= $err;
    push @errors, $string;
  }
#::logDebug("error all=1 found=$found_error contents='@errors'");
  return $found_error unless $text || $opt->{show_error};
  $text .= "%s" if $text !~ /\%s/;
  $text = pull_else($text, $found_error);

  return '' unless @errors;
  @errors = map { filter_value($opt->{filter}, $_) } @errors
    if $opt->{filter};
  my $etext = sprintf $text, join($opt->{joiner}, @errors);
  return join "", $opt->{header}, $etext, $opt->{footer};
}
$found_error = ! (not $err_ref->{$var});
my $err = $err_ref->{$var} || '';
delete $err_ref->{$var} unless $opt->{keep};
#::logDebug("error found=$found_error contents='$err'");
return !(not $found_error)
unless $opt->{std_label} || $text || $opt->{show_error};
$err = filter_value($opt->{filter}, $err)
if $opt->{filter};
if($opt->{std_label}) {
# store the error label in user's session for later
# possible use in [error show_label=1] calls
$Vend::Session->{errorlabels}{$var} = $opt->{std_label};
if($text) {
# do nothing
}
elsif(defined $::Variable->{MV_ERROR_STD_LABEL}) {
$text = $::Variable->{MV_ERROR_STD_LABEL};
}
else {
my $contrast = $::Variable->{CSS_CONTRAST} || 'mv_contrast';
$text = <<EOF;
<span class="$contrast">{LABEL} <small><i>(%s)</i></small></span>
[else]{REQUIRED <b>}{LABEL}{REQUIRED </b>}[/else]
EOF
}
$text =~ s/{LABEL}/$opt->{std_label}/g;
$text =~ s/{REQUIRED\s+([^}]*)}/$opt->{required} ? $1 : ''/ge;
$err =~ s/\s+$//;
}
$text = '' unless defined $text;
$text .= '%s' unless ($text =~ /\%s/ ||
                            length $::Variable->{MV_ERROR_STD_LABEL});

$text = pull_else($text, $found_error);
$text =~ s/\%s/$err/;
return $text;
}

sub {
return tag_error(@_);
}
EOR

AUTHORS

Interchange Development Group

SEE ALSO

warnings(7ic), MV_ERROR_STD_LABEL(7ic), CSS_CONTRAST(7ic)

DocBook! Interchange!