Creating the TCFs

Title

The TCF begins with a <title> node. This contains the title for the New Page Wizard. It is used to help the users confirm they are creating the correct page or section.

<title>New Page</title>

Variable List

The <variable-list> node defines the variables set. It includes a variable for nearly every input field on the New Page Wizard’s form. The variables are configured similarly to those of page parameters. For details on all available variable attributes, visit the Support site and navigate to Development > New Page Wizard (TCF) > TCF Reference.

The variables can be configured as text, a filechooser, drop-down (select), checkboxes, radio buttons, or an asset. It is also possible to include a mini-WYSIWYG Editor with a text element.

For the purposes of this tutorial, the variables to be configured will include the:

  • Page title (text field)
  • Meta description (text field)
  • Keywords (checkboxes)
  • Author (text field)
  • Page type selection (drop-down)
  • Student quotes on or off (drop-down)
  • Automatic side navigation selection (drop-down)

Each variable will include at a minimum:

  • Name: A unique name for the variable. This is passed to the TMPL.
  • Prompt: The friendly identifier for the field.
  • Alt: The instructions for the field.

Without a type defined, the default is text.

When drop-down (select), checkboxes, or radio buttons are being used, options need to be included between the opening and closing variable tags. Options should always include their value and an identifier of whether or not that option has been selected. If these options are going to be echoed into the TMPL, output="xml" needs to be added to the <variable> tag to properly pass the full set of options and not just the selected value’s text.

Code for Variables

<variable-list>
<variable name="title" type="text" prompt="Enter Page Title:" alt="Give your new page a title."></variable> <variable name="description" type="text" prompt="Description:" alt="Describe your new page."></variable> <variable name="keywords" type="checkbox" prompt="Keywords:" alt="Select the appropriate keywords for the page." output="xml"> <option value="Gallena" selected="true">Gallena</option> <option value="GU" selected="true">GU</option> <option value="Gallena University" selected="true">Gallena University</option> <option value="Why Choose Gallena" selected="false">Why Choose Gallena</option> <option value="Undergraduate" selected="false">Undergraduate</option> <option value="Graduate" selected="false">Graduate</option> </variable> <variable name="author" type="text" prompt="Author:" alt="The author name for this page."></variable> <variable name="pagetype" type="select" prompt="Page Type:" alt="What type of page would you like to create?" output="xml"> <option value="article" selected="false">Article</option> <option value="content" selected="true">Content</option> <option value="onecolumn" selected="false">One Column</option> </variable> <variable name="quotes" type="select" prompt="Student Quotes:" alt="Do you want to display the student quotes?" output="xml"> <option value="true" selected="true">Yes</option> <option value="false" selected="false">No</option> </variable> <variable name="autonavigation" type="select" prompt="Add Navigation Item:" alt="Add the page to the left navigation file automatically?"> <option value="true" selected="true">Yes</option> <option value="false" selected="false">No</option> </variable> </variable-list>

Template List

After configuring the variables that will be used in the new page creation, the templates that should be created are defined. For a singular page, one template is generally defined, but for new sections, this will often include a template for the page, a template for the side navigation, and a template for the breadcrumb file. It is possible that other template files will be created. It all depends on the site’s configuration and template needs.

In this case, the TMPL that was created earlier will be created with this New Page Wizard. Within the <template-list> the <template> is defined. For a full list of available attributes, see the Support site, and navigate to Development > New Page Wizard (TCF) > TCF Reference.

This template will focus on:

  • Prompt-Prefix: This identifier for the template gets appended to pre-defined prompts that appear in the New Page Wizard as needed.
  • Filename: Provides a default filename for the page that will be created. If not included, this will default to untitled.
  • Extension: Provides the extension that will be appended to the filename.
  • Filename-Alt: Allows customized alt text to be provided that will show up next to the filenaming field.
  • Display-Group: Setting “no” for this attribute hides the access drop-down for the page creation. This is strongly encouraged in order to prevent users from changing the settings as defined by the administrator.
  • Display-Destination: Setting “no” for this attribute hides the destination field allowing a destination to be included identifying where the new page should be created. This should generally be set to “no,” but if the destination attribute is being used, this can be used to allow the destination to be changed by the user.
  • Display-Overwrite: Setting “no” for this attribute hides the overwrite checkbox, which would allow the user to overwrite a file of the same name. This is strongly encouraged in order to help maintain content integrity and prevent undesired overwrites.
  • Preferred-Redirect: Setting “yes” identifies this file as the desired redirect after the new page is created, taking the user directly to this page for editing purposes.
  • Publish: Setting “no” identifies that this file should not be published upon creation.
  • Autonav: By using the variable name from the <variable-list> within a set of curly braces, the selection from the variable is passed to this attribute, and then ultimately will be passed to the <navigation-list>.

