Overview

Welcome!

This Overview is a general tutorial of the Template system. You can click the menu links on the left if you need to learn about a specific element of the system.

The purpose of the Template System Documentation is to help you understand the way the program uses Templates, Placeholders (and Modifiers), and Template Commands to publish and create your content.

Generic Examples

This documentation is useful for any of our products that use this template system. Since each individual template has it's own applicable Placeholders and TemplateCells (more about them later), we've kept the examples general. The documentation for any specific program has a list of all templates and placeholders available.

Templates

Templates are HTML files used by the program as a "blueprint" for the content it generates. They are normal HTML with a few custom tags, so that the Templates appear as close as possible to the content generated by the program.

You can modify the Templates as easily as any other HTML file, using your favourite text or WYSIWYG web page editor such as HomeSite, UltraEdit, Dreamweaver, FrontPage, etc. (though you might need to make sure your editor isn't configured to remove comments or custom tags).

[ learn more... ]

Placeholders

Templates use Placeholders to tell the program where to insert content. Each placeholder corresponds to different content - usually a single field from a specific record (like the title of an article or the address field for a property listing).

You can find out what placeholders are available on any given page by using the templatePlaceholderList command.

Placeholders begin and end with a dollar sign ($), making them easy to identify in the templates.

Here are some examples of placeholders:

placeholder program outputs
$article.title$ The title of the article
$article.date$ The date, formatted "Jan 1, 2000"
$article.summary$ A short summary of an article's content.
$user.fullname$ The full name entered for a user account
$foo$, $bar$, $baz$, $bip$, $placeholder$ Non-existant placeholders used as examples in this documentation.

[ learn more... ]

templateCell

Some sections of HTML are only displayed in specific circumstances. TemplateCells are used to define the boundaries of these sections.

The rules for when each TemplateCell is used are part of the program, and most templates won't work correctly if they are removed - though they can be modified however you like.

Example:

In the following Template code, the "row" templateCell will typically be repeated several times, once each item in a list of records (like a list of products or article headlines). If there is no content in the program to use for the generated page, the "not_found" templateCell will be output instead. 
1    $foo$
2    <!-- templateCell : row -->
3      <p>
4         <a href="$bar$"><b>$baz$</b></a>
5         <br>
6         $bip$</p>
7    <!-- /templateCell : row -->
8 
9    <!-- templateCell : not_found -->
10         <p>No items were found</p>
11   <!-- /templateCell : not_found -->

TemplateCells are commonly used for repeating code, such as for a list of matches on a search results page or a headlines file.

[ learn more... ]

templateInsert

A templateInsert "hides" the code (usually a Placeholder) from Template View, but the code is displayed normally in Generated View.

It makes it easier to work with the templates by modeling your Template View as closely as possible to your Generated View - the templateInsert hides code that looks odd in the Templates, but is resolved when the content is generated. For example, Placeholders with long names can break a table's width, even though the values displayed for those placeholders look fine when the content is generated.

Example:

In the Template below, we've used templateInserts to hide placeholders on line 11 and 17.

If the templateInserts weren't there, the table would be expanded to break the Welcome image, making the page design appear broken when the template is viewed from the browser (see templateInsert for more details on this example).

Template Source Code 
1   <table cellpadding="0" cellspacing="0">
2   <tr align="center">
3      <td><img src="w1.gif" width="127"
4           height="45" border="0"></td>
5      <td><img src="w2.gif" width="45" 
6           height="45" border="0"></td>
7   </tr>
8   <tr>
9      <td><b>Today's rate:</b></td>
10     <td bgcolor="#eeeeee">
11  <-- templateInsert : $foo$ -->
12     </td>
13  </tr>
14  <tr>
15     <td><b>Previous rate:</b></td>
16     <td bgcolor="#eeeeee">
17  <-- templateInsert : $bar$ -->
18     </td>
19  </tr>
20  </table>
   Template View

Today's rate: 
Previous rate: 

[ learn more... ]

templateComment

TemplateComment is mainly used to mark up the templates with instructions or notes to make working with templates easier. They designate a section of code in the template that will be removed when the program generates the content, but when working with the templates themselves, the code is displayed normally.

Example:

Below, the templateComment in the Template Source Code makes it clear which template you're working with when looking at the file in Template View.

The Generated View shows us that the templateComment was stripped from the page when the program generated the content.

Template Source Code:
<html><body>
<!-- templateComment -->
<div
style="background:#ffffaa;">

    <p><b>Template:</b>
    <i>example.html</i></p>

</div>
<!-- /templateComment -->

<h1>$foo$</h1>

$bar$

<p>&copy; 2006, This
Site.</p>

</body></html>
   Template View:

Template: example.html

$foo$

$bar$

© 2006, This Site.

   Generated View:

Welcome

This is some sample page content.

Donec quis nisl. Duis mauris nibh, ornare vel, aliquam at, tempus et, augue.

© 2006, This Site.

[ learn more... ]

templatePlaceholderList

The templatePlaceholderList command generates a complete list of all the placeholders available for the template. This can be very useful when you're making template modifications.

Template Source Code 
<!-- templatePlaceholderList -->

templateIf

The templateIf command is a very powerful tool for "conditional output" - meaning you can specify the code to generate when a placeholder matches (or doesn't match!) a certain value.

Example:

The code below has two templateIf commands. The text on line 2 will be generated if the $placeholder$ value is Yes, since it matches the first templateIf (the "eq" operator means "equal to"). On any other value for $placeholder$, the text on line 6 will be generated based on the "ne" operator, which means "not equal". All possibilities for $placeholder$ are covered, since it's either equal to "Yes", or it isn't. 
1 <!-- templateIf $placeholder$ eq "Yes" -->
2   Lorem Ipsum.

3 <!-- /templateIf -->
4 
5 <!-- templateIf $placeholder$ ne "Yes" -->
6   Dolor sit amet.
7 <!-- /templateIf -->

The typical format is shown in the example above. Note that:

  • One or both of the two values should be placeholders.
  • Non-placeholder values must be quoted.
  • Numeric values can use mathmatical operators (<, <=, >, >=, ==, and !=), while text values must use "eq" and "ne" (see below).
    • OPERATOR Meaning Description
    eq
    ne    		 equal to
    not equal to    		 For comparing text values.
    ==
    !=
    <, >, <=, >=     		equal to
    not equal to
    less than, greater than, etc.     		For comparing numerical values.

[ learn more... ]

File and Image Uploads

Many fields will give your user the ability to upload different file types, either to put into another content field as Embedded Media or publish in a series as Attached Files.

When you put an upload field's placeholder into the template you will also need to create a corresponding templateCell for that field. The name for the templateCell is "$PLACEHOLDER.row$".

Attributes
Uploaded files have a lot of different data related to them ("attributes"): images have width, height, and filename; a PDF or Word document has filename but not height or width. To the Program, other data are considered attributes, such as the URL to the uploaded image, and any values entered by the user (such as Caption, title, image alignment).

Attributes for an uploaded file can only be called from its templateCell, and are all called using a placeholder formatted as "$file.ATTRIBUTE$" (Read more about "Attributes" here):

Example:

<!-- templateCell : uploadedImage.row -->

    <img src="$file.webUrl$" width="$file.width$" align="$file.align$">

<!-- /templateCell : uploadedImage.row -->

Embedded Media
Some uploaded files are actually put into other content fields by the user. For these "Embedded Media" fields, you don't put a placeholder (or special templateCell) in your templates: instead, users will put a special placeholder in the content of another field corresponding to the file they've uploaded, such as "***image1***".

The format for these Embedded Media fields is contained in "templateCell default.embeddedMedia", located in templates/common/embeddedMedia.html.

[ learn more... ]

Server Side Includes (SSI)

While not actually unique to our Template System, we've included Server Side Includes (or SSI's) in our documentation because our templates often use them as a way of simplifying the content.

SSI's are special tags used to pull the contents of another file into a page. Rather than have the same code on every single page for common elements like navigation or your page footer, you can use SSI on every page to pull in the code from a single file. Modifying the one file will affect all the pages that use SSI to include that file.

The most common SSI's are "virtual" and "file", which look like this: 

<!--#include virtual="/dir/file.ext" -->

<!--#include file="subdir/file.ext" -->

[ learn more... ]

Placeholder Modifiers

Placeholders can have special suffixes attached to them called Placeholder Modifiers.

Placeholder Modifiers alter the content that's displayed for that Placeholder. They can be used to change the format of a date field, convert the content for use in JavaScript or URL's, and much more.

Here are some sample modifiers. As you can see, they are added to the end of the Placeholder, separated by a colon.

Example:

The table below shows how different modifiers convert the same placeholder's content.

template source code generated source code
$foo$ <p>Our Site Re-Launched</p>
$foo:spacesToNbsp$ <p>Our&nbsp;Site&nbsp;Re-Launched</p>
$foo:textOnly$ Our Site Re-Launched
$foo:uppercase$ <p>OUR SITE RE-LAUNCHED</p>
$foo:textOnly:uppercase$ OUR SITE RE-LAUNCHED

[ learn more... ]