Help:Templates/uk

Шаблони у MediaWiki приходять на допомогу тоді, коли ви маєте певні стандартні тексти, які хочете використати на кількох сторінках. На відміну від розширень та медіафайлів, централізованого сховища для шаблонів не існує. Шаблони створюють заново або, щоб не дублювати зроблену роботу, беруть готовими із інших вікі (наприклад, Вікіпедії) й імпортують у свою вікі.

Створення шаблону
Шаблони — стандартні вікісторінки, вміст яких призначений для включення (вбудовування) всередину інших сторінок. Назви сторінок шаблонів за традицією мають префікс « », завдяки чому вони належать до цього простору назв; крім цього, їх можна створювати як будь-яку іншу вікісторінку.

Розглянемо найпростіший приклад застосування шаблону. Якщо створити сторінку «Template:Welcome» з таким вмістом:

Привіт! Ласкаво просимо до вікі.

то це і буде ваш перший шаблон! Тепер використання такого коду:

на будь-якій іншій сторінці приведе до того, що при перегляді цієї сторінки на місці коду  з'явиться текст «Привіт! Ласкаво просимо до вікі.» Так вміст шаблону «включається» до іншої сторінки, тобто інтегрується в неї.

Тепер ви можете вписати  в будь-якому місці будь-якої сторінки, де ви вважаєте доречним появу такого привітання. Нехай ви записали такий код на 100 сторінках. Якщо тепер ви зміните текст шаблону на такий:

Наші вітання! Ласкаво просимо до цієї чудової вікі.

і знову відвідаєте будь-яку з цих 100 сторінок, які використали цей шаблон, то ви побачите вже модифікований текст. У такий спосіб ви можете змінити одразу 100 сторінок без редагування кожної з них, — змінивши шаблон, який ці сторінки включають.

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

Використання
Інші сторінки можуть використовувати сторінки шаблонів в такий спосіб:

Because the template call remains in the pages's source, any subsequent change to Template:Name will be seen on the page containing the template call. Also, the page will be listed among those that "link to" the template. That is, a copy of the contents of Template:Name will be substituted for the template call. No link is maintained between the page and the template, so each can be edited further without affecting the other. In effect, there is little difference between substituting the content in this way and simply typing it into the page's source "manually". See the help page about substitution at the English Wikipedia for more information.
 * — як описано вище, таке посилання буде замінено поточним вмістом сторінки Template:Назва при кожному показі сторінки. Рушій MediaWiki залишає це посилання в вікітексті сторінки незмінним.
 * — при використанні такого посилання на шаблон його буде раз і назавжди замінено вмістом Шаблон:Назва станом на час збереження сторінки з посиланням: копія вмісту Шаблон:Назва замінить посилання на шаблон. Тоді вміст є частиною включеної сторінки, і його можна редагувати на сторінці звичайним чином. Увага: пізніші зміни початкового коду сторінки шаблону не поширяться на сторінку з посиланням на шаблон.
 * — ця конструкція поводить себе точно так, як і, різниця виникає, лише коли вона зустрічається всередині іншого шаблону і цей шаблон або вставляють (за першою схемою), або прямо переглядають.
 * включає шаблон у формі без вікіформатування (так само, як це робить ) при перегляді сторінки з цим шаблоном.

Насправді будь-яка сторінка вікі може бути використана як шаблон, для цього слід явно вказати простір назв, в якому вона знаходиться:


 * включає сторінку
 * включає сторінку
 * включає сторінку
 * заміщується вмістом

Якщо такого простору імен не існує, то повна назва вважатиметься назвою сторінки в просторі шаблонів:


 * включає сторінку

Параметри
Для збагачення механізму включення MediaWiki дозволяє передавати параметри шаблону. Ці параметри дозволяють одному й тому самому шаблону продукувати різні результати чи по-різному поводитися.

Нехай ви вставляєте коротку подяку на сторінку обговорення іншого користувача, приміром:

Ця подяка містить причину (в наведеному прикладі — за вашу працю) та підпис (Я). Зробити те ж за допомогою вашого шаблону Thankyou зможе будь-який користувач.