The TMPL name will be added between the opening and closing <template> tags.

Code for Template

<template-list>
<template prompt-prefix="New Page" filename="untitled" extension="pcf" filename-alt="Use only lowercase letters, numbers, and hyphens only." display-group="no" display-destination="no" display-overwrite="no" preferred-redirect="yes" publish="no" autonav="{autonavigation}">pt-new-page.tmpl</template>
</template-list>

Navigation List

The <navigation-list> defines whether or not a new navigation item is added to the side navigation file. The value passed starts in the variables, gets passed through the templates, and then defines the action to take place.

In this case, if the value passed is “true,” a new line item is created in the _leftnav.inc file of the current directory. The line item will include the value of the title variable that was defined above, as wells as the root relative path to the file. If the value passed is “false,” no additional actions will occur.

The navigation list requires:

  • Name: Identifies whether the selection above was true or false.
  • Path: Identifies the path to the side navigation file.
  • Publish: Entering “no” means that the side navigation file will not be automatically published on creation of the new item, which is preferred as the page to which that would correspond does not yet exist on production.

Code for Navigation

<navigation-list>
	<navigation name="true" path="_leftnav.inc" group="everyone" publish="no">
		<li><a title="{title}" href="{ox_autonav:shorturl}">{title}</a></li>
	</navigation>
	<navigation name="false" path="_leftnav.inc" group="everyone" publish="no"></navigation>
</navigation-list>

Complete TCF Code

When all of the above elements are put together, this creates the TCF. The TCF will be saved as pt-new-page.tcf to /_resources/ou/templates, and a corresponding gif image with the same name (pt-new-page.gif) will be uploaded to the same folder.

Complete Code

<title>New Page</title>
<variable-list> <variable name="title" type="text" prompt="Enter Page Title:" alt="Give your new page a title."></variable> <variable name="description" type="text" prompt="Description:" alt="Describe your new page."></variable> <variable name="keywords" type="checkbox" prompt="Keywords:" alt="Select the appropriate keywords for the page." output="xml"> <option value="Gallena" selected="true">Gallena</option> <option value="GU" selected="true">GU</option> <option value="Gallena University" selected="true">Gallena University</option> <option value="Why Choose Gallena" selected="false">Why Choose Gallena</option> <option value="Undergraduate" selected="false">Undergraduate</option> <option value="Graduate" selected="false">Graduate</option> </variable> <variable name="author" type="text" prompt="Author:" alt="The author name for this page."></variable> <variable name="pagetype" type="select" prompt="Page Type:" alt="What type of page would you like to create?" output="xml"> <option value="article" selected="false">Article</option> <option value="content" selected="true">Content</option> <option value="onecolumn" selected="false">One Column</option> </variable> <variable name="quotes" type="select" prompt="Student Quotes:" alt="Do you want to display the student quotes?" output="xml"> <option value="true" selected="true">Yes</option> <option value="false" selected="false">No</option> </variable> <variable name="autonavigation" type="select" prompt="Add Navigation Item:" alt="Add the page to the left navigation file automatically?"> <option value="true" selected="true">Yes</option> <option value="false" selected="false">No</option> </variable> </variable-list>
<template-list> <template prompt-prefix="New Page" filename="untitled" extension="pcf" filename-alt="Use only lowercase letters, numbers, and hyphens." display-group="no" display-destination="no" display-overwrite="no" preferred-redirect="yes" publish="no" autonav="{autonavigation}">pt-new-page.tmpl</template> </template-list>
<navigation-list> <navigation name="true" path="_leftnav.inc" group="everyone" publish="no"> <li><a title="{title}" href="{ox_autonav:shorturl}">{title}</a></li> </navigation> <navigation name="false" path="leftnav.inc" group="everyone" publish="no"></navigation> </navigation-list>

Example New Page Wizard

New Page Wizard

After creaing the new TCF, test it!

Notes on Filenaming

The result of the above steps provides a filename field in the New Page Wizard which includes the .pcf extension. Users will need to be made aware of the importance of leaving the extension in place when creating a new page. If .pcf is removed and replaced with a different extension, the XSL styling the page will not be called, resulting in no header, footer, includes, styles, or other such elements.

Filename With Extension

