New Page Wizard (TCF)

TCF Overview

A Template Control File (TCF) is one of the components used in a template set in order to produce new content for use in OU Campus. The template fileset also includes a TMPL file and an image file, and typically also includes one or more XSL stylesheets (XSLs). 

The TCF is an XML document that is generally used to present the user who is creating content within the system a form with options whose selections are used to customize a new page, new RSS article, or new section. Advanced use of templates and TCFs might be quite more complex or have a specific purpose such as creating a redirect or creating a directory with specific files.

A TCF controls one or more TMPL files, defines variables, and customizes the form fields. The values of the variables either specified by the user or included in the TCF are injected into PCF by the TMPL with the echo var statements. 

The text node of the template element passes along the specific TMPL file to use. The form questions are defined with the use of the variable node, which is contained within the variable list. The form elements can be transparent to users or they can provide various configuration options to content creaters, and they can be defined as page properties and edited after the fact as necessary.

Requirements & Usage

The template files (.tcf, .tmpl, and .gif) reside in the template directory defined in the site record (Setup > Sites > Use Local Templates/Local Template Directory). Usually, the path is /resources/ou/templates. The location can be defined in the site record to be on the staging server or the production server, but current implementations use local templates (i.e., on the staging server). By placing one or more template sets inside that directory at that specified location, they are immediately available for the site's editors and end-users.

Legacy Templates

Note that the use of TCFs is a site-wide decision. If a site has previously used only TMPL or HTML files as template pages, the presence of one or more TCF files displaces all other forms of templates. Once a TCF has been uploaded, the site can no longer use the TMPL files directly. A TCF must be created to specifically access each TMPL. All TMPL files will be hidden to editors and end-users, and they will only be able to access TMPL files through the TCF format. For more information about HTML templates:

Legacy Templates

TCF Deconstructed

The TCF starts with a title.

<title>New One Column Page</title>

The title tag defines the text that appears at the top of the New Page Template form that users view when creating new content.

TCF New Page Form

Normally, a plain text title is inserted here, but an image can be used. For example:

<title><img style="text-align:center" src="http://workshop202.outc14.com/images/templating-006.png" /></title>

Template Title Image Example

The structural <title> tag is optional and may be seen contained by OmniUpdate properties tags.

The TCF can contain up to four lists:

  • variable list (always included)
  • directory list (included when creating a new directory)
  • template list (always included)
  • navigation list (used for autonav)

There are four structural tags, some of which encapsulate other tags. For example, the variable-list element holds the variable elements, but does not have any attributes.

<variable-list>[variable tags from below]</variable-list>
This structure tag encapsulates a list of variable tags that can be used to present users with one or more questions to answer when creating new pages, or used by administrators to set (hard code) values to be used by one or more TMPL files. The input from these form fields (produced from variable tags) can easily be echoed once or more into multiple pages created using this TCF. Inside a <variable-list> there can be one or more <variable> tags.

The <variable-list> structure tag is optional, but must be used to enclose any <variable> tags.

A variable tag is structured like the following example:

<variable name="pagetitle" prompt="Title" alt="New document title">Untitled</variable>

There is no limit to the number of variables that can be used.

Please see the TCF Reference page for more information regarding the syntax, attributes, and variable list for TCFs:

 

<template-list> [templates from below] </template-list>
This structure tag is the only section of a TCF that must be defined. It's comprised of one or more <template></template> tags, one for each template (.tmpl) file to be used.