Щоб подяка виглядала подібно у всіх місцях, де її використано, ви можете створити шаблон із назвою, наприклад,. Хоча подяка має виглядати подібно, коли б один користувач не дякував іншому, її безпосередній вміст (тобто причина і підпис) буде різним. З цієї причини, вам треба зробити їх параметрами. Знехтувавши кодом форматування рамки та зображення, звернемо увагу на змістовний у даному контексті фрагмент шаблону:

Зверніть увагу на використання  та. Це один зі способів ідентифікувати параметри всередині шаблону, значення яких буде задаватися при використанні шаблона. Зверніть увагу, що назва кожного параметра в шаблоні взята в три фігурні дужки:. Це не те саме, що використання назви шаблона.

Використовуючи цей шаблон на деякій сторінці, ви заповнюєте значення параметрів, розділяючи їх символом вертикальної риски. MediaWiki дозволяє передавати параметри шаблону трьома способами: як анонімні, нумеровані та названі.



Анонімні параметри
Значення анонімних параметрів просто перелічують послідовно одне за одним:

У цьому випадку шаблон  отримує для заміщення   та   і дає в результаті:

Порядок, в якому перелічено параметри, критичний для правильного функціонування шаблона. Якщо при включенні шаблона змінити порядок параметрів таким чином:

дістанемо такий результат:



Нумеровані параметри
Для того щоб передати параметри в нумерованому стилі, просто позначте кожен з них номером:

Цього разу код шаблону  отримає параметри   та , незалежно від порядку їх запису при використанні шаблону, і дасть такий результат:


 * Приклади:

видає



Названі параметри
Третій спосіб передавати параметри шаблону — це надати їм якісь назви замість номерів. Для цього слід змінити сторінку шаблону так:

Спасибі… за. Обіймаю,

Всередині шаблону ми використали назви  та   замість номерів для позначення кожного параметра. Передавати ці параметри за назвою слід так:

У цьому разі код шаблону  отримає параметри   та , в результаті побачимо:

Іменовані параметри регістрозалежні, тому:

дає:

Перевагою такого способу передачі параметрів, крім гнучкості порядку, в якому їх можна вказувати, є те, що код шаблону стає більш зрозумілим, у ньому суттєво легше розібратися у випадку більшої кількості параметрів. Необхідність пам'ятати назви параметрів при використанні шаблону можна віднести як до переваг, так і до вад цього способу.



Значення за замовчуванням
Якщо ви включаєте шаблон, який очікує параметри, але не вказуєте їх аргументи, таким чином:

то результат (для перших двох способів передачі параметрів) вийде схожим на:

Не знайшовши вказаних параметрів, шаблон підставив внутрішні назви цих параметрів замість відповідних значень. Для того, щоб подібне використання шаблону зробити ефективним, слід задати стандартні значення параметрів, тобто ті, які буде виведено у випадку, коли відповідні значенні параметрів шаблону не передано. Так, якщо змінити сторінку шаблону таким чином:

тоді  визначає, що, якщо параметру   не надано аргумент, то використовуватиметься значення. Аналогічно,  встановлює значення за замовчуванням   параметру. Тепер включення шаблону знову без передачі будь-яких параметрів призведе до наступного:

Often default values are used to specify alternate names of parameters. For example, if you have, the template will first look for a parameter named "a". If it is not set, it will use the parameter named "b". If neither "a" nor "b" is set, it will output nothing.

Evaluation
Generally speaking, template parameters are substituted into the template after tokenization, but as is. They are not evaluated until they are used.

This has a few consequences. First of all, if you have a  containing , and a   containing  , and put   on a page, mytemplate isn't transcluded, because tokens like "|" cannot be added by a template and keep their special meaning in templates. You can still use templates to control the name of a parameter or template, but you cannot split a template call amongst multiple templates.

The second consequence of this is dead-code elimination. If you make a template call like, and Template:Foo does not contain  , then the displaytitle is not used, since it is only evaluated when needed, and there is no parameter to substitute it into, so it is never evaluated. This usually comes into play when using Extension:ParserFunctions, and can be especially noticed when used in combination with the  magic word that varies by user language.

