Espresso

Plug-In Structure

Basics

A plug-in is a normal folder with an .espressoplugin extension. Inside that folder, you will create specifically named folders and XML files depending on what you want your plug-in to do.

Where to install plug-ins

Plug-ins live here:

~/Library/Application Support/Espresso/Plug-Ins

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

chflags nohidden ~/Library/

If the Plug-Ins folder does not exist, create it. Inside create a folder named whatever you want your plug-in to be called; for instance MyPlugIn.espressoplugin.

To open your new plug-in, 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 plug-in files and folders; we will refer to it as the root plug-in folder.

Required files

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

  1. Create your plug-in folder as per above
  2. Inside your root plug-in 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 plug-in-->
	<key>CFBundleName</key>
	<string>MyPlugIn</string>
	<key>CFBundleIdentifier</key>
	<string>com.mydomain.espressoplugin.MyPlugIn</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 plug-in template

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

Full plug-in structure

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

Languages.xml, Syntaxes, SyntaxInjections, Itemizers, PlaceholderThemes, and ContextualSettings are all used for language plug-ins.

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

Scripts, ScriptLibraries, and TextActions are used for JavaScript actions.

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

Localizable.strings files make it easy to translate your plug-in's user-facing strings into multiple languages.

Development tips

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

cd ~/Library/Application\ Support/Espresso/Plug-Ins
ln -s MyPlugIn-espressoplugin MyPlugIn.espressoplugin

This also makes it easier to create an Espresso project for your plug-in folder (or store your plug-in source outside of the Application Support folder entirely).

Although we try to keep this documentation up to date 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 plug-in, choose Show Package Contents, and take a look at what's inside. You can find the plug-ins bundled with Espresso by right clicking on the application, choosing Show Package Contents, and navigating to Contents/SharedSupport/Plug-Ins (make sure not to save anything in there, though, or it will be lost when you update Espresso!).