|> Home > Documentation > Latest documentation > Interchange Perl usage > Creating custom Interchange tags|
Creating custom Interchange tags
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:
The custom tags can either be based on Perl subroutines or just be aliases for existing tags. Some quick examples are below.
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
When you place a [company-name] tag in an Interchange page, the text "Your company name" will be substituted.
A simple container tag
The above would expand as follows:
A longer example
Here is a useful one you might like to use:
The above can be called like this:
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:
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.
An alias for an existing (or other user-defined) tag. It takes the form:
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:
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:
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.
A short description for the tag. If you want to to provide a long description, then you should use the Documentation property.
Some usage documentation for the tag.
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.
This defines a parameter as having an implicit value, meaning that it can just be an attribute instead of an attribute=value pair.
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:
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.
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:
This property defines the order in which parameters will be passed to the Routine, and defines parameter names.
A tag that was defined using the above Order could be called like this:
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.
Parameters defined with the Order property will be sent to the subroutine first, followed by any encapsulated text (if HasEndTag is set).
The tag's version number, expressed as a free-form text value.