Snippets. Plug-in to insert templated text
Plug-in to insert templated text
Snippets 1.4.4 (Required OutWiker version: 3.2.0.922 and above)
- Brief description
- Snippets management
- Entering the template text
- Insert snippet as wiki command
- Snippet language
- Snippets storage features
- Version History
Brief description
The Snippets plug-in designed to save the text templates (snippets) which often occurs in the notes. This plug-in allow don't repeat the text entering every time. The variables may be used in the snippet text. The variables values entered by user when the snippet executed. In addition, if you know the Jinja2 template engine, you can use rich ability of the library in yours snippets. The Snippets plug-in uses this library for the text generation on the snippet.
Snippets management
To create a snippet, select menu item "Snippet - Snippets management...". Thereafter the "Snippets management" dialog window will be opening. The tree snippet will be showing in the left part of the window. You can unite the snippets in the folders.
The toolbar with two the button groups located in the upper part of the dialog window.
The left group includes the buttons for creating the snippets folders, creating the new snippet, renaming the folder or snippet, removing the snippet, executing its.
The right group includes the button for inserting built-in or custom variables and button for inserting some Jinja language constructs
If the entered snippet has any syntactically error, it will be displaying in the lower right information box.
All snippets will saved automatically, and thus the dialog window does not have a button to save the snippet.
All created snippets located in the "Snippets" menu of the main OutWiker window. All created folders with snippets in this menu presented as nested submenu. The nesting of folders is almost limitless.
Entering the template text
The Snippets plug-in allows you to insert the snippets in two modes: as generated text and as the wiki command. (the second mode works only for the wiki pages).
To put the template text at the page, you can select the appropriate snippet in the "Snippets" menu or execute the snippet from the dialog management snippets. Thereafter the dialog to enter the variables will be opened. You can enter variable values in the left part of the window (variable values may be blank). On the right part you will seeing the result which will insert in the text page and the snippet source text.
The check box "Insert as wiki command" located in the left bottom part of the dialog window. If the check box is not checked the result directly will be inserted in the page. If the check box is checked, wiki command will be inserted in the page text. The wiki command will be converted to text in the "Preview" mode. The "Insert as wiki command" check box showed only for wiki pages.
Insert snippet as wiki command
If in the dialog to enter the variable values you checked the "Insert as wiki command" check box, in the page text will insert not a generated text, but (:snip:) wiki command. This wiki command will convert to appropriate text in the "Preview" mode. This command has the following format:
(:snip file="path to snippet/snippet name" parameter1="variable value", parameter2="variable value", ...:) Optional text (:snipend:)
If the "file" parameter was set, the snippet specifying as value this parameter is used. The path to snippet is specified relative the snippets root folder. Thus if a template with the name "My snippets" directly visible in the "Snippets" menu, then the "file" parameter value must be equal to “My snippets”. If the "My template" snippet located in the submenu "Snippets – My concrete snippets", the parameter value file must be equal to "My concrete snippets/My template". In this way always used forward slashes (/).
parameter1, parameter1 and etc are the variable names used in the snippet text. Optional text will be saved as the built-in __text variable, which can be used in the template.
In this case, the __text variable will be storing the text between (:snip:) and (:snipend:) commands.
If the file parameter is not specified in the (:snip:) wiki command, it is considered the text template is specified between (:snip:) and (:snipend:):
(:snip parameter1="variable value", parameter1="variable value", ...:) Snippet text (:snipend:)
In this case built-in variable __text will be equal to an empty string "".
Snippet language
The Snippet plug-in uses the language of the jinja2 template engine. This is a very powerful library, but in this section will be showed only the most simple and frequently used features. The plug-in's interface designed for user, who does not know this library, however if you are a programmer and worked with this library, you can use all of its features which is not to be mentioned. Description of all possibilities of this library you can find in the Jinja2 documentation.
Setting variables
The most important part of the syntax of snippets are variables. The variable value in the snippet inserted with the construction {{varname}}, where varname is the name of the variable. The name of the variable may include only Latin letters, numbers and the underscore "_", but the first character in the variable name must be Latin letter.
The Snippets plug-in has a the set of built-in variables, which cannot be defined in the dialog to input variables. Values of the built-in variables depends from the properties of the current page or the current date. A complete list of these variables listed in section Built-in variables. The names of the built-in variables start with the double underscore "__".
Consider this snippet:
from outwiker.core.commands import MessageBox
MessageBox(
_(u'{{message}}'),
_(u'{{title}}'),
wx.ICON_ERROR | wx.OK)
In this snippet uses two variables: message and title, the Snippet plug-in will ask to define them in the dialog that will be open when you calling this snippet:
Built-in variables
In addition to the users variables, the Snippets plug-in has a set of the set of built-in variables, the values of the built-in variables depend of the properties of the current page. The names of all built-in variables start with two underscores "__".
If you click to button to inserting of the variables in the dialog of snippets management, you can see the names of built-in variables.
For example. The __text contains text selected on the page when you invoke the snippet. Also __text variable used with the (:snip:) wiki command, which inserts a snippet from a file (if the parameter file is set). In this case, the __text variable contains the text located between (:snip:) and (:snipend:).
The __type variable equal to the wiki for wiki pages, html for HTML pages, text for simple text pages etc. This variable jointly with if operator you can use to change the behavior of the snippet depending on page type.
Other language constructs
The Snippet plug-in uses inside it the Jinja2 template engine. This engine supports a sufficiently large number of the template constructs, but with the graphic users interface you can insert only some of them. You can use all features of Jinja2 engine if you know this library.
With the interface you can insert three language constructs: if operator, include operator and comments.
The comments are enclosed in braces of the form {# … #} and during processing of the snippet are removed. The comments needed to explain the snippet text: for which it is used, the meaning of the variables, etc.
The if operator
If operator designed for the organization of branching in the snippet and inserting the text depending on the variables value. The syntax of the if operator is as follows:
{% if condition_1 %}
Content 1
{% elif condition_2 %}
Content 2
{% elif condition_3 %}
Content 3
...
{% else %}
Content N.
{% endif %}
Most likely this syntax you know on any other programming language.
Please note, all variables except those that contain dates are string variables, therefore their values need to compare with strings, even if it means, that variable will contain only numbers. So the correct expression, can be as follows:
{% if var == '1' %}100{% elif var == '2' %}200{% elif var == '3' %}300{% else %}xxx{% endif %}
and that expression will be wrong (will always run branch else)
{% if var == 1 %}100{% elif var == 2 %}200{% elif var == 3 %}300{% else %}xxx{% endif %}
The include operator
The include operator is designed to insert a snippet into another snippet, in this case own variables may be declared in the inserted snippet. The syntax the include operator is as follows:
{% include "inserted snippet" %}
In this operator "inserted snippet" is the name of the snippet located in the same folder that the parent snippet (which is located inside the include operator) or in a sub-folder, in this case the operator will look like the following
{% include "Folder 1/Folder 2/inserted snippet" %}
Snippets storage features
All snippets are stored as separate files in the snippets folder inside the program settings directory (in MS Windows is C:\Users\USERNAME\AppData\Roaming\outwiker\snippets\, in Linux is /home/USERNAME/.config/outwiker/snippets/). The name of the snippet corresponds to a file name, so usually these are files without extensions. Folders in the templates is ordinary folders in the same directory snippets.
Versions history
1.4.4 (May 03, 2023)
- Migrate to new API.
1.4.3 (December 11, 2022)
- Update libraries.
1.4.2 (February 19, 2022)
- Fix errors.
- Update libraries.
1.4.1 (December 29, 2020)
- Fix errors.
1.4 (October 19, 2019)
- Migrate to new API.
1.3.3 (May 26, 2019)
- Update Jinja2 library.
1.3.2 (March 22, 2019)
- Update the Ukrainian localization.
- Update the German localization.
1.3.1 (January 24, 2019)
- GUI improvements.
- Fix errors.
1.3 (August 26, 2018)
- Add German localization.
1.2.1 (March 20, 2018)
- GUI improvements.
1.2 (February 15, 2018)
- Add OutWiker 2.1 support. Migrate to Python 3.
1.1.1 (May 22, 2017)
- GUI improvement.
1.1 (February 24, 2017)
- Added the Ukrainian localization.
- Small GUI improvement.
1.0 (February 06, 2017)
- The first version.