CodeRush Templates option page
The Templates option page is required to control your collection of built-in and custom CodeRush code templates. When you open the Templates option page, CodeRush will locate the last template you used by default. This is an excellent way to explore and learn how templates are built. When a template expands, if you want to see how it is built, just bring up the Template options page and the last template expanded will be displayed. Here is what it looks like:
Templates are stored in folders (categories). Each category has a configurable name and a comment. You can also specify the Action Hint caption and its color for each particular template category. Click the Test button to see what it will look like:
The Templates list shows a plain list of templates included into the selected folder and sub-folders.
Near the category name you can find a checkbox which enables or disables the entire folder with templates. To rename a category or template, double-click it in the main tree. A folder may contain nested folders for better template organization.
On the top of the option page there is a Search text box which allows you to find templates by name (abbreviation) or by its content (expansion). Click one of the two buttons near the text box to search in the preferred way:
Under the Search text box there are tool buttons to create a new nested folder, to create a new code template, or delete a folder or template. Plus, there are two navigation button for navigating by the history of visited templates and folders backwards and forwards. All buttons have tooltips to learn more about their purpose:
Clicking the New Category button will show you a dialog where you can type the name of the new nested category that will be added inside the selected category:
If you’d like to create a non-nested Category in the root, use the context menu for this task. A context menu on a folder looks like this:
Clicking the New Root Category shows a similar dialog as a New Category:
The other context menu items are:
|New Template…||Shows a New Template dialog allowing you to create a new template with the desired name.|
|New Root Category…||Shows a New Root Category dialog allowing you to create a new template with the desired name.|
|New Category…||Shows a New Category dialog allowing you to create a nested category for the currently selected folder.|
|Enabled||Toggles the Enabled state for the selected folder.|
|Move to Root||Makes the selected nested folder the root folder.|
|Export Folder…||Allows you to export the selected folder.|
|Import Templates…||Allows you to import previously exported templates.|
|Delete||Removes the selected category.|
|Paste Context||Sets the previously copied Context to all templates inside the selected folder.|
|Collapse all nodes||Collapses all folder nodes.|
Of course, code templates are stored inside the folders. A template has a configurable name, a comment, an expansion, a context, and numerous options. Often, templates have alternate expansions (different versions of the template bound to the same character sequence). Alternate expansions are indicated by a special icon in the list and are differentiated by their context which appears in the tree view:
If you see alternate expansions, look at the contexts to see which one of those expansions will be expanded. Alternate expansion contexts are evaluated in the order you see them in the list, and often a list of alternate expansions will end with a template that has no context defined. That means that it will expand if none of the previous alternate expansion contexts were satisfied.
Here is what the templates configuration page looks like when a particular template is selected:
On the top of the template configuration page, there is a Case-sensitive option which specifies whether or not the name of the template is case-sensitive. A comment is used to identify and describe the template. For instance, the What Happened window uses this comment when a template is expanded:
The Expansion text edit contains the primary template content. The result of a template is composed in this text area by adding the usual text, text commands and/or string providers. It also has several tool buttons to navigate between alternate expansions of a template, to add or remove alternate expansions, or to set their priority by moving an alternate expansion up or down:
The Expansion is the most important part of a template. The result of a template is composed in this text area by adding the usual text, text commands and/or string providers.
The next set of tool buttons provides a quick way to insert most important text commands. Other commands are listed in the Command combobox:
If you see an orange text inside a template expansion, this indicates a call to another template (known as a template alias). You can right-click the template editor to display a menu to jump to any template aliases referenced inside the active template:
An expansion context menu also contain the following menu items:
|Insert Alias…||Shows the Select Template dialog which allows you to choose a template that will be used as an alias.|
|Extract Template…||Allows you to select a part of the template expansion and extract it as a new template. This option will show you a small dialog where it is required to enter a new name for the template.|
|Undo||Performs a simple undo operation which reverts back the last changes to the template expansion.|
|Jump to XXX alias||Navigates to the alias in question.|
|Insert TextCommand…||Shows the Select TextCommand dialog where all text commands are listed and can be filtered.|
|Insert StringProvider…||Shows the Select StringProvider dialog where all string providers are listed and can be filtered.|
|Cut||Cuts the selected text from the template expansion text edit.|
|Copy||Copies the selected text from the template expansion text edit.|
|Paste||Inserts the text from the Clipboard into the template expansion text edit.|
|Delete||Removes the selected text from the template expansion text edit.|
|Select All||Selects the entire context of the template expansion text edit.|
Under the template Expansion text edit, you can specify the advanced options for a template:
[ ] Auto double equals (“==”)
Specifies whether or not to insert an additional equals ‘=’ character. This might be useful for languages like CSharp where the double equals operation is used to compare values.
[ ] Auto line terminator
Specifies whether or not to append a line terminator (a semicolon in C#, C++) to the resulting expansion.
[ ] Suppress formatting
Specifies whether or not to disable the automatic code formatting for this template, so it will be expanded “as is”.
[ ] Suppress the last character if present in code
Specifies whether or not to suppress the last character if the same character exists in code.
[ ] Multi-file template
Specifies whether or not a template will be expanded into multiple files, so a special multi-file undo will be created in order to undo those multi-file expansions.
Another important part of a template is a context. A context specifies the conditions when a particular template is available and can be expanded.
Additional options include:
- A template trigger key indicating whether it is a primary key, a secondary key or either.
- Dependent Namespaces. The list of namespace references (e.g., System.Windows.Forms) which is required for the types from the template expansion. Namespace references will automatically be added to the corresponding usings/Imports section of the file where a template has been expanded.
When you add new templates or alternate expansions, or organize your custom templates, you can use the templates context menu and find a few useful options there:
Some of the menu items are the same as the menu items inside the Category context menu, but there are also additional items specific to templates:
|Create alias…||Creates a new alias for the selected template. Shows a dialog where an alias name should be specified.|
|Create duplicate…||Creates a copy of the selected template with the specified name.|
|Move to ->||Moves the selected template to a different folder chosen from the popup menu.|
|Copy Context||Copies the context of the selected template for further insertion in another template or a category.|
The templates and categories are stored inside their own XML files with a specific file-format. These files are separated by languages, e.g.: