An introduction to Live Templates
Let's start off with a simple example. Our source code contains an array of fruits. If we want to print each fruit to standard output in a foreach loop, we can just type the first few characters of the word foreach.
Once we press TAB, a foreach loop is generated. We can type the name of the array we want to loop and press TAB again to set the variable name we want to use. These "placeholders" which we tab into are clearly visible in the editor.
After filling out the last placeholder (our variable name) and pressing TAB again, we can start writing the body of our loop.
Using this technique, we did not have to write out the entire loop. Instead, we could just use a Live Template (fore in this case) and tab through some placeholders (or "parameters") and start working on what matters: the body of the loop.
Usually in our code we have a lot of pattern structures (if, else), loops (for, while, foreach), tag structures (HTML tables, ul listings) and others. They are just mechanics of the language and not the most important things we should think about while coding. We want to code fast, and a foreach is just a foreach which we can generate and be done with it. And that's what Live Templates do!
There are a few different types of Live Templates:
- Simple Live Templates - these just expand into some code or text. Press Ctrl+J (CMD-J on Mac OS X) to view a list of templates that can be used in the editor.
- Parameterized Live Templates - these expand into some code or text where we can cycle through some parameters that are required for the generated portion of code to work. The foreach loop we generated above is a good example of this. Press Ctrl+J (CMD-J on Mac OS X) to view a list of templates that can be used in the editor.
- Surround Templates - these templates can "surround" existing code. Try selecting a bit of code, press Ctrl+Alt+J (Alt-CMD-J on Mac OS X) and pick one of the surround templates to see what happens. Note that pressing Ctrl+Alt+T (Alt-CMD-T on Mac OS X) brings up some of PhpStorm's default surround templates.
Available Live Templates
We can see all available Live Templates by opening IDE Settings | Live Templates. The list shown contains all Live Templates (and Surround Templates) available in the various supported languages. We can see the source code and settings for the fore template we just used.
Every Live Template has several settings:
- Is it enabled? We can disable specific templates by unchecking the box in front of it.
- What is the abbreviation? Since we want to be able to quickly expand these templates, abbreviations should be short but we also want to be able to remember them. If superawesomeforeachloop works better than fore, we can change the abbreviation.
- A description that will be shown in the completion information. Some templates have a piece of code as the description, others have a textual description.
- Template text, the actual template that will be expanded in the editor.
- The language to which a template applies.
- Variables that can be used in the template code.
- Formatting options.
A lot of choices there! But since Live Templates are intended to make us more productive, we should be able to mold them to our own preference, shouldn't we?
Creating Live Templates
Let's say we are developing Symfony2 applications. Some of the things that are quite repetitive to write after a while are Controller classes and the actions in them. Let's see if we can create two Live Templates for this.
The easiest one will be the one for generating a Controller class. Controllers typically get a name like BlogController, and extend Symfony2's Controller class. From IDE Settings | Live Templates, click the green + icon to create a new Live Template. Give it an abbreviation, for example "sc" (short for Symfony2 Controller) and a description. Next, specify the context in which the template applies, in this case PHP.
Our template text will be this:
Here's what it should look like:
Let's see if it works. After saving the template, we can open any PHP file (or create a new one) and use the "sc" Live Template.
Intriguing! Our template code is added and we can add text and TAB where we used the $Name$ variable in our template. After applying the template, our cursor will be placed where we used the $END$ variable.
Variables and Expressions
So far, we've used one variable of our own ($Name$) and one of the special variables provided by PhpStorm ($END$). By convention, Controllers in Symfony2 are named exactly like the file they are in. This means that the file MyController.php will contain the controller class MyController. Wouldn't it be great if we could let PhpStorm pre-populate the controller name based on the file name?
Let's change our "sb" template text:
We can now click the Edit variables and see that the IDE already recognized $Name$ as a variable. We could provide a default value for the $Name$ variable, as well as an expression. Let's use the fileNameWithoutExtension() expression, which will contain the name of our file without the ".php" part. We'll also check the Skip if defined checkbox so that when the expression provides a value, we don't have to provide it ourselves when we use the live template in the editor.
If we now use the Live Template, the class will be named like our file and our cursor will be placed in the class body immediately.
Creating Live Templates from within the Editor
The "sc" template we created earlier is pretty simple to write directly from the IDE Settings dialog. When a template is more complex, however, it's probably easier to create it in the editor and then make a template out of it.
Let's create a second template, for a basic Symfony2 action. In our editor, we can create one just as we would do writing an application.
Next, we can select the indexAction function and then use the Tools | Save as Live Template... menu to bring up the IDE Settings and configure our Live Template. Note that the context for this template will already be set, based on the type of file we were working with in the editor.
Now of course, if we wanted to add some variables in ur template, we would still have to do that in the template text. Let's change the template to the following:
Using Edit variables, we can specify the expression for the $Folder$ variable.
We can now use our "sa" template to generate a Symfony2 action.
Creating Surround Templates
There are situations where we want to be able to "surround" existing code with a template. As the name implies, Surround Templates are up for that task. They can be created in the exact same way as we create Live Templates, with one minor difference: usage of the $SELECTION$ variable.
As an example, let's create a Surround Template that wraps selected code in a try/catch block and logs the exception. Here's the template text:
We're using several variables here:
- $SELECTION$ will be replaced with the code we select in the editor.
- $TYPE$ will be a placeholder for the exception type.
- #VARIABLENAME$ will be a placeholder for our exception variable name.
- After expanding the template, our cursor will be placed at $END$.
In the Edit variables dialog, let's provide $TYPE$ with the _ complete()_ expression so that when we expand the template, completion is triggered. We'll also provide default values for all variables.
We can now use our surround template: select some code, press Ctrl+Alt+J (Alt-CMD-J on Mac OS X) and select the newly created template.
Our code is wrapped in the template we just created, completion is triggered on the exception type, and the exception variable is named $exception by default. We can pick the correct type and press TAB to end up in the catch body, right underneath the logging statement.