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
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.
// 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;
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 ActionXML.
Working with Xcode
To create a Cocoa Sugar for Espresso:
- Download the Espresso Sugar template for Xcode 4
- Unzip the Xcode template, and move the resulting .xctemplate folder to
- In Xcode 4, create a new project and choose the Espresso Sugar template under the Templates group
- Modify the Sugar’s name, add your reverse domain path, and customize the path to Espresso.app if necessary
Your new Sugar will be setup to properly compile for Espresso 2.0. Any files you add to the “XML Based” directory will be automatically copied into the root of the Sugar 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 Sugar 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 Sugar to
~/Library/Application Support/Espresso/Sugars/ before it will show up in Espresso.