Справка:Механизм шаблонов

«Шаблонами» в MediaWiki (программном обеспечении, на котором работает «Традиция: Право») называется класс особых страниц, содержимое которых можно вставить в другие страницы. Это содержимое используется при каждой загрузке страницы: изменения в шаблонах проявляются на страницах, применяющих шаблон.

Общая информация

Страницы шаблонов — полноценные вики-документы, для которых отведено своё пространство имён «Шаблон:».

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

Вызывается шаблон пометкой

{{Имя шаблона}}

При отображении страницы на место этой пометки будет подставлено содержимое страницы «Шаблон:Имя шаблона». Если её ещё нет, то пометка будет отображена как ссылка на несуществующую статью шаблона. Чтобы не озадачивать читателя красной ссылкою (наподобие «Шаблон:POV cehck»), любой автор может заблаговременно удостовериться в существовании вызываемых шаблонов — это делается предпросмотром страницы до сохранения правки.

Тем же способом можно выполнять подстановку не только страниц из пространства имён «Шаблон:», но и обычных статей. Если в главном пространстве имён существует статья «Имя статьи», то можно вызвать её наподобие шаблона, поставив перед именем двоеточие:

{{:Имя статьи}}

Двоеточие здесь существенно, так как без двоеточия произошло бы включение страницы, имеющей имя «Шаблон:Имя статьи». В Традиции не редки статьи, одноимённые шаблонам (например, статья «Фидонет» и одноимённый навигационный шаблон {{Фидонет}}), так что в таких случаях необходима аккуратность.

Возможен вызов страниц из других (неосновных) пространств имён (тогда пространство имён указывается перед двоеточием):

• вызов изображений:

{{Файл:Имя файла}}

• вызов категорий:

{{Категория:Имя категории}}

Содержимое подстановки зависит от смысла пространства имён. Для изображений будет подставлено описание (но не сама иллюстрация), а для категорий — вводная (описательная) преамбула (но не список статей, входящих в категорию).

Такие подстановки позволяют, например:

• «вытаскивать» подписи и описания картинок;
• изготавливать специальные составные статьи (например, для печати или для дальнейшей обработки особыми функциями парсера).

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

Возможно также включение шаблона в шаблон, то есть вызов одного шаблона из другого и (или) из него же самогó.

Переменные шаблона (cм. ниже) вычисляются после вставки шаблона в вызывающую его статью — например, если в шаблоне содержится подстановка {{PAGENAME}}, то она будет развёрнута в имя статьи, из которой шаблон был вызван, а не в имя самогó шаблона.

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

Параметры

Параметры шаблона могут быть поименованными или пронумерованными. Синтаксис использования может быть

• {{templatename|parname1=parvalue1|parname2=parvalue2}}, тогда в теле шаблона надо ссылаться на {{{parname1}}}, {{{parname2}}};
• {{templatename|parvalue1|parvalue2}}, тогда в теле шаблона нужно использовать {{{1}}}, {{{2}}}.

Лишние (не используемые в теле шаблона) параметры игнорируются.

Имена параметров чувствительны к регистру символов.

Обратите внимание на тройные фигурные скобки при использовании параметров!

Таким образом, механизм шаблонов выполняет два типа подстановок:

• вызов шаблона (двойные фигурные скобки) заменяется содержимым шаблона;
• параметры шаблона (тройные фигурные скобки) заменяются параметрами шаблона.

Параметром шаблона может быть ссылка на другую статью. Пусть, например, у нас есть такой шаблон:

   Начало {{{1}}} Конец.

и он называется «Шаблон». Тогда его вызов

   {{Шаблон| [[Main_Page|Главная страница]]}}

будет развёрнут в

Начало Главная страница Конец.

Неопределённые и пустые параметры

Если какой-то параметр «someparameter» не задан, то он остается нераскрытым текстом {{{someparameter}}} — что позволит раскрыть его в дальнейшем, если вызвавшая шаблон статья также включается куда-то ещё, где этот параметр задан.

