Fork me on GitHub

Starting with v2.5 and later, Vienna supports plugins which are installed on the toolbar and can run defined actions. These plugins are XML-based and can be created by editing a simple .plist-file without any knowledge of Cocoa programming, in as little as 15 minutes. This section describes how to create your own plugins, which will look and work exactly like the built-in ones:

Vienna 2.5 supports user-creatable plugins

Creating the Plugin Bundle

Vienna plugins are distributed in the form of folders with the extension “.viennaplugin“, which OS X automatically treats as bundles. Simply create a new folder, named like your new plugin. Then edit its name and append “.viennaplugin”. This registers the folder as a Vienna plugin folder so that it can be double-clicked or dragged-and-dropped on the Vienna application icon to automatically install it. After this step, you can view the folder’s contents via control/right-clicking and choosing “Show Package Contents” from the menu.

Adding the Necessary Files

There are three types of plugins supported as of the time of writing:

  • Link plugins are simple sharing plugins that work with any web service that has a special URL for posting information. For example, if you wanted to share “xyz.com” (which has the page title “XYZ“) Facebook’s “sharer.php” would be called like this:

    http://www.facebook.com/sharer.php?u=http://www.xyz.com&t=XYZ

    In a Vienna link plugin, you would use special placeholders to represent this information:

    http://www.facebook.com/sharer.php?u=$ArticleLink$&t=$ArticleTitle$
  • Script plugins can run AppleScripts, acting on the information that Vienna and other applications exposes to the user via their script suites.
  • Blog Editor plugins are simple plugins that tell Vienna about any application that can use information about blog posts or websites that it sends to it via its export feature. These include MarsEdit, Ecto, Pukka, Cocoalicious and many others. Quite a few of these are included in the standard distribution. To create your own plugin, you set Type to BlogEditor and BundleIdentifier to the application’s bundle identifier, which you can find in the info.plist file inside the application bundle.

Each type requires:

  • An info.plist file which defines the plugin’s attributes.
  • An icon file, preferably a 16×16 TIFF without layers but with an alpha channel.

Script plugins aditionally require:

  • The AppleScript file which, for example, gets information out of Vienna and sends it to an other application.

Configuring your Plugin

The actual configuration of the plugin happens in its “info.plist”. The following example completely describes Vienna’s built-in Facebook plugin:

<?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>Name</key>
	<string>ShareWithFacebook</string>
	<key>Type</key>
	<string>Link</string>
	<key>URL</key>
	<string>http://www.facebook.com/sharer.php?u=$ArticleLink$&amp;t=$ArticleTitle$</string>
	<key>Default</key>
	<false/>
	<key>FriendlyName</key>
	<string>Facebook</string>
	<key>Tooltip</key>
	<string>Share the current article on Facebook</string>
	<key>ButtonImage</key>
	<string>facebookButton</string>
	<key>MenuPath</key>
	<string>Share With Facebook</string>
	<key>ShortenURLs</key>
	<false/>
</dict>
</plist>

For more information on understanding and editing .plists, please go read this document at the Apple Developer Connection website.

Configuration Entries

  • Name: (mandatory) this is a short, internal, name that uniquely identifies the plugin. It is now displayed in the UI.
  • Type: (mandatory) this specifies the plugin type. Three values are accepted: Link, Script and BlogEditor.
  • BundleIdentifier: Only used for BlogEditor plugins, this defines the identifier of the application that you want to be called.
  • URL: (mandatory for link-type plugins) this is the URL that is browed when the plugin button is clicked. Vienna substitutes the $…$ placeholders with actual values from the current article being viewed. See here for a list of placeholders.
  • Script: (mandatory for script-type plugins) this is the name of the script file in the same folder as the info.plist.
  • Default: if this is set to true then this plugin appears on the default toolbar.
  • FriendlyName: this is the short name of the plugin that appears as the plugin button text on the toolbar. It should be kept as short as possible. If omitted, the internal name is used instead.
  • Tooltip: this is the text of the tooltip that appears when you hover over the plugin button on the toolbar. If omitted, the friendly name is displayed instead.
  • ButtonImage: (mandatory) this is the name of a 16×16 TIFF image in the same folder as the info.plist that will be used as the toolbar button image. For small buttons, Vienna takes this and reduces it to 12×12 automatically. However if you specify a TIFF image with the “small” prefix to the button image name then Vienna will use that for small buttons.
  • ShortenURLs: for link type plugins, specifies whether Vienna shortens the URL before using it. Vienna uses the bit.ly API to do this, there is nothing else you have to specify. To see it in action, try the built-in Twitter plugin.
  • MenuPath: specifies an optional name for the plugin at the end of the Article menu.
  • MenuKey: specifies an optional key association for the plugin in the menu. This should be one or more of: Cmd, Ctrl, Alt and Shift, separated by a ‘+’ character and finally a single letter or number character.