Help:TemplateData/uk

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

Починаючи з квітня 2019 року, TemplateData є частиною користувацького інтерфейсу за замовчуванням всіх вікі Wikimedia при додаванні шаблона до сторінки як зареєстрованими, так і незареєстрованими користувачами. Обидва редактори, текстовий і візуальний, в той чи інший спосіб його використовують. Якщо ви маєте власну Вікіпедію, вам необхідно встановити.

Додавання TemplateData до шаблону по суті є додаванням невеликого блоку коду JSON (як пояснено нижче) до сторінки документації шаблону. Є два основних способа зробити це: або вручну, або з допомогою редактора TemplateData — графічного користувацького інтерфейсу, доступного на сторінці «Редагувати»/«Редагувати код» шаблону на тих вікі, де розширення TemplateData встановлене. JSON містить перелік параметрів з інформацією про кожен із них, а також інформацію про шаблон в цілому.

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

Історія
TemplateData було створено на початку 2013 для, який в MediaWiki тоді працював у тестовому режимі. VisualEditor є основним графічним інтерфейсом для редагування вікі Wikimedia, а TemplateData розширює його можливості при додаванні до сторінки шаблонів. Він одразу був офіційно підтриманий у VisualEditor. З розповсюдженням VisualEditor по всіх головних вікі Wikimedia як редактора за замовчуванням протягом 2013-2016 років, TemplateData так само входив до цих вікі.

У грудні 2016 року в бета-тестовому режимі інтерфейс VisualEditor був прилаштований для редагування коду сторінок вікі. Ця функція отримала згодом назву Редактор вікі-тексту 2017. Тоді функції TemplateData були вперше застосовані при редагуванні коду.

В березні 2018 року Sam Wilson розробив, розширення для вставки шаблонів для роботи у звичайному редакторі коду Wikimedia (знаному як редактор вікі-тексту 2010), з метою спрощення вставки шаблонів із застосуванням інформації з TemplateData. У квітні 2019 року TemplateWizard увійшов до складу редактора вікі-тексту 2010 у всіх вікі Wikimedia. Це значило, що TemplateData стало складовою частиною обох редакторів, візуального та редактора коду, у всіх вікі Wikimedia.

Додавання чи редагування інформації в TemplateData
Аби додати чи змінити інформацію в TemplateData якогось шаблону, перейдіть спочатку на його сторінку — на «/Шаблон:Назва шаблону».

Checking the current state
Before adding or editing TemplateData, check whether the template has a documentation subpage. Then check whether the template already contains TemplateData and, if so, whether it's located on the template page or the documentation subpage.

Documentation subpages
Шаблони у більшості вікі Wikimedia зберігають свої примітки про застосування та іншу інформацію, яка не включається до сторінок разом із шаблоном, як-от категорія, до якої сам шаблон належить, двома способами:

Тут шаблон Документація виконує трансклюзію всього вмісту сторінки /документація на сторінку шаблону. Завдяки такому підходу код власне шаблону виглядає значно коротшим і зрозумілішим.
 * Переважна більшість використовує підсторінку документації.
 * Ви можете швидку з'ясувати, чи містить шаблон підсторінку/документація, перевіривши, чи «Test Template Info-Icon - Version (2).svg Документація шаблону» містить посилання «[перегляд] [редагувати] [історія] [очистити кеш]» одразу за ним.

В такому випадку вона знаходиться після « », що в свою чергу охоплено тегом.
 * Невелика кількість вікі тримають інформацію про шаблон безпосередньо на сторінці шаблону після його коду.

Different wikis may present all this differently. В рідкісних випадках основна сторінка шаблону може містити текст документації навіть якщо ці посилання відображені та підсторінка /документація існує. Таке трапляється, якщо користувач додав іншу назву підсторінки /документація між " " та « », а потім додав власне вміст за.

Дещо менш надійний спосіб перевірки полягає в відшукуванні підпису «Документація вище включена з Шаблон:Назва шаблону/документація» чи подібного внизу сторінки.

Templates without documentation subpages
Якщо шаблон не має сторінки документації, у вас є два варіанти дій: Після цього можна додавати дані TemplateData до підсторінки документації. Це найкращий спосіб.

Створення підсторінки /документація та переніс туди вмісту .

