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.)
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.
To create a Cocoa Sugar for Espresso:
- Download the Espresso plug-in 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 plug-in template under the Templates group
- 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.