The Content Manager and the Template Engine execute link functions when versions are exported or displayed in the integrated, the separate or the live preview. The functions give you the possibility to modify link tags and therefore allow URL-Rewriting. For each tag that may contain a URI (Uniform Resource Identifier), two functions are called, one for the opening and one for the closing tag.
Calling Tcl procedures during export can negatively influence the
speed of the export. The link functions are therefore disabled by
default. They can be enabled by setting the
export.wantLinkCallback
system configuration entry to YES
. The functions are
disabled again by setting the value
to NO
.
The names of the functions are linkCallback
for the
opening and linkCallbackCloseTag
for the closing tag.
linkCallback
ProcedureThe Content Manager and the Template Engine call the
linkCallback
procedure according to the following
definition:
proc linkCallback {tagName srcId absSrcPath \ expId absExpPath relExpPath attrList} {}
The arguments have the following meaning:
tagName
: the name of the link tag.srcId
: the ID of the source file, i.e. of the file
containing the link tag.absSrcPath
: the absolute path of the source file.expId
: the ID of the file to be exported.absExpPath
: the absolute path of the file to be
exported.relExpPath
: the path of the file to be exported,
relative to the source file.attrList
: the list of attributes of the tag. Each
attribute is itself a list with the following elements:
attrName
: the name of the tag attribute.attrValue
: the value of the tag attribute.linkId
: the ID of the link.destId
: the ID of the target file.absDestPath
: the absolute path of the
target file (only for URL attributes, otherwise the empty
string).relDestPath
: the path of the target
file, relative to the source file (only for URL attributes,
otherwise the empty string).Please note that an argument contains an empty string if the value
does not exist. This is valid for, e.g. destId
in external
links. The procedure must return a list with the following elements:
tagName
: the possibly changed name of the link
tag.attrList
: the list of possibly changed attributes
of the tag. Each attribute is itself a list with the following
elements:
attrName
: the name of the tag attribute.attrValue
: the value of the tag attribute.reserved1
: the value of this element is
ignored.reserved2
: the value of this element is
ignored.reserved3
: the value of this element is
ignored.reserved4
: the value of this element is
ignored.Because the Content Manager and the Template Engine expect the
elements reserved1
up to reserved4
in the
subelements of attrlist
, you can create the results list
by assembling it from the first and last arguments of
linkCallback
.
Example (up to version 6.7.0)
The following example shows how to change the http
prefix into an https
prefix for external links.
proc linkCallback {tagName srcId absSrcPath expId absExpPath relExpPath attrList} { if { "$absExpPath" == "" || "$tagName" != "a" } { return [list $tagName $attrList] } set newList "" foreach attribute $attrList { set key [lindex $attribute 0] set value [lindex $attribute 1] if { "$key" == "href" || "$key" == "title" } { regsub "^http:" $value "https:" value } lappend newList [list $key $value {} {} {} {}] } return [list $tagName $newList] } proc linkCallbackCloseTag {tagName expId absExpPath} { return $tagName }
From CMS Fiona 6.7.1: The link callback
procedure supplied is able to call a custom procedure for every link
tag to process. Such custom procedures can be registered easily (see
the example below). This functionality is documented in the callback
script file
share/script/cm/serverCmds/linkCallback.tcl
.
Example (from version 6.7.1)
::linkCallback::registerHandler "a" "addBlankTarget" namespace eval ::linkCallback { proc addBlankTarget \ {tagName srcId absSrcPath expId absExpPath relExpPath attrList} { if {[existsAttr href] && [string match "http*" [attrValue href]]} { addMissingAttrValue target _blank return [dataAsCallbackResult] } return [unmodified] } }
linkCallbackCloseTag
ProcedureThe linkCallbackCloseTag
procedure is called up by the
Content Manager and the Template Engine according to the following
definition:
proc linkCallbackCloseTag {tagName expId absExpPath} {}
The arguments have the following meaning:
tagName
: the name of the link tag.expId
: the ID of the file to be exported.absExpPath
: the absolute path of the file to be
exported.Both CMS applications expect the possibly changed name of the link tag as a return value.