Щоб зробити це, натисніть «Редагувати»/«Редагувати код» на основній сторінці шаблону й відшукайте теги (зазвичай наприкінці), погляньте на їхній вміст.

Він має виглядати приблизно так:

Він також може вже містити дані TemplateData. В такому разі він виглядатиме приблизно так:

Виділіть усе від « » до «», виріжте до буферу обміну, потім видаліть « », аби залишилося щось подібне:

Збережіть сторінку.

Now, to create the new subpage, look at your browser's address bar and add  to the end of the URL. Press Enter, then choose the option to create a new page.

В українській вікі є шаблон Підсторінка документації, тому додайте його на початку створюваної сторінки. Можливо, слід додати й інші шаблони, як-от Purge button чи посилання Purge. Див. m:Вікіпедія:Документація_шаблонів за додатковою інформацією.

Insert the text you cut or saved in the previous text (beneath the notice template, if applicable).

Охопіть категорії, до яких має належати шаблон, тегом.

Деякі вікі, в тому числі українська, мають шаблон Sandbox other. Вставте його, якщо поточний шаблон повинен мати власну пісочницю, яка не належить до тих самих категорій, що й шаблон.

Після цього натисніть «Опублікувати сторінку».

Тепер можна додавати й редагувати дані TemplateData на підсторінці документації за процедурою, описаною в.

Adding and editing TemplateData on the main template page
If you can't create the  page, you can add and edit TemplateData on the template's main page by following the instructions in.

If a template has a documentation subpage, check both the main page and the documentation subpage for the presence of TemplateData (the  tag followed by an array inside curly brackets:   ).

Як альтернатива, розширення TemplateData може виконати цю перевірку замість вас. Натисніть «Редагувати» чи «Редагувати код» на відповідній сторінці. Якщо шаблон уже містить дані TemplateData на тій чи іншій сторінці, ви побачите виділену жовтим примітку нагорі сторінки, де написано таке:


 * «Зверніть увагу: блок TemplateData уже існує на пов’язаній сторінці „Шаблон:Назва шаблону/документація“», або таке:
 * «Зверніть увагу: блок TemplateData уже існує на пов’язаній сторінці „Шаблон:Назва шаблону“»

Якщо шаблон містить дані TemplateData на своїй підсторінці документації

Якщо шаблон має дані TemplateData на своїй підсторінці документації, саме цю сторінку слід редагувати. Це можна зробити натисканням посилання «[редагувати]» біля заголовку « Документація шаблону» (чи подібного), або, якщо ви вже на підсторінці /документація, натисканням «Редагувати» чи «Редагувати код» нагорі сторінки. Далі слідуйте вказівкам із для додавання чи редагування даних TemplateData.

Якщо шаблон містить дані TemplateData на своїй основній сторінці

Якщо шаблон містить дані TemplateData на своїй основній сторінці, є два способи дій:


 * Перенести їх до підсторінки документації. Це найкращий спосіб.
 * Редагувати ці дані на основній сторінці шаблону.

Перенесення даних TemplateData до підсторінки документації

Аби зробити це, натисніть «Редагувати»/«Редагувати код» на основній сторінці шаблону і знайдіть тег, охоплений тегами. Це має виглядати приблизно так:

Виріжте до буферу обміну тег з усім вмістом і збережіть сторінку.

Далі відкрийте редагування підсторінки документації натисканням посилання «[редагувати]» після заголовку Документація шаблону" або подібного.

Наберіть заголовок, приміром, «TemplateData», під ним вставте дані з буферу обміну.

Тепер можна редагувати дані TemplateData згідно із вказівками в.

Редагування даних TemplateData на основній сторінці шаблону

Якщо ви не хочете переносити дані TemplateData до підсторінки /документація, можна редагувати їх просто на основній сторінці шаблону. Див. щодо редагування даних TemplateData.

Якщо шаблон не має TemplateData, але має підсторінку документації

Якщо шаблон наразі не має TemplateData, цей блок слід додавати до підсторінки документації.

Можна зробити це, натиснувши посилання «[редагувати]» біля заголовку « Документація шаблону» (чи подібного), або, якщо ви вже на сторінці /документація, натиснувши «Редагувати» чи «Редагувати код» нагорі сторінки. Напишіть заголовок, на кшталт «TemplateData», потім додайте блок даних під ним. Розділ пояснює, як додавати блок TemplateData.