<template [parameters]> templatefile.tmpl </template>
Each of these template tags defines the settings for the corresponding TMPL file. The following parameters may be used once per template tag.

  • prompt-prefix="_string_"
    Because the tcf format allows for multiple files to be created and referenced, the prompt-prefix parameter helps to identify the file to which a question refers. OU Campus adds the prompt-prefix to each question being asked. As an example, if prompt-prefix was "New file," the user may be asked "New file overwrite if exists?" If undefined, this parameter defaults to the name of template file (i.e., newpage.tmpl).
  • filename="_string_"&display-filename="yes (or) no"
    These parameters specify an output filename for the particular template, and whether the user views (and therefore can change) that name. By default, the filename given to any new page is "untitled" with your site's specified extension. Display-filename defaults to "yes", so that if neither of these parameters are declared, a user is presented with a box pre-filled with "untitled.extension". This can be modified by the user.
  • extension="_string_"
    The extension parameter lets an administrator suggest a particular file extension to the user. It only suggests; no extension is enforced. The default extension is defined in the site record.
  • overwrite="yes (or) no" & display-overwrite="yes (or) no"
    The overwrite parameter specifies an action to take when a file with the same name as the output filename already exists. The safer option, "no," is the default. The display-overwrite parameter, if set to "yes," lets the user decide whether or not to overwrite the file. "Yes" is the default for display-overwrite, allowing users to overwrite the existing file (regardless of permissions set for that file). It is assumed that if a user has access to this TCF, they should have the power to do as it explicitly states, even if it means a file overwrite. However, only Level 9 and 10 users will view this option, even if display-overwrite is set to "yes".
  • group="_string_"& display-group="yes (or) no"
    The group parameter is used to specify which group has edit access to the new page. This can be hard-coded in the TCF, or offered as a drop-down menu to the user. By default, the group selected will be "everyone" and will be displayed to the user for their possible modification. Keep in mind that user below level 9 can only select from groups to which they belong. Of course, these values can be hard-coded and not shown to the user, forcing that particular group upon the file. If a hard-coded group is specified and does not exist, an error will be signaled to the user.
  • toolbar="_string_"
    The toolbar parameter is used to specify the toolbar group that will be used when users edit the page. The default is the full, generic toolbar (when this value is not specified), but it can be customized by creating a Custom Toolbar and specifying it here. This will automatically apply the specified toolbar to the page, which is helpful for page navigation elements and other areas requiring specialized toolbars. If a hard-coded toolbar is specified and does not exist, an error will be signaled to the user.
  • destination="_path_"& force-destination="yes (or) no" & display-destination="yes (or) no"
    Using the destination parameter, the TCF can specify the location that a file will be placed when created using this template. This can include absolute paths from the root of the site, as well as relative paths to child and parent directories. Force-destination defaults to "no" but can be set to "yes," which will create directories as needed to make the specified location valid. The default destination is in the current folder. Display-destination defaults to "no" but allows the user to customize the destination path if set to "yes." Both relative and root paths (deriving from the site root) are allowed.
  • publish="yes (or) no" - Normally, when a file is created from a TCF, it is created on the staging server, awaiting a publish command from the user. However, there are times when the TCF author would like one or more of the pages created by the TCF to be automatically published to the production server upon creation. This parameter automatically publishes the specified page when it is created. For more information about auto-publish:

    Auto-Publish Pros and Cons (PDF)

  • preferred-redirect="yes (or) no"
    More than one file can be created using a TCF. This parameter specifies that the page created with this particular TMPL file will be the one to which the user is redirected for immediate editing, once the pages have been created. The default for this parameter is "no." If this parameter is not set to "yes" anywhere in a TCF, the user will be presented with a report of files created, and whether they were published. 

Examples

Example 1: Populating a Subdirectory with Includes
This TCF requires two TMPL files — one that will be used to create a sub-menu include, and another that will be the index file for the directory.

<title>Populate a New Subdirectory</title>

<variable-list>
<variable name="subtitle" prompt="Give your new page a subtitle" alt="This is the title displayed on the page itself"></variable>
<variable name="email" prompt="Enter your e-mail address to be encoded into the page"></variable> <variable name="pagenum" prompt="Type the page number of the new page" alt="Ex: 1, 2, 3, etc"></variable>
</variable-list>

<template-list>
<template prompt-prefix="Side Navigation file:" filename="nav1.inc" display-filename="no" overwrite="no" display-overwrite="yes" group="sidenav" display-group="yes" display-destination="yes" toolbar="CSS Strict - SideNav" >sidenav.tmpl</template>
<template prompt-prefix="Index file:" filename="index.html" display-filename="no" overwrite="no" display-overwrite="yes" group="everyone" display-group="yes" display-destination="yes" preferred-redirect="yes" toolbar="CSS Strict">TwoColumnIndex.tmpl</template>
</template-list>

Example 2: The TMPL Replacement
In the case that a site is using the TCF format and would like to have the original behavior applied to a page. This TCF is written to mimic the original TMPL functionality. For this method, there must be one TCF for each TMPL that is to possess the original behavior.

<title>New Page Creation</title>

<variable-list>
<variable name="title" prompt="Page Title" alt="Give your new web page a title."></variable>
<variable name="subtitle" prompt="Sub Title" alt="Give your new web page a sub title."></variable>
<variable name="metakey" prompt="Keywords" alt="Words that categorize your new page for search engines."></variable>
<variable name="metadesc" prompt="Description" alt="Describe your new page in about 40 words."></variable>
</variable-list>

