Templates

A template is simply an HTML file with embed tags added to it in the places where you want content to appear. You can use a few different kinds of embed tags for different purposes:

Standard tags

<!--#embed left_column -->
The most common type of embed tag simply says, "Place the piece of content named xxx here." For example, if Contemplate finds the tag <!--#embed left_column --> in your template and the argument left_column=field,main.html,contact_us in your page definition, it will merge the contact_us field from the main.html file into the template file in place of the left_column embed tag.

Hard-coded tags

<!--#embed args=file,header.html -->
If you have an embed tag in a template that will always receive the same piece of content, you can simplify your page definitions by including a reference to that content directly in the embed tag. For example, rather than using the embed tag <!--#embed header --> and including header=file,header.html in your page definition, you can just use the embed tag <!--#embed args=file,header.html -->. We call this a hard-coded tag because you can't pass values for this tag into the template; but you can still benefit from keeping your content in a separate file from your page layout.

Passthru tags

<!--#embed highlight[0] -->
When Contemplate processes a passthru tag, it doesn't go looking for content to display in its place; instead, it simply displays some portion of the page definition. For example, if Contemplate finds the tag <!--#embed highlight[0] --> in your template and the argument highlight=contact_us in your page definition, it will display the text "contact_us" in place of the highlight[0] embed tag.

Passthru tags always include square brackets after the name; this distinguishes them from standard embed tags, and also allows you to access specific elements of a page definition. For example, the tag <!--#embed left_column[1] --> accesses the string "main.html" from the page definition left_column=field,main.html,contact_us. This can be especially useful when adding logic to your templates using client-side or server-side scripts. For example, you could write a PHP script that contains the line $content_file = "<!--#embed left_column[1] -->" and then make the script behave differently depending on what content file the page is reading from.

In addition to accessing every element of the page definition, you can also access the special variables page[0] (the name of the current page), template[0] (the value of the template argument), and page_definition[0] (the complete page definition of the current page). And if you use the "split page names on" preference, you can access specific portions of the page name by setting an index for the page variable. For example, on a page named company_contact with "split page names on: _" in your preferences file, page[1] will return "contact."

If you don't include an index inside the square brackets, Contemplate will return the entire argument or page name. For example, if your page definition includes the argument home=field,main.html,home, then main[2] would return "home" but main[] would return "field,main.html,home." Similarly, if you're splitting page names and accessing individual portions of the page name, you can still access the entire page name with page[].

Combo tags

<!--#embed args=field,lesson+lesson[0],exercise -->
A combo tag is some combination of a hard-coded and passthru tag. This is useful if most of the arguments are the same across multiple page definitions, but they're not all the same. For example, you might be using the embed tags <!--#embed exercise -->, <!--#embed instructions -->, and <!--#embed tips -->, and the page arguments excersise=field,lesson1,exercise&instructions=field,lesson1,instructions&tips=field,lesson1,tips. You could rewrite this to use the embed tags <!--#embed args=field,lesson+lesson[0],exercise -->, <!--#embed args=field,lesson+lesson[0],instructions -->, and <!--#embed args=field,lesson+lesson[0],tips -->, and the page argument lesson=1.

Specifically, a combo tag looks like a hard-coded tag, but you can insert the same values you would use in a passthru tag anywhere in the list of arguments, concatenating with the + sign as needed. Combo tags don't let you do anything that you can't do with the other kinds of tags, but they do let you write simpler page definitions that are easier to read and maintain.

Navigation tags

<!--#embed nav_previous -->, <!--#embed nav_next -->, etc.
If you want to build Next and Previous buttons to page through your site, you can automate this development using Contemplate's navigation tags. For example, if your page definitions file includes these definitions...

home: template=home.html&main=field,main.html,home

joe: template=people.html&main=field,people.html,joe
bob: template=people.html&main=field,people.html,bob
sally: template=people.html&main=field,people.html,sally
sue: template=people.html&main=field,people.html,sue

site_map: template=other.html&main=field,main.html,map

...and you place navigation tags into your template, they would display as follows on various pages:

	page=joe	page=bob	page=sally	page=sue
<!--#embed nav_current -->	1	2	3	4
<!--#embed nav_total -->	4	4	4	4
<!--#embed nav_next -->	bob	sally	sue	joe
<!--#embed nav_previous -->	sue	joe	bob	sally
<!--#embed nav_first -->	joe	joe	joe	joe
<!--#embed nav_last -->	sue	sue	sue	sue

This makes it very easy to build links and counters that automatically update when you add or rearrange pages in your page definitions file. Here's some example HTML that demonstrates this functionality:

