Вікіпедія:TemplateData

Матеріал з Вікіпедії — вільної енциклопедії.
Перейти до навігації Перейти до пошуку

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

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

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

Без TemplateData[ред. код]

VisualEditor - Template without TemplateData-uk.png

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


VisualEditor - Template without TemplateData2-uk.png

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

Із TemplateData[ред. код]

VisualEditor - Template with TemplateData1-uk.png

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


VisualEditor - Template with TemplateData2-uk.png

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

Додавання TemplateData[ред. код]

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

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

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

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

Редактор TemplateData[ред. код]

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

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

Manage template documentation button for TemplateData 2014.png

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

A screenshot of the TemplateData editing tool

Цей редактор дозволяє додавати по одному рядку для кожного параметра шаблона, і задавати найнеобхідніші та найчастіше вживані атрибути. Якщо сторінка, яку Ви редагуєте, вже містить блок 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": {     // назва параметра
    ...    // інформація про параметр іде сюди
}
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, Вам треба просто додати синоніми до інформації про параметр:

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

Автозначення[ред. код]

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

Щоб додати таку інформацію до 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>

Інші інструменти[ред. код]

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