Vim Plugins, surround.vimThis is the seventh post in the article series "Vim Plugins You Should Know About". This time I am going to introduce you to a plugin called "ragtag.vim". A month ago it was still known as "allml.vim" but now it has been renamed to ragtag.vim.

The best parts of RagTag are mappings for editing HTML tags. It has a mapping for quickly closing open HTML tags, a mapping for quickly turning the typed word into a pair of open/close HTML tags, several mappings for inserting HTML doctype, linking to CSS stylesheets, loading JavaScript <script src="...">...</script> and it includes mappings for wrapping the typed text in a pair of <?php ... ?> tags for PHP, or <% ... %> for ASP or eRuby, and {% .. %} for Django.

RagTag is written by Tim Pope. He's the master of Vim plugin programming. I have already written about two of his plugins - surround.vim and repeat.vim and more articles about his plugins are coming!

Previous articles in the series.

Here are examples of using the RagTag plugin.

Quickly closing an open HTML tag.

Suppose you have typed <div> and you want to close it without typing the whole closing tag </div> yourself.

The quick way to do it with RagTag is to press CTRL+X /. This mapping automatically closes the last open HTML tag.

Extra tip: If you didn't have this plugin you could quickly close the tag by typing </ and pressing CTRL+X CTRL+O. The default Vim mapping CTRL+X CTRL+O guesses the item that may come after the cursor. In case of an open HTML tag it's the close tag.

Creating a pair of open/close HTML tags from a word.

Suppose you want to quickly create a pair of <div></div> and place the cursor between the two tags.

The quick way to do it with RagTag is to type div and press CTRL+X SPACE. This mapping takes the typed word and creates a pair of HTML tags, one closing tag and one open tag on the same line.

However, if you want to create open/close tag pair separated by a newline, type CTRL+X ENTER.

Here is an example, if you just typed div and then press CTRL+X ENTER it will produce the following output:


| indicates the position of cursor.

Insert HTML doctype.

If you type CTRL+X ! RagTag will display a list of HTML doctypes to choose from. Defaults to HTML 4.01 Strict.

This mapping is not that useful, given that I already introduced snipmate.vim plugin for creating snippets. Using snipmate.vim you can create a snippet "h" that would insert the whole HTML structure, including doctype, html, body, title, meta tags, etc.

Link to a CSS stylesheet.

Typing CTRL+X @ inserts the snippet for linking to a CSS stylesheet.

&lt;link rel=&quot;stylesheet&quot; type=&quot;text/css&quot; href=&quot;/stylesheets/<strong>|</strong>.css&quot;>

This is again not that useful, given that we have snipmate.vim.

The mapping is easy to remember because code>@</code is used for importing in CSS.

Insert meta content-type tag.

Typing CTRL+X # inserts the HTML meta tag for document's content type and encoding.

&lt;meta http-equiv=&quot;Content-Type&quot; content=&quot;text/html; charset=ISO-8859-1&quot;>

The charset depends on document's charset. If it's utf-8, the mapping will set the charset to utf-8 in the meta tag.

Load JavaScript document.

Typing CTRL+X $ links to a JavaScript file.

&lt;script type=&quot;text/javascript&quot; src=&quot;/javascripts/<strong>|</strong>.js&quot;></script>

The mapping is easy to remember because $ is a valid char in identifiers in many languages.

Wrap the typed text in PHP, Django, eRuby template tags.

There are several different mappings for wrapping text in template tags. It's best to summarize them in the following table. The table assumes you had just typed "foo" and you are editing an eRuby document:

Mapping    Result
---------  -----------
CTRL+X =   foo&lt;%= <strong>|</strong> %>
CTRL+X +   &lt;%= foo<strong>|</strong> %>
CTRL+X -   foo&lt;% <strong>|</strong> %>
CTRL+X _   &lt;% foo<strong>|</strong> %>
CTRL+X '   foo&lt;%# <strong>|</strong> %>
CTRL+X &quot;   &lt;%# foo<strong>|</strong> %>

What this table shows us is, for example, that if you have typed "foo" and press CTRL+X _, the plugin will wrap "foo" in <% %> tags and place the cursor after "foo".

Summary of all the RagTag mappings.

CTRL+X /       Close the last open HTML tag
CTRL+X SPACE   Create open/close HTML tags from the typed word
CTRL+X CR      The same as CTRL+X SPACE but puts a newspace in between
CTRL+X !       Insert HTML doctype
CTRL+X @       Insert CSS stylesheet
CTRL+X #       Insert meta content-type meta tag
CTRL+X $       Load JavaScript document

For the following mappings, suppose that
you have typed "foo".

Mapping        Result
---------      -----------
CTRL+X =       foo&lt;%= <strong>|</strong> %>
CTRL+X +       &lt;%= foo<strong>|</strong> %>
CTRL+X -       foo&lt;% <strong>|</strong> %>
CTRL+X _       &lt;% foo<strong>|</strong> %>
CTRL+X '       foo&lt;%# <strong>|</strong> %>
CTRL+X &quot;       &lt;%# foo<strong>|</strong> %>

How to install ragtag.vim?

To get the latest version:

  • 1. Download
  • 2. Extract to ~/.vim (on Unix/Linux) or ~\vimfiles (on Windows).
  • 3. Run :helptags ~/.vim/doc (on Unix/Linux) or :helptags ~\vimfiles\doc (on Windows) to rebuild the tags file (so that you can read help :help ragtag.)
  • 4. Restart Vim or source ragtag.vim by typing :so ~/.vim/plugin/ragtag.vim (on Unix/Linux) or :so ~\vimfiles\plugin\ragtag.vim

Have Fun!

Have fun closing those HTML tags and until next time!