Picasa Web Templating

# The Picasa Web Templating System

## Overview

When the user does a web page export from the current album in Picasa, the Picasa Web Templating system is used to produce the desired HTML output. Web templates may be either template command (.tpl) files, or files which contain HTML formatting and special templating-system variables (typically with the extension .html)

During an export, thumbnail and large-sized copies of the selected images are written to the "thumbnail" and "image" subdirectories of the selected export directory, respectively. Then, the top-level template command file (always "index.tpl") in a template directory is processed and the commands executed in order. The special loop and targetloop commands are processed for each image in the selection, populating the special image loop and targetloop variables.

Features which have not yet been implemented are indicated like this.

## Template Command (.tpl) Files

Template File Commands
Command | Parameters | Description
--- | --- | ---

define

variableName | The name you'd like to use elsewhere
variableValue | The value to substitute in

Define a value which will be used internally by the exporter, as well as replaced automatically wherever `<%variableName%>` is encountered. Example: `define imageWidth 600` -- sets the default image width of exported images to 600 pixels, and replaces any occurances of `<%imageWidth%>` with "600".

At any given time, only one instance of a variable is active, so placing a "`define imageWidth 400`" on any line below "`define imageWidth 600`" will override all instances of the imageWidth definition.

Some variables are used internally to control export behavior. They are listed in their own table below.

include

fileName | An HTML or template file to include at this point.

Template files are processed recursively, variables are substituted in HTML files at the point where they are included.

loop

per-image include file | This file will be included once per image.
columnCount | The number of images to place in a single row (usually of a table). If this parameter is specified, then you must also specify the rowStartInclude and rowEndInclude parameters
rowStartInclude | include this file at the start of each row (for example, "`<TR>`")
rowEndInclude | include this file at the end of each row (for example, "`</TR>`")

The `loop` and `targetloop` commands both loop over all the images in the export selection. Certain variables (indicated below) are active only for files included via the loop directives.

targetloop

target template file | Template file which specifies the export for the per-image HTML file.
target include file | In the current export file, this file is included once per image, with the special variable `<%targetPath%>` defined, which points to the per-image export file.
columnCount | The number of images to place in a single row (usually of a table). If this parameter is specified, then you must also specify the rowStartInclude and rowEndInclude parameters
rowStartInclude | include this file at the start of each row (for example, "`<TR>`")
rowEndInclude | include this file at the end of each row (for example, "`</TR>`")

`targetloop` causes each image to be exported to a separate file, which may be referenced by the current file. It is used for frame-based designs.

copy

source | A directory, relative to the current template, to copy recursively to `destination`
destination | (optional) A path relative to the current export directory to which the files in `source` are copied

Copies static resources (such as artwork) from the template directory to the export directory. Example: `copy assets\images\ images\` -- copies the contents of the "images" directory in the "assets" directory of the current template to the "images" directory of the current export. Note that the trailing backslashes are required for directory specifications, and that leading backslashes should not be used.

## Command Variables

Some variables are used internally by the exporter (they are also accessible within the HTML).

Command Variables
Variable Name | Description
--- | ---
exportFileName | Name to use for the exported file. For targetloop files, a numerical value will be appended to this name, before the extension. In other words, for a regular template file a value of "index.html" will produce an exported file named "index.html" but for a targetloop template, the files "index0.html," "index1.html," etc. will be produced.
imageWidth | Maximum image width to use when generating the large-sized image files. A value of "0" means "Same width as the original image."
imageHeight | Maximum image height to use when generating the large-sized image files. A value of "0" means "Same height as the original image."
thumbnailWidth | Maximum image width to use when generating the thumbnail image files. A value of "0" means "Same width as the original image."
thumbnailHeight | Maximum image height to use when generating the thumbnail image files. A value of "0" means "Same height as the original image."
bgColor | Color to use when creating shadows around thumbnails. Default is white ("#FFFFFF")
shadowedThumbnails | If set to "true" or "1", draw a shadow around each exported thumbnail. Defaults to "1"
shadowedImages | If set to "true" or "1", draw a shadow around each exported image. Defaults to "0"

## Included HTML Files

The following variables will be active for any page:

Album variables
Variable Name | Description
--- | ---
albumNumber | A number which is unique across all albums in this instance of the Picasa database. Sometimes useful for javascript.
albumName | The short name assigned to this album. Initially the name of the directory that contained the album's images, but editable by the user.
albumCaption | A description of the photographs that the user has entered.
albumDate | Initially, the median date of all photos in the album. May be changed by the user. Formatted as month/year only.
albumItemCount | Total number of images in this album.

Within an image loop, (including any files exported within a targetloop) the following variables will be active in addition to the album variables above:

Image Loop Variables
Variable Name | Description
--- | ---
itemNumber | A number which is unique across all albums in this instance of the Picasa database. Sometimes useful for javascript.
itemName | The name of the image file ("mypicture.jpg")
itemOriginalPath | The full path to the original file on disk ("C:\My Documents\My Pictures\mypicture.jpg").
itemWidth | Actual width of the exported picture, in pixels. Usually smaller than the "imageWidth" command variable.
itemHeight | Actual height of the exported picture, in pixels. Usually smaller than the "imageHeight" command variable.
itemSize | Size of the original image, in kilobytes.
itemThumbnailImage | Path to the exported thumbnail image file, relative to the export directory.
itemLargeImage | Path to the exported large image file, relative to the export directory.
isNextImage | true if there is an image following the current image
isPrevImage | true if there is an image preceding the current image
nextImage | Path to the next exported image, in sequence, relative to the export directory.
prevImage | Path to the previous exported image, in sequence, relative to the export directory.
nextThumbnail | Path to the next exported thumbnail image, in sequence, relative to the export directory.
prevThumbnail | Path to the previous exported thumbnail image, in sequence, relative to the export directory.

Within a target page, the following variables will be active in addition to the album and image loop variables above:

Target Page Variables
Variable Name | Description
--- | ---
referrer | Path to the page which points to this page (so you can implement a "back" link)
isNextTarget | true if there is a target following the current target
isPrevTarget | true if there is a target preceding the current target
isFirstTarget | true if the current target is the first one
isLastTarget | true if the current target is the first one
nextTarget | path to the next target file in sequence
prevTarget | path to the previous target file in sequence
firstTarget | path to the first target file in sequence
lastTarget | path to the last target file in sequence
outputIndex | Number within the total number of images represented by this page (i.e. "5"). Used for creating the export filename, but useful inside HTML.

Within a targetloop (in a containing page) the following variables will be active in addition to the album and image loop variables above:

Target Loop Variables
Variable Name | Description
--- | ---
targetPath | path to the exported target page

Conditional variables can be used for optional inclusion of text -- for example, if you want to deactivate a "previous" button on the first image of a set. Any conditional variable can be preceded by "!" which reverses its meaning.

Conditionals are used like so

    <%if isNextImage%>Some HTML goes here<%endif%><%if !isNextImage%>(no more images)<%endif%>