Anatomy of a plugin - Info.plist Part 1

Previously

We discussed the basic setup required to begin writing Quicksilver plugins in Quicksilver plugins in Objective-C. Anatomy of a plugin is a multi-section guide which explains the various sections of Info.plist, the different components of a plugin and the basic groundwork required in order to write a usable plugin.

To go through this guide, you need to have followed the steps in Quicksilver plugins in Objective-C. Once you’ve got Xcode set up properly for Quicksilver development, create a new Quicksilver plugin project in Xcode, and get ready to start planning your plugin.

Understanding Quicksilver’s plugin system

Info.plist

If you’ve worked with Cocoa or Objective-C, you may be familiar with the Info.plist file. As with any standard Cocoa application, the Info.plist file is an XML file specifying the various settings or options for the project in question. Quicksilver plugins use the Info.plist file to also communicate their features, actions and information to Quicksilver. It is in the Info.plist file that you need to begin editing, and realistically, you may well need to keep updating it as you add, remove, or delete features.

QSPlugIn

Tell me about you

The first thing you should probably fix up in the Info.plist file is the details that are unlikely to change. Find QSPlugIn, and take a look at it’s children. At the moment, it probably looks something like:

  <key>QSPlugIn</key>
 <dict>
    <key>author</key>
    <string></string>
    <key>categories</key>
    <array/>
    <key>description</key>
    <string></string>
    <key>icon</key>
    <string></string>
    <key>qsversion</key>
    <string>29CC</string>
    <key>relatedBundles </key>
    <array/>
 </dict>

The QSPlugIn section needs to be filled out accurately to inform potential users of its function. Lets go through the various keys that can be written inside QSPlugIn.

Author

The author is obviously you, so fill in your name.

<key>author</key>
<string>Ankur Kothari</string>

Categories

Categories is an array of strings corresponding to the appropriate categories as found in Quicksilver’s plugin preferences. You can have zero or more of the following:

• Applications
• Calendar
• Contacts
• Development
• Files
• Images
• Interfaces
• Mail & Chat
• Miscellaneous
• Music
• Quicksilver
• Search
• System
• Text
• Web

If you leave out the categories, then your plugin will still be under the “All plugins” section of Quicksilver, but wont show up under any category specific sections. For a plugin integrating MAMP support, the categories could be

<key>categories</key>
<array>
 <string>Development</string>
 <string>Applications</string>
 <string>Web</string>
</array>

Note: If you use the Mail & Chat category, make sure to escape the ampersand. It should be written as Mail & Chat

Description

The description is the text that is displayed in the info panel under the plugin preferences (unless an extendedDescription is set). Make sure you include the usage and function of your plugin in enough detail so potential users are aware of what it does. An example:

<key>description</key>
<string>Actions to start / stop the MAMP servers. Requires MAMP.app</string>

Extended Description

An extendedDescription is, as you would expect, a lengthier and more in-depth explanation of the plugin’s function. HTML is allowed in the extended description, but most characters must be encoded (For example, ‘<’ becomes ‘<’ and ‘>’ becomes ‘>’). If an extended description is set, it is shown in the info panel under Quicksilver’s plugin preferences. This field is optional. An example of an extended description (taken from the Apple Mail plugin):

<key>extendedDescription</key>
<string>Enables email actions for <a href="http://www.apple.com/macosx/features/mail/">Apple Mail</a>.
Allows browsing mailboxes as children of Mail (beta)</string>

Icon

The icon can be in the form com.developer.app (such as com.apple.Mail or com.apple.iTunes) or <speculation> you can write the name of an image that you’ve imported into your Xcode project </speculation>. This field is not required. If left blank, Quicksilver will assign your plugin an icon. The icon for the Mail plugin reads:

<key>icon</key>
<string>com.apple.Mail</string>

Hidden

A boolean value specifying whether the user can see this plugin in the plugin list or not. Generally only used by internal Quicksilver plugins. The Core Support plugin (bundled in Quicksilver.app/Contents/PlugIns/) has hidden set as:

<key>hidden</key>
<true/>

There is also a boolean key called secret, but it’s obviously, well, secret.

Related Bundles

Related bundles refers to resources or packages that are similar to or related to this plugin. The Mail plugin’s related bundle key reads:

<key>relatedBundles</key>
<array>
    <string>com.apple.Mail</string>
</array>

Required Bundles

requiresBundle is optional and if set, doesn’t allow the plugin to be used unless the specified package is currently also installed. A human-readable version of this value will automatically be shown under the heading “prerequisites” in the plugin info panel. The key is in the form com.developer.app and may look something like

<key>requiresBundle</key>
<array>
    <string>com.flyingmeat.VoodooPad</string>
</array>

webIcon

webIcon is again optional, and may be set to the URL of an image. For example, the Cyberduck module sets the webIcon to a png using the following code:

<key>webIcon</key>
    <string>http://quicksilver.blacktree.com/public/ytrewq1/Cyberduck.png</string>

Info File

If you’d like a readme file associated with your plugin, you can create a simple text or rich text file (.txt or .rtf) and import it into your Xcode project. Then it’s a simple matter of specifying this as file as the infoFile. An example:

<key>infoFile</key>
<string>Info.rtf</string>

Currently, I don’t think the infoFile is actually accessible through Quicksilver’s interface, but it seems likely that the “?” button in the plugin info panel would be used to display it in future versions.

Overwhelmed? Don’t be. There’s really no need to specify all of the above keys in the QSPlugIns section of the Info.plist. Author, categories, and description are the basic necessities, and anything beyond that is a bonus.

So if you haven’t already done so, decide on what your Incredible Plugin™ is going to do, and fill out the QSPlugIn portion of the Info.plist. Then take a break and relax while you wait for the next section in this series!

Also in this series

Quicksilver Actions

A quick look at QSActions in the Info.plist, followed by our first look at the code needed to get a plugin up and running.

Quicksilver plugins in Objective-C

A guide to obtaining the required resources for Quicksilver plugin development in Xcode. Also runs through setting up Xcode to make creating plugins easier.

Quicksilver Interface Creation

A thorough guide on the techniques to create a working Quicksilver interface. Includes an Xcode project template to minimize the effort required.