Link Functions

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.

The linkCallback Procedure

The 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]
  }
}

The linkCallbackCloseTag Procedure

The 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.