Плагин «Мой шаблон»

===== Загрузка и установка =====

Скачать и установить плагин можно с помощью «[[plugin:plugin|менеджера плагинов]]», используя ссылку для скачивания, указанную выше. Чтобы узнать, как установить плагин вручную, см. страницу «[[:plugin|Плагины]]».

===== Синтаксис и использование =====

Плагин позволяет отделить структуру вики-страницы от содержащейся на ней информации. Это позволяет иметь страницы с различными данными, привязанных к странице с определённой структурой. Технически возможно объединять несколько таких «структурных» страниц.

Я буду продолжать использовать термин «структурная страница» для страниц, которые содержат разметку «ДокуВики» и указатели места заполнения (метки) для данных и «страниц данных», которые содержат информацию для заполнения по соответствующшим меткам.

Оба типа страниц могут быть просмотрены через вики. Структурные страниц будут отображаться как есть, а страницы с информацией будут отображатся в скомпилированном (собранном) виде (т. е. данные, расположенные в соответствии с определённой структурой).

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

Это мой первый плагин для «ДокуВики». И я не очень опытен с PHP, поэтому, возможно, что код плагина содержит уязвимости в безопасности и ошибки.

=== Объявление структуры страницы ===

Команды замещения выглядят следующим образом: ~~COMMAND(x[,var]):param1[:param2[:param3]]~[!]~

* Доступные команды перечислены ниже.

* «var» — необязателен. Если он задан, результат замены будет сохранён в переменной с этим именем и впоследствии может быть использован повторно.

* «x» — задаёт последовательность операций, во время которых происходит замена меток (placeholder). В основном значение данного параметра равно нулю, за исключением случаев, когда требуется контроль над очерёдностью (последовательностью) проведения замен. Если это не очень понятно: список команд --- это основа, где возможно использование различной последовательности действий по замене (FIXME).

* В зависимости от заданной команды, требуется до трёх параметров, разделёных двоеточиями. Заметьте, что параметр может быть также следующей заменяющей командой, при этом вложенность замен разбирается автоматически от самой последней к самой первой.

* Чтобы плагин ничего не выводил, вы можете разместить восклицательный знак (!) между двух тильд (~), стоящих в конце строки. Это имеет смысл, если вы хотите получить промежуточные результаты, которые будут использоваться позже.

Доступные команды:

* **VAR** — это ваша основная команда для замены.
Принимает один параметр, который будет заменен значением переменной.
(Пример: ~~VAR(0):key~~)

* **LOOK** This is a map lookup. Вы можете определить массив в «структуре страницы» и использовать переменная, определенная в «страницу данных», как индекс. Как объявлять карту — см. «[[#Объявление данных]]». (Пример: ~~LOOK(0):MAP:3~~)

* **LOOKRANGE** — Похож на LOOK, но в этой команде карта не должна содержать точный индекс.

* **CALC** — Позволяет производить математические вычисления, основанные на переменных или результатах предыдущих команд. Все математические операторы и большинство php-функций должны работать. (Пример: ~~CALC(0):round(~~VAR(0):FOO~~ * ~~VAR(0):BAR~~)~~

* **COUNT** — Подсчитывает количество вхождений первого параметра во втором. (Пример: ~~COUNT(0):,:~~VAR(0):FOO ~~ ~~)

* **IF** — Если «param1» возвращает «ИСТИНА», будет выводиться «param2», иначе бужет выведен «param3».
(Пример: ~~IF(0):~~VAR(0):SAYWHAT~~:what:huh~~)

* **REPLACE** — заменяет все вхождения «param2» в «param1» и «param3». (Пример: ~~REPLACE:Hello NAME:NAME:~~VAR(0):NAME~~ ~~)

* **LIST** — создаёт таблицу из значений со страницы данных.

Пример для списка:

WIKISOFTWARE = ( 'ДокуВики', '2009-12-25', 'GPL 2' ),

( 'МедиаВики', '2010-04-07', 'GPL' )

Использование в шаблоне было бы тогда похоже на это:

^ Название ^ Последний выпуск ^ Лицензия ^

~~LIST(0):WIKISOFTWARE:[| @0 | @1 | @2 | ]:5~~

Как видите,

=== Объявление данных ===

Данные объявляются простыми парами «ключ—значение» в одну линию: VARIABLENAME = VALUE

При объявлении переменной для команды «LIST», «VALUE» — список строк, где строка заключена в скобки:

LIST = (5, true, "foo"),

(3, false, "bar")

Обратите внимание: текст в строках, идущих после первой, нужно располагать с отступом от начала строки(, чтобы парсер мог работать.)

Объявление переменной должно начинаться тегом [VARIABLES], а заканчиваться — [ENDVARIABLES].

NAME = a, b, c, d, e,

f, g, h, i, j

В этом случае это — простой массив, индекс «0» (ноль) отобразится на «a», индекс «2» на «c» и т. д. Опять же, не забывайте располагать строки, идущие после первой, с отступом от (левого) края.

Также можно напрямую указать индексы:

NAME = 1 = a, 3 = b, 8 = c

Это имеет смысл, если «LOOKRANGE» будет использоваться для поиска.

Объявление карты должно начинаться тегом [MAPS], а заканчиваться — [ENDMAPS].

=== Сбор воедино ===

Наконец, нужно собрать данные. Просто поместите в конце своей «страницы данных» конструкцию вида: [INCLUDE:namespace:foo:template]

Когда «страница данных» выведена на экран, всё находящееся между [VARIABLES] и [ENDVARIABLES] выполнено (преобразованов в текст), а не напечатано. «INCLUDE» будет заменён контентом интерпретируемой шаблонной страницы, показывая только то, что будет отображаться. Можно иметь многократное влючение, таким образом создавая страницу из многократных шаблонов, или же можно включать определения переменных отдельных страниц.