Метод редактора TemplateData
Це простіший спосіб додавання чи змінювання TemplateData, придатніший для недосвідчених користувачів.

Редактор TemplateData — графічний користувацький інтерфейс для додавання та редагування TemplateData. Він входить в розширення TemplateData. Він доступний після переходу на сторінку будь-якого шаблону (або підсторінку документації) та натиснення «Редагувати» або «Редагувати код».

Після натискання на «Редагувати» чи «Редагувати код» ви побачите кнопку над полем редагування та заголовком сторінки з назвою «».

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

Функції, доступні в показаному вікні:


 * Верхнє вікно «Мова». Це стосується опису шаблону, який можна зробити декількома мовами, за замовчуванням буде обрано ту, яку користувач обрав в особистих налаштуваннях. Інформація з іншомовних вікі тут не подається, оскільки різні вікі мають різні бази даних шаблонів. Якщо даних різними мовами в TemplateData немає, у вікні буде відображено лише мову поточної вікі. Користувач кнопкою «Додати мову» може додати інші мови для опису шаблону. Код мови вказується на екрані в дужках поряд із параметром, якого він стосується. Це можуть бути описи й мітки.
 * Наступне поле містить опис шаблону. Це опис шаблону в цілому, він показується користувачеві в різних місцях при додаванні шаблону. Його функції детально описано тут.
 * Далі можна обрати варіант вікітекстового форматування шаблону, що вставляється. Доступні варіанти «Невизначено», «Вбудований» (все на одному рядку), «Блоковий» (розбивка по рядках) і «Нестандартний». Ці параметри детальніше описані тут.
 * Якщо користувач обирає «Нестандартний», він зможе описати цей формат набором вікітексту в параметрі «Рядок нестандартного формату», згідно з правилами, описаними тут, і саме з такої розбивкою по рядках вставлятиметься шаблон, коли користувач в редакторі натискатиме «Вставити».


 * Далі поле «Параметри шаблону», яке містить перелік параметрів шаблону з їхнім описом. Воно може уже містити інформацію у випадку редагування існуючого блоку TemplateData. Якщо у коді шаблону є параметри, не описані наразі в TemplateData, ви можете побачити кнопку «Додати запропоновані параметри». Розширення знаходить їх в коді шаблону за фрагментами  або  . Натискання кнопки додасть опис цих параметрів під їх назвами, визначеними в коді. Також буде відображено зеленим примітку нагорі: «2 нових параметри імпортовано: назви параметрів».
 * Внизу є посилання «Додати параметр». Це дозволяє вручну додати опис параметра з довільною назвою.

Наступним кроком є натискання на один із параметрів у списку. Там можна задати інформацію про параметр.



Всі ці функції та їхню дію описано в підрозділі #Всередині назви параметру.

Після завершення редагування натисніть «Застосувати». Це автоматично вставить блок TemplateData внизу сторінки перед тегом, або, якщо такий блок вже існував, замінить інформацію відповідно до редагування, не змінивши положення блоку. Також блок TemplateData буде виділено після натискання «Застосувати».

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

Після цього натисніть «Зберегти», аби записати зміни до редагованої сторінки.

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

Додавання блока TemplateData вручну

