HTML templates

Starting with AGG version 0.2.4, AGG includes an option to use custom (user-provided) HTML templates.
To use a custom HTML template, go to Gallery->Configure->Advanced Options, and from the "Html Template" drop-down list select "New...". In the dialog that appears, give your template some name (to recognize it later, if you use several templates). Select a directory to store the template files, and, when asked, confirm that you want to clone the default HTML template into the selected directory.

Having done this, you can proceed creating a gallery with your images, as usual. When finished, you can go on and edit the template files in the directory you specified.

Template files

A custom HTML template consists of four template files - named mainpage.html, viewerpage.html, exifpage.html and style.css. They represent, correspondingly, the index page(s) of the gallery, the view.html "Single-image viewer" page, the page with Exif statistics, and the CSS style page. All files share a similar syntax, demonstrated below:

<meta http-equiv="Content-Type" content="text/html; charset=($CHARSET)">
($IF rollover)
<script language="JavaScript" type="text/javascript">

... some JavaScript code follows here


<body bgcolor="#($BGCOLOR)" ($IF background)background="($BACKGROUND)"($ENDIF) text="#($TEXT)"($IF rollover) onLoad="MM_preloadImages(($ONLOAD))"($ENDIF)>
<p> </p>
<h1 align="center">($FONT)Gallery for <font color="#($TEXTLIGHTER)">[</font><b>($MINITITLE)</b><font color="#($TEXTLIGHTER)">]</font></font></h1>
<h6 align="center">($FONT)[<i>Number of Images:</i> <b>($NUMIMAGES)</b>]($IF zip) -- <a href="">Download all</a>($ENDIF)</font></h6>

As you can see from the example, the templates are mostly plain text, which is used verbatim in the final HTML files, and there are some special marks that specify where AGG should insert stuff that vary (marked with greenish color in the example). There are fields, (e.g., ($TITLE)), which AGG plainly substitutes with data from the project configuration, and there are conditionals, such as ($IF rollover)...($ENDIF). The code inside the conditionals is only emitted if the associated boolean value is true. The conditionals can be nested, and can also take the form ($IF something)...($ELSE)...($ENDIF).

You can change whatever you want in the templates - be it the verbatim text, or the AGG marks (you can remove them, reorder them, apply different logic than the originally intended...). You cannot change what is being substituted, though, as it is hardcoded in AGG. But, for example, you can remove the ($TITLE) mark and put something else - AGG doesn't need to encounter ($TITLE) in the code.

When you're done editing your HTML template, you can hit "Generate Gallery" or Gallery->Create Preview to see how the final gallery looks like. If you're not happy with the result, you can tune the templates a further bit, and then rerun Create Preview, etc...

Example uses

Limitations and pitfalls

Right now, some of the things that AGG generates is difficult to templatize well, for example the code for the table with thumbnails in the index pages. Currently, it is just a big blob of code, that AGG generates and inserts, without giving you the ability to customize per-image stuff (or even the ability to abandon table-based layout completely). If you need such stuff, you are probably better off customizing view.html, as things there are less restrictive.

Also, the input template parser cannot handle non-8bit code (e.g. UTF-16). However, it will accept UTF-8 input happily, as well as most (all?) 8-bit code pages (German, Russian, French or whatnot). Also, the parser isn't quite foolproof, so if you give it incorrect code (unclosed ($IF...) tags, marks with undefined contents, etc.) it might silently fail, without emitting output code or error message. Use caution when writing your templates.


If you come up with some feature or improvement (about HTML templates), that you think will be useful in AGG, don't hesitate to write me.
Also, if you create a cool/interesting HTML template that you think is worth sharing, you can send it to me - so I can include it in future AGG versions.

Get Anrieff's Gallery Generator at Fast, secure and Free Open Source software downloads