Alternatively, a variable could be used for the filename, and then passed to the filename attribute in the <template> node using curly braces. In this case, be sure to include the attribute display-filename="no" as the filename will be populated from the variable. The filename-alt attribute is also not needed. If using this method, be sure to train users that an extension should not be included when creating a new page. If an extension is included (e.g., html), the resulting filename would appear like this: newpage.html.pcf. It can be valuable to update the alt text of the variable to include a note about not including the extension.

File Name With No Extension

Example TCF Code

<title>New Page</title>
<variable-list> <variable name="title" type="text" prompt="Enter Page Title:" alt="Give your new page a title."></variable> <variable name="description" type="text" prompt="Description:" alt="Describe your new page."></variable> <variable name="keywords" type="checkbox" prompt="Keywords:" alt="Select the appropriate keywords for the page." output="xml"> <option value="Gallena" selected="true">Gallena</option> <option value="GU" selected="true">GU</option> <option value="Gallena University" selected="true">Gallena University</option> <option value="Why Choose Gallena" selected="false">Why Choose Gallena</option> <option value="Undergraduate" selected="false">Undergraduate</option> <option value="Graduate" selected="false">Graduate</option> </variable> <variable name="author" type="text" prompt="Author:" alt="The author name for this page."></variable> <variable name="pagetype" type="select" prompt="Page Type:" alt="What type of page would you like to create?" output="xml"> <option value="article" selected="false">Article</option> <option value="content" selected="true">Content</option> <option value="onecolumn" selected="false">One Column</option> </variable> <variable name="quotes" type="select" prompt="Student Quotes:" alt="Do you want to display the student quotes?" output="xml"> <option value="true" selected="true">Yes</option> <option value="false" selected="false">No</option> </variable> <variable name="autonavigation" type="select" prompt="Add Navigation Item:" alt="Add the page to the left navigation file automatically?"> <option value="true" selected="true">Yes</option> <option value="false" selected="false">No</option> </variable> <variable name="filename" type="text" prompt="New Page Filename" alt="Use only lowercase letters, number, and hyphens. Do not include an extension.">untitled</variable> </variable-list>
<template-list> <template prompt-prefix="New Page" filename="{filename}" extension="pcf" display-filename="no" display-group="no" display-destination="no" display-overwrite="no" preferred-redirect="yes" publish="no" autonav="{autonavigation}">pt-new-page.tmpl</template>
</template-list>
<navigation-list> <navigation name="true" path="_leftnav.inc" group="everyone" publish="no"> <li><a title="{title}" href="{ox_autonav:shorturl}">{title}</a></li> </navigation> <navigation name="false" path="leftnav.inc" group="everyone" publish="no"></navigation> </navigation-list>

 Creating a New Section TCF

A new section TCF is created in a similar fashion to the new page TCF. The main differences include:

  • Defining a directory name
  • Hiding the page’s filename
  • Calling additional templates as part of the <template-list> in order to create the supporting files

Additionally, <directory-list> will be used as a part of this demonstration. It is possible to create the new directory for the section without the <directory-list>, but the using of <directory-list> allows for empty directories to be created and access settings to be assigned. This is helpful in cases where an images or documents folder is desired.

Create the new TCF by making a copy of the existing TCF, and making the updates described:

  1. Update the text within the <title> node to: New Section.
  2. Add a new variable for defining the new section's directory name:
    <variable name="dirname" type="text" prompt="Enter a Directory Name:" alt="Use lowercase letter, numbers, or hyphens only to create a new directory name."></variable>
  3. Create a new <directory-list>, and pass the newly created directory name to it. Use {directory/} to pull in the current directory's path, and also create a new directory for PDFs.
    <directory-list>
    <parent path="{directory/}">
    <directory name="new-dir">{dirname}</directory>
    <directory name="new-images">{dirname}/pdfs</directory>
    </parent>
    <directory-list>
  4. Update the template for the page to have:
    • filename="index" — This will be the homepage for the section, and it should always have the same name. For this instance, it should be index, but depending on the institution’s settings, it may be default, or some other common name.
    • Remove filename-alt — Since the filename will not be displayed, the filename-alt is no longer needed.
    • Add display-filename="no" — To prevent the user from accidentally changing the filename from the desired index to something else, the filename is hidden.
    • Add destination="{new-dir}" — Defines the destination for the files to be created in the new directory. Uses the variable created in the <directory> tag above.
    • Add force-destination="yes" — Creates the folders or directories if they do not exist already and have not been defined.
  5. Add in two new <template> tags. One for creating the side navigation file (_leftnav.inc) and one for creating the breadcrumb file (_properties.inc). Make sure to change the preferred-redirect to “no” for each of these templates.