Template calls starting with the magic word  or   are evaluated in a separate first pass that only happens at save time, along with ~ and links using the pipe trick. If they cannot be evaluated during the first pass,  calls are ignored, and   are treated as if a normal template.

Many but not all parser functions, parser tags and trancluded special pages are not directly included like templates but instead are replaced by a "strip marker". This means you cannot manipulate the results with parser functions like padleft: or similar functions from extensions, as they see the strip marker instead of the result of the parser function.



Рекурсія в шаблонах
Включення шаблону в себе не кине MediaWiki в нескінченну рекурсію. MediaWiki зупинятиме рекурсію, а назву шаблону зробить жирним шрифтом. Наприклад, якщо вмістом Template:Aaaa є, він відображатиме «a a Template loop detected:  Template:Aaaa z z».

Forbidden idiom
This safeguard precludes a potentially useful template idiom where a template self-normalizes its own calling arguments. In this forbidden example  can either be called   or. If called in the first manner, it recurses into itself with the second argument structure (obtained using string parser functions), which then follows a unified processing path.



If  is modified to recurse into   and   is an identical manual copy of   this idiom works fine as the self-recursion safeguard operates dynamically and not statically.

A feasible way for the MediaWiki software to loosen the self-recursion rule would be to require that each recursive call have a distinct argument count from all previous active calls, at most once recursing with the argument count non-decreasing. That would provide a strong guarantee against infinite self-recursion while enabling useful idioms such as the one described here in a flexible manner.

If the processing path is of low complexity, a simple solution using only one template is to handle each calling convention on a separate if/else branch, duplicating the logic of the processing path within each case. If the processing path is more complex, each call-structure case can delegate to an implementation template with a unified call structure which provides the final template behaviour.

Tables in parameters
Since the pipe character and equality sign  have different meanings in template calls and wikitables, in order to use table markup in the value of a template parameter one generally needs to "escape" those characters (i.e., protect them from interpretation as template markup) using special sequences:


 * the built-in magic word  provides an "escaped" version of   since MediaWiki 1.24
 * the built-in magic word  provides an "escaped" version of   since MediaWiki 1.39

Before the introduction of these magic words, many wikis used templates to accomplish the same things. On such a wiki, the magic words take precendence over the same-named templates.

Example table
Table code:

Escaped table code:

Note that the first left-brace is interpreted as a literal left-brace character because it is immediately followed by the   magic word. Similarly, the last right-brace is interpreted as a literal right-brace character because it is immediately preceeded by the same magic word. However, in some cases these brace characters do cause problems, so some wikis provide templates for escaping these characters, as well:


 * the template call  might provide an "escaped" version of
 * the template call  might provide an "escaped" version of

Some wikis go even further and provide other convenience templates like and. On such a wiki, the code can be simplified a bit to this form:



Управління включенням тексту шаблону до сторінок
За звичайного стану справ текст шаблону цілком відображується як при прямому перегляді, так і на сторінці, яка включає шаблон. Але є можливість обирати, які частини сторінки шаблону буде видно прямо, а які буде включено, за допомогою теґів, та.

Будь-який текст між та  буде відображено при прямому перегляді сторінки шаблону, але не буде включено до будь-якої іншої сторінки. Це корисно, якщо необхідно включити до шаблону частину коду, яка не буде розповсюджуватися на інші сторінки, що цей шаблон включають, таку як:


 * Посилання категорій, до яких віднесений сам шаблон
 * Міжмовні посилання на той самий шаблон іншими мовами
 * Пояснювальний текст про використання шаблону

Аналогічно, будь-який текст між та  буде відображено лише при включенні шаблону на тій сторінці, яка його включає. Але його не буде відображено при прямому перегляді сторінки шаблону. Це корисно для:


 * Категоризації сторінок, які включають шаблон. Примітка: якщо в такий спосіб змінити категорії, до яких віднесено шаблон, на відображення цієї зміни на сторінках, що включають цей шаблон, необхідний певний час: це зумовлено . Щоб примусити рушій MediaWiki терміново переглянути категорії певної сторінки, відкрийте її для редагування та збережіть без жодної зміни.
 * Гарантування того, що код шаблону не виконуватиметься при перегляді сторінки шаблону. Зазвичай це роблять, коли шаблон очікує параметри, а без параметрів дасть безглуздий результат.