Заметим, между прочим, что вызов {{Шаблон||a}} делает первый параметр определённым, но равным пустой строке. Если, напротив, нужно задать второй параметр, никак не определяя первый, то для этого следует использовать вызов {{Шаблон|2=a}}.

Аналогичный синтаксис (явное указание номера параметра) приходится использовать также и в тех случаях, когда значение параметра само содержит знак равенства: например, если значением параметра является строка «a=b», то вызов {{Шаблон|a=b|c}} не присвоит значение «a=b» параметру «1», а создаст параметр «a» со значением «b»; только вызов {{Шаблон|1=a=b|2=c}} (с явным указанием номера первого параметра) сделает всё как надо. Единственный недостаток такого подхода состоит в том, что приходится нумеровать все параметры шаблона.

Кроме этого, для вставки символа равенства (понимаемого буквально, то есть именно как символ, отображаемый в тексте страницы, а не как элемент управляющей конструкции механизма шаблонов) можно использовать принятую в языке HTML кодовую запись, содержащую цифровой код этого символа (в соответствии с его номером в кодировке Unicode): для этого достаточно записать «=» — например, {{Шаблон|a=b|c}}.

Если вызов одного шаблона является параметром другого шаблона и механизм шаблонов сбивается, не будучи в состоянии верно определить то место, где оканчивается параметр, то и тогда явное указание номера параметра может помочь. (Типичной причиною сбоя является появление знака равенства в указании имён параметров внутреннего шаблона, которое ошибочно воспринимается как разделитель имени и значения параметра внешнего шаблона. Явное указание имени параметра внешнего шаблона создаёт знак равенства ранее, в нужном месте.)

Условное включение параметров

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

   {{{parameter|альтернативный текст}}}

будет включён в текст шаблона только в том случае, если значение параметра задано. А в противном случае вместо значения параметра появится альтернативный текст. Этот способ уместен в тех обстоятельствах, когда для некоторого параметра шаблона подразумевается определённое значение по умолчанию. Самый простой пример: если некоторый параметр parameter записан внутри шаблона в форме {{{parameter|}}} (то есть если в качестве альтернативного текста используется пустая строка), тогда на его месте не будет вообще ничего выводиться (даже {{{parameter}}}) в том случае, если этот параметр окажется не заданным.

Иногда возникает необходимость переменить в тексте шаблона нечто большее, чем сам параметр, если этот параметр не задан. Для этой цели употребляются функции парсера: #if и другие. Функция #if вызывается следующим образом:

   {{#if: проверяемая-переменная-или-параметр
    | текст-для-случая,-когда-значение-test-не-пустое
    | текст-для-случая,-когда-значение-test-пустое
    }}

Параметр else не является обязательным, поэтому можно использовать сокращённую форму:

   {{#if: проверяемая-переменная-или-параметр
    | текст-для-случая,-когда-значение-test-не-пустое
    }}

Демонстрационный пример употребления:

   {{#if: {{{sample|}}}
     | параметр '''sample''' определён!
     | параметр '''sample''' пуст!
     }}

Реальный пример применения #if вы можете найти в коде шаблона {{Fidonet}}.

Просмотр содержимого шаблона

Чтобы увидеть «сырое» содержимое шаблона (подстановки параметров и т. д.), нужно смотреть на шаблон в режиме редактирования, поскольку в противном случае некоторые подстановки вроде {{PAGENAME}} могут раскрыться.

msgnw

Для показа содержимого шаблона (без wiki-интерпретации) можно использовать кодовый «волшебный» префикс «msgnw:». То есть {{Заготовка}} и {{msgnw:Заготовка}} будут показаны как

Это незавершённая статья. Вы можете помочь проекту, исправив и дополнив её.

и 