<template prompt-prefix="Navigation" filename="_leftnav" extension="inc" display-filename="no" destination="{new-dir}" force-destination="yes" display-group="no" display-destination="no" display-overwrite="no" preferred-redirect="no" publish="no">leftnav.tmpl</template>
<template prompt-prefix="Properties" filename="_properties" extension="inc" display-filename="no" destination="{new-dir}" force-destination="yes" display-group="no" display-destination="no" display-overwrite="no" preferred-redirect="no" publish="no">properties.tmpl</template>

Complete Section TCF Code

When all of the above elements are put together, this creates the TCF. The TCF will be saved as pt-new-section.tcf to /_resources/ou/templates, and a corresponding gif image with the same name (pt-new-section.gif) will be uploaded to the same folder.

Complete Code

<title>New Section</title>
<variable-list> <variable name="dirname" type="text" prompt="Enter a Directory Name:" alt="Use lowercase letter, numbers, or hyphens only to create a new directory name."></variable> <variable name="title" type="text" prompt="Enter Page Title:" alt="Give your new page a title."></variable> <variable name="description" type="text" prompt="Description:" alt="Describe your new page."></variable> <variable name="keywords" type="checkbox" prompt="Keywords:" alt="Select the appropriate keywords for the page." output="xml"> <option value="Gallena" selected="true">Gallena</option> <option value="GU" selected="true">GU</option> <option value="Gallena University" selected="true">Gallena University</option> <option value="Why Choose Gallena" selected="false">Why Choose Gallena</option> <option value="Undergraduate" selected="false">Undergraduate</option> <option value="Graduate" selected="false">Graduate</option> </variable> <variable name="author" type="text" prompt="Author:" alt="The author name for this page."></variable> <variable name="pagetype" type="select" prompt="Page Type:" alt="What type of page would you like to create?" output="xml"> <option value="article" selected="false">Article</option> <option value="content" selected="true">Content</option> <option value="onecolumn" selected="false">One Column</option> </variable> <variable name="quotes" type="select" prompt="Student Quotes:" alt="Do you want to display the student quotes?" output="xml"> <option value="true" selected="true">Yes</option> <option value="false" selected="false">No</option> </variable> <variable name="autonavigation" type="select" prompt="Add Navigation Item:" alt="Add the page to the left navigation file automatically?"> <option value="true" selected="true">Yes</option> <option value="false" selected="false">No</option> </variable> </variable-list>
<directory-list> <parent path="{directory/}"> <directory name="new-dir">{dirname}</directory> <directory name="new-images">{dirname}/pdfs</directory> </parent> <directory-list>
<template-list> <template prompt-prefix="New Page" filename="index" extension="pcf" display-filename="no" destination="{new-dir}" force-destination="yes" display-group="no" display-destination="no" display-overwrite="no" preferred-redirect="yes" publish="no" autonav="{autonavigation}">pt-new-page.tmpl</template> <template prompt-prefix="Navigation" filename="_leftnav" extension="inc" display-filename="no" destination="{new-dir}" force-destination="yes" display-group="no" display-destination="no" display-overwrite="no" preferred-redirect="no" publish="no">leftnav.tmpl</template> <template prompt-prefix="Properties" filename="_properties" extension="inc" display-filename="no" destination="{new-dir}" force-destination="yes" display-group="no" display-destination="no" display-overwrite="no" preferred-redirect="no" publish="no">properties.tmpl</template> </template-list>
<navigation-list> <navigation name="true" path="_leftnav.inc" group="everyone" publish="no"> <li><a title="{title}" href="{ox_autonav:shorturl}">{title}</a></li> </navigation> <navigation name="false" path="leftnav.inc" group="everyone" publish="no"></navigation> </navigation-list>

Example New Page Wizard

New Page Wizard

Test the new section!

Converting Common Variables to Includes

When multiple TCFs are being created, it is common to have variables, template sets, and the navigation items repeat. In order to make editing the TCFs easier in the future, it is useful to group the repeated elements together and add them to an include file. The include file can be added to applicable TCFs. If the elements within the include file need to be updated, they only need to be updated in one location, and the updates will apply to all TCFs using that file.

There are certain requirements to use include files:

  1. The include file must have an extension of .inc. It cannot be a .tcf extension as it will then be included in the New File template selecting page and will result in an error if chosen.
  2. The include file must be in the same templates directory as the TCFs referencing the file/performing the inclusion or an error will result.
  3. The content of the include file must be a valid TCF command set.

