MacRabbit

SugarStructure

A Sugar is a normal folder with a .sugar extension. Inside that folder, you will create specifically named folders and XML files depending on what you want your Sugar to do.

Where to install Sugars

Sugars live here:

~/Library/Application Support/Espresso/Sugars 

To access your Library folder in Lion, hold down option while you click the Go menu in the Finder, and then click the Library item. Alternatively, run this in Terminal to permanently unhide your Library folder:

chflags nohidden ~/Library

If the Sugars folder does not exist, create it. Inside create a folder named whatever you want your sugar to be called; for instance MySugar.sugar.

To open your new Sugar, right click on it and choose Show Package Contents. A new window will open in the Finder. This is where you will need to create your Sugar files and folders; we will refer to it as the root Sugar folder throughout this wiki.

Required files

The Info.plist file is the only required file for a Sugar, and should live inside of a Contents folder. To get started with a new Sugar:

  1. Create your Sugar folder as per above
  2. Inside your root Sugar folder, create a folder called Contents
  3. Inside the Contents folder, create a plain text file called Info.plist

Info.plist is a standard Mac OS X file. You can create it with a plist editor, or just edit it in Espresso. Here are example contents:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<
plist version="1.0">
<
dict>
    <!--
Modify these for your Sugar-->
    <
key>CFBundleName</key>
    <
string>MySugar.sugar</string>
    <
key>CFBundleIdentifier</key>
    <
string>com.mydomain.sugar.MySugar</string>
    <
key>CFBundleVersion</key>
    <
string>1.0</string>
    <!--
No need to modify these values-->
    <
key>CFBundleInfoDictionaryVersion</key>
    <
string>6.0</string>
    <
key>CFBundlePackageType</key>
    <
string>BNDL</string>
    <
key>CFBundleSignature</key>
    <
string>????</string>
</
dict>
</
plist

Download basic Sugar template

You now have a fully-functioning Sugar (albeit one that adds nothing to Espresso)! If you relaunch Espresso, your Sugar will be silently loaded. In order to add functionality, you now simply need to add XML files for LanguageSugars, CodeSense, JavaScriptActions, or similar.

Full Sugar structure

The folders and files inside of a Sugar use the following names and structure. Directories are suffixed with a / character, * is a wildcard for filenames, and bold items are required for all Sugars:

  • MySugar.sugar/
    • CodeSenseLibraries/
      • *.xml
    • CodeSenseProviders/
      • *.xml
    • Contents/
      • Info.plist
      • Resources/
        • *.lproj/
          • Localizable.strings
    • ContextualSettings/
      • *.xml
    • FileActions/
      • *.xml
      • *Categories.xml
      • *Sorting.xml
    • Itemizers/
      • *.xml
    • Languages.xml
    • PlaceholderThemes/
      • *.css
    • ScriptLibraries/
      • *.js
    • Scripts/
      • *.js
    • Syntaxes/
      • *.xml
    • SyntaxInjections/
      • *.xml
    • TextActions/
      • *.xml
      • *Categories.xml
      • *Sorting.xml

Languages.xml, Syntaxes, SyntaxInjections, Itemizers, PlaceholderThemes, and ContextualSettings are all used for LanguageSugars.

CodeSenseLibraries and CodeSenseProviders are used to define new CodeSense auto-completions.

Scripts, ScriptLibraries, and TextActions are used for JavaScriptActions.

TextActions and FileActions can both be used to create custom actions with the CocoaAPI.

Localizable.strings files make it easy to translate your Sugar’s user-facing strings into multiple languages.

Development tips

An easy way to work on Sugars without needing to be constantly right clicking them in the Finder is to name your Sugar folder without a .sugar extension, and then create a symlink to it in your Sugars folder. For instance, if you have created a sugar folder called MySugar-sugar in your Sugars folder, you could run this in Terminal to make sure Espresso recognizes it:

cd ~/Library/Application\ Support/Espresso/Sugars
ln 
-s MySugar-sugar MySugar.sugar 

This also makes it easier to create an Espresso project for your Sugar folder.

Although we try to keep this wiki up to date with documentation for all portions of the Espresso API, often the best way to figure out how to do things is to right click on an existing Sugar, choose Show Package Contents, and take a look at what’s inside. You can find the Sugars bundled with Espresso by right clicking on the application, choosing Show Package Contents, and navigating to Contents/SharedSupport/Sugars (make sure not to save anything in there, though, or it will be lost when you update Espresso!).