Участник:BabylonAS/Песочница/Альфа/Справка:Шаблоны и включения
Шаблоны — мощное средство, позволяющее использовать один участок вики-кода (часто настраиваемый параметрами) несколько раз, благодаря механизму включения страниц. Практически ни одна статья на Minecraft Wiki не обходится без использования шаблонов.
Описание
Шаблоны — особые страницы, которые используются внутри других страниц через механизм включения, позволяющий их содержимому появиться в основной странице. Вообще говоря, включить можно почти любую страницу; шаблоны создаются специально для использования в других страницах. В этом смысле они похожи на функции в программировании.
Шаблоны позволяют значительно упростить вставку однотипных конструкций в статьях. Их применение позволяет не только избавиться от необходимости заново копировать один и тот же код (с возможными изменениями), но и централизованно изменять эти конструкции одновременно на всех страницах. С другой стороны, необходимо проявлять аккуратность при изменении шаблона, используемого на множестве страниц. Поэтому ряд шаблонов защищён от редактирования определёнными группами участников.
Шаблоны могут поддерживать параметры, которые передаются им при включении. Тогда шаблон может настраиваться в зависимости от параметров и их значений. Параметры поддерживаются большинством шаблонов, в частности такими, как
Бо́льшая часть шаблонов созданы для общего использования и помещаются в отдельное пространство имён Шаблон:. Но многие включаемые страницы могут располагаться вне этого пространства и использоваться в качестве шаблонов (например, Обсуждение:Шалкер/выбор, Заглавная страница/style). Участники могут создавать в своём пространстве шаблоны, которые являются неподходящими для пространства шаблонов или же незаконченными, или которые предназначены для личного пользования (например, навигация по пространству какого-либо участника; пример — Участник:Ivan r/Навигация).
Включение
Для включения страницы (шаблона) в состав другой страницы используется следующий синтаксис:
{{Имя шаблона}}для включения без параметров;{{Имя шаблона|параметры...}}для включения с параметрами. Параметры отделяются вертикальной чертой|.
Правила по структуре Имени шаблона схожи с правилами по структуре имени целевой страницы в ссылке, но без поддержки синтаксиса /подстраница/ и якорей. По умолчанию также подразумевается, что Имя шаблона относится к странице в пространстве имён Шаблон:, а не к основному пространству статей (чтобы включить страницу из него, следует перед его названием добавить двоеточие :). Так, {{Заготовка}} вызовет включение шаблона Шаблон:Заготовка ({{Шаблон:Заготовка}} сделает то же самое), {{Обсуждение:Шалкер/выбор}} — страницы Обсуждение:Шалкер/выбор, а {{:Заглавная страница/edition}} — страницы Заглавная страница/edition.
У каждого параметра есть своё имя и значение. Передаваемые параметры при этом делятся на последовательные и именованные. Для последовательных указывается только значение, а имя указывается неявным образом в соответствии с порядковым номером, начиная с 1. В случае именованных параметров имя передаётся явным образом, а значение указывается через знак «равно» (имя=значение; например, текст=Текст сообщения). Оба вида параметров могут комбинироваться. Допускается явное указывание числового значения в качестве имени. В самом шаблоне параметры доступны через синтаксис {{{имя}}} (см. Структура).
При наличии знака «равно» будет в качестве имени параметра указано всё, что расположено слева от знака. Если установлено несколько таких знаков, то разделять имя и значение будет первый из них. Если в значении последовательного параметра необходимо использовать знак «равно», то следует прибегнуть к одному из двух способов:
- Заменить каждый знак «равно» в параметре на вызов шаблона
{{Мой шаблон|x >{{=}} 12}}. Этот способ более наглядный, но менее эффективный, особенно если в значении используются несколько знаков равенства. - Напрямую указать номер параметра в качестве его имени. Например:
{{Мой шаблон|2=x = y = z = 12}}. Этот способ исключает затраты на включения лишних шаблонов и, поэтому, считается более эффективным.
Чтение параметров идёт слева направо (от первого к последнему). Если один и тот же параметр указывается несколько раз, то шаблоном принимается последнее указанное ему значение, а страница с таким шаблоном включается движком вики в категорию «Страницы, использующие повторяющиеся аргументы в вызовах шаблонов».
Включаемые страницы (а также функции парсера) можно подстанавливать. Это означает, что включаемое содержимое при редактировании будет записано напрямую, шаблон «раскроется». Для этого перед названием шаблона необходимо вставить фрагмент subst:, подст: или подстановка:. Например, если {{Мой шаблон}} состоит из кода Внимание, то при сохранении конструкция {{subst:Мой шаблон}} будет заменена на этот же текст. Однако, если в самом шаблоне есть другие шаблоны или же функции парсера, они не будут раскрыты. Чтобы они так делали, необходимо у каждого вызова после открывающих фигурных скобок указать конструкцию |safesubst:. Фактически это использование параметра (см. Структура) с пустым названием (которое, как ни странно, допустимо); если он не указан (в большинстве случаев это будет так), то указывается значение по правую сторону вертикальной черты, то есть safesubst:. safesubst: отличается от обычного subst: тем, что при обычном включении (а не подстановке) того шаблона, где он используется, он игнорируется. Использование безымянного параметра требуется для исключения преждевременной подстановки.
Структура
Многие шаблоны имеют сложный синтаксис, непонятный обычному читателю или начинающему редактору. Часто он состоит из использований параметров, использований так называемых «волшебных слов» (в первую очередь — функций парсера), тегов, указывающих, какой текст включать или не включать, и прочего содержимого, которое может не использоваться в статьях.
Для использования параметров в шаблоне используется синтаксис |параметр=. Если параметр не указан, то этот текст передаётся как есть. Если вместо этого нужно указать значение по умолчанию, то используется синтаксис |параметр=умолчание, при этом умолчание может быть пустым. Заметьте, что умолчание передаётся тогда и только тогда, когда параметр не указывается вообще. Например, если шаблон {{Мой шаблон}} состоит из текста |1=б, то {{Мой шаблон|а}} и {{Мой шаблон}} выведут соответственно а и б, а вот {{Мой шаблон|}} не выведет ничего, поскольку в этом случае передаётся хоть и пустое, но всё же значение. Для исправления этого следует использовать условные функции парсера, в данном случае {{#if: {{{1|}}} | {{{1}}}| б}}.
Часто шаблоны используют так называемые функции парсера. Подробно некоторые из них описаны в статье на вики-проекте по MediaWiki (ПО, на котором работает Minecraft Wiki): Help:Extension:ParserFunctions (на английском языке; доступен русский перевод, но он неполный и не совсем хорошего качества). Функции парсера используют синтаксис, схожий с вызовами самих шаблонов — сравните вызовы шаблона и вызов функции парсера #if: наверху. Одна из часто используемых функций парсера — {{#invoke:}}, которая вызывает указываемый в параметрах модуль на языке программирования, позволяющий реализовать функции, которые невозможны или неэффективны при использовании только шаблонов.
Теги контролирования включения текста
Если нужно указать, что должно отображаться при включении шаблона в страницу, а что нет, то нужно в шаблоне использовать теги <noinclude> и </noinclude> или <onlyinclude> и </onlyinclude>. Оба тега по сути противоположны друг другу. Первыми размечается то, что не должно включаться (например, документация). Вторые указывают те единственные участки кода, которые, наоборот, должны включаться (всё остальное не включается). Например, в шаблоне с кодом 1<noinclude>2</noinclude>3 при включении будет отображаться число 13, при просмотре — 123; в шаблоне же с кодом 1<onlyinclude>2</onlyinclude>3 при просмотре также будет отображаться 123, но при использовании будет показана только цифра 2.
Если же что-то не должно отображаться при просмотре шаблона, но всё же включаться при вызове, то этот участок должен быть обёрнут в теги <includeonly> и </includeonly>. Эти теги также обратны тегам <noinclude>, но в плане отображения текста. Допустим, что некий шаблон состоит из следующего кода: <includeonly>1</includeonly>2<noinclude>3</noinclude>. При просмотре самой страницы такого шаблона будут показаны только цифры 23, а при включении — только цифры 12.
Все вышеперечисленные теги — <noinclude>, <onlyinclude>, <includeonly> — можно использовать по нескольку раз каждый в одной странице.
Документация к шаблонам
Многие из шаблонов имеют также свою документацию. Она обычно располагается в подстранице /док; так, шаблон
Документация, как правило, включается через шаблон <noinclude> (см. выше), в результате чего он не мешает обычной работе шаблона. Часто шаблон {{subst:Док}}), которая приводит к появлению в коде помимо шаблона
Страница документации начинается с шаблона <includeonly>, где указываются категории и интервики самого шаблона, и <noinclude>, где указываются категории и интервики документации.
Такая архитектура (документация, категории и интервики — на отдельной странице) позволяет изменять текст документации, переопределять категории или исправлять ссылки на версии шаблона на других языках отдельно от шаблона. Это может быть полезно, если сам этот шаблон защищён от редактирования.
Такой же формат страниц документации используется для модулей и системных сообщений.
Если документация отличается низким качеством, то следует передать шаблону плохдок=1. Тогда в документации будет сказано об этом, а также будет предложено её исправить. Если документации вообще нет, то на самом шаблоне будет предложено её создать. В любом случае в шаблоне на страницу документации будут указаны ссылки, позволяющие её отредактировать (а равно — при её отсутствии — создать), отдельно посмотреть (если она существует), или же обновить страницу самого шаблона (в случае изменения документации).
- Примечание
- В некоторых старых шаблонах документация и/или интервики с категориями указываются не в отдельной подстранице, а в самом шаблоне, в тегах
<noinclude>. Преимуществом является некоторое сокращение затрат на вызов шаблонов, но недостатком является то, что при защите шаблона от редактирования может быть невозможным редактирование и документации, а также категорий и межъязыковых ссылок. Рекомендуется заменять такие конструкции на современные.
Классификация и список шаблонов
Шаблоны делятся на несколько групп: информационные, навигационные, спрайтовые (использующие иконки, полученные методом спрайтирования), технические, карточки, шаблоны форматирования, лицензирования и для страниц обсуждения.
- Информационные шаблоны используются для отображения информации, относящейся к состоянию статьи или её раздела. Обычно они устанавливаются сверху раздела или статьи.
- Навигационные шаблоны используются для компактного отображения ссылок на статьи на общую тему. Они обычно устанавливаются снизу статьи.
- Карточки — шаблоны, добавляющие панель-карточку с основными характеристиками предмета статьи (реже — раздела) справа от остального текста.
- Спрайтовые шаблоны — шаблоны, использующие технологию спрайтирования для отображения конкретного изображения, изначально расположенного в составе таблицы иконок.
- Технические шаблоны — шаблоны, используемые преимущественно в других, более сложных шаблонах.
- Шаблоны форматирования влияют на форматирование страницы.
- Шаблоны лицензирования используются на страницах файлов для указания их лицензии.
- Шаблоны для страниц обсуждения (или просто шаблоны обсуждений) предназначены для применения на страницах обсуждения.
Дерево категорий:
| Правовые вопросы | |||
|---|---|---|---|
| Правила | |||
| Группы участников |
| ||
| Редактирование | |||
| Прочее | |||