{| align=center border=0 cellpadding=0 cellspacing=4 style="background:#FADFAD"
100px]]	помочь проекту]], [{{SERVER}}/index.php?stub&title={{FULLPAGENAMEE}}&action=edit исправив и дополнив её.]''	}<includeonly>[[Категория:Статьи-заготовки]]</includeonly> <noinclude>[[Категория:Шаблоны]]</noinclude>

соответственно.

Ссылка на редактирование шаблона

«Редактирующая» ссылка на каждой странице-статье не позволяет редактировать текст используемого шаблона, а иногда желательно иметь такую ссылку (приглашающую поправить шаблон, например, если шаблон еще не устоялся, или если его содержимое может часто изменяться). Такую ссылку можно «зашить» внутрь самого шаблона, даже более того — сделать шаблоном, который можно использовать внутри других шаблонов. См. шаблон {{править}}.

Использование вложенных двойных или тройных фигурных скобок внутри двойных фигурных скобок

Передача параметров из внешнего шаблона во внутренний

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

Примером такого вызова служит код шаблона {{Фидонет}}, начинающийся вот как:

{{Навигационная таблица
|имя                       = Фидонет
|заголовок                 = <span style="font-size: 1.4em;">[[Фидонет]]</span>
|поместить_в_категорию     = Фидонет
|звезда_в_категории        = {{{mainFidonetPage|}}}

(далее следуют прочие параметры). Таким образом, шаблон {{Фидонет}} вызывает шаблон {{Навигационная таблица}} — причём значение параметра {{{mainFidonetPage}}}, указанное при вызове шаблона {{Фидонет}}, становится значением параметра {{{звезда_в_категории}}} внутри вызванного шаблона {{Навигационная таблица}}.

Извлечение имени вызываемого шаблона из другого шаблона или параметра

Вот пример: есть шаблон под названием {{ТестовыйВыводИмени}}, содержащий (выводящий) текст «ТестовоеИмяШаблона», и есть шаблон под названием {{ТестовоеИмяШаблона}}, содержащий (выводящий) текст «Готово!».

Можно ли использовать результат работы одного шаблона (в нашем примере — шаблона {{ТестовыйВыводИмени}}) как имя при вызове другого шаблона (в нашем примере — шаблона {{ТестовоеИмяШаблона}})?

Да, можно — но будьте внимательны!

Напрашивающийся простейший вызов «{{{{ТестовыйВыводИмени}}}}» не подходит для этой цели: многочисленные скобки, идущие подряд, сбивают с толку механизм шаблонов, поэтому их содержимое не станет обрабатываться, так что результатом будет простой (необработанный) текст «{{{{ТестовыйВыводИмени}}}}».

Необходимо упростить механизму шаблонов его задачу. Для этого достаточно пробелом разделить пары закрывающих фигурных скобок (записать «{{{{ТестовыйВыводИмени}} }}») — тогда механизм шаблонов сумеет однозначно осознать желаемое и выдаст текст «Готово!».

Аналогичное разделение закрывающих скобок следует использовать и в том случае, когда один шаблон вызывается из другого, причём имя внутреннего (вызываемого) шаблона берётся из параметра, указанного при вызове внешнего (вызывающего) шаблона.

Примером этого является шаблон {{ТестовыйВыводПараметра}}, содержащий текст «{{{{{1}}} }}». Обратите, пожалуйста, внимание на пробел, отделяющий внутреннюю тройку закрывающих фигурных скобок (обрамляющую номер параметра) от внешней пары закрывающих фигурных скобок (которые указывают, что значение параметра будет использоваться как имя вызываемого шаблона). Если записать «{{ТестовыйВыводПараметра|ТестовоеИмяШаблона}}», то текст «ТестовоеИмяШаблона» станет значением первого параметра шаблона {{ТестовыйВыводПараметра}}, так что из этого шаблона произойдёт вызов шаблона {{ТестовоеИмяШаблона}}, и результатом будет текст «Готово!».

Тэг категории в шаблоне

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

Такие категории уместно использовать и в шаблонах, предназначенных для пометки статей (к примеру, {{stub}}), и в навигационных шаблонах (к примеру, {{Фидонет}}).

Очередь заданий

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

Чтобы не тормозить после редактирования шаблонов, размещающихся на многих страницах, сервер откладывает эти действия (ставит в очередь заданий). Раньше количество ещё не выполненных заданий можно было отследить на странице «Special:Statistics», но начиная от версии MediaWiki 1.17 это количество видно только при служебном вызове API (значение параметра «jobs» в элементе «statistics» отражает длину очереди заданий).

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

Теги <noinclude> и <includeonly>

Всё, что находится между тегами <noinclude> и </noinclude> будет обрабатываться и показываться только в случае когда шаблон показывается непосредственно, не включенным в другую страницу. Возможные применения:

• категоризация шаблонов самих по себе (а не тех страниц, в которые шаблон включён);
• интервики на аналогичные шаблоны на других языках;
• страницы в пространстве имён MediaWiki;
• текст с объяснением того, как использовать шаблон.

Тег <includeonly> обладает противоположным действием. Текст между <includeonly> и </includeonly> будет обрабатываться и показываться только тогда, когда шаблон включён в статью. Очевидное применение:

• включение всех статей, содержащих шаблон, в категорию (при этом сам шаблон в категорию не попадёт).

Будьте внимательны! Не допускайте пустых строк вокруг конструкций <noinclude> и <includeonly>, так как пустая строка будет интерпретироваться как перенос строки, который будет внесён шаблоном в статью.

Следует отметить, что при этом сохраняется описанная в предыдущем разделе проблема: если включить статью в категорию посредством шаблона, а затем изменить категорию в шаблоне, то статьи будут содержаться в старой категории, хотя при их просмотре будет создаваться впечатление, что они содержатся в новой; и статьи будут на деле включены в новую категорию либо немедленно после их редактирования и сохранения, или через некоторое время (по мере отложенной обработки заданий сервером Традиции).

Кэширование

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

В таких случаях используйте системную гиперссылку-вкладку «обновить», последнюю на верху страницы, где она следует за гиперссылкою «следить» (или «не следить»).

Подстановка

Используя «подст:» (или «subst:») после двойных фигурных скобок заставляет выполнять подстановку текста шаблона или даже переменной в момент сохранения ссылающейся страницы.

Например, текущие дата и время:

{{подст:CURRENTDAY}} {{подст:CURRENTMONTHNAMEGEN}} {{подст:CURRENTYEAR}}, {{подст:CURRENTTIME}} (UTC)

подставится при сохранении страницы:

29 апреля 2007, 12:32 (UTC)

в то время как

{{CURRENTDAY}} {{CURRENTMONTHNAMEGEN}} {{CURRENTYEAR}}, {{CURRENTTIME}} (UTC)

каждый раз будет показывать текущее время:

22 декабря 2024, 14:17 (UTC)

Если нужно использовать подстановку для статьи из основного пространства имён, используйте конструкцию с двумя двоеточиями подряд. Так, следующий пример:

 {{subst::Страница}}

подставит в текст содержимое страницы Страница.

Альтернатива подстановке

• Для подстановки можно использовать msgnw, как описано выше.

Перенаправления

Когда страница, вызванная для включения, является страницей-перенаправлением, то включается содержимое страницы, на которую указывает перенаправление.

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

• Заголовок страницы-результата есть имя исходной страницы, а не включаемой страницы.
• Вся функциональность, (редактирование, обсуждение, watch-list, …) относится к включающей странице, и ничего (если не смотреть код) не связывает ее с включаемой страницей.
• Включающая страница лежит в тех же категориях, что и включаемая.
• Работают «двойные перенаправления» основанные на включении.

Ссылки на шаблон

Если ссылаться (ставить гиперссылки) на шаблоны, как на обычные статьи, то нельзя передать им параметры.

История изменений для страниц, содержащих шаблоны

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

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

См. также

• Шаблоны по назначению
• Функции парсера
• Job queue (англ.)