Special Considerations for Bowtie Touch

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

Developing themes for Bowtie Touch — which runs on iPhone, iPod touch, and iPad — is very similar to developing themes for Bowtie on the Mac: touch themes use the same API, and work very much in the same way. It's even possible to build one theme that will run on both Bowtie for Mac and Bowtie Touch. There are, however, a few considerations that you should take into account when developing touch themes.

Please note that Bowtie Touch (formerly, Bowtie for iPhone) does not support themes in versions older than 2.0. Prior to Bowtie Touch 2.0, Bowtie for iPhone was only used as a reverse remote control for Bowtie. Bowtie Touch 2.0 is not yet available.

Some Features are Unavailable

While the vast majority of the Bowtie API is available on Bowtie Touch, not all features are available. In general, the only features that have been omitted from Bowtie Touch are those that would not make sense on a mobile device (like pseudo-mouseover tracking) and methods that are deprecated in Bowtie for Mac.

Before using a feature in Bowtie Touch, check the relevant documentation for that feature to ensure that its "Availability" section contains "Available in Bowtie Touch x.y and later." Bowtie and Bowtie Touch availability are listed separately — if one of the two platforms is not listed, it is not available on that platform.

Use a Lowercase <head> Element

In order for the Bowtie API to work on mobile devices, Bowtie Touch needs to inject a gratuitous amount of JavaScript and CSS into each theme as it loads. This injection relies on the fact that your opening head tag is in all lowercase letters. In modern websites, this is the convention, and only particularly old hypertext documents contain uppercase element names. Nevertheless, you must be mindful of this requirement.

Device Orientation

Unlike a Mac, iPhones and iPads can be flipped and turned into a number of different orientations (well, you can do that with a Mac, too, but it'd be awfully hard to use upside down). For this reason, it will likely be wise to pay attention to this within your theme, as all themes are assumed to support all orientations.

You can observe orientation changes in both CSS and JavaScript. Both methods are described below, and are non-exclusive (you can use both).

Note: at any time, you can determine the current screen orientation using Bowtie.orientation().

Use CSS to Handle Orientation Changes

The easiest way to allow your theme to take advantage of multiple orientations is to use CSS. Bowtie Touch automatically assigns numerous classes to the html element based on the orientation of the device. At any given time, there will always be two orientation-related classes in effect: a generic class, and a specific class.

The two generic classes are BTOrientationPortrait and BTOrientationLandscape. If, for instance, you wanted all text to be red when your theme is being displayed in either landscape orientation, you would do something like this:

.BTOrientationLandscape {
	color: red;
}

There are four specific classes: BTOrientationPortraitNormal, BTOrientationPortraitUpsideDown, BTOrientationLandscapeLeft (when the Home button is to the left of the screen), and BTOrientationLandscapeRight (when the Home button is to the right of the screen). You could therefore extend the above code so that the text is red when the device is in either landscape orientation, or upside down:

.BTOrientationLandscape, .BTOrientationPortraitUpsideDown {
	color: red;
}

Use JavaScript to Handle Orientation Changes

You can also opt to handle orientation changes manually using JavaScript. This works like any other Bowtie event: specify the name of a function in your Info.plist file under BTOrientationFunction, and implement it according to the Orientation Changed event.

One parameter is passed to this function, an integer representing the orientation in the same manner as Bowtie.orientation(): 0 is portrait, 90 is landscape with the Home button on the left, -90 is landscape with the Home button on the right, 180 is portrait upside down.

Code for Mobile Safari, Not Safari

Safari and its younger sibling Mobile Safari share a large part of the same codebase, particularly Snow Leopard's version of Safari 5 with iOS 4 Mobile Safari. However, the two are not one-and-the-same, and there are some things that work quite well on Safari that don't on Mobile Safari, and vice versa. Code with the intent of releasing on Mobile Safari, and always test your theme thoroughly before you release.

Use Touch Events, Not Mouse Events

Mobile Safari does a good job of emulating most mouse events, but in order to ensure that multitouch gestures are properly handled, it will sometimes delay the processing of click events, among others. This creates a noticeable lag in your themes, which is undesirable. Instead, use Mobile Safari's touch-based events for your theme's controls, like touchstart and touchend. Beyond eliminating this annoying delay, these events also allow you to take advantage of cool multitouch gestures in your themes!

A terrific tutorial on using these events can be found on the SitePen blog: Touching and Gesturing on the iPhone.

Please note that the dblclick event is NEVER fired in Mobile Safari because this is ordinarily reserved for context-sensitive zooming.

Preventing Scrolling

A small amount of JavaScript is automatically injected into your theme to disable the touchmove event, effectively disabling scrolling. This is identical to the behavior of Bowtie for Mac. Be aware, however, that if you intend to use document's touchmove event, you will need to do the same to prevent your page from scrolling:

document.ontouchmove = function(e) {
    e.preventDefault();  // prevents scrolling
    // ... your code here ...
}

Adjust for Resource Loading Time

On Mobile Safari, resources take longer to load than on Safari on the desktop. For this reason, you may want to make some adjustments to your code. The two most common examples are play/pause images, and artwork.

Play/Pause Buttons

In an attempt to be more memory-efficient, Mobile Safari (as used by other applications, like Bowtie Touch) does not cache loaded images that are specified non-globally (ie, inline with an element) via CSS. Therefore, if you use inline CSS or the DOM style object to swap out play and pause images in response to a "Playback State Changed" event, you may notice a momentary flicker (the period during which the next image is loaded). To avoid this, use an img element and change the src attribute dynamically — Mobile Safari automatically accounts for this flicker on images.

Alternatively, if you must use CSS, define two classes — .play and .pause — each with the appropriate background image. Then, use JavaScript to swap out the className attribute on the button element. The first time, there may be a flicker; from there on, however, the images will remain cached because they are loaded document-globally.

Artwork

For the same reason as described above, you may observe a momentary flicker when loading artwork if you do so by swapping out the background-style CSS property. It is recommended that you instead use an img element to account for this.

Memory Constraints

iPhone applications are generally given up to 46MB of RAM before being terminated. It is unwise, however, to use all of that. While it is unlikely that most themes will bring Bowtie even near the memory cap, do be kind to your user's mobile devices, and try not to abuse resources too heavily.

Some CSS Styles are Overridden

In order to ease the transition of primarily desktop web developers into developing for mobile devices, the following CSS is automatically injected into themes as they're loaded:

body {
    -webkit-touch-callout: none;
    -webkit-user-select: none;
    -webkit-tap-highlight-color: rgba(0, 0, 0, 0);
}

This disables the "Copy Image" popup when tapping and holding on images, and the Copy/Paste/Select/Select All popup, and also turns off the slight grey highlight that ordinarily appears in Mobile Safari when tapping a button or link. You can reenable any of these features (should you desire to do so) by overriding the relevant property in your own CSS.

Be Aware of the Interaction Model

iPhone, iPod touch, and iPad all have different interaction models: on a pocket device, it's highly likely that apps are treated in a functional manner, and will be used for directed tasks over relatively short periods of time; on an iPad, it's increasingly likely that apps will be used for visual enjoyment. Take this into account when designing your theme if you plan to deploy on both iPhone/iPod touch and iPad.