Cocoa API

Although you can do quite a lot in your plug-in using XML, CSS, and JavaScript, more complicated TextActions and FileActions will require writing Objective-C classes to leverage Espresso's Cocoa API.

Some common situations that require using the Cocoa API:

• FileActions; currently the support for FileActions in non-Cocoa Sugars is minimal or nonexistent
• Any action that provides custom GUI elements (such as windows, sheets, etc.)
• Actions that need to work directly with the file system or shell, or that need to make use of default Cocoa objects (NSUserDefaults, etc.)

API header files

Unlike the JavaScript API, Espresso Cocoa API methods are not documented here. Instead, you will need to download Espresso, right click the application, choose Show Package Contents, and open the files in Contents/Headers. These header files outline the complete Cocoa API (with documentation inline in comments).

However, if you have used the JavaScript API, you will be very familiar with the basics of the API already (particularly if you are writing a TextAction) as the two use the same basic classes, methods, and properties.

Basic action class

Cocoa actions can be written using only four methods (two of which are optional):

@interface NSObject (EspressoAction)

// Optional; called instead of -init if implemented.
// Dictionary contains the keys defined in the <setup> tag of action definitions. This is 
// how you can create generic item classes that behave differently depending on the 
// XML settings.
- (id)initWithDictionary:(NSDictionary *)dictionary bundlePath:(NSString *)bundlePath;

// Required: return whether or not the action can be performed on the context.
// It's recommended to keep this as lightweight as possible, since you're not the only 
// action in Espresso.
- (BOOL)canPerformActionWithContext:(id)context;

// Required: actually perform the action on the context.
// If an error occurs, pass an NSError via outError (warning: outError may be NULL!)
- (BOOL)performActionWithContext:(id)context error:(NSError **)outError;

// Optional; useful for changing titles depending on characteristics of the context.
// By default, actions will use the title from the <title> tag in their definition.
- (NSString *)titleWithContext:(id)actionContext;

@end

To enable a Cocoa action, all you need to do is create a class using at least the two methods outlined above, and then define the action in your Actions.xml.

Working with Xcode

To create a Cocoa Sugar for Espresso:

1. Download the Espresso plug-in template for Xcode 4
2. Unzip the Xcode template, and move the resulting .xctemplate folder to ~/Library/Developer/Xcode/Templates/
3. In Xcode 4, create a new project and choose the Espresso plug-in template under the Templates group
4. Modify the plug-in's name, add your reverse domain path, and customize the path to Espresso.app if necessary

Your new plug-in will be setup to properly compile for Espresso 3.0. Any files you add to the "XML Based" directory will be automatically copied into the root of the plug-in when you build it; you do not need to add those files to Xcode if you do not want to (the default XML Based group that is included with the plug-in is only added to Xcode to cause the folder to be properly copied from the template).

Remember that you will need to install your compiled plug-in to ~/Library/Application Support/Espresso/Plug-Ins/ before it will show up in Espresso.