Note: this section is intended for folks comfortable editing HTML files.
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 Core Foundation, so you’ll find them used by many native OS X applications. You can edit plist files using a text editor or Apple’s PropertyListEditor, found on the Developer CD or on Apple’s web site.
Plist files can contain just a few types, represented as XML tags. These are the tags you’ll find in Image Rodeo plist files:
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.
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>
The plist file must end by closing the <dict> tag, then finally the enclosing <plist> tag:
</dict>
</plist>
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 of the file, in which case Image Rodeo will look for it in the same folder as the plist file.
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 tacked on. You can create any sort of file name you want, but it must include the %@ part somewhere in the string. Examples: indexpage%@.html or pagenum%@.html.
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 want. The name may include the %@ string, in which case the %@ will be replaced by 0 - the uid of the top-level index page. Here’s an example of this key in action:
<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>root name</key> <string>rootcount.txt</string> <key>source file</key> <string>simple.count.irml</string> </dict> </array>
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 generate an output file named index.html.
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 overwrite the existing file named index.html. To solve this problem, the root name tag specifies a different file name - in this case rootcount.txt. The net result is 2 output files per index page, with the top-level files named index.html and rootcount.txt.
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 paths or names of your IRML files, and modify the destination format strings as desired. Note that in this example one IRML file generates files of the form p%@.html, while the other generates files of the form s%@.html - this is so that the two files generated for this photo will have different names, one starting with “s” and the other one with “p”.
You can also specify only one photo IRML file, or three, or zero.
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.
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.
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.
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 variables can be pinned:
<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.