Creating Bowtie Themes

Anyone can create their very own theme for Bowtie — well, anyone with a little experience in HTML, CSS, and JavaScript!

Bowtie is based on the powerful WebKit engine, the same one that powers Safari and Dashboard. In fact, creating a Bowtie theme is akin to creating a Dashboard widget: it’s as simple as creating a standard web page, only you also provide a bit of metadata (in Info.plist), and have a handy JavaScript API to access special Bowtie features.

Getting Started

To get started, create a folder for your theme. It is recommended that this folder share your theme’s name, and required that it have the extension “bowTie” (for example, the theme named iPhoney is contained in a folder called iPhoney.bowTie). If you have Bowtie installed, this folder should automatically become a “package”, or a folder that’s trained to act as a single file. To get into it from here, Control + Click it, and select “Show Package Contents”. Alternatively, you can just remove the “.bowTie” extension until you’re ready to test it.

Theme Location

When Bowtie launches, it searches three places for themes:

You should never place your own themes in the internal themes directory, and only sparingly use the System Application Support directory (for themes that you want accessible to every user on your system). That leaves us with the User Application Support directory, so we’ll move our theme there for now.

Info.plist

Bowtie themes contain metadata in an Info.plist file, the de facto standard for OS X package metadata. Info.plist is a property list file, which is simply an XML file using Apple’s Property List syntax. If you have the Developer tools (ie, Xcode) installed, you already have an application on your system called Property List Editor, which you can use to help you create these files.

If you don’t have this application, you can create one in any text editor — the basic syntax is shown below:

<?xml version="1.0" encoding="UTF-8"?>
	<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
	<plist version="1.0">
	<dict>
	    <key>BTMainFile</key>
	    <string>index.html</string>
	    <key>BTWindowWidth</key>
	    <integer>220</integer>
	</dict>
	</plist>
	

When using Property List Editor, numbers are specified using the “Number” type; if you create one by hand, you must distinguish between integers, floats, etc. For Bowtie’s purposes, only integers should be used.

Theme API

The Theme API is what you will use to get your theme to interact with Bowtie properly. For this, three mechanisms are provided for you: a set of keys in your Info.plist file; and two JavaScript objects, “iTunes” and “Bowtie”.

Info.plist Keys

“iTunes” API Object

“Bowtie” API Object

BTWrapper Interface

Sample Project

The best way to become familiar with Bowtie is by experimenting with the sample project, which includes pre-made scripts that you can use to perform common functions in your own controller. The sample project is a tidied version of the Heads Up Mini controller, by Laurent Baumann.