How To Define Templates In YASnippet

Xah Lee, 2009-02-18, 2009-11-06, 2010-08-04

This page shows you how to define your own templates for emacs's YASnippet template system. If you don't know what's yasnippet, see a intro here: Emacs Templates with YASnippet.

This tutorial has been tested with YASnippet version “0.5.9” and “0.6.1c”.

Basics

Dir Structure By Emacs's Modes

In your yasnippet dir, you'll find a path like this:

~/.emacs.d/plugins/yasnippet/yasnippet-0.6.1c/snippets/text-mode/

All template definitions are inside this dir or subdir.

In the text-mode dir, there are subdirs like: cc-mode, perl-mode, python-mode, html-mode, css-mode, etc. Each dir contains templates that will be active when you are in that mode.

One Template Definition Per File

Each template definition is a file. For example, suppose you have a template definition for “while” keyword for the Perl language. Then, there should be a file at this path: “text-mode/perl-mode/while”.

Each file may end with the suffix “.yasnippet”.

THE FILE'S NAME DEFINES THE ABBREV FOR THE TEMPLATE. For example, if you have a file “html-mode/h1”, then, typing “h1” then Tab, will expand according to that template file's definition.

Technically, each file's name, up to the first period, defines the abbrev. For example: you might have these files named:

doctype.xhml1
doctype.xhtml1_1
doctype.xhtml1_strict
doctype.xhtml1_transitional

When user types “doctype” then press Tab, a multiple choice menu will be shown.

File names starting with a period are not template definition but provide infomation purposes. For example: “.readme”.

Template Syntax

Each template file has this line: # -- (there MUST be a space). Everything above that line is either comment or directive (don't worry about directives for now). Below the line is the actual template definition.

Here's a example of the template “html-mode/doctype”.

#name : Doctype HTML 4.01 Strict
# --
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

When user types “doctype” then Tab, it'll expand to:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

The line “#name : ” is for a short title for the template. This title is used in menus. For example, look at the the menu “YASnippet”. When there are multiple templates for the same abbrev, yasnippet will popup a multiple-choice menu, and each template's title is also shown in the menu.

Special Characters

In the template definition, some chars have special meaning:

“$0” is the position the cursor after the snippte is inserted. You don't need to put a “$0” if you don't need to.
“$n” is a field, where the “n” is a integer starting with 1. (Example: “$1”, “$2”, ...). Pressing tab will move cursor to these stops for user to fill in. Multiple occurance of the same “$n” means typing in one field will automatically fill the other.
“${n:‹default text›}” is same as “$n”, but provides a default text.
“$&” means indent the line according to the mode's indentation rule.
“`” (backtick) is used to enclose a elisp code. The lisp code will be evaluated in the same buffer the snippet is being expanded.

Sample Snippet Files

Examples of defining html tags with field stop points:

<h1>$1</h1>

<img src="$1" class="$2" alt="$3">

You can also include lisp code in your template. For example, you might want to have a date stamp. Here's a example that insert user's email address and datestamp.

`user-mail-address`

`(current-time-string)`

Loading Your Template

Once you create a template file, you have to load it. Pull the menu “menu-bar‣yasnippet‣yas/Reload everything”, or type 【Alt+x yas/reload-all】.

Then, your new template definition will show up in the menu. You can also type the abbrev word followed by Tab to insert the new template. (Note: you must be in the emacs major mode that template is defined for)

Was this page useful? If so, please do donate $3, thank you donors!

Home

About

Advertise

2009-02