Wiki:Механизм шаблонов

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

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

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

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

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

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

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

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

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

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

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

Параметры

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

• {{имя шаблона|имя параметра 1=значение параметра 1|имя параметра 2=значение параметра 2}} — используются именованные параметры. Тогда в теле шаблона надо ссылаться на имя параметра: {{{имя параметра 1}}}, {{{имя параметра 2}}}.
• {{имя шаблона|значение параметра 1|значение параметра 2}} или {{имя шаблона|1=значение параметра 1|2=значение параметра 2}} — используются нумерованные параметры. Тогда в теле шаблона надо использовать порядковый номер параметра {{{1}}}, {{{2}}}.

Обратите внимание, что фигурные скобки вокруг имён параметров тройные, а не двойные.

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

При вызове шаблона выполняются два типа подстановок:

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

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

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

и он называется «Шаблон». Тогда при вызове шаблона в тексте страницы записью

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

шаблон будет развёрнут в

Начало [[Заглавная страница|Главная страница]] конец.

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

Если в строке вызова шаблона с именованными или нумерованными параметрами параметр не получил значение, то он остается нераскрытым текстом: с именованными параметрами {{{параметр 1}}}, с нумерованными параметрами {{{1}}}. Параметр будет раскрыт в дальнейшем, если вызвавшая шаблон статья включается в другую, где этот параметр задан.

Заметим, что вызов шаблона с именованными параметрами {{шаблон 1|параметр 1=|параметр 2=а}} делает параметр «параметр 1» определённым, равным пустой строке. Вызов {{шаблон 1|параметр 2=а}} задаёт параметр «параметр 2», «параметр 1» не определён.

Аналогично для шаблона с нумерованными параметрами: вызов {{шаблон 2||а}} делает первый параметр определённым, равным пустой строке, вызов {{шаблон 2|2=а}}) задает второй параметр, первый параметр не определен.

Когда код между вертикальными чёртами содержит знак равенства (например, а=б), вызов шаблона {{шаблон|а=б|в}} не присвоит значение «а=б» нумерованному параметру «1», а создаст параметр «а» со значением «б»; а вот {{шаблон|1=а=б|2=в}} всё сделает правильно. Единственный минус в том, что при вызове шаблона приходится нумеровать все параметры шаблона, если нумеруется хотя бы один. Для вставки символа равенства в значение параметра можно использовать цифровую ссылку на этот символ (англ. numeric character reference), записав =, или же использовать специальный шаблон {{=}}, вставляющий символ «=».

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

Чтобы не появлялся нераскрытый текст параметра с незаданным значением, используют условное значение параметра в тексте шаблона. Именованный или нумерованный параметр параметр внутри шаблона записывается в форме {{{параметр|альтернативный текст}}}. Если значение параметра не задано в вызове шаблона, то будет использован альтернативный текст; если задано значение параметра (в том числе пустое), то используется заданное значение. Например, альтернативный текст пустой: {{{параметр|}}}. Тогда если значение параметра задано при вызове шаблона — используется заданное значение; если значение параметра не задано — используется пустое значение, то есть в месте параметра никакой текст выводиться не будет.

