## 1 Introduction

This manual describes how to use CamlTemplate, a template processor for Objective Caml programs. It can be used to generate web pages, scripts, SQL queries, XML documents and other sorts of text.

### 1.1 About This Manual

This manual is provided in HTML and PDF formats in the CamlTemplate distribution.

### 1.2 Licence

CamlTemplate is free software, released under the GNU General Public License. This manual is released under the same licence.
In addition, as a special exception, Benjamin Geer gives permission to link the code of this program with the Apache HTTP Server (or with modified versions of Apache that use the same license as Apache), and distribute linked combinations including the two. You must obey the GNU General Public License in all respects for all of the code used other than Apache. If you modify this file, you may extend this exception to your version of the file, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.

### 1.3 Features

- A versatile, easy-to-learn template syntax that supports common scripting-language constructs, while encouraging a separation between presentation logic and application logic.
- The supported Caml data structures accomodate lists, tables and trees of items in a straightforward manner.
- Works well with mod_caml and mod_fastcgi.
- Supports any ASCII-compatible encoding, including UTF-8.
- Optional support for multithreading.

CamlTemplate works by merging data with handwritten templates. This process is illustrated in Figure 1.
The template contains only the handwritten material; some other program provides the data. The template's author doesn't need to be involved in writing that program; he or she only needs to know what data the program provides, and can therefore change the template without involving the program's developers. Likewise, the program can be modified so that it obtains data in a different way, without affecting the template. Different templates can be used to display the same data in different ways (e.g. to generate normal and `printer-friendly' versions of a web page).

> Figure 1: Generating a document

### 1.4 Getting CamlTemplate

The CamlTemplate source code and documentation can be downloaded from the CamlTemplate web site.

### 1.5 Installing CamlTemplate

#### 1.5.1 Installing with GODI

If you use GODI, you can install CamlTemplate from `godi_console`. Otherwise, you can install manually as described below.

#### 1.5.2 Installing Manually

Requirements:

- Objective Caml 3.08.3 or above.
- findlib.
- PCRE-Ocaml.
- GNU make.

Unpack the archive:

    tar zxf camltemplate-x.y.z.tar.gz
    cd camltemplate-x.y.z

To see the configuration options, type:

    ./configure --help

Type the following, adding any options you need:

    ./configure

Then type:

    make
    make opt
    make test

If there are no errors, type `make install` as root. This installs bytecode and native-code versions of the library using `ocamlfind`. Documentation in HTML and PDF formats is installed in `$PREFIX/doc/camltemplate`. Several sample programs can be found in `$PREFIX/share/camltemplate`.
To uninstall the library, type `make uninstall` as root.

#### 1.5.3 Integration with mod_caml

Mod_caml is an Apache module that dynamically loads OCaml bytecode to handle HTTP requests.
CamlTemplate has been tested with mod_caml 1.3.6 and Apache 1.3. (We haven't tested it with Apache 2.0, because a bug in Apache 2.0 has prevented mod_caml from working at all; this looks as if it will be fixed in Apache 2.2. If you need to use Apache 2.0, try the instructions on the mod_caml web site, and let us know if it works.)
1. Install mod_caml, and make sure it works on its own before proceeding (try the `hello.ml` example that comes with it).
2. In your `httpd.conf`, after the configuration you added for mod_caml, add the following line:

    CamlLoad /path/to/camltemplate/camltemplate.cma

(If you don't know where it is, type `ocamlfind query camltemplate` at a shell prompt.)
3. Restart Apache.
4. Try compiling and installing the example in `examples/mod_caml` (see the `README` there).

#### 1.5.4 Integration with mod_fastcgi

Mod_fastcgi is an Apache module that allows the web server to hand off HTTP requests to a pool of long-running programs; these can be OCaml programs compiled to bytecode or native code.
This has been tested using Christophe Troestler's OCaml-CGI package and mod_fastcgi 2.4.2, and works with Apache versions 1.3 and 2.0. For an example, see `examples/fastcgi`. You'll need to use CamlTemplate's optional thread support (see Section 4.4 for instructions).

### 1.6 Mailing List and Support

The camltemplate mailing list is used for questions, suggestions, bug reports and discussion about CamlTemplate.
There is also a Frequently Asked Questions page.

### 1.7 Author

CamlTemplate is developed and maintained by Benjamin Geer (`benjamin DOT geer AT gmail DOT com`).

### 1.8 History

In 1999, Benjamin Geer wrote a template processor in Java, called FreeMarker, based on the experience of using a similar tool with graphic designers in a web development shop. CamlTemplate borrows some aspects of FreeMarker (small library not tied to web development, JavaScript-like expressions, Perl-like data structures), as well as some ideas from the Apache Jakarta project's Velocity template processor (generated parser, more concise syntax), released in 2001. The first version of CamlTemplate was released in October 2003.