Плагин для хранения и вставки шаблонного текста

Snippets 1.4.4 (Требуемая версия OutWiker: 3.2.0.922 и выше)

• Краткое описание
• Управление шаблонами
• Вставка шаблонного текста
• Вставка шаблона в виде викикоманды
• Язык шаблонов
  • Задание переменных
  • Встроенные переменные
  • Другие языковые конструкции
    • Оператор if
    • Оператор include
• Особенности хранения шаблонов
• История версий
• Комментарии

Краткое описание

Плагин Snippets предназначен для сохранения шаблонного текста, который часто используется в заметках, для того, чтобы каждый раз не набирать повторяющийся текст заново. В тексте шаблона могут встречаться переменные подстановки, значения которых вводится пользователем при использовании шаблона. Кроме того, если вы знакомы с шаблонизатором Jinja2, то можете использовать его возможности в шаблонах, поскольку плагин Snippets использует эту библиотеку для генерации текста по шаблону.

Управление шаблонами

Чтобы создать шаблон, выберите пункт меню "Шаблоны - Управление шаблонами...", откроется диалог "Управление шаблонами". В левой части диалога будет показано дерево шаблонов, в котором шаблоны можно группировать по папкам.

В верхней части диалога расположена панель инструментов с двумя группами кнопок.

В левую группу входят кнопки для создания папки шаблонов, создания нового шаблона, переименования папки или шаблона, удаления шаблона, запуска шаблона на выполнение.

В правую группу входят кнопка для вставки встроенных или пользовательских переменных, а также кнопка для вставки некоторых языковых конструкций Jinja в текст шаблона.

Если во введенном шаблоне есть синтаксическая ошибка, то она выводится в правом нижнем информационном поле.

Все шаблоны при редактировании сохраняются автоматически, поэтому в диалоге нет кнопки для сохранения шаблона.

Все созданные шаблоны помещаются в меню "Шаблоны" главного окна программы OutWiker, а созданные папки с шаблонами в этом меню представлены вложенными подменю. Вложенность папок практически не ограничена.

Вставка шаблонного текста

Плагин Snippets позволяет вставлять шаблоны в двух режимах - в виде сгенерированного текста и в виде викикоманды (этот режим работает только для викистраниц).

Чтобы вставить шаблон в текст страницы, нужно выбрать соответствующий шаблон в меню "Шаблоны" или запустить на выполнение шаблон из диалога управлением шаблонами. После этого откроется диалог для ввода значений переменных. В левой части диалога будут перечислены переменные, которые необходимо ввести (при желании, их значения можно оставить пустыми), а справа можно увидеть результат, который будет вставлен в текст страницы, и исходный текст шаблона.

В левом нижнем углу диалога расположен переключатель "Вставить как викикоманду". Если он не установлен, то полученный результат будет непосредственно вставлен в текст страницы. Если этот переключатель установлен, то в текст страницы будет вставлена викикоманда, которая будет преобразована в соответствующий текст в режиме просмотра. Переключатель "Вставить как викикоманду" существует только в том случае, если выбранная в данный момент страница является викистраницей (а не HTML-страницей, текстовой страницей и т.д.)

Вставка шаблона в виде викикоманды

Если в диалоге ввода переменных установить переключатель "Вставить как викикоманду", то в текст страницы будет вставлен не сгенерированный текст, а викикоманда (:snip:), которая будет преобразована в соответствующий текст в режиме просмотра. Эта команда имеет следующий формат:

(:snip file="Папка с шаблоном/имя шаблона" varname1="значение переменной", varname2="значение переменной", ...:)
Необязательный текст
(:snipend:)

Если задан параметр file, то используется шаблон, указанный в качестве значения этого параметра. Путь до шаблона задается относительно корневой папки шаблона, т.е. если шаблон с именем "Мой шаблон" виден непосредственно в меню "Шаблоны", то значение параметра file должно быть равно "Мой шаблон". Если "Мой шаблон" находится в подменю "Шаблоны - Папка с шаблонами", то значение параметра file должно быть равно "Папка с шаблонами/Мой шаблон". При этом в пути всегда используются прямые слеши (/).

varname1, varname2 и т.д. - имена переменных, встречающихся в тексте шаблона, а "Необязательный текст" будет сохранен во встроенную переменную __text, которая может использоваться в шаблоне.

В этом случае переменная __text будет хранить текст между (:snip:) и (:snipend:), т.е. в данном примере значение "Необязательный текст".

Если в викикоманде (:snip:) параметр file не задан, то считается, что текст шаблона задан между (:snip:) и (:snipend:):

(:snip varname1="значение переменной", varname2="значение переменной", ...:)
Текст шаблона
(:snipend:)

В этом случае встроенная переменная __text будет равна пустой строке "".

Язык шаблонов

В шаблонах используется язык из библиотеки-шаблонизатора jinja2. Это очень мощная библиотека, но в данном разделе будут перечислены только наиболее простые и часто используемые в шаблонах возможности. Интерфейс плагина Snippets рассчитан на пользователя, незнакомого с этой библиотекой, однако если вы программист и работали с ней, то вы можете использовать все ее возможности, о которых здесь не будет упомянуто. Описание всех возможностей этой библиотеки вы можете найти в документации к Jinja2.

Задание переменных

Наиболее важная часть синтаксиса шаблонов - это переменные. Значение переменной в шаблоне вставляется с помощью конструкции {{varname}}, где varname - это имя переменной. Из-за особенности используемой библиотеки имя переменной может включать в себя только латинские буквы, цифры и знак подчеркивания "_", причем первым символом в имени переменной может быть только латинская буква.

