For more information... RTFM!

You are not logged in

Powered by Interchange version 5.7.0

Creating custom Interchange tags

UserTag introduction


To define a custom Interchange tag that is website-specific, you can place UserTag directives in your catalog.cfg file.  For server-wide tags, define your UserTags in interchange.cfg.  Website-specific tags take precedence if both are defined.  In fact, you can use this facility to override the supplied Interchange tag set with your own custom code.  The UserTag directive takes the following form:

UserTag tagname  property  value

  • tagname is the name of the custom tag.
  • property is the attribute (described below).
  • value is the value of the property for the tag.

The custom tags can either be based on Perl subroutines or just be aliases for existing tags.  Some quick examples are below.

Tag aliases

UserTag product_name Alias data products title

This will alias [product_name 99-102] into [data products title 99-102], which will output the title column for product code "99-102".  Don't use this with [item-data] and [item-field], as they are parsed separately.

A simple UserTag

UserTag company_name Routine <<EOR
sub {
    return "Your company name";

When you place a [company-name] tag in an Interchange page, the text "Your company name" will be substituted.

A simple container tag

UserTag caps HasEndTag 1
UserTag caps Routine   <<EOR
sub {
    return uc(shift);

The above would expand as follows:

[caps]This text should be all upper case[/caps]

A longer example

Here is a useful one you might like to use:

UserTag quick_table Order       border
UserTag quick_table HasEndTag   1
UserTag quick_table Interpolate 1
UserTag quick_table Routine     <<EOR
sub {
    my ($border,$body) = @_;
    $border = qq{ border="$border"} if length($border);

    my $out = qq{<table align="left"$border>};
    my @rows = split("\n+",$body);
    my ($left,$right);

    foreach (@rows) {
        ($left,$right) = split /\s*:\s*/, $_, 2;

        $left =~ s/^\s+//;
        $right =~ s/\s+$//;

        $out .= '<tr><td align="right" valign="top">';
        $out .= '<b>' unless $left =~ /</;
        $out .= $left;
        $out .= '</b>' unless $left =~ /</;
        $out .= '</td><td valign="top">';
        $out .= $right;
        $out .= '</td></tr>';
        $out .= "\n";
    return "$out</table>";

The above can be called like this:

[quick-table border=2]
    Name: [value name]
    City: [value city][if value state], [value state][/if] [value country]

As is the case with [perl] tag, user tags run under the Perl Safe module, with warnings disabled.  Unlike [perl] tags, however, custom user tags use Perl's "strict" pragma.

UserTag file locations

Local UserTags should be placed in a directory called "usertags", under your website's home directory (as specified using the Catalog directive, and where you'll find your "catalog.cfg" file).

Global UserTags should be placed in a directory called "usertags", under your interchange Instance's installation directory (where you'll find your "interchange.cfg" file).

If you don't have these directories, then you can create them as and when required.

To load your UserTags, you should ensure that your "interchange.cfg" and/or "catalog.cfg" file has a line that looks like the following:

include usertags/*tag


Avoid the temptation to place custom UserTags in one of the directories under the RunDir (usually "code") directory.  The files in these directories are considered to be part of the Interchange core distribution, and may be overwritten whenever you upgrade.

UserTag properties


Setting this property true causes Interchange to append a hash reference to the tag subroutine's argument list.  The passed hash reference contains all of the parameters passed to the tag, whether they appear in the Order list or not.  This allows for on-the-fly parameters, and parameters that depend upon other parameters etc.

UserTag tagname AddAttr 1


An alias for an existing (or other user-defined) tag.  It takes the form:

UserTag tagname Alias existing_tag parameters

An Alias is the only property that does not require a Routine to process the tag.


An alias for an existing attribute for defined tag.  It takes the form:

UserTag tagname AttrAlias alias attr

As an example, the standard [value] tag takes a named parameter called name, meaning that [value name="var"] will display the value of a form field called var.  If you put this line in your catalog.cfg file:

UserTag value AttrAlias identifier name

then [value identifier=var] will be an equivalent call.


Notifies Interchange that this tag must be checked for nesting.  This only applies to tags that have HasEndTag defined, of course. 

UserTag tagname CanNest 1



Your routine must handle the subtleties of nesting, so don't use this unless you are quite conversant with parser code.  See the tag_loop_list() and tag_if() subroutines in lib/Vend/ for examples of nesting tags.


A short description for the tag.  If you want to to provide a long description, then you should use the Documentation property.

UserTag tagname Descrption This is the tag's description


Some usage documentation for the tag.

UserTag tagname Documentation <<EOD

    Usage: [tagname foo="bar"]

    Returns: Baz



This attribute marks your custom tag as a "container".  Calls to your tag will be expected to include an ending [/tagname] marker.  The text in between the beginning [tagname] and ending [/tagname] will be the last argument sent to the defined subroutine.

UserTag tagname HasEndTag 1


This defines a parameter as having an implicit value, meaning that it can just be an attribute instead of an attribute=value pair.

UserTag tagname Implicit attribute value

If you want to set a standard include file to a fixed value by default, but don't want to have to specify [include file="/long/path/to/file"] every time, you can just use the following:

UserTag include Implicit file file=/long/path/to/file

and [include file] will be the equivalent.  You can still specify another value with [include file="/another/path/to/file"], of course.



The definition must refer to an attribute that has been defined using the Order property, otherwise there will be big problems.  Use this facility with caution!


The behaviour for this property depends upon whether the tag is a container (i.e. whether or not HasEndTag is defined).  If the tag is not a container then the Interpolate property causes the resulting text from the UserTag to be re-parsed for more Interchange tags.  If it is a container tag then Interpolate causes the contents of the tag body text to be parsed for further Interchange tags before the tag routine is run.

UserTag tagname Interpolate 1

Also see the NoReparse attribute.


The text returned by container tags is usually re-parsed for Interchange tags.  This is not always desirable, and can lead to unexpected results.  To counter this, the NoReparse attribute can be used to switch off this facility for the current UserTag, as follows:

UserTag tagname NoReparse 1


This property defines the order in which parameters will be passed to the Routine, and defines parameter names.

UserTag tagname Order param1 param2

A tag that was defined using the above Order could be called like this:

[tagname param1="foo" param2="bar"]


Deprecation notice

Deprecation notice

This property has been deprecated, as the number is automatically calculated from the Order property.  Please do not use this property as it may be removed, without warning, at any time.

UserTag tagname Order     foo bar baz
UserTag tagname PosNumber 3


Identical to the Routine property.  This defines a subroutine that will be called when positional, rather than named, parameters are used (i.e. [usertag value] instead of [usertag parameter=value].  If not defined then the Routine is used, and Interchange will usually do the right thing.  There is no real reason to use this property - just use Routine.


An inline Perl subroutine that will be used to process the tag.  It must not be named, and will be allowed to access unsafe elements only if AllowGlobal is set for the website in the interchange.cfg file.

UserTag tagname Routine <<EOR
sub {
    # your Perl code here

Parameters defined with the Order property will be sent to the subroutine first, followed by any encapsulated text (if HasEndTag is set).

The UserTag facility, combined with AllowGlobal, allows the user to define tags just as powerful as the standard Interchange tags.  This is not recommended for the novice, though.


The tag's version number, expressed as a free-form text value.

UserTag tagname Version 1.2

Category:  Interchange Perl usage
Last modified by: Kevin Walsh
Modification date: Tuesday 14 August 2007 at 10:26 AM (CDT)
Home  |  Legal nonsense  |  Privacy policy  |  Donations  |  Contact us