Попередні міркування:


 * Якщо ви додаєте блок TemplateData на підсторінку документації шаблону, можете додавати його в будь-якому місці сторінки; перевірте рекомендації власної вікі, аби з'ясувати, чи не обумовлене там рекомендоване положення цього блоку. Приміром, в англомовній вікі блок TemplateData зазвичай наприкінці сторінки, а в німецькомовній — зазвичай нагорі.
 * Якщо ви додаєте блок TemplateData на головну сторінку шаблону (що не рекомендовано, див. #Попередні міркування), то маєте пересвідчитися, що він охоплений тегом .

Спочатку натисніть посилання «Редагувати» чи «Редагувати код» на відповідній сторінці, потім пересуньте покажчик в позицію, куди ви хотіли б додати блок TemplateData і напишіть заголовок, приміром, «TemplateData».

Багато які вікі (зокрема, україномовна; але не всі) містять шаблон TemplateData header, який додає коротку примітку щодо блоку TemplateData. Додайте його після заголовку.

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

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

Параметри можна записувати в будь-якому порядку, але порядок, що найкраще корелює з порядком в документації щодо TemplateData і з відображенням редакторів TemplateData, такий:

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

Приклад

Ось приклад блоку TemplateData для гіпотетичного шаблону прибирання. Шаблон має демонструвати сповіщення, а його код запрограмований вміщувати сторінку до відповідної категорії на ґрунті вказаної дати (рік і місяць). Сповіщення також має містити посилання на розділ сторінки обговорення, якщо вказано. Блок TemplateData виглядатиме приблизно так:

Відповідна документація TemplateData відображуватиметься так:

{	"description": "Use this template to indicate that an article is in need of cleanup.", "format": "inline", "params": { "date": { "label": "Month and year", "description": "The month and year that the template was added", "type": "string", "autovalue": " ", "example": "January 2013", "suggested": true },		"reason": { "aliases": ["1"], "label": "Reason", "description": "The reason the article is in need of cleanup", "type": "string" },		"talk": { "aliases": ["talksection"], "label": "Talk page section", "description": "The section of the talk page containing relevant discussion", "type": "string" }	},	"paramOrder": [ "date", "reason", "talk" ] }

Параметри TemplateData
Кожен параметр TemplateData подано нижче із описом та прикладом застосування. Вони також перелічені в Extension:TemplateData#Format.

Всередині назви параметру
Примітка: якщо жоден із атрибутів «required», «suggested» чи «deprecated» для параметра шаблону не встановлений, його статус в документації TemplateData відповідатиме «optional» (необов’язковий).

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

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

Зверніть увагу, що кожна порція інформації береться у лапки (за винятком  та  ), і відокремлюється від наступної порції комою (за винятком останньої).

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

Як користуватися

Додати параметр, за яким двокрапку, пропуск та будь-який із типів, вказаний у першому стовпчику таблиці нижче.

Приклад:

Вплив

З лютого 2020 р. лише 5 із 13 типів впливають на інтерфейс візуального редактора та редактора вікітексту 2017, а в TemplateWizard таких типів 8.

Вплив певних типів напевне змінюватиметься, коли редактори шаблонів отримуватимуть оновлення для їхньої підтримки. Один із таких проєктів для візуального редактора та редактора вікітексту 2017 відслідковується в задачі Phabricator T55613. Подібний проєкт підтримки логічного типу в TemplateWizard відслідковується в T200664.

Нижче перелічено актуальні ефекти.

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


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

Вікітекст має щонайменше задовольняти мінімуму, інакше буде видано помилку форматного рядку.

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

Синтаксичні помилки в JSON/Неправильний формат JSON
Ця помилка виникає в разі спроби запису блоку TemplateData, який містить помилки в коді JSON, як-от дублікатні ключі (параметри) або надлишкові чи відсутні коми, із візуального редактора чи з редактора вікітексту 2017 (тобто редакторів на JavaScript).

«Синтаксична помилка в JSON» виникає при спробі записати такий код із візуального чи редактора вікітексту 2017, а «Неправильний формат JSON» — при спробі відкрити подібний код у графічному редакторі TemplateData зі сторінки шаблону.

These errors can be difficult to detect and come in too many forms to list. The best way to avoid them is to edit template data exclusively with the TemplateData editor; the best way to detect them once they've occurred is to use an external JSON validator, such as JSONLint, which will highlight errors and aid in fixing them.

Внаслідок довготривалої помилки користувачі редактора вікітексту 2010 можуть записати неправильний JSON (подробиці: ), оскільки парсер JavaScript менш прискіпливий і дозволяє неправильний JSON. Pages that contain invalid JSON may throw alarming "Internal error" messages. To fix these errors, your best bet is to use a JSON validator (see above).

Обов'язковий атрибут «paramOrder(номер)» не знайдено.
Ця помилка виникає, коли певний параметр введено в, але він відсутній в. Число в квадратних дужках посилається на параметр із, відсутній в подальшому. Це порядковий номер, нумерація починається з 0, тобто перший параметр має номер 0, другий — 1 тощо.

Для усунення помилки упевніться, що всі параметри, визначені в, також зібрані в. Або ж ви можете взагалі прибрати об'єкт  із блоку TemplateData.

Неправильне значення атрибуту «paramOrder(номер)».
Ця помилка виникає, коли певний параметр введено в, але він відсутній в. Число в квадратних дужках посилається на параметр у, якого там не має бути. Це порядковий номер, нумерація починається з 0, тобто перший параметр має номер 0, другий — 1 тощо.

Для усунення помилки упевніться, що всі параметри, визначені в, також зібрані в. Або ж ви можете взагалі прибрати об'єкт  із блоку TemplateData.

Атрибут «params.parametername.required» повинен мати тип «boolean».
Ця помилка виникає, якщо взяти в лапки значення параметрів  або.

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

Атрибут «format» очікується як…
Якщо параметр  вказаний зі значенням, відмінним від ,   чи коректного рядка форматування, виникне помилка «Атрибут „format“ очікується як „inline“, „block“ чи правильний форматний рядок.»

Аби усунути помилку, перевірте, що значення після  дорівнює   чи   і що в ньому немає помилок написання. Або ж, якщо робота з вікітекстом, перевірте, що він містить якнайменше  і не містить синтаксичних помилок, які зазвичай не дозволять обробити код шаблону, як-от подвійні знаки рівності чи зайві/відсутні фігурні дужки див. розділ #Нестандартні формати за подробицями синтаксису. Або ж ви можете взагалі прибрати параметр, щоб усунути цю помилку.

Неочікуваний атрибут «parametername».
Ця помилка виникає, якщо створити неприпустимий параметр блоку TemplateData. Радше за все це помилка друку.

Вона також трапляється, якщо записати параметр одного блоку з TemplateData в інший його блок. Це також може бути спричинено помилкою друку (розстановка дужок).

Приміром, можна було помилково записати параметр  в кореневому блоці об'єкту TemplateData замість всередині  :

Або ж, якщо неочікуваний параметр знаходиться всередині параметра parametername шаблону, в описі помилки ви побачите його назву як «params.parametername.»

Аби усунути помилку, перевірте, що всі назви параметрів написано правильно, а також що всі параметри записано у відповідному блоці. Ще перевірте, що ви не додали неіснуючий в об'єкті TemplateData параметр. Можна перевірити, які параметри відомі для певного об'єкту, в розділі #Параметри TemplateData.

Обов'язковий атрибут «params» не знайдено.
Ця помилка виникає, якщо в блоці TemplateData відсутній об'єкт. Це обов'язковий об'єкт, оскільки він містить всю інформацію про кожен із параметрів шаблону, тож виправте цю помилку, перевіривши, що він доданий без синтаксичних помилок. Див. вище інструкцію з додавання параметра.

Обмеження і запитання

 * Відсутні функції – TemplateData є, значною мірою, прикладом інструмента, який було випущено з небагатьма функціями в надії, що користувачі допоможуть спрямувати розвиток функцій у бажане для них русло. Якщо Ви хочете подати запит на нові функції TemplateData, будь ласка, дайте нам знати.
 * Затримки у відображенні в шаблонах – Після додавання TemplateData до шаблону, метадані повинні бути видимі миттєво, як тільки шаблон буде відкрито у Візуальному редакторі. Однак існує ймовірність, що оновлення метаданих займе більше часу — навіть до кількох годин. Ви можете пришвидшити оновлення, виконавши нульове редагування сторінки самого шаблону (але не сторінки документації). Для виконання нульового редагування відкрийте сторінку шаблону для редагування, та збережіть її без внесення будь-якої зміни і без додавання будь-якого опису редагування.
 * Поточні проблеми – Список поточних баґів та запитів на функції можна переглянути на баґтрекері Вікімедіа.

Інші інструменти

 * : Діалогове вікно панелі інструментів для введення вікі-тексту шаблону через форму, що будується з TemplateData.
 * TemplateData Wizard: Інструмент, що генерує TemplateData через інтерактивний інтерфейс.
 * Skeleton TemplateData generator: Інструмент, що зчитує вихідний код шаблона, намагається відшукати усі параметри, що в ньому використовуються, та продукує макет TemplateData із вже занесеними до нього параметрами.
 * JSONLint: Інструмент, що дозволяє перевірити написаний вручну код JSON, відшукуючи помилки у синтаксисі.
 * [ Список усіх шаблонів із TemplateData] у цій вікі
 * При використанні шаблону TemplateData у німецькій Вікіпедії, дані шаблону відображаються в окремому, графічно оформленому розділі, а сам шаблон додається до категорії шаблонів із TemplateData
 * https://query.wikidata.org/ і помічник запитів