Useful Sublime Text 3 Snippets

An example of the auto-completion dropdown in Sublime Text 3.
Sublime Text (3) Snippets!

I have been using the Sublime Text for a while now—it’s already up to version 3!—and have grown very fond of it. One of the many features that I have found extremely useful is the snippet system. Snippets allow you to store blocks of code that can be accessed with a keyword via the auto-completion pop-up when typing. I have a few snippets below that I tend to use over and over again. Perhaps you’ll find a use for them as well.

Using Snippets

In case you are unfamiliar with the snippet system, i’ll give you a little run down. With the right information, the snippet system becomes really easy to use. However, there is a definite pattern that has to be used to get these cool chunks of code to work.

This pattern is as follows:

<snippet>
	<content>
<![CDATA[
echo "<pre>";
var_dump(\$${1:var});
echo "</pre>";
]]>
	</content>
	<tabTrigger>predump</tabTrigger>
	<scope>source.php</scope>
	<description><pre>var_dump(...)</pre></description>
</snippet>

The snippets are in an XML format, starting with the snippet tag. That just indicates to Sublime that i’m describing a snippet for it to use.

The content tag allows us to customize the actual output of the snippet. That is, what you’ll see when you hit Tab or Enter to auto-complete the snippet. The snippet above outputs the following into the current file, at the position of my cursor:

echo "<pre>";
var_dump(\$${1:var});
echo "</pre>";

The tricky part of the content tag is the <![CDATA[...]]> block. This XML tag indicates to the Sublime XML parser that it should not parse any of the characters inside the block. This allows us to use characters like less-than and greater-than signs without having to type out their HTML entity codes (&lt; & &gt;, respectively). Funnily enough, that is exactly what i’ve been doing for this post! The CDATA block will capture new lines and other forms of whitespace, which is why the formatting looks weird. If I were to properly indent the CDATA block like this…

<snippet>
	<content>
                <![CDATA[
                        echo "<pre>";
                        var_dump(\$${1:var});
                        echo "</pre>";
                ]]>
	</content>

The output would not remain the same. Instead I would get the following dumped into my file.

                        echo "<pre>";
                        var_dump(\$${1:var});
                        echo "</pre>";
                

Yuck! Newlines, spaces, and all. This means that if my cursor is already indented a few tabs/spaces, the snippet output is going to be off in the middle of nowhere. Then i’ll have to waste time properly indenting the output. That is something to keep in mind.

predump-snippet-output-250x250
An example of bookmarking. Note how “var” is highlighted. This correlates with the “${1:var}” bookmark.

The other cool part of the content tag is the use of cursor bookmarks—as I believe they are called. Sublime snippet bookmarks are indicated by the ${1:...} syntax. In the above snippet there is only one bookmark, ${1:var}. The number 1 indicates that Sublime should target that bookmark first (if there are other bookmarks). The text, var, indicates the default text that will be displayed at the position of the bookmark. When I output the snippet and begin typing, the var text will be selected and overridden. Of course, you could add more bookmarks and even use the same number on multiple to replace multiple chunks of text at once. Cool stuff!

The tabTrigger tag allows you to customize the text that you’ll have to type to get your snippet to appear in the auto-completion pop-up. In this case mine is, “predump”. I recommend using a short and unique name. Definitely don’t name your snippet something extremely common like, “for”. Otherwise, you’ll end up searching through seven different version of “for” to find your snippet. The whole point is to save time and headaches.

The scope tag, to the best of my knowledge allows you to indicate in which context the snippet should appear. In this case i’ve chosen source.php to make my snippet available to me within PHP blocks. It doesn’t appear in the auto-completion pop-up if i’m outside of a PHP tag. I have other snippets that use source.js in the scope tag, for use in JavaScript files. Therefore, I believe that you can change the file extension of the source.extension text depending on your needs. If for some reason you need to use the snippet in multiple contexts, say in a JavaScript and a PHP file, the scope tag would look like (verbatim): <scope>source.php,source.js</scope>.

The description tag is where you can leave yourself a short message—be careful, it will be truncated—to explain what the snippet is for. This will appear along side the name you provided in the tabTrigger tag, in the auto-completion pop-up. If no description is provided, the name of the snippet will simply be used instead. Also, having just tested this, you can use a <![CDATA[...]]> block here as well.

Saving Snippets

browse-packages-250x250
SHIFT+CMD+P or SHIFT+CTRL+P (Windows) to open the Command Palette.

Now, where the heck do these snippets go? Well they should be placed in your User Packages folder. To find this folder hit SHIFT+CMD+P (SHIFT+CTRL+P on Windows) and type “Preferences: Browse Packages”, then hit Enter. this should bring your Finder window (or folder browser) to the Packages folder. On Mac OSX, it is located under /Users/yourUserName/Library/Application Support/Sublime Text 3/Packages/. On Windows 7, it is located under C:\Users\yourUserName\AppData\Roaming\Sublime Text 3\Packages\. You are going to want to copy and paste your .sublime-snippet files under the User sub-directory. That’s it. You can start using them immediately!

Here are a few of the snippets that I use most frequently in my WordPress and PHP based projects.

Pre-formatted Output

Simply typing predump and hitting the Tab key will dump a nice pre-formatted block onto any PHP page. This is very nice for quick debugging.

Function Call Stack Trace

I find that I use this far less frequently than other methods of debugging, so having the block of code stored as a snippet prevents having to google it each time. This is an excellent way to dissect how functions are being called.

WordPress DocBlock

Since I am doing a good amount of refactoring and documentation for Game On, i’ve found that having the proper documentation standards on top is a massive stress and time saver. In this snippet in particular, you can see how i’ve used bookmarking fairly extensively. This allows me to zip through entering the documentation by simply pressing the Tab key.

That’s it. They’re simple, but that’s why they’re so useful! I encourage you to use these and make your own. I’m sure there are at least few blocks of code that you use frequently that could find a home in a snippet. Happy coding!

More Reading

For more information on XML CDATA Sections, check out this tutorialspoint page.

Also checkout this page for more in-depth documentation on manipulating snippet contents.