В зависимости от значения параметра шаблона в текст статьи можно вставлять фрагменты. Для этой цели в тексте шаблона используются функции парсера, многие из которых являются частными случаями условного оператора: {{#if}} (также поддерживается {{#если}}) и другие. Синтаксис функции {{#if}} выглядит так:

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

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

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

Если проверяемый параметр шаблона записан в форме {{{параметр}}}, то непустое значение параметра означает: либо его значение задано непустым при вызове шаблона, либо оно не задано и остается неопределённым (и если вывести его на страницу, то мы так и получим: {{{параметр}}}). То есть мы не можем понять, задано значение параметра или нет. Чтобы иметь возможность вызывать шаблон с меньшим количеством параметров, чем в тексте шаблона, и чтобы незаданные параметры игнорировались, параметры в теле шаблона записываются в форме {{{параметр|}}}. Если при вызове шаблона задано непустое значение параметра, то оно будет использоваться. В противном случае используется условное значение параметра пусто.

Пример использования условного значения пусто для параметра sample:

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

Реальный пример использования функции парсера {{#if}}, которая является частным случаем условного оператора, можно найти в коде шаблона {{Userbox/Fidonet}}.

Эффект пустых строк

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

{{#if: {{{sample1|}}} | '''sample1'''! }}
{{#if: {{{sample2|}}} | '''sample2'''! }}
{{#if: {{{sample3|}}} | '''sample3'''! }}

Если все значения параметров заданы и не пустые, то результаты условных операторов выстраиваются в одну строку. Если значение второго параметра не задано или задано пустым, то между первым и третьим результатом появляется пустая строка. Такой же же эффект дает вариант со вторым оператором в полной форме: {{#if: {{{sample2|}}} | '''sample2'''!| |}}. Такое действие условного оператора позволяет увидеть по пустым строкам, что не все значения параметров заданы. Однако, если шаблон используется для последовательной вставки фрагментов текста, текст будет выглядеть разорванным.

Тот же пример, но второй условный оператор в полной форме и выводит неразрывный пробел. Результаты выводятся в строку:

{{#if: {{{sample1|}}} | '''sample1'''! }}
{{#if: {{{sample2|}}} | '''sample2'''! |{{nobr|}} }}
{{#if: {{{sample3|}}} | '''sample3'''! }}

Тот же пример, но второй условный оператор в сокращенной форме и после него стоит неразрывный пробел. Результаты также выводятся в строку:

{{#if: {{{sample1|}}} | '''sample1'''! }}
{{#if: {{{sample2|}}} | '''sample2'''! }}{{nobr|}}
{{#if: {{{sample3|}}} | '''sample3'''! }}

Примеры реализованы в таблице:

Варианты	Код при вызове шаблона	Код	Результат
Значения параметров заданы	|sample1=sample1 |sample2=sample2 |sample3=sample3	{{#if: {{{sample1|sample1}}} | '''sample1'''! }} {{#if: {{{sample2|sample2}}} | '''sample2'''! }} {{#if: {{{sample3|sample3}}} | '''sample3'''! }}	sample1! sample2! sample3!
Значение второго параметра не задано	|sample1=sample1 |sample2= |sample3=sample3	{{#if: {{{sample1|sample1}}} | '''sample1'''! }} {{#if: {{{sample2|}}} | '''sample2'''! }} {{#if: {{{sample3|sample3}}} | '''sample3'''! }}	sample1! sample3!
		{{#if: {{{sample1|sample1}}} | '''sample1'''! }} {{#if: {{{sample2|}}} | '''sample2'''! |{{nobr|}} }} {{#if: {{{sample3|sample3}}} | '''sample3'''! }}	sample1! sample3!
		{{#if: {{{sample1|sample1}}} | '''sample1'''! }} {{#if: {{{sample2|}}} | '''sample2'''! }}{{nobr|}} {{#if: {{{sample3|sample3}}} | '''sample3'''! }}	sample1! sample3!
		{{#if: {{{sample1|sample1}}} | '''sample1'''! }}{{nobr|}} {{#if: {{{sample2|}}} | '''sample2'''! }}{{nobr|}} {{#if: {{{sample3|sample3}}} | '''sample3'''! }}{{nobr|}}	sample1! sample3!

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

sample1!

(пустая строка)

sample3!

Если один перевод строки подавлен, например, малым неразрывным пробелом {{nobr|}}, то условный оператор во второй строки не выводит ни одного перевода строки и весь результат обработки выводится в строку:

sample1! sample3!

Эффект пустых строк может проявляться в шаблонах-карточках, когда на месте неопределённых параметров появляются пустые строки. Чтобы этого не происходило нужно исключать перевод строки между условными операторами. Этого можно добиться не только описанными выше, но и способами, исключающими все (и это обязательно!) переводы строки между условными операторами. Примеры реализованы в таблице:

Способ	Код	Результат
Писать все условные операторы в одну строку	{{#if: {{{sample1|sample1}}} | '''sample1'''! }}{{#if: {{{sample2|}}} | '''sample2'''! }}{{#if: {{{sample3|sample3}}} | '''sample3'''!}}	sample1!sample3!
Включать комментарии для исключения знака переноса	{{#if: {{{sample1|sample1}}} |'''sample1'''! }}<!-- разделитель -->{{#if: {{{sample2|}}} |'''sample2'''! }}<!-- разделитель -->{{#if: {{{sample3|sample3}}} |'''sample3'''! }}	sample1!sample3!
Делать переносы внутри условных операторов, а не между ними	{{ #if: {{{sample1|sample1}}} | '''sample1'''! }}{{ #if: {{{sample2|}}} | '''sample2'''! }}{{ #if: {{{sample3|sample3}}} | '''sample3'''! }}	sample1!sample3!

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

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

msgnw

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

а {{#tag:pre|{{msgnw:Заготовка}}}} как

{{Stub-meta|specification=Википедия:Шаблоны/Незавершённые статьи}}<noinclude>{{doc}}</noinclude>

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

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

Ограничения и возможности

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

Не получится вызывать шаблоны в зависимости от содержимого других шаблонов.

Предположим, у нас есть шаблон {{tctc}} с содержимым «tc», и шаблон {{tc}} с содержимым «Ура». Тогда вызов {{{{tctc}}}} даст текст

{{{{tctc}}}}

а не «Ура».

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

Правильное использование значения раскрытого шаблона при вызове другого шаблона

Тем не менее, вызов {{{{tctc}} }} даст желаемый текст «Ура».

То есть использовать следует с пробелом между парами закрывающих фигурных скобок.

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

Тег категории в шаблоне. Проблема с кэшированием

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

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

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

Теги noinclude, includeonly, onlyinclude

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

• Категоризация шаблонов самих по себе, а не тех страниц, в которые шаблон включён. Для шаблонов, имеющих страницы документации, рекомендуется проставлять категории в них, при этом там, напротив, используется <includeonly>.
• Интервики на аналогичные шаблоны на других языках. Аналогичным образом рекомендуется проставлять на странице документации.
• Страницы в пространстве имён MediaWiki.
• Текст с объяснением того, как использовать шаблон. Как правило, для этого создаётся документация шаблона.

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

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

Если текст обёрнут в теги <onlyinclude></onlyinclude>, при включении этой страницы в другую будет выводиться только фрагмент внутри этих тегов (фрагменты, если тегов несколько). Обёртывание в этот тег определённого фрагмента текста аналогично обёртыванию всего остального текста страницы, кроме обёрнутого в onlyinclude, в тег noinclude.

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

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

Кэширование

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

В таких случаях используйте action=purge, то есть вызывайте URL типа ru.wikipedia.org/wiki/Статья?action=purge. Существует стандартный гаджет часов (см. в настройках), по клику по которым очищается кэш страницы. Чтобы добавить ссылку на очистку кэша на произвольную страницу, используйте шаблон {{Очистить кэш}}.

Подстановка

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

Например, если мы напишем

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

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

23 августа 2012, 14:53 (UTC)

в то время как

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

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

19 апреля 2024, 09:39 (UTC)

А следующий код используется для приветствия новых участников:

{{подст:приветствие}} ~~~~

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

{{подст::Страница}}

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

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

• Напишите {{имя паттерна}}, затем воспользуйтесь страницей Служебная:Развёртка шаблонов, скопируйте оттуда результат и замените исходные {{имя паттерна}}.
• Аналогично можно использовать msgnw: (см. выше), имея в виду его ограничения.

Подстановка и функции парсера в примечаниях

Избегайте использования подстановки шаблонов в примечаниях (теги <ref></ref>) или проверяйте их правильную работу. Ошибка в MediaWiki препятствует разворачиванию некоторых (если не всех) подстановок в примечаниях. Для обхода проблемы сделана псевдофункция парсера {{#tag:}}; см. mw: Extension:Cite/Cite.php #Substitution and embedded parser functions (англ.). Например, {{subst:#tag:ref|{{subst:#time: j xg Y }}}} даст .

Та же проблема и решение относятся к функциям парсера, хотя их редко требуется вызывать из <ref> напрямую.

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

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

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

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

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

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

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

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

См. также

На «Мета-вики» имеется страница «Механизм шаблонов»

• Шаблоны Википедии
• Категория:Википедия:Шаблоны
• Википедия:Функции парсера
• Википедия:Пределы шаблонов
• Служебная:Развёртка шаблонов
• «Волшебные слова» в MediaWiki