Template (TMPL) Files

TMPL Overview

The TMPL file is one of the core files used in templating. When a user fills out the New Page Wizard, the TCF, along with the TMPL work together to create new content. A basic use case for a template file set is to create a new page file (PCF) on the staging server. By default, the template file sets are XML/XSL-based and the TMPL is an XML file; although, legacy HTML-based templates are also supported. 

The TMPL, as an XML file, can perform a wide variety of functionality in creating content, but for purposes of getting started, the simple use case of creating a page in OU Campus is used for the purposes of illustration and discussion. In this case the TMPL provides a basic structure for the resulting PCF, includes prolog information, includes XML nodes structure, OU Campus page tagging, and echo var statements for passing values to the resultant PCF.

The TMPL contains code that tells the template control file (TCF) what and where to insert the text the user defines. The echo var statements can use predefined system variables or use variables defined in the TCF to pass the user's text and other values to the TCF, which get added as the new content.

For example, when creating a new page the user is prompted to enter the page title. The value entered here is passed by the {title} variable in the TCF. The echo var declaration in the TMPL uses the value of the variable in manufacturing the PCF.

The resulting PCF includes both the value of the variable, the actual page title, and the appropriate XML page tagging such as a <title></title> element.

More than one TMPL file can be used with a TCF. In advanced templates, the process of creating a new page can actually create many pages, files, and folders all at once. A template file might also provide more than one pcf-stylesheet declaration, which specifies the XSL files used for transforming the PCF. This is included as part of the prologue in the TMPL:

<?pcf-stylesheet path="/_resources/xsl/default.xsl" extension="html"?>

The template must be saved with the extension .tmpl. The prefix to the extension should follow the file naming convention for the site.

Typically, although can easily vary from site to site, or account to account, templates are placed in the following directory:

_resources/ou/templates

The location of templates can be changed by editing the site record. Level 10 administrator privileges are required.

1. Navigate to access Setup > Sites.
2. Select the Use Local Templates checkbox.
3. Define the path for the templates on the staging server.

A super admin can upload template files to the OMNI-INF/templates folder and these templates are inherited for sites within the account as well as templates that are defined at the site level.

File Naming Convention

For standard template, the TMPL and the TCF prefixes in a file name will match. For example, if the TCF is named onecolumn.tcf, the TMPL should take the name of onecolumn.tmpl. The name of the TMPL is used in the TCF <template /> tag.

By default, file naming convention in the OU Campus CMS restricts the available character set that may be used when creating and naming a new page file or uploading a file. This file naming conventions includes lowercase letters, numeric values, hyphens, underscores, and periods only. The regex for this naming convention would be:

[a-z0-9\-_.]*

File naming convention can be configured for a site from Setup > Sites > File Naming.

Creating Logical Paths

During new page creation, the page may be stored in many possible directories at different levels of the server. For that reason the image and link paths should be absolute from the site root. For instance, if the image has a src="/ox/z-includes/../images/coolnavbutton.gif", the image could wind up missing if it is put it in a directory that was at a different level within the site. A correct path should look something like this:

/images/coolnavbutton.gif

Processing Instructions

The TMPL file includes the processing instructions for the XSL stylesheet declaration to use to create a final page that will be published. This processing instruction for the stylesheet declaration is included in the prolog. While strict XHTML can be used, the file should not include HTML. All of the HTML structure for a particular template file set belongs in the XSL file.

OUC Tags and Tagging

In addition to the XML and echo var statements, OU Campus tagging style is also used. Previously tags were structured in the form of HTML comments and this is being phased out. The change in style provides greater XML compliance and allows the OmniUpdate tags to be represented as valid XML nodes. The comment-style tags use the following syntax:

<!-- com.omniupdate.xxx --><!-- /com.omniupdate.xxx -->

While these will still work, the new form of the tag for new implementations is:

<ouc:xxx></ouc:xxx>

There is a transitional form of the tag that is used in current implementations:

<!-- ouc:xxx --> <!-- /ouc:xxx -->

or

<!-- ouc:xxx / -->

For example, rather than:

<!-- com.omniupdate.div label="new_content" group="Everyone" button="707" --><!-- /com.omniupdate.div>

The new tag is:<ouc:div label="new_content" group="Everyone" button="707">

And the closing tag for the element:

</ouc:div>

All three styles of tagging will work and continue to be supported.
The tags for two elements are auto-updated in current implementations of the OU Campus system. The editor and multieditor tags are converted to the transitional tags. For example, when within an editable region in the WYSISYG editor, saving will generate the intermediary style tag for the editor element for that area. Viewing code within OU Campus shows the tagging style.

