Руниверсалис:Механизм шаблонов
Шаблоны — класс особых страниц в MediaWiki (программном обеспечении Руниверсалис), содержимое которых можно вставить в другие страницы. Причём это содержимое считывается при каждой загрузке страницы: изменения в шаблоне проявятся на страницах, их применяющих (за исключением случая, когда шаблон используется с подстановкой, — см. ниже). Далее описывается их работа.
Общая информация
Страницы шаблонов — полноценные вики-документы, для которых отведено своё пространство имён «Шаблон».
Вызывается шаблон помещением в текст редактируемой страницы записи {{имя шаблона}}. Первая буква имени может быть строчной или заглавной — без разницы. Имя статьи или шаблона чувствительно к регистру (кроме первого символа), а пробел эквивалентен подчёркиванию. При отображении страницы на месте вызова будет развернуто содержимое страницы Шаблон:Имя шаблона'.
Если представить, что в основном пространстве имён существует статья Имя шаблона, то можно вызвать её, поставив перед именем шаблона двоеточие: {{:Имя шаблона}}. Таким образом, любую страницу можно использовать как шаблон. Если вызвать картинку, загруженную в Руниверсалис, а не на Викисклад ({{Файл:Имя шаблона}}), или категорию ({{Категория:Имя шаблона}}), то будет подставлена описательная часть картинки или категории соответственно. Таким способом удобно:
- экспериментировать с шаблонами (не залезая в пространство шаблонов),
- «вытаскивать» подписи и описания картинок,
- изготавливать специальные составные статьи (например, для печати).
Если в редактируемую страницу поместить вызов шаблона {{/Имя подстраницы}}, то в этом месте в процессе предпросмотра отобразится содержимое её подстраницы.
Возможно также включение шаблона в шаблон, то есть вызов одного шаблона из другого или из него же самого́.
Переменные в шаблоне получают значения после вставки шаблона в статью, где он вызван. Если в шаблоне содержится подстановка {{PAGENAME}}, то она будет развёрнута в имя вызывающей статьи, а не в имя этого шаблона.
Список ссылок на используемые в тексте страницы шаблоны показывается в окне редактирования статьи, причём показываются все шаблоны, даже если редактируется только раздел документа, который не содержит шаблонов (при предварительном просмотре).
При вызове шаблона выполняются два типа подстановок:
- На странице вызова шаблона: имя шаблона в двойных фигурных скобках заменяется содержимым шаблона;
- На странице шаблона: имя или номер параметра шаблона в тройных фигурных скобках заменяется значением параметра, полученного со страницы вызова.
При указании ссылок на страницы-шаблоны (например, [[Шаблон:имя шаблона]]), нельзя указать параметры шаблона. Однако иногда это могло бы быть полезно, например, для получения ссылки на увеличенное изображение.
При просмотре предыдущих версий статей, содержащих шаблоны и/или картинки, всегда используются текущие версии шаблонов и картинок, то есть автоматически невозможно получить полные реконструкции (со ссылками на предыдущие версии шаблонов и картинок) предыдущих версий статей.
Параметры шаблона
Параметры шаблона могут быть именованными или нумерованными. Они различаются синтаксисом вызова шаблона и способ использования параметров.
На странице шаблона параметры должны быть окружены тройными фигурными скобками — {{{}}}.
Именованные и нумерованные параметры
Именованные параметры чувствительны к регистру символов.
{{имя шаблона |имя параметра 1=значение параметра 1 |имя параметра 2=значение параметра 2}}
В этом случае в теле шаблона (на странице шаблона) надо ссылаться на имя параметра: {{{имя параметра 1}}}, {{{имя параметра 2}}}.
Нумерованные параметры регистронезависимы.
{{имя шаблона |значение параметра 1 |значение параметра 2}} что эквивалентно {{имя шаблона |1=значение параметра 1 |2=значение параметра 2}}
В этом случае в теле шаблона (на странице шаблона) надо использовать порядковый номер параметра {{{1}}}, {{{2}}}.
Частные случаи: неопределённые и пустые значения
Если вызываемого параметра нет на странице шаблона, то он игнорируются.
Если вызываемый параметр не получил значение, то он остаётся нераскрытым текстом:
- с именованными параметрами
{{{параметр 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! |
Вики-разметка и перенос строк в параметрах
Будьте аккуратны с вики-разметкой около параметров. Вики-разметка в шаблоне может взаимодействовать с вики-разметкой внутри параметра и вики-разметкой текста окружающего шаблон. Например, для ''<span>{{{1}}}</span>'' и |1=''текст'' получим <i><span></i>текст<i></span></i> — разрыв span. Для ''{{{1}}}'' и |1=''текст'' получим <i></i>текст<i></i> — некорректное использование разметки: должна давать курсив, но тут она его лишает. Соответственно и обратные примеры, когда совпадающая вики-разметка есть в тексте до использования шаблона. Этого можно избежать, задавая CSS-правила тегам и теги i/b без вики-разметки, но проблемные варианты использования викиразметки всё ещё возможны — ''{{lang-en|1=''текст''}}'' закроет теги раньше времени <i><span style="font-style:italic;"></span></i>текст<i></i> вместо ожидаемого <i><span style="font-style:italic;"><i>текст</i></span></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}}'''.
Пустой параметр {{шаблон|}} может cхлопнуть вики-разметку '''{{{1|}}}'''., которая неправильно развернётся - ''''''. - '<b><i>.</i></b>. Беспроблемный вариант {{#if:{{{1|}}}|'''{{{1}}}'''}}.
Просмотр шаблона
Чтобы увидеть «сырое» содержимое шаблона, нужно смотреть на шаблон в режиме редактирования, без подстановок вроде {{PAGENAME}}, которые могут раскрыться.
Для показа необработанного содержимого шаблона можно использовать кодовый «волшебный» префикс msgnw: (от «message, nowiki»). Например, {{Памятник архитектуры}} на странице будет выглядеть так:
А {{#tag:pre|{{msgnw:Памятник архитектуры}}}} — так:
<span class="noprint">{{#ifeq:{{{тип}}}|выявленный объект|[[Файл:Sight symbol grey.svg|link=|alt=|14px]]|[[Файл:Sight symbol black.svg|link=|alt=|14px]]}} <span title="Памятник архитектуры" style="font-size:85%; cursor:arrow; margin-left:0.2em; color:#888">[[Памятник архитектуры|памятник архитектуры]]{{#If:{{{тип|}}}| ({{{тип}}})|}}</span></span><noinclude> {{doc}}<!-- категории должны добавляться на страницу документации --> </noinclude>
В некоторые шаблоны разумно зашить, приглашающую поправить шаблон, например, если шаблон ещё не устоялся, или если его содержимое может часто изменяться. Такую ссылку можно «зашить» внутрь самого шаблона, например, с помощью {{править}}.
Ограничения
Использование вложенных двойных или тройных фигурных скобок внутри двойных вложенных скобок
При использовании обычной формы вызова не получится вызывать те или иные шаблоны в зависимости от содержимого других шаблонов.
Предположим, у нас есть шаблон {{шблшбл}} с содержимым «шбл», и шаблон {{шбл}} с содержимым «Ура». Тогда вызов {{{{шблшбл}}}} даст текст «{{{{шблшбл}}}}», а не «Ура», как можно было бы подумать, предположив, что {{шблшбл}} раскроется в «шбл», а {{шбл}} — в «Ура».
Тем не менее, вызов {{{{шблшбл}} }} даст желаемый текст «Ура». То есть следует ставить пробел между парами закрывающих фигурных скобок.
Также можно использовать значения переданных переменных при указании значений переменных для вызываемого шаблона.
Категории в шаблоне и проблема с кэшированием
Если шаблон содержит код категории, то в указанную категорию помещается не только шаблон, но и все страницы, включающие его, поэтому удобно использовать шаблоны для рубрикации статей.
Но может возникнуть проблема с кэшированием — если поменять категорию у шаблона, то категория у включающих этот шаблон страниц поменяется не сразу, а только через некоторое время, после того как серверы выполнят необходимые действия. При необходимости быстро обновить большое количество статей с изменённым шаблоном можно обратиться к ботоводам с запросом на проведение нулевых правок. Кроме того, категория немедленно меняется у только что отредактированных статей, включая статьи, в которых сделана нулевая правка.
Служебные категории включаются в статьи обычно шаблонами, предназначенными для пометки статей (типа {{stub}}), а классифицирующие — с помощью шаблонов-карточек и однородных навигационных шаблонов.
Ручной сброс кэша
Правка шаблона автоматически сбрасывает кэширование всех статей, напрямую использующих этот шаблон. Однако, в случае с косвенными зависимостями (шаблоны, зависящие от параметров и т. п.), внутренний кэш системы не сбрасывается и стандартное обновление страницы в браузере может не помочь.
В таких случаях используйте action=purge, то есть вызывайте URL типа https://ru.wikipedia.org/wiki/Статья?action=purge. Существует стандартный гаджет часов (см. в настройках), по клику по которым очищается кэш страницы. Чтобы добавить ссылку на очистку кэша на произвольную страницу, используйте шаблон {{очистить кэш}}.
Если шаблон рассчитан на постоянную работу с косвенными зависимостями, можно воспользоваться шаблоном {{очищать кэш}}, чтобы заставить бота периодически сбрасывать кэш страницы.
Теги noinclude, includeonly, onlyinclude
Всё, что находится между тегами <noinclude> и </noinclude>, будет обрабатываться и показываться только в случае, когда шаблон показывается непосредственно, не включённым в другую страницу. Возможные применения:
- Категоризация шаблонов самих по себе, а не тех страниц, в которые шаблон включён. Для шаблонов, имеющих страницы документации, рекомендуется проставлять категории в них, при этом там, напротив, используется
<includeonly>. - Страницы в пространстве имён MediaWiki.
- Текст с объяснением того, как использовать шаблон. Как правило, для этого создаётся документация шаблона.
Тег <includeonly> обладает противоположным действием. Текст между <includeonly> и </includeonly> будет обрабатываться и показываться только тогда, когда шаблон включён в статью. Очевидное применение:
- включение всех статей, содержащих шаблон, в категорию (при этом сам шаблон в категорию не попадёт).
Если текст обёрнут в теги <onlyinclude></onlyinclude>, при включении этой страницы в другую будет выводиться только фрагмент внутри этих тегов (фрагменты, если тегов несколько). Обёртывание в этот тег определённого фрагмента текста аналогично обёртыванию всего остального текста страницы, кроме обёрнутого в onlyinclude, в тег noinclude.
Не допускайте пустых строк вокруг конструкций <noinclude> и <includeonly>, так как пустая строка будет интерпретироваться как перенос строки, который будет внесён шаблоном в статью.
Следует отметить, что при этом сохраняется описанная в предыдущем разделе проблема: если включить статью в категорию посредством шаблона, а затем изменить категорию в шаблоне, то статьи будут содержаться в старой категории, хотя при их просмотре будет создаваться впечатление, что они содержатся в новой; и статьи будут на деле включены в новую категорию либо немедленно после их редактирования и сохранения, или через некоторое время (по мере отложенной обработки заданий сервером).
Подстановка
Конструкция подст: (или subst:) после двойных фигурных скобок заставляет выполнять подстановку текста шаблона или даже переменной в момент сохранения ссылающейся страницы.
Например, если мы напишем
{{подст:CURRENTDAY}} {{подст:CURRENTMONTHNAMEGEN}} {{подст:CURRENTYEAR}}, {{подст:CURRENTTIME}} (UTC)
при сохранении страницы подставятся текущие дата и время:
23 августа 2012, 14:53 (UTC)
в то время как
{{CURRENTDAY}} {{CURRENTMONTHNAMEGEN}} {{CURRENTYEAR}}, {{CURRENTTIME}} (UTC)
каждый раз будет показывать текущее время:
25 апреля 2024, 08: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 }}}} даст[2].
- ↑ https://html.spec.whatwg.org/#syntax-charref
- ↑ 25 апреля 2024
Та же проблема и решение относятся к функциям парсера, хотя их редко требуется вызывать из <ref> напрямую.
Перенаправления
Если страница, вызванная для включения, является страницей-перенаправлением, то включается содержимое страницы, на которую указывает перенаправление.
Страница, которая ничего не содержит, кроме включения другой страницы, отличается от страницы-перенаправления, например, следующим:
- заголовок страницы-результата есть имя исходной страницы, а не включаемой страницы;
- вся функциональность (редактирование, обсуждение, список наблюдения и т. п.) относится к включающей странице, и ничего (если не смотреть код) не связывает её с включаемой страницей;
- включающая страница лежит в тех же категориях, что и включаемая;
- работают «двойные перенаправления», основанные на включении.
Пример работы
Параметром шаблона может быть ссылка на другую статью.
Пример работы шаблона.
Пусть, у нас есть страница шаблона Шаблон:Песенка и статья на странице Статья.
Пусть, у нас на странице Шаблон:Песенка записан текст:
{{{1}}} — жу-жу-жу…
Если на странице редактирования Статья создать обращение к шаблону Песенка с параметром «Ля-ля-ля»
{{Песенка|Ля-ля-ля}}
тогда на записанной странице Статья наш шаблон будет развёрнут в текст:
Ля-ля-ля — жу-жу-жу…
Т. е. механизм работы шаблона следующий: на странице Статья из имеющегося шаблона {{Песенка|Ля-ля-ля}} считывается первый параметр (он находится после первого знака | и является простым текстом Ля-ля-ля); затем этот считанный параметр вставляется на странице Шаблон:Песенка вместо {{{1}}}
После этого всё содержимое страницы шаблона Песенка с произведённой подстановкой Ля-ля-ля — жу-жу-жу… возвращается на страницу Статья, заменяя собой место вызова шаблона {{Песенка|Ля-ля-ля}}