<a href=../contemplate/assembler.php?page=<!--#embed nav_previous -->>Previous</a> |
<!--#embed nav_current --> of <!--#embed nav_total --> |
<a href=../contemplate/assembler.php?page=<!--#embed nav_next -->>Next</a>

Note that when processing navigation tags, Contemplate assumes that double line breaks in the page definitions file indicate a group of pages, and only considers the other pages in the same group as the current page.

Navigation tags don't require any arguments in your page definition. They do, however, require the use of a page definitions file rather than passing page definitions through the query string.

Conditional tags

<!--#if (left_column[2] != "home") -->, <!--#else -->, <!--#end if -->
If you want to use one template rather than two in cases where both templates are only slightly different, you could add logic to your template using client-side or server-side scripting to make it display differently in different circumstances. Or, you can use Contemplate's built-in conditional functionality to "show" or "hide" different portions of your template. The advantages of using Contemplate's conditional tags are that they're language-neutral and don't have to be rewritten if you move your site to a different platform, they run faster since Contemplate will completely eliminate the portions of the template you don't need when it assembles your page, and they allow easy access to portions of your page definition for making decisions based on those values.

Conditional tags can contain the same kind of references that you would include in a passthru tag, as in this example:

<!--#if (left_column[2] != "home") -->
<a href=home.html>Home</a>
<!--#else -->
Home
<!--#end if -->

They can also include any code that's compatible with the scripting language of the version of Contemplate you're using. For example, if you're using the PHP version of Contemplate, you could write a conditional tag that uses the strpos() function, as in this example:

<!--#if (strpos(left_column[1], "corporate/") !== false) -->
We're reading a content file from the content/corporate folder.
<!--#end if -->

However, including portions of the host scripting language means that you would have to rewrite those portions if you move your site to a different platform and change the version of Contemplate you're using.

As of version 1.0.3, conditional tags can even contain the names of the nav_* and env_* tags. For example, you could choose to display some content if the current page is the last in a group:

<!--#if (page[0] == nav_last) -->
Sorry, there are no more pages after this one!
<!--#end if -->

Or you could display some content if the page was modified today (this example uses the PHP strpos and date functions):

<!--#if (strpos(env_last_modified, date("Y-m-d") == 0) -->
Hey, this page is brand new!
<!--#end if -->

Environment tags

<!--#embed env_http_user_agent -->, <!--#embed env_remote_addr -->, etc.
Finally, you can display environment variables on your pages by including environment tags in your templates. The value of an environment tag is "env_" plus the name of the environment variable you wish to access, and is not case-sensitive. One additional environment variable is unique to Contemplate: <!--#embed env_last_modified --> will display the modification date of the newest of all the files used to build the page -- effectively, the modification date of the dynamic page.

Tag attributes

With standard, hard-coded, and passthru tags, you can also include a few different attributes to modify the display of the embedded content:

strip

<!--#embed main strip -->
If you include the strip attribute in your embed tag, Contemplate will strip all HTML tags from the embedded content before merging it into the template. This is a good way to clean up content if you need to override its formatting in your template, or embed it into a JavaScript variable.

replace

<!--#embed main replace /[\r\n]// -->
You can take even more control of the formatting of embedded content by running regular expression replacements on it. The example above removes all line breaks, which is also useful when embedding content into a script. You can include both the strip and replace attributes in a single embed tag, and you can list several replace attributes, each with its own regular expression values. Regular expressions are Perl-compatible and use the $n syntax for backreferences.

variable

<!--#embed main variable -->
If you want to embed content into a template but process the content using your own server-side scripts before displaying it, you can include the variable attribute in your embed tag. In this case, Contemplate finds your requested content, but rather than merging it into the template, creates a variable that you can access from scripts written in the same language as the version of Contemplate you're using. For example, if you're using the PHP version of Contemplate and you include the embed tag above, any PHP scripts in your template or content files can automatically access the embedded content through the $main variable. Note that it's then up to you to eventually print the content when you're finished working with it. Also note, if you use the variable attribute in a hard-coded tag, the content will be available in a variable called $hardcoded. If you use the variable attribute in more than one hard-coded tag, the content will be available in a series of variables called $hardcoded_1, $hardcoded_2 and so on.

show_errors, hide_errors

<!--#embed main show_errors -->, <!--#embed main hide_errors -->
These attributes override the SHOW_ERRORS setting in config/constants.php for a single tag. This is useful, for example, if you want to place a tag into some PHP code where the error message formatting would cause problems. With errors hidden, Contemplate will still output a simple message wrapped in HTML comment tags, but with no formatting.