About Echo Vars

The TMPL file is an XML document that includes the nodes that will contain the content. It can utilize XHTML, as the document will be well formed. It also includes the tagging for the predefined variables that collect data passed from the TCF. The echo var tag is included within HTML comment tags, or OUC tagging style, and uses a system variable to echo, or "print," the value. For example, the parent variable:

<!--%echo var="parent" -->

This prints the path from the site root to the directory that contains the current directory. They are placed to receive entered information from the TCF file as well as any needed OU Campus tagging. For example:

<!-- com.omniupdate.properties -->
<title><!--%echo var="title" --></title>
<!-- /com.omniupdate.properties -->

In this example, the TMPL echo var will get passed the value of title. The PCF and published HTML file will include the <title> </title> element with the value of the variable. The OU Campus properties tag encloses both the echo var statement and XML <title> </title>, indicating it is a page property.

Prolog

<?xml version="1.0" encoding="utf-8"?>
<?pcf-stylesheet path="/_resources/xsl/default.xsl" extension="html"?>
<?pcf-stylesheet path="/_resources/xsl/page2pdf.xsl" extension="pdf" alternate="yes" title="PDF"?>
<!DOCTYPE document SYSTEM "http://commons.omniupdate.com/dtd/standard.dtd">

Root Node

<document>

Echo Var Example

<!-- com.omniupdate.properties -->
<title><!--%echo var="title" --></title>
<!-- /com.omniupdate.properties -->

Page Main Content

In this case, the <content> tag includes a OUC div and editor tag. The new page, upon creation, will have an editable region that allows for the WYSIWYG editor.

<content>
<!-- com.omniupdate.div label="twocolumn_content" group="Everyone" button="700" break="break" -->
<!-- com.omniupdate.editor csspath="/_resources/ou/editor/onecolumn.css" cssmenu="/_resources/ou/editor/styles.txt" width="1050" -->
<h2 class="h-color-link"><!--%echo var="title" --></h2>
<!-- /com.omniupdate.div -->
</content>

More About TMPL/Echo Var

Replacing the Title

<title>Gallena University: <!--%echo var="subtitle" --></title>

Replacing Keyword and Description Tags

<meta name="keywords" content="<!--%echo var="metakey" -->">
<meta name="description" content="<!--%echo var="metadesc" -->">

Adding the Title Tag to the Template 

<p><font size="+3"><!--%echo var="subtitle" --></font></p> (with formatting) 
<!--%echo var="subtitle" --> (without formatting)

Creating Editable Regions

<!-- com.omniupdate.div 
label="twocolumn_content"
group="Everyone"
button="700"
break="break" -->
<!-- com.omniupdate.editor
csspath="/_resources/ou/editor/twocolumn_content.css"
cssmenu="/_resources/ou/editor/styles.txt" width="1050" -->
<h2 class="h-color-link"><!--%echo var="title" --></h2>
<!-- /com.omniupdate.div -->

For the "label" attribute for the div element, the value must be unique. In other words, do not assign multiple areas on the same page with the same name. The file naming convention for the label does not allow for any punctuation characters.

The "group" attribute can be used to define the user group that has access to that editable region. It is often helpful to use the default group "Everyone" for the main content division. Unique groups such as "Side Navbar Editors" can be assigned to the editable region for the side navigation to limit access to specific users. Because the group "Everyone" contains all users you'll be able to quickly assign page access to any specific sub-group without changing the group tag in the code.

Note that users must also have assigned access to a page or directory before they can edit the page -- regardless of the "Group" attribute assigned to the editable region. Levels 9 and 10 administrators trump the group assignment access.

Using Include Files in a TMPL

Using the div and editor tags can also be used with include files to create global navigation elements. For example, a text file called footer.inc can be created and put in an includes directory. The Path attribute can be included with the div to include the file.

TMPL files can define variables, usually at the begining of the file, and then echo the value of these variables one or more times within the new page when it's created.

Final Notes and Reminders

A TMPL:

  • Must be saved with the extension .tmpl
  • Is XML
  • Usually includes a prolog with pcf-stylesheet declarations for the XSLT 
  • Can be HTML, but is deprecated 
  • Contains code that tells the TCF what and where to insert the text the user defines
  • Can use echo var statements <!--%echo var="description" -->
  • Can use predefined system variables or TCF variables
  • Can include OU Campus page tagging
  • The TCF uses one or more TMPLs in the <template> node (nested in <template-list>