Editing Image Rodeo Templates

Note: this section is intended for folks comfortable editing HTML files.

Last updated 4/19/04.

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 a deep understanding of IRScript or even HTML, but some may require more knowledge.

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; change it using the Preferences panel) and searches for files with a .plist extension. These files will be read and used to load and parse IRML files.

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 template will win over the internal template.

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

• Editing Plist Files
• Editing IRML Files

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 into one folder.

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

1. Property List File (.plist) There is one plist file for each template, and the name of the file is the template name (not including the .plist extension). The plist files control which IRML files (and other files) make up each template. They also contain the description that shows up in the Template Settings... panel as well as a reference to the jpeg that’s displayed.
2. IRML Files (.irml) IRML files are HTML files with the addition of IRScript commands wrapped in SGML processing directives - the funny tags that start with <? and end with ?>.
3. Sometimes a few other files, such as folder.jpg. These are helper files used in the template.

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, and folder.jpg. The index file is used to generate index pages, and the photo and slide files are used to generate photo pages.

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 CD. You’ll find a description of how Image Rodeo uses plist files here.

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 that information to read the various IRML files. If the plist and IRML files are parsed successfully, your new or modified template will show up in the popup menu in the Template Settings... panel. If your template has the same name as a built-in template then your template will override the built-in 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. If this happens only one will show up in the menu.

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 there first. Image Rodeo errors and messages will be clearly labeled.

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, set the value of the variable strict to any non-zero value near the top of your template. Errors that occur after that point will be logged to the Console.

	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

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 on the Developer CD) to make sure it’s a legal plist file.

Troubleshooting 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 when you rebuild the web site. Check the error messages in the Console application: all parse errors will generate an error message.

Troubleshooting 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.