Page Templates


Since most sites have certain aspects of the site that remain the same as the content of the pages changes, we are going to create a template that we can use for all pages. We'll divide the page into four sections:

|                     |
|         top         |
|                     |
|      |              |
|      |              |
| left |     main     |
|      |              |
|      |              |
|                     |
|        bottom       |

The main section will hold the content different for each page. The top section will be used for headers, banners, menus, and so on. The left section can be used as a sidebar or navigation bar, and the bottom section can contain the copyright and contact info. The top, left, and bottom sections will remain constant throughout the site. Making a change to information in one of these sections will make that change to all pages in your site.

Now using the code displayed below, create the appropriate HTML files for each of the sections (naming the files after sections). No '.html' suffixes are needed here because those file parts are not meant to (and in fact can't) be parsed as standalone documents by Interchange (or the web server).


<title>The Interchange Test Catalog</title>

  <div align=center>
  <table width="80%" border cellpadding="15">
  <tr><td colspan="2" align="center">
    <h1> The Interchange Test Catalog </h1>



  <td align="center">
  <td align="center">



  <tr><td colspan="2" align="center">


ITL: the Interchange Tag Language

We need a way to pull those template pieces we just created into the proper places to make complete, reviewable pages. This is done using ITL, the Interchange Tag Language.

[Tip] Tip

ITL uses "tags" (enclosed in [tag] brackets), much like the HTML uses tags enclosed in <tag>. The major difference, however, is in the hierarchy where the tags are parsed. ITL tags, parsed on the server side by the Interchange daemon, are expanded into the plain text and HTML which is then (over the web server) delivered to the end user and parsed there for final presentation in user's browser.

ITL is at the heart of almost all Interchange catalog pages: ITL is the way you use Interchange's functionality. The ITL tags appear between square brackets, and accept all named or all positional parameters; here's an example (make sure you understand this!):

[data table="products" column="price" key="1299"]  (named parameters, NAME=VALUE NAME=VALUE ...)

[data products price 1299]  (positional parameters, VALUE VALUE ...)

[Important] Important

You can't use positional parameters if the values contain whitespace. For example, [tagname "[data session mv_arg]"] is invalid; the only way to specify that is [tagname optionname="[data session mv_arg]"]. Also, if the first parameter is positional, all must be positional (and vice versa, if the first parameter is named — all must be named).

Tags can span multiple lines which helps readability when the tags have a large number of (long) options. There's a whole lot of tags available (around 200 in Interchange 5.2), but in this tutorial very few will be addressed. For a complete listing of the ITL tags, see the Tags reference.

The first tag we'll use is going to be the [include] tag; it reads the specified file (relative to the catalog directory — CATROOT), reparses it for any Interchange tags, and puts the final result in place of the tag. We'll demonstrate that now on the next page you'll need to create.

Welcome Page

Create a directory called pages/ in your tutorial catalog directory (the CATROOT).

Save the following text as pages/index.html. This will create a page to test that everything works so far.

[include top]
[include left]

This is where your content goes.

[include bottom]


Interchange pages in the pages/ directory (or elsewhere, when configured) must have the .html suffix. You can omit the suffix in both your URLs when accessing pages with a Web browser, and in the tags you call (such as [page]), but the files on the disk must be properly named. (In fact, the actual suffix is controlled by the HTMLsuffix config directive).

Tutorial Catalog in Action

As the superuser, first restart Interchange to make sure all changes are applied to the Interchange server and catalog.

Monitor the log files: tail -f /var/log/{interchange,apache*}/*log

Open the web browser and load the page. Your URL should be http://myhost.mydomain.local/cgi-bin/ic/tutorial/index.html or http://myhost.mydomain.local/cgi-bin/tutorial/index.html. Since the catalog.cfg only contains minimal configuration, index.html is not defined as the default page, so you can't leave it out of the URL.

Congratulations! Your basic, "phase 1" catalog is now hopefully finished and working ;)

[Note] Note

If you receive an error visiting the catalog ("Interchange server unavailable"), edit interchange.cfg and add SocketPerms 0666 to the end of file; then restart Interchange and try again.

If you get a script error ("Internal Server Error"), chances are you tried visiting the catalog without "/index.html at the end of the URL).

Phase 1: Tutorial Files

We have prepared the files from this tutorial phase for download in .tar, .tar.gz, .tar.bz2, and expanded formats. Special notes on turning the files into a working catalog are not included; that's what this document is for.

DocBook! Interchange!