Creating Bowtie Touch Themes

Note: this document contains information about unreleased beta software, and is likely to change substantially over time.
This document is a condensed version of Special Considerations for Bowtie Touch. It will get you up to speed quickly, but it's highly recommended that you read the full version before doing any serious theme development for Bowtie Touch.

Creating Bowtie Touch themes is practically no different from creating themes for Bowtie for Mac. Touch themes use the same API, the same file format, and are structurally the same as their Mac counterparts. The only real differences are the additional things you will need to take into account in your design:

Before proceeding, make sure you have read and understand Chapter 2: Creating Your First Theme.

Device Orientation

All themes are expected to support both portrait and landscape orientations. Bowtie automatically applies two CSS classes on the html element for each orientation:

If you specify a function for the "Orientation Changed" event (using BTOrientationFunction), you will also be able to modify things using JavaScript.

For more information, see Device Orientation under Special Considerations for Bowtie Touch.

Status Bar

Unlike with Bowtie for Mac, on Bowtie Touch, you have to deal with the standard iOS status bar. Regardless of which device you're using, the status bar will overlap your theme by a certain amount: 40px on iPhone/iPod touch (assuming you're targeting a Retina Display, which you should be), and 20px on iPad. On iPhone and iPod touch, it will be black with 50% alpha; on iPad, it will be solid black.

If you'd like to disable the status bar, simply set BTDisableStatusBar to true. Note that, on the iPad, the corners of your theme will be rounded when the status bar is displayed, but square when it is hidden. To achieve a solid black status bar on iPhone/iPod touch, simply leave 40px of black at the top of your theme.

If at all possible, design around the status bar: it is useful to your users to be able to see battery and time information at all times, and on the iPad, it quite neatly blends in with the device frame. Only disable the status bar if completely necessary for the aesthetic of your design.


On iPhone and iPod touch, the portrait screen dimensions are 320x480 for a traditional display, and 640x960 for a Retina Display. On iPad, the portrait screen dimensions are 768x1024. Your theme will always fill this canvas: window dimension values in Info.plist are ignored.

Retina Display

On iPhone and iPod touch, you should always target the Retina Display to save effort and make sure your themes don't look fuzzy. At the top of the head section of your main HTML file, use:

<meta name="viewport" content="width=device-width, minimum-scale=0.5, maximum-scale=0.5, user-scalable=no">

This will give you a virtual canvas of 640x960 (on any device, Retina and non-Retina alike) rather than the traditional 320x480.

Touch Interaction

With Bowtie Touch, people will be interacting using their fingers, not a mouse. Make sure your hit targets are nice and big, and use touch-based events (like touchstart and touchend) instead of mouse-based events (like click).

For more information, see Code for Mobile Safari, Not Safari under Special Considerations for Bowtie Touch.

Theme Start-up

On Bowtie Touch, the load event (ie, the event handled by the body element's onload attribute) is fired before Bowtie has had a chance to fully attach to the theme. For this reason, you should instead perform any initialization in the "Theme Ready" event. This event is also available in Bowtie for Mac 1.2, so there's no time like the present to start the migration!

Packaging and Installation

Installing themes into Bowtie Touch works differently (obviously) than on Bowtie for Mac. In almost all cases, the first step is to zip your theme: on OS X, simply right-click your ".bowtie" file, and choose "Compress 'themename.bowtie'." You then have two options: host the theme yourself, or distribute it through Bowcase for Bowtie.

While you're still testing your theme, you'll want to simply host the theme yourself: stick it on your web server, and from your device, visit the following URL:


Thus, for example, if I were to put a theme called on my website, I would visit:


During testing, I'll typically write up a quick HTML file on my website with the above link in it, and keep it open in Mobile Safari, so that I can quickly reinstall whenever I make changes to it. Themes with identical identifiers (see BTThemeIdentifier) automatically overwrite one another.

Once your theme is ready for distribution, you should consider publishing it to Bowcase for Bowtie. This way, users will be able to download and install your theme directly from within Bowtie, on both Bowtie for Mac and Bowtie Touch.