Create your own templates

What is a template?

A template defines what and how the output is generated by this program. In other programs this feature is called layout or skin. Here a template is a directory under the "templates" directory. It contains the following files:

template.cfg: (mandatory)

This is a must and defines, which of the 3 picture files are created and how they are created. Additionally it defines at least one output file for text (most time HTML).
This template configuration file must match its used template files! For example, if the template defines, that "full" pictures should not be created or copied, the template files must not use "pic.fullXX" properties!

Template files: (one is mandatory)

This program uses a foreign Python module named EmPy, written by Erik Max Franzis, to generate its output files. The syntax to use that module is explained in this manual, but EmPy has far more features! If you want to dive deeper, go to its home page and read.
At least one template file must exist and be defined in "template.cfg".
There are three types of template files:

1. OnceFile: is generated once in the base output directory of a gallery. This is useful for frame sets, empty frames or style sheets. Files that need no transformation could simply be copied with the resource directory (see below).
2. IndexFile: is generated once for each index page in the base output directory of a gallery. If there are more pictures than fit on a single index page (according to options PicsPerRow and MaxRows), several index pages are generated.
3. PictureFile: is generated once for each picture in the html directory (option HtmlRelDir) of a gallery.

Resources directory: (optional)

You can define one sub directory which is copied verbatim to the base output directory of a gallery. This directory can contain every resource you can imagine, like navigation graphics, style sheets, sounds, text files, ...
Usage is simply "@gal.resHref/<any file inside ResDir>" in a template file.
There are two options which define the behaviour:

1. Option ResDir: a directory inside the template directory. It will be copied verbatim into the base directory of the created output album.
2. Option ResRoot: True or False. Defines if the directory is copied only once (True) into the topmost album or at each directory level (False). True saves disk space, but False makes copying of sub albums easier. If you switch templates at any directory level, the new output directory is considered as new root.

template.txt: (optional)

Describes the template in words.
This text will be shown in the GUI (later version!) or can be viewed by the end user directly.

preview.jpg: (optional)

A sample picture of the generated gallery layout.
This picture will be shown in the GUI (later version!).

How to create a new template:

The simplest way to create a new template is to copy the whole directory under a new name.
After that, edit the template.cfg, the template files or graphics.

Template language

PyAlbum uses Empy as underlying driver for its templates. Empy is a very powerful and robust templating system for Python.
You can use @variables, @obj.attributes, @(functions) @(conditionals?...!...), @[if statements], @[for loops], @{statements} and much more here!
For a full documentation of Empy take a look at its home page. If you do not want to dive very deep, simply look at the template files in template 'testall'. But pay attention to the different meanings of @(), @[] and @{}!
You also need some very basic knowledge of Python.
The most important thing to know here is, that an @[if xx] yields False, if xx is an empty string or an empty list or a "None" object.

To be continued...

Usable objects in template files

Classes and attributes in template files

  @[for desc in gal.description]@
    @desc <br/>
  @[end for]@

  @[for dir in gal.dirs]@
    <...handle @dir attributes...>
  @[end for]@

  @[if gal.indexFooterInc]@
    @{empy.include(gal.indexFooterInc)}
  @[end if]@

  @[for actpart in gal.parts]@
    <...handle @actpart attributes like hmtlHref...>
  @[end for]@

  @[for (href,name) in gal.pathlist[:-1]]@
    <a href="@href">@name</a>&nbsp;::&nbsp;
  @[end for]@
  @gal.pathlist[-1][1]

@gal.resHref/leftarrow.gif

	<table>
	@[for row in part]@
	  <tr>
	@[for pic in row]@

	@[if pic]@
		<td colspan="@pic.panoramaWidth">
			<...use @pic...>
	@[else]@
		<td>
			&nbsp;
	@[end if]@
		</td>
	@[end for]@
	  </tr>
	@[end for]@
	</table>

  @[if pic.exif.Make]@
  <table width="100%" border="1">
  @[for (exifname, exifval) in pic.exiflist]@
  @[if exifval]@
    <tr>
      <td>@exifname:</td>
      <td>@exifval</td>
    </tr>
  @[end if]@
  @[end for]@
  </table>
  @[end if]@