Creating Zipline Sources

Zipline gets its data from a variety of sources. Users can selectively enable, add and remove these sources, which are implemented as loadable Cocoa bundles. By default, Zipline includes several sources; this document explains how to create additional sources to provide information to Zipline.

Setting up a Zipline plugin project
As previously stated, Zipline sources are loadable Cocoa bundles. You can create one manually by launching Xcode and choosing File > New Project, selecting Framework & Library in the source list, and then selecting Cocoa Bundle. Alternatively, you can download an example project.

Configuring the Bundle
When Zipline loads a plugin, it instantiates the class corresponding to the NSPrincipalClass key in the bundle's Info.plist. Consequently, your plugin should use this class as the beginning of execution. This class also needs to conform to the ADTickerSource formal protocol. You can download the header file here and import it into your principal class.

Conforming to ADTickerSource
The ADTickerSource protocol requires that classes that conform to it implement several methods. Descriptions of each are as follows:

- (NSDictionary *)nextDataItem
This method is called when Zipline wants a new item from the plugin. If your plugin does not have any new information to give to Zipline, you should return nil. Otherwise, you should return a dictionary with three keys: string, image and expirationDate.

The object corresponding to string should be an NSString that will be displayed as the textual content of your item in Zipline.

Likewise, the object corresponding to image should be an NSImage that will be displayed next to the textual content of your item. Keep in mind that this image will be displayed at a small size (20x20px); while you can return a larger image, a smaller image will result in lower memory usage.

Finally, expirationDate's object should be an NSDate at which the item will be removed from circulation in Zipline. If your plugin provides information that changes on a relatively infrequent basis, such as RSS feeds, consider setting an expirationDate 30 minutes or an hour in the future. On the other hand, if your plugin provides information frequently (for example, a system monitor), set a short expirationDate, such as a a few seconds. Don't set the expiration date to the current time, as this may result in your item never getting added to Zipline.

- (NSInteger)supportedPluginProtocolVersion
This method returns an NSInteger corresponding to the version of the Zipline plugin protocol your plugin supports. For now, simply return 0; if the Zipline plugin protocol changes in the future, Zipline will interact with your plugin according to this version of the protocol (unless you update it to return the new plugin protocol version number)

- (NSImage *)pluginIcon
This method returns an NSImage that will be used as your plugin's icon in the Sources section of Zipline's preferences. This image should be at least 38x38px, and should be an attractive icon representative of the information your plugin provides.

NOTE: Don't use NSImage's imageNamed: method when creating the image to be returned. Since plugins are not proper applications, this method may not work properly. Instead, use NSBundle to get the path to the image you want to use and initialize an NSImage with the contents of that file. (See the Hello World plugin example)

- (NSString *)pluginName
This method should return the name of your plugin as you want it to appear in the Sources section of Zipline's preferences.

- (NSString *)pluginDescription
This method should return a 1 or 2 sentence description of the information your plugin provides. Typically, this should be in the form of "Fetches <content> from <source>."

- (NSString *)pluginVersion
This method should return the current version number of your plugin.

- (BOOL)hasOptions
This method should return TRUE if your plugin has user-configurable options. Otherwise, return FALSE.

- (NSView *)optionsView
This method should return an NSView that allows the user to configure your plugin. Zipline will handle presentation and dismissal of the view.

- (void)dataItemClicked:(NSString *)itemTitle
This method is called when an item provided by your plugin is clicked in Zipline. If there is an action that would correspond to "opening" the items provided by your plugin, perform it. For examples, see the behavior of the default Zipline plugins.

Other Considerations
Zipline is designed to run on Mac OS X 10.5 Leopard and later. Consequently, your plugin should be able to run on both Mac OS X 10.5 and 10.6. Additionally, your plugin should support the x86, x86_64 and ppc architectures. Since Zipline is garbage collected, your plugin should also use garbage collection. If your plugin does not have these characteristics, it will not be able to be loaded by Zipline.