AppleScript Commands: The Road to Extensibility

Starting with version 1.1.0 ^(*), iPliz allows you to create your own commands in AppleScript. Once created, these commands can be executed by email just like any other iPliz command. Using AppleScript commands you can:

Remote control programs on your desktop e.g. start, stop or monitor torrent downloads
Launch Automator scripts
Control smart home appliances (requires additional software and hardware)
And really, whatever you can think about!

Creating an AppleScript Command

Each AppleScript command is contained in a Mac OS X bundle. This is in fact a directory with a specific structure (all iPliz plugins are bundles, too). The bundle directory contains one subdirectory, called Contents, which contains all of the bundle's, well, contents.

All iPliz plugins, including AppleScript commands, reside in a folder named Pliz/Plugins under the user or system's library folder. Typically, you'll find plugins in /Library/Pliz/Plugins on your HD.

Under the Contents directory there is a Property List file, called Info.plist. This file contains information about the bundle. In the case of AppleScript commands, the file contains at least the following keys:

Key Description

CFBundleIdentifier A unique identifier for the bundle. For example, com.zigsterz.asjob.isight.

CFBundleInfoDictionaryVersion 6.0

CFBundlePackageType BNDL

PlizCommandName Name of iPliz command. This is the name that should be specified in the subject line for iPliz to run the command.

PlizCommandScript Name of script file within the bundle (see below) implementing the command.

Several additional keys may appear in the property list of the bundle, but these will be discussed later. We recommend that you start with the Screenshot.bundle AppleScript command bundle provided with iPliz and base your AppleScript iPliz commands on this bundle.

Key	Description
CFBundleIdentifier	A unique identifier for the bundle. For example, `com.zigsterz.asjob.isight`.
CFBundleInfoDictionaryVersion	6.0
CFBundlePackageType	BNDL
PlizCommandName	Name of iPliz command. This is the name that should be specified in the subject line for iPliz to run the command.
PlizCommandScript	Name of script file within the bundle (see below) implementing the command.

The PlizCommandScript entry in the command bundle property list file is the name of an AppleScript file that contains the script for the command. iPliz will look for a file of this name, with the extension .applescript added to it, under the Contents/Resources folder of the command bundle. For example, in the Screenshot.bundle AppleScript command, the PlizCommandScript entry in Info.plist is screenshot, which refers to the file Screenshot.bundle/Contents/Resources/screenshot.applescript.

The AppleScript script file implementing the command should look like the following template:


on executeJob(aCommandLine, aResponse)

   -- Code for command execution comes here

end executeJob

When the command is executed, executeJob will be invoked with the command line in aCommandLine and a response object in aResponse. The response object is used to relay the command result back to the user, using the following AppleScript snippets:


            set html body of aResponse to "..."

	    set title of aResponse to "..."

	    add attachment to aResponse from path "..."

Including AppleScript Commands in iPliz Help

Commands you create in AppleScript can appear in the output for the iPliz help command by including a dictionary with the following keys under the PlizCommandHelp Info.plist key:

Key Description

name Name of command

description A description of the command in the help response.

example A short example for invocation of the command.

For example, this is a fragment of the Info.plist file to include help info for the screenshot AppleScript command:

Key	Description
name	Name of command
description	A description of the command in the help response.
example	A short example for invocation of the command.


	<key>PlizCommandHelp</key>

	<dict>

		<key>name</key>

		<string>screenshot</string>

		<key>description</key>

		<string>Takes a screenshot and sends it</string>

		<key>example</key>

		<string>screenshot</string>

	</dict>

Adding Configurable Preferences to AppleScript Commands

You can configurable preferences to AppleScript commands which would be configurable through the iPliz preference pane, just like for any other command. To add preferences for a command, include an array of preference names in the Info.plist for the command bundle, under key ScriptPreferences. You can also specify default values for the parameters by including a dictionary named ScriptPreferencesDefaults.

To access preference values in the command script, use the following syntax:


on executeJob(aCommandLine, aResponse)

... 

value of preference "..." 

... 

end executeJob

Examples

An example AppleScript command is installed with iPliz, in /Library/Pliz/Plugins/Screenshot.bundle. You can find some AppleScript command examples in the plugins page.

^(*) This feature is only available on Mac OS X version 10.6.0 or higher.