Будь-який текст поза межами теґів та  обробляється та відображується за звичайними правилами, тобто як при перегляді сторінки шаблону, так і при включенні шаблону до іншої сторінки. Основна увага приділяється тому, що є всередині цих тегів.

Усе, що поза тегами, відкидається при включенні шаблона. Навіть шматки всередині тегів includeonly не будуть включені, якщо тільки вони теж не позначені як onlyinclude. Основна увага приділяється тому, що є поза цими тегами.

Вкладення цих тегів одні в одні також можливе.

Три пари тегів часткового включення дозволяють усі можливі комбінації того, що буде оброблятися і виводитися. Коментарі також мають значення.



Організація шаблонів
Для ефективного користування шаблонами, користувачі мають могти їх знайти і дізнатися, як їх використовувати.

Знайти сторінки шаблонів користувач може так:
 * 1) Натиснути ' → '
 * 2) У переліку ' обрати Template та натиснути '.

Для надання інформації про використання шаблону слід вмістити на його сторінці приклад, подібний до такого:

Використання
Подякувати користувачу:

Тоді дописувач може скопіювати цей приклад і вставити його на сторінку, а потім вписати актуальні параметри.



Посилання на шаблон
На сторінку шаблона можна дати посилання, як і на будь-яку іншу вікісторінку. Наприклад, посилання Template:Navbar утворюється завдяки вікікоду.

У багатьох вікі існує Template:Tl, який дозволяє дати посилання на шаблон, і до того ж вивести подвійні фігурні дужки, потрібні для включення шаблона, але при цьому не роблячи самого включення. Наприклад, використання коду  дасть Navbar.

Така форма подачі зазвичай використовується у документації шаблона, на сторінках довідки, а також на сторінках обговорення, коли мова йде про шаблони. Того ж ефекту можна досягти, скориставшись кодом, але викорстання   дозволяє друкувати менше тексту. У конкретній вікі шаблон Tl, якщо він так існує, може виводити або не виводити текст в елементі «code», як це показано тут. Якщо ні, то можливо, це робить інший шаблон, з подібною назвою. Наприклад, можете переглянути розділ «See also» документації шаблона en:Template:Tl в англомовній Вікіпедії.



Копіювання з однієї вікі до іншої
Шаблони зазвичай спираються на CSS чи на інші шаблони, тому користувачі часто стикаються із проблемами при переносі шаблону з однієї вікі до іншої. Кроки, перелічені нижче, мають допомогти у більшості ситуацій.



Код MediaWiki
Якщо у вас є права на імпортування (конкретно, «») у цільовій вікі:


 * 1) Перейдіть до сторінки Special:Export оригінальної вікі і завантажте файл .xml, який містить повну історію всіх необхідних шаблонів, таким способом:
 * 2) * Введіть повну назву потрібного шаблону у текстове поле, приміром, «Template:Welcome». Особливу увагу звертайте на регістр літер та спеціальні символи — якщо назва шаблону не є абсолютно точною, експорт може все одно відбутися, але отриманий .xml-файл не міститиме очікуваних даних.
 * 1) * Поставте прапорець біля «».
 * 1) * Зніміть прапорець біля «».
 * 1) * Натисніть «».
 * 2) У цільовій вікі перейдіть до сторінки Special:Import та вивантажте отриманий файл .xml.

Якщо у вас немає прав імпорту у цільовій вікі:


 * 1) Перейдіть до сторінки необхідного шаблону, потім до сторінки його редагування, звідки скопіюйте весь вікітекст
 * 2) У цільовій вікі перейдіть до створення/редагування сторінки з такою самою назвою, як сторінка шаблону, текст якого ви скопіювали. Вставте скопійований вікітекст. У короткий опис змін нового шаблону запишіть посилання на його оригінал.
 * 3) На сторінці редагування шаблону в оригінальній вікі, нижче вікна редагування, знайдіть перелік «». Для кожного шаблону з цього переліку відтворіть інструкції, описані вище. Зробіть так само для шаблонів, використовувані шаблонами з цього переліку, і так далі.

