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:
- Device Orientation: iPhone, iPod touch, and iPad can all be rotated into a number of orientations
- Status Bar: the iOS status bar (unless you disable it) takes up the top 20px (40px on Retina Display) of your theme
- Dimensions: in Bowtie Touch themes, you don't need to specify the window dimensions — on iPhone/iPod touch, it's 640x960; on iPad, it's 768x1024
- Retina Display: you should target the Retina Display on iPhone/iPod touch to prevent fuzziness
- Touch Interaction: people are using their fingers, not a mouse
- Theme Start-up: use the "Theme Ready" event, not the
- Packaging and Installation: there are a couple of extra steps required to distribute your theme
Before proceeding, make sure you have read and understand Chapter 2: Creating Your First Theme.
All themes are expected to support both portrait and landscape orientations. Bowtie automatically applies two CSS classes on the
html element for each orientation:
- Portrait (normal):
- Portrait (upside down):
- Landscape (Home button on left):
- Landscape (Home button on right):
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.
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.
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
touchend) instead of mouse-based events (like
On Bowtie Touch, the
load event (ie, the event handled by the
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 CoolTheme.bowtie.zip 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.