Editing Image Rodeo Templates

Overview

The real power of Image Rodeo is that you can edit the existing templates or create your own using standard HTML editing tools and techniques. Some edits – such as changing link colors – don’t require any programming. Other edits – such as generating a table of contents – require the use of IRScript, Image Rodeo’s built-in scripting language.

Image Rodeo ships with the source code to the built-in templates so you can inspect and modify them. When launching, Image Rodeo looks for the default template location (~/Library/Image Rodeo Templates).

Of course, Image Rodeo will load and parse the internal templates as well. Both sets of templates – internal and external – will be presented in the template list. If there’s a name conflict, the external (user-installed) template wins.

To start editing templates, read the rest of this page for an overview, then jump to these sections for more details:

Step 1: Install the Template Source Files

Download the template source from the Image Rodeo website. Copy the Image Rodeo Templates folder to the Library folder in your home directory (~/Library).

Step 2: Create or Modify the Template Source Files

Inside the Image Rodeo Templates folder you’ll find a collection of folders – one for each template. This organization is strictly a convenience for editing; if you like you can cluster several templates together in one folder, or split one template across several folders.

Inside each template folder you'll find the following files:

  • A plist file describing the template.
  • One or more IRML files containing HTML and IRScript.
  • Optional supporting files (images, CSS, JavaScript, etc.).

The IRML files that ship with Image Rodeo are organized by name. For example, the default template consists of 5 files: Simple.plist, simple.index.irml, simple.photo.irml, and simple.slide.irml, plus a few supporting files.

If you’re comfortable with HTML you can open any IRML file and modify it. You can edit IRML files with any text or HTML editor. I suggest you learn IRScript before making wholesale changes.

Plist files are written in XML using Apple’s plist DTD. You can edit the plist file using any text editor, but the easiest way to edit a plist file is with the PropertyListEditor tool that ships with the OS X developer tools. See Editing Plist Files for details.

Step 3: Launch Image Rodeo and Select the Modified Template

When you launch Image Rodeo it will read all the files ending in .plist in the ~/Library/Image Rodeo Templates folder (or wherever you’ve set it if you’ve changed it in the Preferences panel), then use the Template Settings… command in the Web Site menu to pick your template.

After setting the template, simply re-build the web site using the Build Web Site command, and check your results.

Be careful: Image Rodeo will scan subfolders of ~/Library/Image Rodeo Templates looking for plist files, so it’s possible to end up with two plist files – and therefore two user-installed templates – with the same name. Don’t do that.

If you change a template while Image Rodeo is running, you'll need to force a re-scan and re-parse of the templates by selecting the Reload Templates command in the Web Site menu.

Using Strict Mode

Image Rodeo writes error messages to the UNIX stream stdout, which under OS X is available in the Console application (/Applications/Utilities/Console). If you run into problems be sure to check the Console for error messages.

IR 1.3.2 and later support a strict mode which may help you catch some common errors. You can turn strict mode on and leave it on – it reports errors, but doesn't change the build behavior. To enable strict mode, add this line near the top of your IRML file:

strict = 1;

foo = bar;     /* If bar was never assigned a value (Perl: undef), this will generate an error. */
foo = bar[4];  /* If bar is undef or null, this will generate an error. */

There may be more error checking in the future.

Troubleshooting

Tip #1: if you don’t see any user-installed templates you might have made an error in the appropriate plist file – check the syntax carefully. Open it in PropertyListEditor (available with the OS X developer tools), which will report XML errors.

Tip #2: if Image Rodeo can’t read or understand an IRML file then that file won’t be used when generating HTML files. A common symptom is that your changes to an index or photo page just don’t show up. Check the Console for error messages.

Tip #3: remember that you must force Image Rodeo to reload and reparse the templates after you make a change. Select the Reload Templates command in the Web Site menu.