Author: Ralph Krause
Contemplate is available in PHP, ASP, and Perl versions. We’ll cover the latter here.
To install Contemplate you need write access to your Web server. The Contemplate installation archive file contains several programs and utilities, but the only file you need in order to use Contemplate in its basic mode is assembler.cgi. Operation of this assembler script is controlled by a preferences.ini file.
My host allows scripts to run only from the cgi-bin directory, so I copied assembler.cgi there, renamed it assembler.pl, and made sure that it was executable. I copied the preferences.ini file to the same directory. Finally, I copied the contemplate folder from the installation archive to the top level of my Web site directory, then created two more top-level folders called content and templates, as indicated in the installation instructions.
There is a line in the preferences.ini file called external link target that is set to ‘_blank.’ Contemplate rewrites all the links on your pages to use this target, so set this field to an empty string unless you want all the links in your site to open new browser windows.
Creating Web sites with Contemplate
As we noted, the raw material used by Contemplate consists of page templates and content files. Templates contain markup information indicating where content items are to be inserted. Content files contain one or more uniquely named blocks of text that can be inserted into templates. Both of these types of files are standard HTML files with the Contemplate markups entered as specially formatted comments.
The URL passed to the assembler.pl script determines which content items are inserted into templates when the page is generated. A typical URL is shown below:
http://www.arjekservices.com/cgi-bin/assembler.pl?template=default.html&main=field,main.html,welcome
This URL calls the assembler script in my cgi-bin directory and tells it to use the template called default.html. In default.html there is markup code that defines a field called main where content is to be inserted. The text to be used for main is found in a file called main.html and is identified with the name of welcome.
While the URL structure can be a bit confusing, it provides great flexibility. Luckily, there are several ways to make the URLs simpler, which we’ll cover in a moment.
You can change the look of a page simply by passing a different filename in the template parameter. You can change content by using a different content file or a different content identifier. Examples of this can be found on
Creating templates
Contemplate templates are stored in the templates directory. The default.html template for my site contains the page header, footer, and side menu. The rest of the page is given the label “main” and is where content is inserted. Areas where content is to be inserted are indicated with embed tags.
The simplest embed tag simply defines a named spot where content is to be inserted. The command is #embed, which is surrounded by a standard HTML comment block. The argument following #embed is the name that identifies the spot; for example, <!--#embed main -->.
Looking back at the example URL above we see that content for main is in a file called main.html. Furthermore, it is read from the section named welcome in that file.
When you use the standard embed tag shown above you have to explicitly tell Contemplate where to obtain content from in the URL. There is a different type of embed tag that inserts the contents of a file into the template. For example, the tag <!--#embed args=file,sidemenu.html --> is used to insert the side menu for my site. The file sidemenu.html is in the content folder and is inserted verbatim into the page right after this tag.
Creating content files
The content files that Contemplate reads are stored in the content directory. One way to define individual content items is a two-column table. One content item is defined per row. The first column of the row contains a unique name used to identify the content (e.g. “welcome”) and the second column contains the text to be inserted into the template. This text is standard HTML and can be as simple or as complex as you need it to be. Here’s an example:
<table>
<tr>
<td>
##welcome
</td>
<td>
<p>This is the content item identified as welcome. The identifier begins with two pound signs followed by a unique name as shown above.</p>
<p>A content file can contain as many or as few content items as you would like. The content items are standard HTML code which can be as simple or complex as you want.</p>
</td>
</tr>
</table>
Creating the site
When creating templates and content items I’ve found that it is best to provide absolute paths to any stylesheets or pictures used.
To test the appearance of the site, enter the URL to the assembler program and specify the template and content files to use. You also need to specify content files and identifiers for the embed tags in the page. These are separated by ampersands (&), as in http://www.arjekservices.com/cgi-bin/assembler.pl?template=default.html&main=field,main.html,welcome&sitepromo=random,site_thumbnails.html.
In this case I have a second embed tag called sitepromo in the welcome section of the main.html file. Embed tags aren’t limited to templates; they can appear in content also.
Using random instead of field for the sitepromo tag causes Contemplate to insert random items from the site_thumbnails.html file each time the page is shown. In this case the elements in thumbnails.html are <img> tags to different pictures.
The other pages on my site are Portfolio, Clients, Testimonials, and notes for this article. Each of these pages is defined in a row in the main.html file. I display a page by replacing welcome with the desired item in the URL.
How to simplify the URLs
It can be difficult to remember the correct Contemplate URLs for links on large or complex sites. Furthermore, a complex URL to your home page makes it hard for visitors to find your site.
One of the methods Contemplate provides to simplify URLs is the use of a pages.txt file. This file is stored in the contemplate directory and matches a simple name with template and file specifications for each page of the site. The layout for entries in the pages.txt file is shown below:
home: template=default.html&main=field,main.html,welcome&sitepromo=random,site_thumbnails.html
To display the home page using pages.txt you can use the URL http://www.arjekservices.com/cgi-bin/assembler.pl?page=home.
After creating a pages.txt file you can add a rule to Apache’s htaccess file to make URLs even simpler. Instructions for this are found in the documentation on the Contemplate Web site.
The other method to avoid complicated URLs is to use the Flattener
program supplied with Contemplate. It generates HTML files for each page
of the site. The resulting files can be copied to your Web server so the site can be accessed without using Contemplate.
One way to keep the URL for your home page as simple as possible is to create an index.html file that automatically redirects the browser to the Contemplate-generated page. You do this using an HTML META refresh tag containing the Contemplate assembler URL or a line of JavaScript that sets the browser location to the Contemplate URL. In my index.html file I use the line <META http-equiv="refresh" content="0; url="http://www.arjekservices.com/cgi-bin/assembler.pl?page=home">.
Conclusion
The Contemplate Web Templating System is a very flexible system for creating Web sites. The extreme flexibility of the program means you have to give some thought before you begin to the initial design of a site. However, since it keeps site content separate from page layout, Contemplate makes it very easy to change one without affecting the other.
Ralph Krause is a freelance Delphi programmer, Webmaster, and writer living in Michigan.
Category:
- Web Development
