Using Variables in External Files and Templates

Variables

When you use variables in any of the HTML templates or text based additional files in Author-it, they resolve when publishing to web based outputs. This allows you to substitute text and/or graphics used by the external files.

Namespace declaration

When used in external files, the variable must be defined using a namespace declaration, where the text "authorit:" is prefixed to the variable itself. For example:

<authorit:variablename> where variablename is the variable to substitute.

In the world of XML and HTML, a namespace is a multi-part naming system that provides universally unique names for elements and attributes. This means the variable is always recognized as being unique, and won't conflict or trample over another element or tag used by another entity. For example, if the name of your variable was the same as a javascript or ASP function, you could get some rather unusual results in your published output. While we could simply sit back and say you need to take care when naming your variables, using namespaces removes the element of risk.

Important: If a variable does not use the namespace declaration it will not be resolved.

How does it work?

Variable substitution can be made in any plain text files that have a file extension. These extensions are defined in the Author-it Administrator program, with the defaults set to: .htm;.html;.xhtml;.mv;.asp;.aspx; and .js.
To substitute variables in additional files, enter further extensions as required.

Substitution is carried out the same as it is usually - with Author-it first substituting the value assigned on specific objects. If an object does not have an assignment, the value assigned to the Book is used. If there are no assignments, the default value is substituted.

So where would I use them?

Variables can be used to include changeable information in headers, footers, banners, feedback forms, for user tracking, and numerous other mechanisms in your web based documentation. Let's look at some examples:

  • Inserting the text: Last modified by: <authorit:sys_modifiedby> on <authorit:sys_modified> into your HTML template resolves at publishing time to display who last modified the topic and when.
  • Inserting a link of: mailto:feedback@abc.com?Subject=Article <authorit:sys_objectid> <authorit:sys_description>, into your HTML template creates an email link with the subject line prefilled to include the Topic ID and Description.
  • You can create and use a <charset> variable in Author-it, then reference this in an external HTML template to ensure the appropriate character sets are used when publishing into multiple languages.

You can even use variables when you need to localize text elements called by javascript functions.

External files and graphic substitution

Variable substitution in external files does not support File Object type variables. To include a changeable graphic, you need to use a Text or List of Values type variable defining the name of the graphic.

For example, img src=<authorit:logo> could be used to replace a company logo, allowing you to create various customizations for different products or customers without the need for different external templates for each customization. Simply define the variable <logo> in Author-it first, assign the appropriate value to the relevant books - image1.gif for Book A and image2.gif for Book B - and ensure the referenced graphics exist in the correct location. Specify the graphics as Additional Files in the HTML properties of the Book object, and Author-it will automatically copy the files to the publishing folder when publishing your HTML based outputs.