Вікіпедія:TemplateData

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

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

Вигляд TemplateData у Візуальному редакторі

Без TemplateData

Без TemplateData кожен параметр необхідно додавати вручну під час вставки нового шаблону на сторінку.

Немає інформації щодо того, яке значення має бути вписане в поле параметра.

Із TemplateData

TemplateData доступно, отже відображено список підтримуваних параметрів із описом.

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

Додавання TemplateData

Єдина річ, яка потребує волонтерської уваги — це додавання TemplateData до шаблонів (особливо тих, що вживаються найчастіше, такі як шаблони-картки, шаблони цитування).

Сторінка довідки щодо TemplateData пояснює, як додавати інформацію TemplateData до шаблону.

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

Ви можете переглянути автоматично згенерований список найчастіше вживаних шаблонів у Вашій вікі на спеціальній сторінці MostUsedTemplates. Якщо ви зацікавлені в отриманні копії цього списку у вікі-форматі (полегшує співпрацю користувачів над таким списком), ми можемо такий список для Вас створити. Будь ласка, відішліть свій запит електронною поштою на адресу okeyes-at-wikimedia-dot-org.

Редактор TemplateData

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

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

Натисніть цю кнопку, аби перейти в інтерфейс GUI для редагування TemplateData.

A screenshot of the TemplateData editing tool — The TemplateData editing tool, on a page that contains no TemplateData yet.

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

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

Screenshot of the TemplateData editor, showing a second parameter being added

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

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

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

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

Структура TemplateData

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

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

<templatedata>
{
    ...     // вміст TemplateData іде сюди
}
</templatedata>

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

Приклад

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

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

На сторінці шаблону це виглядатиме так:

Шаблон для посилання на категорію на Вікісховищі за темою статті

Параметри шаблону
Параметр		Опис	Тип	Статус
Категорія на Вікісховищі	`1`	Категорія на Вікісховищі, на котру ви хочете вказати посилання. За замовчуванням Category:CommonsRoot	Рядок	обов'язковий

Опис та параметри

description	Перший тег `"description"` (опис) — описує користувачеві призначення і дію всього шаблону.	"description": "Шаблон для посилання на категорію на Вікісховищі за темою статті",
params	Далі йде тег `"params"` (параметри) — контейнер опису кожного параметра шаблону. Усі параметри шаблону мають бути включені в секцію `"params"`.	"params": { ... // параметри йдуть сюди }
	У підсекції кожного параметра перший теґ співпадає із назвою цього параметра в самому шаблоні. Якщо параметр має назву на кшталт `{{{посилання-на-категорію}}}`, цей теґ буде `"посилання-на-категорію"`. Якщо такий параметр є порядковий, без назви, — цифра на кшталт `{{{1}}}`, цей теґ буде `"1"`. Вся інформація, що стосується конкретно цього параметра, буде включена в секцію із його (параметра) назвою.	"1": { // назва параметра "1" ... // інформація про параметр "1" іде сюди }
label	Далі є тег `"label"` (мітка), в якому треба вказати зручну для читання назву параметра для відображення в редакторі шаблонів. (!) Цей тег не рекомендовано використовувати, оскільки він часто викликає плутанину із реальною назвою параметра.	"label": "Категорія на Вікісховищі",
description	Далі йде `"description"`: текст-опис параметра (а не всього шаблону).	"description": "Категорія на Вікісховищі, на котру ви хочете вказати посилання.",
default	Наступним йде `"default"` (замовчання). Окремі шаблони мають стандартне значення, яке буде використане, якщо Ви його не зміните. Цей елемент повідомляє користувачеві, яке стандартне значення для цього параметра. Ви можете проігнорувати заповнення цього параметра, якщо стандартне значення для нього відсутнє.	"default": "Category:CommonsRoot",
type	Після цього ми маємо `"type"`, що відповідає за те, яким чином редактор шаблонів інтерпретує цей параметр. Тут можна вказати: `"string"`: набір символів, наприклад фраза; `"number"`: набір цифр; `"wiki-user-name"`: набір символів, що являє собою ім'я користувача; `"wiki-page-name"`: набір символів, що являє собою заголовок вікісторінки. `"wiki-file-name"`: назва файлу.	"type": "string",
required	Також є `"required"` ("необхідний"), який може мати лише булеві значення: `true` або `false`. Визначає чи є заповнення параметра обов'язковим для цього шаблону. Якщо не вказати ніякого значення, автоматично буде використано значення `false`.	"required": true
suggested	І нарешті, є ще `"suggested"` ("рекомендовано"), який приймає булеві значення: `true` або `false`. Це — статус для параметрів, які не є «обов'язковими», але їх використання рекомендоване (але не необхідне) через значну цінність для користувачів шаблонів. Якщо нічого не вказувати, автоматично буде використано значення `false`.	"suggested": true

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

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

Псевдоніми параметрів

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

Наприклад, {{Вікісховище|категорія=Apples}} можна також записати як {{Вікісховище|Apples}}, або {{Вікісховище|посилання=Apples}}.

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

    "params": {
        "категорія": {
            ...
            "aliases": ["1", "посилання"]
        }

Автозначення

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

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

    "params": {
        "дата": {
            ...
            "autovalue": "{{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}"
        }

Декілька параметрів

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

    "params": {
    "1": {
        ...
    },      // зверніть увагу на кому тут
    "2": {
        ...
    },      // і тут
    "3": {
        ...
    }
    }

Подібні параметри

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

    "params": {
        "тема1": {
            "label": "Тема",
            "description": "Тема, що згадується на цій сторінці неоднозначності",
            "type": "string"
        },
        "тема2": {
            "inherits": "тема1"
        },
        "тема3": {
            "inherits": "тема1"
        },
    }

Порожня заготовка

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

<templatedata>
{
    "description": "",
    "params": {
        "1": {
            "label": "",
            "description": "",
            "type": ""
        },
        "2": {
            "label": "",
            "description": "",
            "type": ""
        }
    }
}
</templatedata>

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

Модуль:TemplateDataGenerator — Lua-модуль для створення скелету TemplateData.
TemplateDataEditor — Користувацький скрипт, що полегшує процес додавання TemplateData. Він зараз існує у французькій мовній версії (містить переклади на англійську, італійську, японську та корейську мови), і з легкістю може бути перекладений і на інші мови.
TemplateData Wizard — Інструмент, що генерує TemplateData через інтерактивний інтерфейс.
Skeleton TemplateData generator — Інструмент, що зчитує вихідний код шаблону, намагається виявити усі параметри, які використовуються в ньому, і виводить «кістяк» документації TemplateData із переліченими в ньому параметрами.
JSONLint — Інструмент, що дозволяє перевірити написаний вручну код JSON, відшукуючи помилки в синтаксисі.
JSON Formatter — Інструмент, який дозволяє редагувати, форматувати JSON.
Список усіх шаблонів із TemplateData на цій вікі