The Storyist Plugin Architecture

The Storyist plugin architecture (available in version 1.4 and later) is based on the Automator Actions API as described in Apple’s Automator Programming Guide. This means that plugins (actions) written for Storyist can be used in Automator workflows and workflows created by Automator can be used by Storyist.

You can use the API to extend Storyist in two ways:

  1. by providing text processing plugins for use in the Tools menu and by the import and export assistants.
  2. by providing converter plugins for other file formats.

Both text processing and format converter plugins are based on the AMBundleAction class. The difference is that text processing plugins specify the Storyist styled text object UTIs (described below) as both input and ouput, while converter plugins specify the UTI for the file format as either input or output and the styled text object UTI for the other.

The Styled Text Object

Storyist identifies styled text objects by the UTI com.storyist.storyist.styled-text-object. Styled text objects are simple NSDictionary objects having the following keys:

  • NSTextStorage - a reference to an NSTextStorage object containing the styled text to operate on.
  • DocumentAttributes - a reference to an NSDictionary containing document attributes such as described here.
  • NSTextView - (optional) - an reference to the interface element (an NSTextView) that operates on the NSTextStorage. Storyist provides this value when possible to allow the action to implement undo.
  • RangeValue - (optional) - an NSValue containing the range of text on which to operate. If this key is not available, the operation operates on the entire NSTextStorage.

Limitations in Storyist 1.4

Storyist 1.4 has the following limitations with respect to Automator:

  • Automator workflows are available only during import and export. You can still access and run the individual actions from the Tools menu, however.
  • The import and export assistants can only run Automator workflows containing text processing actions, i.e. all actions in the workflow must take styled text objects (or arrays of styled text objects) as input and provide styled text objects (or arrays of styled text objects) as output.

Sample Code

<Coming Soon>