Home » Support » Index of All Documentation » Wing IDE Reference Manual » Source Code Editor »
4.8. Templating (Code Snippets)
Wing Professional provides support for defining and using templates for commonly reused bits of code (sometimes called snippets) and other text. Templates might be used for standard file skeletons, comment formats, dividers, class definitions, function definitions, HTML tables, and much more. Variants of templates may be defined for different contexts, for example to include or omit self in a def depending on whether or not it is a method in a class.
Wing's templating functionality is implemented in the Templating tool panel and by providing the templates by name in the editor's auto-completer. Key bindings can be assigned to templates so that the templating tool does not have to be visible in order to use a template.
Although Wing comes with a few example templates, in most cases users will want to define their own, to match their coding conventions and preferences.
User Interface
The Templates tool panel provides the means for adding, editing, removing, and executing templates, and also assigning key bindings for pasting selected templates into the current editor. Most of the functionality is provided by the options menu in the top right and by right clicking on the template list. Note that some of the operations (those followed by ... in the menus) will prompt for input at the bottom of Wing IDE's window.
The option menu in the top right of the Templates tool (also accessible by right-clicking on the notebook tab area) provides items for adding, removing, and renaming file types into which to organize templates. The name of the file type is the file extension that Wing should use by default when creating a new file based on a template. It is also used to look up the mime type of the file, so that the template can be made available within any file of that type, regardless of its actual name.
To add, edit, renamed, copy, and remove templates, use the items in the context menu that appears when you right-click on the surface of the template list in the Templates tool. This menu also provides items for inserting the template into the current file or a new file.
Contexts
It is possible to specify the context within the file for which a template is appropriate. This allows, for example, the definition of a template def that varies to include or omit self depending on whether or not it is within a class. When available, this is done with items in the template list context menu. The template defined for context all will be used when no specific context match is made. The default set of templates that ship with Wing illustrate this feature with the def and class template variants.
The set of valid contexts depends on file type. For Python files the valid context names are module, class, method, function, comment, string. For HTML and XML, files are divided into content, code (within < and >), comment, and string. Other files only distinguish code, comment, and string. Additionally, the context all is used for all file types to indicate any context.
To set the context for a template, click on the context name in the template lists's Context column, or use the items in the right-click context menu on the template list.
Key Bindings
The template list context menu menu also allows assigning key bindings to templates, so they can be executed more easily. The key binding entry area is shown at the bottom of the IDE window, and Enter is pressed to accept the displayed binding. Note that bindings can be multi-key sequences such as Ctrl-Shift-H Ctrl-A. Pressing the keys in sufficiently rapid succession creates a sequence. Waiting a moment will start a new sequence when further keys are pressed. Clicking away from the entry area will abort the operation without assigning any key binding.
Note that key bindings are assigned to the template by name and not to a particular template file. If multiple like-named templates exists for different file types or contexts, the appropriate template is chosen when the key binding is used.
Execution and Data Entry
When templates are executed, Wing chooses the template by name and places the correct variant according to the file type and the context within the current editor. The caret position on the editor is used to determine the context, so altering the position of the caret within leading indentation may alter which template variant Wing selects.
When a template is used, Wing will place default arguments into the template, convert indentation and line endings to match the target file, paste it into the active editor, and place the editor into inline data entry mode to collect additional arguments for the template.
In data entry mode, Wing will move between the data entry fields in the template when Tab or BackTab are pressed. The position within the template's fields will be displayed in the status area at the bottom of the editor window.
In this mode, the right and left arrows can be used to increase or decrease the indentation of the whole template within the editor. However, the same template variant that was used initially will be used regardless of subsequent changes in indentation.
To exit data entry mode, press Esc (or Ctrl-G in emacs mode) or move the caret outside of the pasted template. To undo the template insertion, use Undo in the Edit menu or its key binding.
Auto-completion
Templates are also listed in the editor's auto-completer and may be activated from there. To disable this feature, turn off the auto-completer preference Include Templates in Completer.
Template Syntax
Templates are text files that contains markers where user-provided values should be inserted. These markers are similar to Python's %(varname)s string substitution syntax but instead of containing only a variable name, the body of the marker contains richer argument collection information in the following format, with vertical bars dividing each value:
%(varname|type|default)s
Type and default are optional but the vertical bars must be present if omitting type but including a default. To write a template that includes Python style string formats, escape each % by writing %% instead.
Each part is defined as follows:
varname -- The name of the variable. Since arguments are collected inline, this name is used internally only. Future extensions may display this name to the user, by replacing underscores with spaces and capitalizing words (for example "user_name" would be rendered "User Name").
Any number of the following special characters may be prefixed to the variable name to control how it is used:
Exclamation point (!) indicates that the value should be included in the field list during data collection even if a default value can be found for it. Otherwise, the default is simply placed into the template and tabbing among fields will skip it.
At sign (@) indicates that the value should be wrapped if it exceeds the configured text wrap line column.
type -- The type of data to collect. Currently this is one of:
string(length) -- a string with given maximum length (uses default 80 chars if length is omitted)
date -- current date in locale's preferred format or in the time.strftime() format given in the environment variable __DATE_FORMAT__
datetime -- current date+time in locale's preferred format or in the time.strftime() format given in the environment variable __DATETIME_FORMAT__
If this field is omitted or empty, string is assumed.
default -- The default value to use. This may be the actual value, or may contain environment variable references in the form $(envname) to attempt to read all or part of the value from the named environment variable.
Environment variables can be specified either in the Debug tab of Wing's Project Properties or in the environment that exists before Wing is launched. Values in the Project Properties override any values set before starting Wing.
When this field is omitted, or when no default environment value can be found, the field will be left blank .
Indentation and Line Endings
Templates should always use one tab for each level of indentation. Tabs will be replaced with the appropriate indentation type and size when the template is used in a new or existing file (either according to content of the target file or using the configured indent style and indent size for new files). Wing will force tab indentation in all newly created template files.
Similarly, line endings in templates will be replaced with the appropriate type to match the file to which the template is applied. However, there is no requirement for template files to contain any particular kind of line ending.
If the template starts with |x| then x is a specification of how the indents in the template should be converted. It can be one of:
- An integer: Re-indent as a block, like Wing's indent-region command, so the first line is at the given number of indent levels.
- The character 'm': Re-indent as a block, like Wing's indent-to-match command, so the first line is at the expected indent level according to context in the source.
- The character 'm' followed by '+' or '-' and an integer: Re-indent as for 'm' and then shift left or right by the given number of indents.
Any |x| at the start of a template file will be removed before the template is inserted into an editor.
Cursor Placement
Templates can contain |!| to indicate the final resting position of the cursor after all other fields have been filled. When this is present, inline data entry mode is terminated automatically when this position is reached (after all other fields have been entered). The mark will be removed before templates are inserted into an editor.
Template Directory Layout
Templates are stored in the templates directory in the user settings directory. The first time the Templates tool is used, this directory is populated by making a copy of the default set of templates that ship with Wing (these can be found in templates within your Wing IDE installation).
File Types
This directory is organized by the file type to which they apply. Templates stored at the top level of this directory can be used with any file in the editor. Those stored in sub-directories are used only for files of a particular type. The name of the sub-directories is the file extension for that file type (for example py for Python). This is converted to a mime type so that the templates are available for all files of that type, regardless of their naming. The name of the file type directory also provides the file extension to use for new untitled files when a template is pasted into a new file.
Contexts
When templates are defined for a particular context within a file, they are stored in a sub-directory named context.ctx where context is replaced with the context name (see above). When a template is defined as the default, or without a particular context, it is stored in the top level of the file type directory.
Configuration
Wing also stores a configuration file in the user's templates directory. This file is named .config and is used for internal book keeping. It should not be altered or removed, as this may cause the loss of your template files.
Commands
The following commands are available for invoking templates:
template -- This will insert a template (selected by name) at the cursor in the current editor. If there is a non-empty selection on the editor, it will replace the selection. The editor will be placed into data entry mode for the collection of the template arguments.
template-file -- This will create a new file of the type specified by the template file's extension and insert the selected template into it before entering data entry mode in the editor for the collection of the template arguments.
In most cases, you will use the Assign Key Binding item in the Templates tool's context menu to invoke these commands for a particular template.
Scripting Templates
Wing's extension scripting API exposes the editor's data entry mode and template processing capabilities. This can be used to write scripts that generate templates and paste them into the editor for user data entry. This approach may be preferable when the template markup language described above is not sufficient.
For details, see the PasteTemplate and StartDataEntry methods in wingapi.py and refer to Scripting and Extending Wing IDE.
| « 4.7. User-defined Bookmarks | Table of Contents | 4.9. Indentation » |