У такий спосіб буде скопійовано весь необхідний код, і цього для багатьох шаблонів буде достатньо. Зазначимо, що експортуються лише ті елементи сторінки, які було розібрано при відображенні сторінки, тож, приміром, підсторінки документації в такому процесі не експортуються. Якщо це не спрацює, у цільовій вікі перевірте червоні посилання під «», що знаходиться під вікном редагування. Якщо такs посилання там є, повторіть описані вище кроки і для цих сторінок, а також скопіюйте код модулів.

Після успішного імпорту шаблону та всіх пов'язаних з ним шаблонів з іншої вікі, відредагуйте його у цільовій вікі, налаштувавши його відповідно до ваших потреб. Наприклад, можна змінити логотип, вилучити даремні категорії чи червоні посилання.

Розширення
Розширення ParserFunctions часто використовується в шаблонах. Зайдіть на сторінку і перевірте, чи використовує скопійований вам шаблон будь-які з цих функцій. Якщо так, вам слід встановити розширення. Для цього знадобиться доступ системного адміністратора до сервера, на якому розміщено вашу вікі.

Інша залежність, яку ви часто побачите в шаблонах, особливо у Вікіпедії, — це Lua. Команда   у коді шаблону є характерним показником. Якщо вона присутня, слід встановити розширення, для чого знов-таки необхідний адміністративний доступ. Див. інструкції із встановлення та використання функцій на сторінці розширення.



Код CSS та JavaScript
Крім коду MediaWiki, багато які шаблони використовують CSS, а деяким для повноцінного функціонування потрібен JavaScript. Це може бути причиною неочікуваної поведінки скопійованого шаблону. Для того, щоб скопіювати необхідний код CSS або JavaScript, необхідний адміністративний доступ до цільової вікі, оскільки доведеться редагувати системні повідомлення з простору назв «MediaWiki:».


 * 1) Знайдіть у коді шаблону посилання на клас CSS (типовий вигляд —  ). Якщо ці класи визначено в «MediaWiki:Common.css» або в «MediaWiki:Monobook.css» оригінальної вікі, скопіюйте ці класи до «MediaWiki:Common.css» цільової вікі та перевірте функціонування шаблону.
 * 2) Якщо функціональність шаблону все ще не відновлено, перевірте наявність коду в «MediaWiki:Common.js» та «MediaWiki:Monobook.js» в оригінальній вікі. Якщо він є, можете спробувати скопіювати його до «MediaWiki:Common.js» цільової вікі. Зазвичай вам слід копіювати такий код лише з довірених джерел, і навіть тоді спочатку переглянути код, спробувавши виділити частини, що можуть стосуватися вашого шаблону. Варто звертати увагу на коментарі, які можуть пояснити функціонування кожної частини.



General template usage

 * w:Help:Template – a little more detail than here
 * m:Help:Template — значно детальніша інформація про функціонування шаблонів
 * m:Help:Advanced templates — описує ще просунутіші техніки шаблонів, на кшталт динамічних викликів шаблону та змінних назв параметрів

Special constructs used in templates

 * – корисні фрагменти коду, які зустрічаються в багатьох шаблонах
 * – додаткові привабливі контрольні функції на кшталт #if та #switch
 * – настанова з використання функцій парсеру в шаблонах

Other relevant information

 * – приклад особливого застосування шаблону
 * – Using templates as the starting text of a page
 * m:Help:Embed page — заміщення сторінок із інших просторів назв, ніж.
 * – Using templates as the starting text of a page
 * m:Help:Embed page — заміщення сторінок із інших просторів назв, ніж.
 * m:Help:Embed page — заміщення сторінок із інших просторів назв, ніж.



Посилання

 * Репозиторій шаблонів Miraheze - Шаблони MediaWiki, призначені для загального використання.