<template-list>
<template prompt-prefix="New File">tmpl-to-use.tmpl</template>
</template-list>

Calendar Tutorial

One has the ability to produce and insert a calendar, using the TCF syntax, on any page being created. The concept is simple — define a variable in the TCF under the <variable list> tag, and echo it into the template using a standard <!--%echo var="" --> tag. Thus, there are two major steps to using the calendar insertion ability — defining the calendar variable in the TCF, and echoing the variable into the page. An optional third step is to apply CSS to adjust the calendar's look and feel.

  1. Define the calendar variable in the TCF. This is done using a standard <variable> tag (including the name="" parameter), and specifying your type="" as type="calendar". You can specify whether the user has the ability to specify a particular month for the calendar. If the variable's display="" property is set to "yes," the user will be presented with dropdowns to select an appropriate month and year. However, if it is set to "no," the TCF creator defines the following calendar-specific variables:
    • month="[1-12]" — specify the month that your calendar represents.
    • year="[yyyy]" — specify the four-digit year that your calendar represents.

    All of this information is processed by OU Campus, and converted into a variable which can be echoed into the templates by using the name="" parameter.
  2. Echo the calendar variable into the template. Calendars are displayed in new pages by echoing the calendar variable into the page, just as any other variable defined in the TCF. Place <!--%echo encoding="none" var="calendarVariable" -->. The encoding parameter is important! Without it, the calendar code will not display the calendar in an HTML table, but will convert all of the < & > tags into &lt; and &gt;, making the table unusable. Besides this special case, the standard procedure to echoing values into templates as they're created is the same.

    For more information about echo vars, visit the TMPL Reference page
  3. Optionally, apply CSS to the calendar to adjust the look and feel. When the calendar is displayed, CSS classes are used to define the look and feel of the calendar. The following class names are used, which can be defined in the site's CSS:
    • ox-calendar-div — Points to a <div> container which holds the entire calendar. Useful for some sizing and positioning of the calendar as a whole.
    • ox-calendar — Applies to the actual calendar table itself, allowing styles like borders and background colors to be applied.
    • ox-calendar-day-cell — Each cell (<td>) of the table has this class applied to it, regardless of whether it is an actual day, or just an empty placeholder.
    • ox-calendar-day-number — This class applies to a div that surrounds only the day number. It positions the day number anywhere in the day cell.

Filechooser Tutorial (Utilizing Directory Variables)

Users may be allowed to choose files for insertion into a page; for example, as a link or an include file, through the utilization of the "type=filechooser" parameter in the TCF. This option also allows administrators to make use of directory variables to determine the default directory displayed in the filechooser per directory.

  1. For each folder, create a new directory variable to determine the default include directory that will appear in the filechooser.The values of this variable can be defined as anything. Here is one example:

    Adding a Directory Variable

    For more information, visit the Directory Variables page.
  2. Include the directory variable within a variable node in the TCF. This directory variable will be reflected in the "path" parameter in the <variable> node of the TCF, accompanied by type="filechooser", as in the following example:

    <variable name="include" type="filechooser" path="{includesdir}" prompt="Include" alt="Choose a file to include on the page."></variable>
  3. Alternately, you can add a subdirectory path to the "path" parameter in the TCF to force the filechooser to open to that subdirectory. See the following example:

    <variable name="include" type="filechooser" path="{includesdir}/subdir" prompt="Include" alt="Choose a file to include on the page."></variable>

Additional Notes

  • You may wish to use the "lockout" parameter in the <variable> node of your TCF. This will prevent users from browsing outside of this directory in the filechooser "window".
  • You may choose to utilize the "filter" parameter in the <variable> node of your TCF. This will restrict the user from choosing certain filetypes from the files listed in the filechooser "window".

The value of a variable defined in a TCF can be used elsewhere in that TCF. Curly braces {} are used to define variable names. For example, a variable can be defined using a file name:

<variable name="filename" prompt="Enter Filename:" alt="Provide a filename for this new page. Use only letters, numbers and underscores. Do not enter the extension.">untitled</variable>

The TCF can also make use of directory variables in the TCF. Since directory variables can be set independently for each directory, this can come in useful for placing users in a specific directory when users are given the ability to choose files with a filechooser.