Previous: Writing Documentation ----- Contents: Contents ----- Next: Contents

Quick Reference

Command Line Usage

java -jar tazuna.jar [-c <template name>] [-e <file extension>] [-l <log level>] <project directory>

Options

-c simple|creole|menu|book: Creates a site from a given template name.

-e <file extension>: Extension for output files, if you don't want .html

Examples

java -jar tazuna.jar -c simple myproject

creates a project named myproject from the simple template.

java -jar tazuna.jar myproject

Builds the project named myproject. All files are written to the myproject/out directory.

java -jar tazuna.jar -e .php myproject

Does the same, but the output file ending is now .php instead of .html.

java -jar tazuna.jar -e .php -l NONE myproject

Does the same, but no messages are displayed during built.

Structure of a Tazuna Project

Files in Input Directory

+ TazunaProjectDir/
  + in/
    - index.cnt
    - index.tpl
    - private_scripts/
  - out/

.tpl ending: Template files contain the basic structure of a website. Content is inserted into these files by the use of placeholders.

.cnt ending: Content files. These files define the content of placeholders.

private_ prefix: These directories and files are not touched by Tazuna.

private_scripts: Directory where Tazuna searches for script extensions.

All files must be in UTF-8 encoding.

Templates

For every content file (.cnt) Tazuna searches a matching template file (.tpl) using the following algorithm:

Look for a template file with the same name in the same directory.
Continue search in upper directories.
If no template file with the same name can be found, look for template files that best match the content file, for example chapter.tpl matches chapter.cnt, chapter01cnt, chapter02.cnt and so on.
If there is still no matching template, use a master template. A master template is always named index.tpl. First look in the current directory, than look in upper directories.

For example a file named index.tpl in the root directory matches all content files, it there are no other template files defined.

Placeholders

In Template Files

$myplaceholder: defines a placeholder named myplaceholder. A placeholder is terminated by any whitespace or special character.

${myplaceholder}: means exactly the same, but placeholders in curly brackets my contain special characters, for example ${my.dotty.placeholder}

In Content Files

$myplaceholder Some content: Defines the content of a placeholder. Every placeholder at the beginning of a line starts a new content definition.

Predefined Placeholders

There are some predefined placeholders that are especially usefull in scripting:

teProjectInDir: Project input directory (in)
teProjectOutDir: Project output directory (out)
teInDir: Input directory of the file currently being processed.
teOutDir: Output directory of the file currently being processed.
teOutFileName: Name of the current output file without the path.
teOutFileServerPath: Full path and name of the current output file, starting from the server's/project's root directory.
teOutFileServerDir: Current output directory, starting from the server's/project's root directory.
teHome: relative Path to Home directory.
teContent: content of a placeholder (only for use in a script)

Build-in Scripts:

teDate.py: Prints out the current date in ISO format. This is an example script and can't be used in other scripts.
teEnvironment.py: Prints out the current environment variables.

Scripts

User defined scripts can be placed in the the private_scripts directory. Scripts are written in Python. A simple example script:

# -*- coding: utf-8 -*-
# filename: hello.py
# Inserts 'Hello World!' into the template

result = u'Hello World!'

The result of this script can be placed in a template file by inserting $hello or ${hello.py}. I recommend ${hello.py}, because it makes clear that a script is used.

Notes:

Encoding is UTF-8
The result of a script must be assigned to a variable named result.
The result must be a Unicode string.

Scripts can also change the content of a placeholder. Thus acting as a filter. Example:

Script:

# -*- coding: utf-8 -*-
# filename: dotty.py
# Adds ... at the beginning and at the end of a placeholders content.

result = u'...' + teContent + u'...'

Content file:

${dotty.py}
moonlight

Template file:

This is my ${dotty.py} template.

The result would be: This is my ...moonlight... template.

Previous: Writing Documentation ----- Contents: Contents ----- Next: Contents