Help:TemplateData/uk



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

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



Редактор TemplateData
Існує вбудований інструмент для спрощення редагування TemplateData.

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

Ви можете вказати назву параметра, перерахувати будь-які його синоніми чи альтернативні написання, а також задати його назву та опис, які будуть показані користувачам. Єдиним обов'язковим для заповнення полем є Назва (перше поле кожного рядка), в якому треба вказати точну назву параметру, із врахуванням регістру. У спливному меню Ви можете вибрати тип вмісту, яким має бути заповнений параметр, наприклад, «рядок» (для заповнення звичайним текстом), «сторінка» (для посилань на інші сторінки), чи «дата». Коли Вам відомо, що якщо залишити певний параметр незаповненим, то шаблон відображатиметься з помилками — будь ласка, позначте такий параметр як «обов'язковий». Якщо ж параметр використовується часто, або є рекомендованим — позначте його як «пропонований». Кнопка «Видалити» вилучить запис для цього параметра із TemplateData.

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

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



Структура TemplateData
Структура TemplateData базується на стандартах JSON, і є досить простою. Зауважте, що всі описи у TemplateData мають бути подані простим текстом (без вікірозмітки, без посилань тощо).

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

Цим Ви повідомите програмі, що все, що розташоване між цими двома тегами, є документацією TemplateData, і саме звідти треба брати інформацію при використанні шаблону.



Приклад
Описи всередині TemplateData даються за стандартним форматом; скажімо, Ви маєте шаблон під назвою «Commons», що веде на категорію Вікісховища на певну тематику. Він містить лише один обов'язковий параметр: назва категорії на Вікісховищі. У такому випадку блок TemplateData виглядатиме якось так:

На сторінці шаблону це виглядатиме так: {       "description": "Шаблон для посилання на категорію на Вікісховищі за темою статті", "params": { "1": {                       "label": "Категорія на Вікісховищі", "description": "Категорія на Вікісховищі, на котру ви хочете вказати посилання.", "default": "Category:CommonsRoot", "type": "string", "required": true }       } }



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

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



Синоніми параметрів
Деякі шаблони дозволяють мати різні назви для одного й того ж параметра.

Наприклад,  можна також записати як , або.

Щоб додати цю інформацію до TemplateData, Вам треба просто додати синоніми до інформації про параметр:



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

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



Декілька параметрів
Якщо у Вас є декілька параметрів без назв, просто повторіть кожну секцію (починаючи тегом "1") і заповніть її так, як вважаєте за потрібне. Зауважте, що якщо шаблон має декілька параметрів, у TemplateData їх треба відокремлювати один від одного комами, отак:



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



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



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

 * Відсутні функції — TemplateData є наочним прикладом інструменту, який був введений у використання із малою кількістю функцій з надією на те, що користувачі допоможуть спрямувати розробку нових функцій у той бік, в який вони самі забажають. Тож якщо Ви бажаєте зробити запит на нові функції у TemplateData, будь ласка, повідомте нас.
 * Затримки у відображенні в шаблонах — After adding TemplateData to a template, the metadata should be visible immediately when the template is opened in VisualEditor. However, it is possible that it takes hours before the metadata show. You can force an update by making a null edit to the template page itself (not the documentation subpage). To perform a null edit, open the template page for editing, and save the page without making any change.
 * Поточні проблеми — Список поточних помилок і запитів на функції доступний у багзіллі.



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

 * TemplateDataEditor — A user script that makes the process of adding TemplateData easier. It currently exists in French (contains English, Italian, Japanese and Korean translations), and can easily be translated into other languages.
 * TemplateData Wizard — A tool that generates TemplateData through an interactive interface.
 * Skeleton TemplateData generator — A tool that reads the source wikicode of a template, tries to find all the parameters used and outputs a skeleton document with the parameters listed.
 * JSONLint — A tool that allows you to validate manually-written JSON to help find errors in the syntax.
 * List of all templates with TemplateData on this wiki