Creating the Common Variables and Navigation Includes

To create the include files for the common variables and navigation, copy the code from one of the created and confirmed TCFs. For this demonstration, start with the pt-new-page.tcf file, and copy the variables for:

  • Title
  • Description
  • Keywords
  • Author
  • Page type
  • Quotes
  • Auto navigation

In an empty text file, paste the variables. Save the file with the name pt-commonvars.inc, and upload it to /_resources/ou/templates.

<variable name="title" type="text" prompt="Enter Page Title:" alt="Give your new page a title."></variable>
<variable name="description" type="text" prompt="Description:" alt="Describe your new page."></variable>
<variable name="keywords" type="checkbox" prompt="Keywords:" alt="Select the appropriate keywords for the page." output="xml">
	<option value="Gallena" selected="true">Gallena</option>
	<option value="GU" selected="true">GU</option>
	<option value="Gallena University" selected="true">Gallena University</option>
	<option value="Why Choose Gallena" selected="false">Why Choose Gallena</option>
	<option value="Undergraduate" selected="false">Undergraduate</option>
	<option value="Graduate" selected="false">Graduate</option>
</variable>
<variable name="author" type="text" prompt="Author:" alt="The author name for this page."></variable>
<variable name="pagetype" type="select" prompt="Page Type:" alt="What type of page would you like to create?" output="xml">
	<option value="article" selected="false">Article</option>
	<option value="content" selected="true">Content</option>
	<option value="onecolumn" selected="false">One Column</option>
</variable>
<variable name="quotes" type="select" prompt="Student Quotes:" alt="Do you want to display the student quotes?" output="xml">
	<option value="true" selected="true">Yes</option>
	<option value="false" selected="false">No</option>
</variable>
<variable name="autonavigation" type="select" prompt="Add Navigation Item:" alt="Add the page to the left navigation file automatically?">
	<option value="true" selected="true">Yes</option>
	<option value="false" selected="false">No</option>
</variable>

Then replace the variables in the TCF with:

<variable-list>
<include>pt-commonvars.inc</include>
</variable-list>

Repeat the steps for the two <navigation> nodes. Save the include file as pt-navigation.inc.

<navigation name="true" path="_leftnav.inc" group="everyone" publish="no">
<li><a title="{title}" href="{ox_autonav:shorturl}">{title}</a></li>
</navigation>
<navigation name="false" path="leftnav.inc" group="everyone" publish="no"></navigation>

Then within the TCF, replace the <navigation> nodes with:

<navigation-list>
<include>pt-navigation.inc</include>
</navigation-list>

After making the changes, test the updates using the New Page Wizard.

Creating the Section Templates Include

Now that the common variables include has been created, open the pt-new-section.tcf. Start by replacing the variables that were just put in the include file with the same include syntax, and repeat for the navigation section.

<variable-list>
<variable name="dirname" type="text" prompt="Enter a Directory Name:" alt="Use lowercase letter, numbers, or hyphens only to create a new directory name."></variable>
<include>pt-commonvars.inc</include>
</variable-list>
<navigation-list>
<include>pt-navigation.inc</include>
</navigation-list>

Then copy the two <template> nodes for the side navigation and breadcrumb files. Repeat the steps for creating an include that were described above for these two <template> nodes. Save this file with the name pt-sectiontemplates.inc.

<template prompt-prefix="Navigation" filename="_leftnav" extension="inc" display-filename="no" destination="{new-dir}" force-destination="yes" display-group="no" display-destination="no" display-overwrite="no" preferred-redirect="no" publish="no">leftnav.tmpl</template>
<template prompt-prefix="Properties" filename="_properties" extension="inc" display-filename="no" destination="{new-dir}" force-destination="yes" display-group="no" display-destination="no" display-overwrite="no" preferred-redirect="no" publish="no">properties.tmpl</template>

In the pt-new-section.tcf file, replace the two <template> nodes with:

<template-list>

<template prompt-prefix="New Page" filename="index" extension="pcf" display-filename="no" destination="{new-dir}" force-destination="yes" display-group="no" display-destination="no" display-overwrite="no" preferred-redirect="yes" publish="no" autonav="{autonavigation}">pt-new-page.tmpl</template>
<include>pt-sectiontemplates.inc</include>
</template-list>

These same steps could be repeated for the <directory-list>’s child nodes if desired and repeated in other sections.

After making all changes and saving all files, test the outcome.