Theme Error Descriptions

Note: this document contains information about unreleased beta software, and is likely to change substantially over time.

In the interest of not overloading the user with unnecessary information, prior to Bowtie 1.2, broken themes would generate no error message, and would instead simply fail silently to load. In order to balance this desire with the ability to provide developers more information about why their theme isn't working, in Bowtie 1.2 and Bowtie Touch 2.0, Bowtie for Mac will display a consistent, simple error message for broken themes, including only an error code for use by the developer.

Note that, for themes installed via the built-in theme repository, users will have the option of submitting an automatically-generated error report (which you can set to have emailed to you) that contains platform information, the error code and its description, the raw contents of all relevant property list files, and a snapshot of the settings tree (the merged values of Info.plist and its cohorts) as seen by Bowtie.

Text of the Error Messages

The error message text is carefully chosen to reflect the situation, and is reproduced here for use in your documentation should you so desire.

Because of differences in screen real estate and pattern of user interaction, Bowtie and Bowtie Touch display slightly different error messages. The error message will also vary between themes installed via {13bold}'s own theme repository, and themes installed manually (via URL or direct installation by file download). The buttons displayed for each message are mentioned under the message text; primary, second, and tertiary buttons are typically ordered from right-to-left on-screen, in accordance with the Human Interface Guidelines for each device.

Bowtie for Mac Error Messages

For themes installed manually (all themes installed prior to installing Bowtie 1.2, when the theme repository was introduced), the following error message will be displayed:

The theme "Default" is broken and cannot load.
Try reinstalling the theme. If reinstalling the theme doesn't fix the problem, contact the author ({13bold}) with error code FIL001.

The primary button is "OK", the secondary button is "Visit Website" (which opens the author's website in the default browser), and the tertiary button is "Details…" (which opens this page to the appropriate error code).

For themes installed via the built-in theme repository, the following error message will be displayed:

The theme "Default" is broken and cannot load. Would you like to submit an error report?
The error report is completely anonymous and automatically generated, and could help the author fix this theme.

The primary button is "Submit", the secondary button is "Don't Submit", and the tertiary button (as above) is "Details…".

Bowtie Touch Error Messages

For themes installed manually from an author's website (via a specially-formed bowtie:// URL), the following error message will be displayed:

Could Not Load Theme
The theme "Default" is broken and cannot load. Try reinstalling, then contact the author with error code FIL001.

The primary (and only) button is "OK".

For themes installed via the built-in theme repository, the following error message will be displayed:

Could Not Load Theme
The theme "Default" is broken and cannot load. Would you like to submit an anonymous error report?

The primary button is "Submit", and the secondary button is "Don't Submit".

Error Descriptions

Note: there are three error domains, indicated by the first three letters of the error code: FIL indicates a file error, INF indicates a configuration error (eg, with your Info.plist), and TCH indicates an error specific to Bowtie Touch development.

Also note that the existence of an error code does not imply that an error will always be thrown in the associated conditions: some errors are defined here for future use, but not implemented in Bowtie.

FIL001: Insufficient Configuration Information

This error indicates that no settings tree could be built. On Bowtie for Mac, this means that no Info.plist file was provided. On Bowtie Touch, this means that neither an Info.plist, Touch.plist, or device-specific property list (iPhone.plist or iPad.plist) file was provided.

All themes require an Info.plist file for use with Bowtie for Mac, and at least one of Info.plist, Touch.plist, or a device-specific property list for use with Bowtie Touch. Refer to Chapter 2: Creating Your First Theme for more information on building this property list.

FIL002: Main File Not Found

This error indicates that the theme's main file — specified in your settings tree as BTMainFile — could not be found. This can happen when you don't include the main file that you indicated, but more often than not is the result of a typo. Make sure there are no leading or trailing spaces surrounding your definition of BTMainFile.

FIL003: Preview Image Not Found

This error indicates that the theme's preview image file — specified in your settings tree as BTThemePreviewImage — could not be found. This can happen when you don't include the image file that you indicated, but more often than not is the result of a typo. Make sure there are no leading or trailing spaces surrounding your definition of BTThemePreviewImage.

Note that this error does not indicate that you didn't specify a preview image. In spite of the fact that BTThemePreviewImage is marked as a required key, if you fail to provide one, Bowtie will silently ignore the issue and display a "No Preview Provided" image. This error indicates that you did define it, but the file was not found in your theme's bundle.

FIL004: Unrecognized Main File Type

This error indicates that you specified a main file of some type other than .html or .htm. Please rename your file (and update your configuration accordingly) with one of these more standard file extensions.

FIL005: Unrecognized Preview Image Type

This error indicates that you specified a preview image of some type not recognized by Mac OS X or iPhone OS (depending on the platform on which your theme is installed). Please use a more commonly-supported image format for your preview image.

INF001: BTMainFile Was Left Blank or Undefined

This error indicates that you either did not specify a value for BTMainFile anywhere in your settings tree, or else specified a blank string. Every theme requires a main file. Refer to Chapter 2: Creating Your First Theme for more information.

INF002: BTThemeIdentifier Was Left Blank or Undefined

This error indicates that you either did not specify a value for BTThemeIdentifier anywhere in your settings tree, or else specified a blank string. Every theme requires a unique identifier for organizational and logistical purposes. Refer to Chapter 2: Creating Your First Theme for more information.

INF003: BTThemeName Was Left Blank or Undefined

This error indicates that you either did not specify a value for BTThemeName anywhere in your settings tree, or else specified a blank string. Every theme requires a name for display in the theme browser. Refer to Chapter 2: Creating Your First Theme for more information.

INF004: Window Dimensions Were Not Provided

This error indicates that you did not specify valid values for BTWindowWidth and BTWindowHeight. Bowtie for Mac requires that you specify the size of the transparent window used to display your theme. Refer to Chapter 2: Creating Your First Theme for more information.

INF005: Unsupported Platform

This error indicates that the platform specified by BTThemeDevice is not supported. In other words, you're trying to run a Bowtie Touch theme on Bowtie for Mac, or vice versa.

TCH001: No Lowercase <head> Start Tag Found

This error indicates that the case-sensitive string "<head>" occurred nowhere in your theme's main file. Bowtie Touch relies on the presence of a lowercase head element to properly inject JavaScript and CSS during theme loading. Please adjust your theme to use the more modern convention of all lowercase element names.