Help:TemplateData/uk

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

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

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

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

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

У грудні 2016 року в бета-тестовому режимі інтерфейс VisualEditor був прилаштований для редагування коду сторінок вікі. Ця функція отримала згодом назву. Тоді функції 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 зберігають свої примітки про застосування та іншу інформацію, яка не включається до сторінок разом із шаблоном, як-от категорія, до якої сам шаблон належить, двома способами:


 * Переважна більшість шаблонів зберігає нотатки про використання та інші дані, які не належать самій сторінці шаблону, на підсторінці документації: «/Template:Templatename/doc». На сторінках, шаблон Documentation виконує трансклюзію всього вмісту сторінки /документація на сторінку шаблону, зберегти вихідний код шаблону набагато чистішим.
 * У шаблонах із підсторінками документації за заголовком «Test Template Info-Icon - Version (2).svg Template documentation» супроводжуватимуться такі посилання, як [переглянути], [редагувати], [історія] та [очищення].


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

Different wikis may present all this differently. Рідко головні сторінки шаблонів можуть містити документацію, навіть якщо ви перевірили все вищесказане; тут користувач додасть іншу назву підсторінки /документація між « » та « », а потім додав власне вміст за « ».

Ви також можете знайти сповіщення внизу сторінки, подібне до цього: «Наведена вище документація включена з Template:Templatename/doc».

Templates without documentation subpages
Якщо шаблон не має підсторінки документації, створіть його та перемістіть туди документацію шаблону (або заповнювач для нього). Тоді можна додавати дані TemplateData до підсторінки документації.

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

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

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

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

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

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

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

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

Оберніть будь-які категорії в теги, щоб вони застосовувалися лише до головної сторінки шаблону:

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

Нарешті, опублікуйте сторінку.

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

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

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

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

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



or

Якщо шаблон містить дані 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. You can change the  by dragging the parameters up and down in the TemplateData editor using the three horizontal bars on the left. and its effects are described here.

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

Ручний спосіб
Альтернативою використанню візуального редактору 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.

«Синтаксична помилка в JSON» з’являється у візуальному редакторі та редакторі вікітексту 2017 року; Під час редагування в редакторі TemplateData GUI з’являється повідомлення «Поганий формат JSON».

These errors can be difficult to detect and come in too many forms to list. Найкращий спосіб уникнути їх — редагувати дані шаблону виключно за допомогою редактора TemplateData; найкращий спосіб виявити їх після того, як вони виникли, — це використати зовнішній валідатор JSON, наприклад JSONLint, який виділить помилки та допоможе їх виправити.

Редактор вікітексту 2010 року не перевіряє недійсний JSON завдяки старій невиправленій помилці. Pages that contain invalid JSON may throw alarming "" 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/ і помічник запитів