Вікіпедія:TemplateData

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

"params": {
    ...    // параметри йдуть сюди
}

"1": {     // назва параметра "1"
    ...    // інформація про параметр "1" іде сюди
}

"label": "Категорія на Вікісховищі",

"description": "Категорія на Вікісховищі, на котру ви хочете вказати посилання.",

"default": "Category:CommonsRoot",

"type": "string",

"required": true

"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 на цій вікі