Action XML Definitions

Just like a regular TEA or Espresso action, Spice actions require at minimum two files:

1. the action definition in XML
2. the actual script you want to run

If you are creating a custom user action with Spice, you’ll first need to enable TEA for Espresso’s custom user action functionality in the TEA Preferences. Once custom user actions are enabled, your action definition files will live here:

~/Library/Application Support/Espresso/Support/TextActions/

Sugars utilizing Spice simply need to store their action definitions in the standard TextActions folder: MySugar.sugar/TextActions/.

Spice XML action syntax

If you were to use every available element in an action XML definition for Spice, it would look something like this (assuming the file only held one action; for multiple actions in one file you would of course have multiple <action> elements inside your <action-recipes> element):

<action-recipes>
    <action id="com.mydomain.example" category="category.id">
        <class>Spice</class>
        <title>Example Action</title>
        <text-trigger>example</text-trigger>
        <key-equivalent>cmd opt shift E</key-equivalent>

        <setup>
            <script>example_script</script>
            <undo_name>My Example</undo_name>
            <syntax-context>html *, css *, js *</syntax-context>

            <arguments>
                <array>
                    <string>My first argument</string>
                    <true/>
                </array>
            </arguments>

            <function>custom_function_name</function>
            <no-frills>1</no-frills>
        </setup>
    </action>
</action-recipes>

Standard Espresso elements and attributes

<action> Attributes

id

The unique identifier for this action; convention is to use reverse domain name formatting (com.yourdomain.typeofaction.uniqueIdentifier).

category

The category ID that defines where in the Actions menu your action is placed. You can add a slash and another category ID to nest the action, as well. For instance, category="actions.text.HTML/actions.snippets" would place the action in Actions → HTML → Snippets (assuming you have the HTMLBundle.sugar installed, which defines the actions.snippets category). You can also use category="hidden" to hide your action from the Actions menu. See the Espresso action documentation for more info about defining categories, sorting, and more.

Standard elements

class

This defines what Objective-C class your action should call; it will always be Spice.

title

The title is what will be shown in the Actions menu.

text-trigger

If you set a text-trigger for your action, then when that text is typed in Espresso your action will be triggered. In the example above, typing example and hitting tab would cause the action to be executed. You may also use the optional key-equivalent attribute to set which key triggers the action. For instance, if you used <text-trigger key-equivalent=".">example</text-trigger> then the action would be triggered when you typed example. (hitting tab would not longer be necessary).

key-equivalent

Not to be confused with the text-trigger attribute of the same name, this element allows you to set a shortcut for accessing your action. In the example above, the action would be triggered by holding down command-option-shift-E (shift is optional because the letter “E” is capitalized; however, I’ve found that it’s typically best to explicitly include shift). Available modifiers include: cmd (or command), control, shift, and opt (or option). You can also use keys such as enter or tab instead of a character.

Spice-specific elements

All Spice-specific fields must be nested within the setup element.

Common elements

script (required)

The name of the script file you want to execute for this action; the .js extension is optional (in the above example Spice would be looking for Support/Scripts/example_script.js).

undo_name

This is a common element shared with TEA; if your script uses text recipes then including an undo name is a good idea.

syntax-context

Another common element shared with TEA; define in which contexts your action will be active/possible using Espresso’s selector syntax.

arguments

Formatted as a plist array, nested elements will be passed as parameters to your main action function. In the above example, the function would receive two parameters, the first of which is a string and the second a boolean.

Uncommon elements

function

By default Spice will look for a main() or act() function. If you wish to use a custom name instead, define it here.

no-frills

Acceptable values are 0 or 1 (defaults to 0/off); when you turn on no-frills mode, none of Spice’s utility classes or functions will be loaded; only your Javascript. You will likely never use this unless you want to prototype an action using the Espresso API alone.

← Getting Started • Table of Contents • Javascript Actions →