Creating custom Interchange tags

Table of contents
1. UserTag introduction
1.1. General
1.2. Tag aliases
1.3. A simple UserTag
1.4. A simple container tag
1.5. A longer example
1.6. UserTag file locations
2. UserTag properties
2.1. AddAttr
2.2. Alias
2.3. AttrAlias
2.4. CanNest
2.5. Description
2.6. Documentation
2.7. HasEndTag
2.8. Implicit
2.9. Interpolate
2.10. NoReparse
2.11. Order
2.12. PosNumber
2.13. PosRoutine
2.14. Routine
2.15. Version

UserTag introduction

General

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";
}
EOR

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);
}
EOR

The above would expand as follows:

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

THIS TEXT SHOULD BE ALL UPPER CASE

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>";
}
EOR

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]
[/quick_table]

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

Warning

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

AddAttr

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

Alias

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.

AttrAlias

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.

CanNest

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

Warning

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/Interpolate.pm for examples of nesting tags.

Description

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

Documentation

Some usage documentation for the tag.

UserTag tagname Documentation <<EOD

Usage: [tagname foo="bar"]

Returns: Baz

EOD

HasEndTag

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

Implicit

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.

Warning

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!

Interpolate

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.

NoReparse

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

Order

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"]

PosNumber

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

PosRoutine

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.

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
}
EOR

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.

Version

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

UserTag tagname Version 1.2