Snippet XML

Snippets provide shortcuts for frequently used pieces of code. This documentation describes how to bundle snippets inside Sugars. If you wish to define personal snippets through the GUI, choose Actions ⟩ Show Snippets in the app.

Regardless of how you create your snippets, remember that they are not plain text! You must use snippet syntax.

XML syntax

Snippets are defined in an XML file in the TextActions subdirectory of your plug-in. They can be placed in the same file as your other text actions, or in their own file. The name of the file doesn't matter, as long as it has an .xml extension and doesn't end with "Categories" or "Sorting". By convention, the file typically ends with Snippets (Snippets.xml, PHPSnippets.xml, etc.) but this is not required.

The syntax is very similar to other action definitions. For instance, here is a Javascript "for loop" snippet:

<?xml version="1.0" encoding="UTF-8"?>
<action-recipes>

		<snippet id="com.example.snippets.for" category="tools.Snippets">
			<title>for loop</title>
			<text><![CDATA[for (var ${1:i} = 0; $1 < ${2:myArray.length}; $1++) {
	$0
}]]></text>
			<syntax-context>js, js *</syntax-context>
			<text-trigger>for</text-trigger>
			<key-equivalent>control option shift f</key-equivalent>
		</snippet>

</action-recipes>

The <title> element is optional and defines the name shown in the Actions menu or Snippet GUI. Note that we recommend using Localizable.strings instead.

The <text> element defines the contents of the snippet (using snippet syntax). As per the example, note that you need to wrap your snippet in a CDATA block if you use special characters such as < or &.

The <syntax-context> element is a selector that defines in what syntax zones the snippet will be available.

The <text-trigger> element is optional and defines a tab-trigger. Adding a key-equivalent attribute allows a custom trigger key to be set instead of using tab. For instance this would cause the snippet to be inserted when the user typed for{ instead of for + tab:

<text-trigger key-equivalent="{">for</text-trigger>

The <key-equivalent> element is optional and defines a keyboard shortcut for the snippet composed of any number of modifiers (command, control, option, and/or shift) and a character ("tab", "enter", "space", "arrow-up", etc. may also be used for some special keys). If you are using a letter key, make sure to keep it lowercase unless you want to require the shift modifier!

Special snippet categories

If you use the special category "tools.Snippets" your snippet will be included in the Snippets GUI. Otherwise, the category will define where in the Actions menu your snippet will live.

If you want your snippet to be entirely hidden, you can use the special category "hidden". We do not recommend this, unless your snippet is something that is commonly typed (for instance, the HTML "close tag" snippet that completes when you type "</" is hidden because users will find it through normal coding).