В плагине Snippets есть набор встроенных переменных, которые нельзя задать через диалог ввода переменных, их значения зависят от свойств текущей страницы или текущей даты. Полный список таких переменных перечислен в разделе Встроенные переменные. Эти переменные начинаются с символа двойного подчеркивания.

Рассмотрим такой шаблон:

from outwiker.core.commands import MessageBox

MessageBox(
    _(u'{{message}}'),
    _(u'{{title}}'),
    wx.ICON_ERROR | wx.OK)

В нем используются две переменные: message и title, плагин Snippets попросит их определить в открывшемся диалоге при вызове данного шаблона:

Встроенные переменные

Кроме заданных пользователем переменных, плагин Snippets создает набор встроенных переменных, значения которых зависят от свойств текущей страницы. Имена всех встроенных переменные начинаются с двух знаков подчеркивания.

Имена встроенных переменных можно увидеть в диалоге управления шаблонами, если нажать кнопку для вставки переменных.

Например. Переменная __text содержит в себе текст, выделенный на странице в момент вызова шаблона. Также переменная __text используется при работе викикоманды (:snip:), которая вставляет шаблон из файла (если задан параметр file). В этом случае переменная __text содержит текст, находящийся между (:snip:) и (:snipend:).

Переменная __type равна значению wiki для викистраниц, html для страниц в формате HTML, text для простых текстовых страниц и т.д. Эту переменную вместе с оператором if можно использовать для изменения поведения шаблона в зависимости от типа страницы.

Другие языковые конструкции

Используемая внутри плагина Snippets библиотека Jinja2 поддерживает достаточно большое количество языковых конструкций, но через интерфейс плагина можно вставить только некоторые из них. Если вы знакомы с данной библиотекой, то можете использовать все поддерживаемые ей конструкции.

Через интерфейс можно вставить три языковые конструкции: операторы if, include и комментарии.

Комментарии обрамляются скобками вида {# ... #} и во время обработки шаблона удаляются. Они нужны, чтобы пояснить текст шаблона - для чего он используется, что означают переменные и т.п.

Оператор if

Оператор if предназначен для организации ветвления в шаблоне и вставки текста, зависящего от значений переменных. Синтаксис оператора if следующий:

{% if условие_1 %}
    Текст 1
{% elif условие_2 %}
    Текст 2
{% elif условие_3 %}
    Текст 3
...
{% else %}
    Текст N.
{% endif %}

Скорее всего подобная конструкция вам знакома по какому-либо языку программирования.

Обратите внимание, что все переменные кроме тех, что содержат даты, являются строковыми переменными, поэтому их значения нужно сравнивать именно со строками, даже если подразумевается, что переменная будет содержать только цифры. Поэтому правильное выражение может быть такое:

{% if var == '1' %}100{% elif var == '2' %}200{% elif var == '3' %}300{% else %}xxx{% endif %}

А такое выражение будет ошибочно (всегда будет выполняться ветвь else):

{% if var == 1 %}100{% elif var == 2 %}200{% elif var == 3 %}300{% else %}xxx{% endif %}

Оператор include

Оператор include предназначен для вставки одного шаблона в другой, при этом во вставляемом шаблоне могут быть объявлены собственные переменные. Синтаксис оператора include следующий:

{% include "Вставляемый шаблон" %}

В этом операторе "Вставляемый шаблон" - это имя шаблона, который должен находиться в той же папке, что и родительский шаблон (внутри которого находится оператор include) или во вложенной папке, в этом случае оператор будет выглядеть следующим образом:

{% include "Папка 1/Папка 2/Вставляемый шаблон" %}

Особенности хранения шаблонов

Все шаблоны хранятся в виде отдельных файлов в папке snippets внутри директории с настройками программы (под Windows 7 / 8.x / 10 - C:\Users\USERNAME\AppData\Roaming\outwiker\snippets\, под Linux - /home/USERNAME/.config/outwiker/snippets/). Имя шаблона соответствует имени файла, поэтому чаще всего это будут файлы без расширения. Папки в шаблонах - это обычные папки в той же директории snippets.

История изменений

1.4.4 (03.05.2023)

• Переход на новый API.

1.4.3 (11.12.2022)

• Обновление используемых библиотек.

1.4.2 (19.02.2022)

• Исправление ошибок.
• Обновление используемых библиотек.

1.4.1 (29.12.2020)

• Исправление ошибок.

1.4 (19.10.2019)

• Переход на новый API.

1.3.3 (26.05.2019)

• Обновление библиотеки Jinja2.

1.3.2 (22.03.2019)

• Обновление украинской локализации.
• Обновление немецкой локализации.

1.3.1 (24.01.2019)

• Улучшения в интерфейсе.
• Исправление ошибок.

1.3 (26.08.2018)

• Добавлена немецкая локализация.

1.2.1 (20.03.2018)

• Улучшения в интерфейсе.

1.2 (15.02.2018)

• Добавлена поддержка OutWiker 2.1. Переход на Python 3.

1.1.1 (22.05.2017)

• Улучшения в интерфейсе.

1.1 (24.02.2017)

• Добавлена украинская локализация.
• Небольшие улучшения в интерфейсе.

1.0 (06.02.2017)

• Первая версия.

---

---

	Подписаться на комментарии
Автор:
Тема:
	Ваш комментарий
Введите код 489