Image Rodeo Plist Files

Overview

A plist file is an XML file using Apple’s plist DTD. Plist stands for Property List, and refers to the fact that plist files typically hold lists of properties. Plist files are a standard part of OS X.

Plist files can contain just a few types, represented as XML tags. These are the tags you’ll find in Image Rodeo plist files:

  • <true/> and <false/> – Boolean values.
  • <string> – A string of text.
  • <integer> – An integer number.
  • <array> – An ordered list.
  • <dict> – A dictionary of key/value pairs.

Image Rodeo uses plist files to describe user-installable templates. Image Rodeo derives the name of the template from the name of the plist file (minus the .plist extension).

We describe each part of an Image Rodeo plist file, using Simple.plist as an example.

Header

The plist file must start with an XML header, and then open with a <plist> (property list) and <dict> (dictionary) tag:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist SYSTEM "file://localhost/System/Library/DTDs/PropertyList.dtd">
<plist version="0.9">
<dict>

Footer

The plist file must end by closing the <dict> tag, then finally the enclosing <plist> tag:

</dict>
</plist>

Index IRML

Each plist file must specify one index IRML file, using the following syntax:

<key>index irml</key>
<array>
    <dict>
        <key>dest format</key>
        <string>%@.html</string>
        <key>source file</key>
        <string>my.file.name</string>
    </dict>
</array>

The string my.file.name should be replaced by the name of the IRML file that will be used to generate index pages for this template. You can specify a full Unix path for the IRML file, or just the name and Image Rodeo will prepend the path to the template folder.

The string %@.html will be used to make up a name for the resulting HTML file. The %@ part is replaced by the page’s unique id (uid – see page properties in IRScript), while the .html part is just the extension.

IR 1.2.6 introduces the root name key in the index irml section. This key – if present – specifies the name of the top-level index page. The default name is index.html, but you can choose any name you like.

<key>index irml</key>
<array>
    <dict>
        <key>dest format</key>
        <string>f%@.html</string>
        <key>source file</key>
        <string>simple.index.irml</string>
    </dict>
    <dict>
        <key>dest format</key>
        <string>count%@.txt</string>
        <key>source file</key>
        <string>simple.count.irml</string>
    </dict>
</array>
<key>root name</key>
<string>index.html</string>

In this example, there are two source IRML files per index page. The first file will generate output files with names of the form f%@.html, where %@ is replaced by the uid of the file. However, the top-level index page will be named index.html thanks to the root name key.

The second file will generate output files with names of the form count%@.txt. If the root name key were not present, the top-level index page would also generate an output file named index.html – which would collide with the output from the first IRML file.

Photo IRML

Each plist file should specify one or more photo IRML files, using the following syntax:

<key>photo irml</key>
<array>
    <dict>
        <key>dest format</key>
        <string>p%@.html</string>
        <key>source file</key>
        <string>simple.photo.irml</string>
    </dict>
    <dict>
        <key>dest format</key>
        <string>s%@.html</string>
        <key>source file</key>
        <string>simple.slide.irml</string>
    </dict>
</array>

In this example there are two IRML files specified, so both will be used when generating HTML files for photos – resulting in two HTML files per photo. Replace simple.photo.irml and simple.slide.irml with the names of your own IRML files.

You can also specify only one photo IRML file, or three, or zero.

Other Files

You can specify that other files should be copied into the web site folder when the template is built:

<key>other files</key>
<array>
    <string>folder.jpg</string>
</array>

Any number of files can be copied during the build process – just add additional sections of the form <string>filename</string>. You can specify file names or complete Unix paths.

Preview

You can provide an optional picture that will show up in the Template Settings… panel when this template is selected:

<key>preview</key>
<string>Simple.jpg</string>

Replace Simple.jpg with the name of your JPEG file.

Description

You can provide an optional description that will show up in the Template Settings… panel when this template is selected:

<key>description</key>
<string>Anything goes here. It can span multiple lines.</string>

Enter any text between the <string> </string> tags.

Variable Overrides

You can override and “pin” some of the variables in the Template Settings… panel by specifying their value in the plist file. When a variable is pinned it can’t be changed by the user. The following keys are supported:

<key>showPhotoTitles</key>
<true/>

Use <true/> to show photo titles on photo pages, or <false/> to hide them. This variable is not used by Image Rodeo, except to set the document.showPhotoTitles variable in IRScript.

<key>showThumbnailTitles</key>
<true/>

Use <true/> to show thumbnail titles on index pages, or <false/> to hide them. This variable is not used by Image Rodeo, except to set the document.showThumbnailTitles variable in IRScript.

<key>columns</key>
<integer>4</integer>

Specify any number of columns. This variable is not used by Image Rodeo, except to set the document.columns variable in IRScript.

<key>photoSize</key>
<integer>400</integer>

Specify any reasonable photo size. Setting this variable may cause Image Rodeo to re-scale all the photos.

<key>thumbnailSize</key>
<integer>100</integer>

Specify any reasonable thumbnail size. Setting this variable may cause Image Rodeo to re-scale all the thumbnails.

<key>printable</key>
<true/>

Use <true/> to generate printable images, <false/> to suppress them.