How to create a WebKit-based Growl style

About WebKit styles

There are currently two types of Growl display plugins:

• Plugins written in Objective-C which contain native code and have complete control over their appearance and interaction with the user.
• WebKit-based plugins which use CSS for their layout. No programming skills are required to create or customize these plugins.

This tutorial shows how to create and install WebKit-based display plugins.

Requirements

In order to create a WebKit style for Growl, you'll need some basic knowledge about Cascading Style Sheets (CSS). There are several good tutorials on the net, for example:

• Westciv Complete CSS Guide
• SelfHTML

Creating a new plugin

A display plugin is a simple directory structure like this:

<stylename>.growlStyle [directory]
	Contents [directory]
		Info.plist
		Resources [directory]
			main.css
			template.html

The Info.plist file is a description of your style and looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>CFBundleName</key>
	<string>Example</string>
	<key>CFBundleDevelopmentRegion</key>
	<string>English</string>
	<key>CFBundleGetInfoString</key>
	<string>Example Growl WebKit Style</string>
	<key>CFBundleIconFile</key>
	<string></string>
	<key>CFBundleIdentifier</key>
	<string>com.Growl.WebKit.Example</string>
	<key>CFBundleInfoDictionaryVersion</key>
	<string>6.0</string>
	<key>CFBundlePackageType</key>
	<string>GWKS</string>
	<key>CFBundleShortVersionString</key>
	<string>1.0</string>
	<key>CFBundleSignature</key>
	<string>GRRR</string>
	<key>CFBundleVersion</key>
	<string>1.0</string>
	<key>CSResourcesFileMapped</key>
	<string>yes</string>
	<key>GrowlPluginAuthor</key>
	<string>Ingmar Stein</string>
	<key>GrowlHasShadow</key>
	<true/>
	<key>GrowlPaddingX</key>
	<real>10.0</real>
	<key>GrowlPaddingY</key>
	<real>10.0</real>
</dict>
</plist>

The entries you should change are:

CFBundleName

The name of your style.

CFBundleGetInfoString

A short description of your style.

CFBundleIdentifier

Should be set to com.Growl.WebKit.<stylename>

CFBundleShortVersionString

A short string which contains the version number of your style.

CFBundleVersion

The version number of your style.

GrowlPluginAuthor

Your name.

GrowlHasShadow

Set this optional value to true if your style should have a drop shadow. By default, WebKit styles have no shadow.

GrowlPaddingX

This value is optional and specifies the amount of horizontal padding in pixels. Default is 5.0.

GrowlPaddingY

This value is optional and specifies the amount of vertical padding in pixels. Default is 5.0.

The main.css file contains the actual stylesheet. Let's look at an example:

body {
	color: darkblue;
	margin: 0px 0px 0px 0px;
	padding: 6px 6px 6px 6px;
	border: medium solid black;
	font-family: Skia, sans-serif;
	min-height: 51px;
	text-shadow:black 3px 2px 4px;
}
#background {
	background-color:#D0D0D0;
}
#icon {
	float: left;
	top: 10px;
	left: 10px;
	width: 32px;
	height: 32px;
	margin-right: 5px;
}
#icon img {
	width: 32px;
	height: 32px;
}
#title {
	font-weight:bold;
	font-size:medium;
}
#text {
	font-size:small;
}
#emergency #text {
	color: red;
}

The three items that make up a notification (icon, title and text) are displayed as <div> elements whose id attribute is set to the item's name. Thus, in order to specify how the notification title is rendered, you need to write a rule for #title.

The title and text elements contain simple strings while the icon element contains an <img> element.

The content items have a parent div element whose id attribute is set to the priority level, i.e. verylow, moderate, normal, high or emergency. You can use this element to customize your display according to the priority of the notification.

The template.html file is optional and not needed in most cases. However, if you want to add additional content to your notifications or need to change the HTML structure, you can supply your own HTML template (probably derived from the default template).

When Growl loads the template, it replaces the following keywords with the actual values:

%baseurl%

A file:// URL that points to the Resources directory of your style bundle.

%opacity%

The user's opacity setting.

%priority%

The priority name.

%image%

A unique identifier for the notification image. In order to display the image, use <img src="growlimage://%image%" />.

%title%

The notification title.

%text%

The notification text.

You can download the above example style to begin with.

Installing the plugin

Just doubleclick your new plugin and Growl will copy it to ~/Library/Application Support/Growl/Plugins. Select your plugin in the display tab and click on the preview button to see your new style in action.