Википедия:Механизм шаблонов
Шаблоны — класс особых страниц в MediaWiki (программном обеспечении Википедии), содержимое которых можно вставить в другие страницы. Причём это содержимое считывается при каждой загрузке страницы: изменения в шаблоне проявятся на страницах, их применяющих (за исключением случая, когда шаблон используется с подстановкой, — см. ниже). Ниже описывается их работа.
Общая информацияПравить
Страницы шаблонов — полноценные вики-документы, для которых отведено своё пространство имён «Шаблон». В Википедии их позволено править любому участнику.
Вызывается шаблон помещением в текст редактируемой страницы записи {{имя шаблона}}
и, если нужно, после имени шаблона указываются значения параметров. Первая буква имени может быть строчной или заглавной — без разницы. При отображении страницы на месте вызова будет развёрнуто содержимое страницы Шаблон:Имя шаблона. Если страница не существует, то вызов будет отображён как ссылка на несуществующую статью шаблона. Поэтому, чтобы не появлялась красная ссылка «Шаблон:Несуществующий шаблон», удостоверьтесь в существовании вызываемых шаблонов предпросмотром страницы до сохранения правки.
Если представить, что в основном пространстве имён существует статья Имя шаблона, то можно вызвать её, поставив перед именем шаблона двоеточие: {{:Имя шаблона}}
. Таким образом, любую страницу можно использовать как шаблон. Если вызвать картинку, загруженную в Википедию, а не на Викисклад ({{Файл:Имя шаблона}}
), или категорию ({{Категория:Имя шаблона}}
), то будет подставлена описательная часть картинки или категории соответственно. Таким способом удобно:
- экспериментировать с шаблонами (не залезая в пространство шаблонов),
- «вытаскивать» подписи и описания картинок,
- изготавливать специальные составные статьи (например, для печати).
Если в редактируемую страницу поместить вызов шаблона {{/Имя подстраницы}}
, то в этом месте в процессе предпросмотра отобразится содержимое её подстраницы. В пространстве имён «Википедия» часто используется шаблон {{/Шапка}}
. Если перейти в режим правки страницы Википедия:Заявки на статус патрулирующего, то в её начале можно увидеть вызов шаблона {{/Шапка}}
. В режиме предпросмотра отображается текст подстраницы Википедия:Заявки на статус патрулирующего/Шапка.
Как обычно в MediaWiki, имя статьи или шаблона чувствительно к регистру (кроме первого символа), а пробел эквивалентен подчёркиванию.
Возможно также включение шаблона в шаблон, то есть вызов одного шаблона из другого или из него же самого́.
Переменные (см. ниже) в шаблоне получают значения после вставки шаблона в статью, где он вызван. Если в шаблоне содержится подстановка {{PAGENAME}}
, то она будет развёрнута в имя вызывающей статьи, а не в имя этого шаблона.
Список ссылок на используемые в тексте страницы шаблоны показывается в окне редактирования статьи, причём показываются все шаблоны, даже если редактируется только раздел документа, который не содержит шаблонов (при предварительном просмотре).
ПараметрыПравить
Параметры шаблона могут быть именованными или нумерованными. Синтаксис вызова шаблона и способ использования параметров в теле шаблона в этих двух случаях будут различаться:
- В первом случае — на странице с вызовом шаблона используются именованные параметры:
{{имя шаблона |имя параметра 1=значение параметра 1 |имя параметра 2=значение параметра 2}}
В этом случае в теле шаблона (на странице шаблона) надо ссылаться на имя параметра: {{{имя параметра 1}}}
, {{{имя параметра 2}}}
.
- Во втором случае — на странице с вызовом шаблона используются параметры, не имеющие имени, которые автоматически нумеруются или явно нумерованные параметры:
{{имя шаблона |значение параметра 1 |значение параметра 2}}
или {{имя шаблона |1=значение параметра 1 |2=значение параметра 2}}
В этом случае в теле шаблона (на странице шаблона) надо использовать порядковый номер параметра {{{1}}}
, {{{2}}}
.
Обратите внимание, что фигурные скобки вокруг имён параметров на странице шаблона должны быть тройными {{{
}}}
.
Параметры, присутствующие на странице с вызовом шаблона, но отсутствующие в теле шаблона (на странице шаблона), игнорируются. Именованные параметры чувствительны к регистру символов. При вызове шаблона выполняются два типа подстановок:
- На странице вызова шаблона: имя шаблона в двойных фигурных скобках заменяется содержимым шаблона;
- На странице шаблона: имя или номер параметра шаблона в тройных фигурных скобках заменяется значением параметра, полученного со страницы вызова.
Параметром шаблона может быть ссылка на другую статью.
Пример работы шаблона.
Пусть, у нас есть страница шаблона Шаблон:Песенка и статья на странице Статья.
Пусть, у нас на странице Шаблон:Песенка записан текст:
{{{1}}} — жу-жу-жу…
Если на странице редактирования Статья создать обращение к шаблону Песенка с параметром «Ля-ля-ля»
{{Песенка|Ля-ля-ля}}
тогда на записанной странице Статья наш шаблон будет развёрнут в текст:
Ля-ля-ля — жу-жу-жу…
Т. е. механизм работы шаблона следующий: на странице Статья из имеющегося шаблона {{Песенка|Ля-ля-ля}}
считывается первый параметр (он находится после первого знака |
и является простым текстом Ля-ля-ля
); затем этот считанный параметр вставляется на странице Шаблон:Песенка вместо {{{1}}}
После этого всё содержимое страницы шаблона Песенка с произведённой подстановкой Ля-ля-ля — жу-жу-жу…
возвращается на страницу Статья, заменяя собой место вызова шаблона .
{{Песенка|Ля-ля-ля}}
Неопределённые и пустые значения параметровПравить
Если в строке вызова шаблона с именованными или нумерованными параметрами параметр не получил значение, то он остаётся нераскрытым текстом: с именованными параметрами {{{параметр 1}}}
, с нумерованными параметрами {{{1}}}
. Параметр будет раскрыт в дальнейшем, если вызвавшая шаблон статья включается в другую, где этот параметр задан.
Заметим, что вызов шаблона с именованными параметрами {{шаблон 1 |параметр 1= |параметр 2=а}}
делает параметр «параметр 1» определённым, равным пустой строке. Вызов {{шаблон 1 |параметр 2=а}}
задаёт параметр «параметр 2», «параметр 1» не определён.
Аналогично для шаблона с нумерованными параметрами: вызов {{шаблон 2||а}}
делает первый параметр определённым, равным пустой строке, вызов {{шаблон 2|2=а}}
) задаёт второй параметр, первый параметр не определён.
Когда код между вертикальными чертами содержит знак равенства (например, а=б
), вызов шаблона {{шаблон |а=б |в}}
не присвоит значение «а=б» нумерованному параметру «1», а создаст параметр «а» со значением «б»; а вот {{шаблон |1=а=б |2=в}}
всё сделает правильно. Единственный минус в том, что при вызове шаблона приходится нумеровать все параметры шаблона, если нумеруется хотя бы один. Для вставки символа равенства в значение параметра можно использовать HTML ссылку на этот символ (англ. character reference)[1], записав =
=
, или же использовать шаблон {{=}}, вставляющий символ «=» {{шаблон |a{{=}}b}}
.
Условное значение параметраПравить
Чтобы не появлялся нераскрытый текст параметра с незаданным значением, используют условное значение параметра в тексте шаблона.
Именованный или нумерованный параметр параметр внутри шаблона записывается в форме {{{параметр|альтернативный текст}}}
.
Если в вызове шаблона значение параметра не задано |параметр =
, то при раскрытии шаблона вместо значения параметра будет подставлен альтернативный текст.
Если альтернативный текст пустой {{{параметр|}}}
, используется пустое значение, то есть в месте параметра никакой текст выводиться не будет.
В зависимости от значения параметра шаблона в текст статьи можно вставлять фрагменты. Для этой цели в тексте шаблона используются функции парсера, многие из которых являются частными случаями условного оператора: {{#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!
Эффект пустых строк может проявляться в шаблонах-карточках, когда на месте неопределённых параметров появляются пустые строки. Чтобы этого не происходило нужно исключать перевод строки между условными операторами. Этого можно добиться не только описанными выше, но и способами, исключающими все (и это обязательно!) переводы строки между условными операторами. Примеры реализованы в таблице:
Способ | Код | Результат |
---|---|---|
Писать все условные операторы в одну строку |
|
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! |
Вики-разметка и перенос строк в параметрахПравить
Будьте аккуратны с вики-разметкой около параметров. Вики-разметка в шаблоне может взаимодействовать с вики-разметкой внутри параметра и вики-разметкой текста, окружающего шаблон. Например, для ''<img>{{{1}}}</img>''
и |1=''текст''
получим <i><img></i>текст<i></img></i>
— разрыв img. Для ''{{{1}}}''
и |1=''текст''
получим <i></i>текст<i></i>
— некорректное использование разметки: должна давать курсив, но тут она его лишает. Соответственно и обратные примеры, когда совпадающая вики-разметка есть в тексте до использования шаблона. Этого можно избежать, задавая CSS-правила тегам и теги i/b без вики-разметки, но проблемные варианты использования викиразметки всё ещё возможны — ''{{lang-en|1=''текст''}}''
закроет теги раньше времени: <i><img style="font-style:italic;"></img></i>текст<i></i>
вместо ожидаемого <i><img style="font-style:italic;"><i>текст</i></img></i>
, тогда нужен поиск компромиссных вариантов по желаемому использованию.
Параметр может приходить с переносом на новую строку.
вызов шаблона | шаблон | развёртка | html |
|param1=text1 |param2= |
text '''{{{param1|no-text}}}'''. |
text '''text1 '''. |
text <b>text1</b> <p><b>.</b> </p> |
Перевод строки пропадёт в случае |param1=text1|param2=
или '''{{#if:{{{param1|}}}|{{{param1|}}}|no-text}}'''
.
Пустой параметр {{шаблон|}}
может схлопнуть вики-разметку '''{{{1|}}}'''.
, которая неправильно развернётся - ''''''.
- '<b><i>.</i></b>
. Беспроблемный вариант {{#if:{{{1|}}}|'''{{{1}}}'''}}
.
Просмотр содержимого шаблонаПравить
Чтобы увидеть «сырое» содержимое шаблона (подстановки параметров и т. д.), нужно смотреть на шаблон в режиме редактирования, поскольку в противном случае некоторые подстановки вроде {{PAGENAME}}
могут раскрыться.
msgnwПравить
Для показа необработанного содержимого шаблона можно использовать кодовый «волшебный» префикс msgnw:
(от «message, nowiki»). Например, {{Заготовка}}
на странице будет выглядеть так:
- Это статья-заготовка. Вы можете помочь проекту, дополнив эту статью, как и любую другую в Википедии. Нажмите и узнайте подробности.
А {{#tag:pre|{{msgnw:Заготовка}}}}
— так:
{{Stub-meta|specification=Википедия:Шаблоны/Незавершённые статьи}}<noinclude>{{doc}}</noinclude>
Ссылка на редактирование шаблонаПравить
Ссылка «[править]» на каждой странице-статье не позволяет редактировать текст используемого шаблона, а иногда желательно иметь такую ссылку (приглашающую поправить шаблон, например, если шаблон ещё не устоялся, или если его содержимое может часто изменяться). Такую ссылку можно «зашить» внутрь самого шаблона, даже более того — сделать шаблоном, который можно использовать внутри других шаблонов. См. шаблон {{править}}.
Ограничения и возможностиПравить
Использование вложенных двойных или тройных фигурных скобок внутри двойных вложенных скобокПравить
При использовании обычной формы вызова не получится вызывать те или иные шаблоны в зависимости от содержимого других шаблонов.
Предположим, у нас есть шаблон {{шблшбл}}
с содержимым «шбл», и шаблон {{шбл}}
с содержимым «Ура». Тогда вызов {{{{шблшбл}}}}
даст текст «{{{{шблшбл}}}}», а не «Ура», как можно было бы подумать, предположив, что {{шблшбл}}
раскроется в «шбл», а {{шбл}}
— в «Ура».
Тем не менее, вызов {{{{шблшбл}} }}
даст желаемый текст «Ура». То есть следует ставить пробел между парами закрывающих фигурных скобок.
Также можно использовать значения переданных переменных при указании значений переменных для вызываемого шаблона.
Тег категории в шаблоне. Проблема с кэшированиемПравить
Если шаблон содержит код категории, то в указанную категорию помещается не только шаблон, но и все страницы, включающие его, поэтому удобно использовать шаблоны для рубрикации статей.
Но может возникнуть проблема с кэшированием — если поменять категорию у шаблона, то категория у включающих этот шаблон страниц поменяется не сразу, а только через некоторое время, после того как серверы Википедии выполнят необходимые действия. При необходимости быстро обновить большое количество статей с изменённым шаблоном можно обратиться к ботоводам с запросом на проведение нулевых правок. Кроме того, категория немедленно меняется у только что отредактированных статей, включая статьи, в которых сделана нулевая правка.
Служебные категории включаются в статьи обычно шаблонами, предназначенными для пометки статей (типа {{stub}}), а классифицирующие — с помощью шаблонов-карточек и однородных навигационных шаблонов.
Теги noinclude, includeonly, onlyincludeПравить
Всё, что находится между тегами <noinclude>
и </noinclude>
, будет обрабатываться и показываться только в случае, когда шаблон показывается непосредственно, не включённым в другую страницу. Возможные применения:
- Категоризация шаблонов самих по себе, а не тех страниц, в которые шаблон включён. Для шаблонов, имеющих страницы документации, рекомендуется проставлять категории в них, при этом там, напротив, используется
<includeonly>
. - Страницы в пространстве имён MediaWiki.
- Текст с объяснением того, как использовать шаблон. Как правило, для этого создаётся документация шаблона.
Тег <includeonly>
обладает противоположным действием. Текст между <includeonly>
и </includeonly>
будет обрабатываться и показываться только тогда, когда шаблон включён в статью. Очевидное применение:
- включение всех статей, содержащих шаблон, в категорию (при этом сам шаблон в категорию не попадёт).
Если текст обёрнут в теги <onlyinclude></onlyinclude>
, при включении этой страницы в другую будет выводиться только фрагмент внутри этих тегов (фрагменты, если тегов несколько). Обёртывание в этот тег определённого фрагмента текста аналогично обёртыванию всего остального текста страницы, кроме обёрнутого в onlyinclude
, в тег noinclude
.
Не допускайте пустых строк вокруг конструкций <noinclude>
и <includeonly>
, так как пустая строка будет интерпретироваться как перенос строки, который будет внесён шаблоном в статью.
Следует отметить, что при этом сохраняется описанная в предыдущем разделе проблема: если включить статью в категорию посредством шаблона, а затем изменить категорию в шаблоне, то статьи будут содержаться в старой категории, хотя при их просмотре будет создаваться впечатление, что они содержатся в новой; и статьи будут на деле включены в новую категорию либо немедленно после их редактирования и сохранения, или через некоторое время (по мере отложенной обработки заданий сервером Википедии).
КэшированиеПравить
Правка шаблона автоматически сбрасывает кэширование всех статей, напрямую использующих этот шаблон. Однако, в случае с косвенными зависимостями (шаблоны, зависящие от параметров и т. п.), внутренний кэш системы не сбрасывается и стандартное обновление страницы в браузере может не помочь.
В таких случаях используйте action=purge, то есть вызывайте URL типа https://ru.wikipedia.org/wiki/Статья?action=purge. Существует стандартный гаджет часов (см. в настройках), по клику по которым очищается кэш страницы. Чтобы добавить ссылку на очистку кэша на произвольную страницу, используйте шаблон {{очистить кэш}}.
Если шаблон рассчитан на постоянную работу с косвенными зависимостями, можно воспользоваться шаблоном {{очищать кэш}}, чтобы заставить бота периодически сбрасывать кэш страницы.
ПодстановкаПравить
Конструкция подст:
(или subst:
) после двойных фигурных скобок заставляет выполнять подстановку текста шаблона или даже переменной в момент сохранения ссылающейся страницы.
Например, если мы напишем
{{подст:CURRENTDAY}} {{подст:CURRENTMONTHNAMEGEN}} {{подст:CURRENTYEAR}}, {{подст:CURRENTTIME}} (UTC)
при сохранении страницы подставятся текущие дата и время:
23 августа 2012, 14:53 (UTC)
в то время как
{{CURRENTDAY}} {{CURRENTMONTHNAMEGEN}} {{CURRENTYEAR}}, {{CURRENTTIME}} (UTC)
каждый раз будет показывать текущее время:
11 февраля 2023, 06:30 (UTC)
А следующий код используется для приветствия новых участников:
{{подст:приветствие}} ~~~~
Если нужно использовать подстановку для статьи из основного пространства имён, используйте конструкцию с двумя двоеточиями подряд. Так, следующий пример:
{{подст::Страница}}
подставит в текст содержимое страницы Страница.
Альтернатива подстановкеПравить
- Напишите
{{имя шаблона}}
, затем воспользуйтесь страницей Служебная:Развёртка шаблонов, скопируйте оттуда результат и замените исходные{{имя шаблона}}
. - Аналогично можно использовать
msgnw:
(см. выше), имея в виду его ограничения.
Подстановка и функции парсера в примечанияхПравить
Избегайте использования подстановки шаблонов в примечаниях (теги <ref></ref>
) или проверяйте их правильную работу. Ошибка в MediaWiki препятствует разворачиванию некоторых (если не всех) подстановок в примечаниях. Для обхода проблемы сделана псевдофункция парсера {{#tag:}}
; см. mw: Extension:Cite/Cite.php #Substitution and embedded parser functions (англ.). Например, {{subst:#tag:ref|{{subst:#time: j xg Y }}}}
даст[2].
- ↑ https://html.spec.whatwg.org/#syntax-charref
- ↑ 11 февраля 2023
Та же проблема и решение относятся к функциям парсера, хотя их редко требуется вызывать из <ref>
напрямую.
ПеренаправленияПравить
Если страница, вызванная для включения, является страницей-перенаправлением, то включается содержимое страницы, на которую указывает перенаправление.
Страница, которая ничего не содержит, кроме включения другой страницы, отличается от страницы-перенаправления, например, следующим:
- заголовок страницы-результата есть имя исходной страницы, а не включаемой страницы;
- вся функциональность (редактирование, обсуждение, список наблюдения и т. п.) относится к включающей странице, и ничего (если не смотреть код) не связывает её с включаемой страницей;
- включающая страница лежит в тех же категориях, что и включаемая;
- работают «двойные перенаправления», основанные на включении.
Ссылки на шаблонПравить
Отметим, что при указании ссылок на страницы-шаблоны (например, [[Шаблон:имя шаблона]]), нельзя указать параметры шаблона. Однако иногда это могло бы быть полезно, например, для получения ссылки на увеличенное изображение.
История изменений для страниц, содержащих шаблоныПравить
При просмотре предыдущих версий статей, содержащих шаблоны и/или картинки, всегда используются текущие версии шаблонов и картинок, то есть автоматически невозможно получить полные реконструкции (со ссылками на предыдущие версии шаблонов и картинок) предыдущих версий статей.