Розширення:TemplateData

**Довідка про розширення MediaWiki**
TemplateData; Статус релізу: стабільний
Реалізація	Tag, API
Опис	Дозволяє зберігати, отримувати та візуалізувати інформацію про шаблони
Автор(и)	Timo Tijhof, Moriel Schottlender, James Forrester, Trevor Pascal, Bartosz Dziewoński, Marielle Volz, ...
Найновіша версія	0.1.2 (Постійні оновлення)
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
MediaWiki	1.25+
PHP	5.4+
Зміни в БД	No
Ліцензія	GNU General Public License 2.0 or later
Завантажити	Download extension ; Git [?]: Download Git master; browse repository (Phabricator · GitHub); commit history; repository contributors (GitHub); code review;
	Параметри $wgTemplateDataSuggestedValuesEditor; $wgTemplateDataUseGUI;
	Теги ‎<templatedata>
	Використані hook'и EditPage::showEditForm:fields; EditPage::showEditForm:initial; MakeGlobalVariablesScript; MultiContentSave; ParserFetchTemplateData; ParserFirstCallInit; ResourceLoaderRegisterModules;
	Translate the TemplateData extension if it is available at translatewiki.net
	Переглянути використання
Issues	Open tasks · Report a bug

This page is a translated version of the page Extension:TemplateData and the translation is 100% complete.

Other languages:

Це розширення постачається з MediaWiki 1.35 і вище. Отже, вам не треба завантажувати його знову. Проте ви все одно повинні дотримуватися інших наданих інструкцій.

Розширення TemplateData виводить тег ‎<templatedata> та API, які разом дозволяють редакторам вказувати, як слід викликати шаблони. Ця інформація доступна як гарно відформатована таблиця для кінцевих користувачів, і як JSON API, який дозволяє іншим системам (наприклад, VisualEditor) будувати інтерфейси для роботи зі шаблонами та їхніми параметрами. Поглиблену довідку див. на Help:TemplateData .

Встановлення

Завантажте і розмістіть файли в каталозі з назвою TemplateData у вашій extensions/ папці.
Додайте такий код унизу вашого LocalSettings.php:
```
wfLoadExtension( 'TemplateData' );
```
Готово – Перейдіть до Special:Version вашої вікі, щоб переконатися, що розширення встановлено успішно.

Редагування даних

Розширення TemplateData працює через визначення тегу ‎<templatedata> у вікі-тексті сторінки шаблону (необов'язково його можна включити і з іншої сторінки). Його розроблено для сумісності зі спільним компонуванням багатьох вікіпедій включення документації шаблонів з окремих сторінок (але не вимагається). Цей вміст тегу ‎<templatedata> повинен бути дійсним JSON, використовуючи нижчеописаний формат; зауважте, що всі описи повинні бути у простому тексті (вікі-текст неприйнятний усередині даних шаблонів).

При включенні блоку ‎<templatedata> на сторінку розширення TemplateData виконує наступні перевірки при збереженні сторінки.

Вміст повинен бути дійсним JSON;
Кожен елемент структури JSON повинен бути очікуваного типу, як зазначено нижче (наприклад, об'єкт, масив або примітив); і
Для елементів із визначеним списком можливих значень (наприклад, params.yourParameterName.type) значення в об'єкті JSON повинно відповідати одному з тих значень.

Якщо будь-яка з перевірок не вдається, серверу не дозволяється збереження, а над сторінкою редагування показується повідомлення про помилку.

Для елементів із автоматичним значенням помилка 2700 запобігає спрацюванню subst: у будь-якому шаблоні, доданому всередині ‎<tag>, включаючи теги ‎<ref> і ‎<gallery>. Блок TemplateData коректно зберігатиметься, але результатний вікі-текст не аналізуватиметься коректно при використанні шаблону.

Зауважте, що не можна використовувати {{#tag:templatedata}} замість ‎<templatedata>.

Формат

Нижче подано візуалізовану версію даних JSON, як вони подаються на сторінці шаблону в тегах ‎<templatedata>‎</templatedata>. Формалізований опис доступний в репозиторії TemplateData. Зверніться до Specification.md за найновішою версією.

Об'єкт TemplateData

Об'єкт TemplateData є кореневим елементом JSON, охопленим елементом ‎<templatedata> на сторінці шаблону чи його документації.

Ключ	Тип	Опис
`description`	InterfaceText або `null`	Короткий опис шаблону. Має бути суто текстовим без вікірозмітки. Щойно заповнений, він може відображуватися як заголовок при редагуванні одного шаблону і, можливо, під назвою шаблону в результатах пошуку, де користувач обирає потрібний йому шаблон. За замовчуванням: `null`.
`params`	Об'єкт, що містить об'єкти Param	Об'єкт, який ставить у відповідальність назву параметра шаблону до об'єкту Param, який описує властивості цього параметра.
`paramOrder`	Масив, що містить назви параметрів шаблону	Логічний порядок, в якому мають бути відображені параметри. Масив, який містить кожен параметр-ключ точно один раз. Кожний рядок має бути правильним ключом до об'єкту `params`.
`sets`	Масив містить об'єкти Set	Масив, який містить опис набору параметрів. Параметри, що належать до одного набору, мають застосовуватися разом. За замовчуванням це []. Зазначимо, що функціональність `sets` ще в розробці.
`format`	рядок, `inline` або `block`	Як вікітекстове представлення шаблону має бути викладене в коді сторінки. За замовчуванням це `inline`. Див. #Нестандартні формати за подробицями щодо користувацьких форматів.
`maps`	Об'єкт Maps	Об'єкт, який зіставляє спрощену назву третьої сторони - споживача даних про шаблон (це Citoid, Special:MyLanguage/Wikidata тощо) з об'єктом, який у свою чергу зіставляє назву параметра споживача з одною чи кількома назвами параметрів шаблону.

Об'єкт Param

Ключ Тип Замовчування Опис

label InterfaceText null (Дуже) коротка назва параметра. Намагайтеся утримувати в межах 20 символів.

description InterfaceText null Короткий опис параметра, аби користувачам було легше обирати з переліку варіантів.

required булеве значення false Чи є параметр обов'язковим для коректної роботи шаблону (true якщо параметр має бути вказаний).

suggested булеве значення false Чи є параметр рекомендованим для того, аби шаблон був корисним (true якщо параметр має бути заданий).

deprecated булеве чи рядок false Чи є параметр застарілим. Значення може бути рядком, який надає користувачу інструкції, як обійти використання параметра, або ж просто true.

aliases Масив рядків [] Перелік синонімів. Синонім є альтернативною назвою параметра, яка може бути застосована замість (але не на додачу до) первинної назви. Синоніми не документовані в окремому об'єкті Parameter. Якщо щодо них треба більше інформації, їх слід утримувати в окремих атрибутах поміченими "застарілий".

default InterfaceText null Значення за замовчуванням, використовуване шаблоном, якщо при його вставленні параметру не надано значення, або його опис.

autovalue рядок null Створене динамічно значення за замовчуванням у форматі вікітексту, як-от поточна дата чи ім'я активного користувача; часто включає підстановку вікітексту, як {{subst:CURRENTYEAR}}.

example InterfaceText null Приклад тексту, який подається значенням параметру, аби допомогти користувачу надати правильне значення.

type

рядок

"unknown"

Тип параметра, для (нечітких) підказок. Одне з:

Значення рядку	Тип параметра
"unknown"	Невизначений
"number"	Будь-яке числове значення (без десяткової коми чи роздільника розрядів)
"string"	Будь-яке текстове значення. Може містити переходи на новий рядок.
"line"	Коротке текстове поле - для назв, міток тощо. Текст, який не містить переходів на новий рядок.
"boolean"	Булеве значення ('1' для true, '0' для false, '' для невизначеного), див. тризначну логіку.
"date"	Дата у форматі ISO 8601, як-от "2014-05-09" чи "2014-05-09T16:01:12Z"
"url"	URL, включно із протоколом, як-от "http://www.example.org", "https://example.org", чи "//example.org"
"wiki-page-name"	Правильна для даної вікі назва сторінки. Сторінка не обов'язково існує, але може бути створена з такою назвою.
"wiki-file-name"	Правильна для даної вікі назва файлу. Файл не обов'язково існує, але може бути завантажений з такою назвою. Не має включати простів назв (тобто "Схема.svg", але не "Файл:Схема.svg" чи "Рисунок:Схема.svg").
"wiki-template-name"	Правильна для даної вікі назва шаблону.
"wiki-user-name"	Правильне для даної вікі ім'я користувача. Не обов'язково існує, але може бути створене з такою назвою. Не має включати простір назв (тобто "Грицько", але не "Користувач:Грицько" чи "User:Грицько").
"content"	Частина вікітексту сторінки: зі стилями, посиланнями, малюнками тощо.
"unbalanced-wikitext"	Вікітекст (код сторінки), який не є самодостатнім, тобто не може бути відображений внаслідок незбалансованості, - приміром, шаблони, які містять веб-розмітку, як-от `{{echo\|before=<u>\|after=</u>}}`.

inherits рядок нічого
не підставляється Ключ-назва іншого параметра шаблону (має існувати в об'єкті params) Поточний об'єкт Parameter наслідуватиме атрибути вказаного об'єкту Parameter, локальне перевизначення атрибутів за наявності перекриває наслідувані.

Об'єкт Set

Ключ	Об'єкт або простий тип	Опис
`label`	InterfaceText	(Дуже) коротка назва для набору параметрів. Намагайтеся утримувати в межах 20 символів.
`params`	Масив рядків	Одна чи більше назв параметрів, включених до набору (кожна має бути існуючим ключом в об'єкті `params`). Параметр може належати до кількох наборів водночас. Параметр може не належати до жодного набору.

Об'єкт Maps

Ключ	Тип	Замовчування	Опис
назва споживача	об'єкт	{}	Об'єкт, який зіставляє "назву споживача" даних про шаблон з об'єктом, який у свою чергу зіставляє "назву параметра споживача" з одною чи кількома "назвами параметрів шаблону". Назви параметрів шаблону можуть бути задані як рядок (одна назва), масив рядків (декілька назв) чи масив масивів рядків (кілька наборів назв); кожен із рядків-компонентів має бути наявним ключем в об'єкті `params`, записаному десь в TemplateData цього самого шаблону. Параметр шаблону може належати до кількох зіставлень, а може бути значенням кількох різних ключей в тому самому асоціативному масиві; параметр також може не зустрічатися в жодному зіставленні. Скорочений приклад із Template:Cite_news#TemplateData англомовної вікі ілюструє структуру об'єкту Maps. { "proveit": { "main": "title", "textarea": [ "quote" ] }, "citoid": { "title": "title", "url": "url", "publisher": "publisher", "publicationTitle": "work", "date": "date", "ISSN": [ "issn" ], "ISBN": [ "isbn" ], "contributor": "others", "author": [ [ "first", "last" ], [ "first2", "last2" ], [ "first9", "last9" ] ], "editor": [ [ "editor-first", "editor-last" ] ] } }

InterfaceText (рядок чи об'єкт)

Рядок простого тексту (без вікі- та HTML розмітки) вільної форми основною мовою даної вікі, або ж об'єкт із такими рядками як значеннями ключей мовного коду.

Значенням за замовчуванням для всіх полів InterfaceText є null.

Рядковий тип

Якщо це рядок, він має містити нелокалізований щодо поточної вікі текст.

Тип Object

Якщо це об'єкт, він має відтворювати таке зіставлення:

Ключ	Тип	Опис
Мовний код Вікіпедії	рядок	Локалізований текст для застосування у Вікіпедії, що відповідає даному мовному коді.

Приклад зіставлення об'єктів:

Ключ	Значення
"en"	"Welcome to Wikipedia"
"de"	"Willkommen bei Wikipedia"
"fe"	"Bienvenue sur Wikipédia"
"nl"	"Welkom op Wikipedia"
"it"	"Benvenuti su Wikipedia"
"es"	"Bienvenidos a Wikipedia"
"ru"	"Добро пожаловать в Википедию"

Приклад

Приклад структури TemplateData, записаний в коді сторінки шаблону чи його опису:

<templatedata>
{
    "description": "Label unsigned comments in a conversation.",
    "params": {
        "user": {
            "label": "User's name",
            "type": "wiki-user-name",
            "required": true,
            "description": "User name of person who forgot to sign their comment.",
            "aliases": ["1"]
        },
        "date": {
            "label": "Date",
            "suggested": true,
            "description": {
                "en": "Timestamp of when the comment was posted, in YYYY-MM-DD format."
            },
            "aliases": ["2"],
            "autovalue": "{{subst:#time:Y-m-d}}"
        },
        "year": {
            "label": "Year",
            "type": "number"
        },
        "month": {
            "label": "Month",
            "inherits": "year"
        },
        "day": {
            "label": "Day",
            "inherits": "year"
        },
        "comment": {
            "required": false
        }
    },
    "sets": [
        {
            "label": "Date",
            "params": ["year", "month", "day"]
        }
    ],
    "maps": {
        "ExampleConsumer": {
            "foo": "user",
            "bar": ["year", "month", "day"],
            "quux": [
                "date",
                ["day", "month"],
                ["month", "year"],
                "year"
            ]
        }
    }
}
</templatedata>

Цей код відображуватиме на сторінці шаблону ось таке:

Label unsigned comments in a conversation.

Template parameters
Parameter		Description	Type	Status
User's name	`user` `1`	User name of person who forgot to sign their comment.	User	required
Date	`date` `2`	Timestamp of when the comment was posted, in YYYY-MM-DD format. Auto value `{{subst:#time:Y-m-d}}`	Unknown	suggested
Year	`year`	no description	Number	optional
Month	`month`	no description	Number	optional
Day	`day`	no description	Number	optional
comment	`comment`	no description	Unknown	optional

API

Див. згенеровану довідку на Special:ApiHelp/templatedata. Приклад виклику (форматований задля кращого розуміння людиною):

api.php?action=templatedata&titles=Template:Cite%20web&format=json [спробуйте в ApiSandbox]

Повертає дані шаблону для Template:Cite web. Блок ‎<templatedata>...‎</templatedata> цього шаблону знаходиться на сторінці його документації, en:Template:Cite web/doc, і включається трансклюзією.

Додатки та зміни структури JSON, отриманого від API

Структура JSON, отримуваного у відповідь на API HTTP запит get, суттєво відрізняється від тієї, що притаманна блоку ‎<templatedata>...‎</templatedata>. У відповіді на запит API розширення TemplateData вносить такі зміни до об'єкта JSON:

Додає два охоплюючі об'єкти:
1. Загальний об'єкт Pages, який містить один чи більше об'єктів Page.
2. Об'єкт із числовим ключем: об'єкт Page
Доповнення/зміни до самого об'єкта TemplateData
1. Додано ключ title з назвою сторінки, звідки було запитано дані шаблону (приміром, "Template:Cite web").
2. Додано ключ sets
3. Змінено всі зустрінуті TemplateText, які були рядковими параметрами, на об'єкти з єдиним ключем для основної мови вікі
4. Прибрано всі ключі inherits.
  - Додано всі атрибути параметрів, для яких визначено наслідування і значення яких не перевизначено безпосередньо атрибутом параметра-спадкоємця в його об'єкті Parameter.
5. Додано значення за замовчуванням для всіх ключей в об'єктах Parameter, які не було визначено безпосередньо чи успадковано.

Наочно відображені відмінності в об'єкті JSON TemplateDataЮ отриманому через API

Корінь JSON
Ключ	Тип	Опис
`pages`	Об'єкт Page	Об'єкт Page (містить єдиний ключ - номер сторінки). Якщо у відповіді декілька сторінок, буде декілька об'єктів Page.

Об'єкт Page
Ключ	Тип	Опис
(номер сторінки)	Об'єкт TemplateData	Об'єкт TemplateData, який містить запитану інформацію. Ключем є статичний номер сторінки шаблону, з якої ці дані JSON було запитано.

Об'єкт TemplateData (додано API)
Наступний ключ додано на кореневому рівні об'єкта JSON, який оточений тегом `‎<templatedata>` на сторінці шаблону чи його опису.
Ключ	Тип	Опис
`title`	рядок	Номер сторінки шаблону (приміром, "Template:Cite web"). Цього ключа немає в структурі JSON на сторінці шаблону. Він додається до структури програмою MediaWiki при отримуванні цих даних через API.
`sets`	Масив, що містить об'єкти Set	Масив, який містить опис набору. Набір є групою параметрів, які слід застосовувати разом. Якщо цього немає на сторінці шаблону чи його документації, він додається API у вигляді порожнього масиву.

Об'єкт Parameter від API
Ключ	Тип	Опис
`label`	InterfaceText	перетворено на об'єкт InterfaceText, якщо спочатку не було в такому форматі.
`required`	булеве значення	Якщо не визначене, додано значення за замовчуванням false.
`description`	InterfaceText або `null`	Якщо було визначено як рядок, перетворюється на об'єкт InterfaceText. Якщо не було визначено, додано ключ зі значенням `null`.
`deprecated`	булеве чи рядок	Якщо не визначене, додано значення за замовчуванням false.
`aliases`	Масив рядків	Якщо не було визначено, за замовчуванням подано порожній масив (приміром, []).
`default`	рядок	Якщо не визначене, додано значення за замовчуванням "".
`type`	рядок	Якщо не визначене, додано значення за замовчуванням "unknown".
`inherits`	(removed)	Цей ключ прибрано, натомість в явному вигляді додано всі успадковані атрибути. Атрибути, визначені в поточному параметрі, мають пріоритет, а атрибути, не визначені ні в поточному параметрі, ні в параметрі, який було наслідувано, отримують значення за замовчуванням.

InterfaceText (об'єкт або `null`):
Об'єкт, який містить текст із мовними кодами як ключами.
Ключ	Об'єкт або простий тип	Опис
Об'єкт (містить локалізовані рядки відповідно до мовного коду) Якщо поле TemplateData в блоці TemplateData містить лише один рядок, а не асоціативний масив локалізованих рядків, то MediaWiki перетворює його на об'єкт InterfaceText, де кожний рядок є значенням для ключа-Wikipedia мовного коду Wikipedia. Значенням за замовчуванням для всіх полів InterfaceText є `null`.
(Мовний код вікі)	рядок	Локалізований рядок для застосування на Wikipedia з основною мовою відповідно до мовного коду.

Приклад об'єкту JSON, отриманого через API

Відповідь на запит API структури TemplateData із попереднього розділу Приклад буде така:

У форматі HTML: https://www.mediawiki.org/w/api.php?action=templatedata&titles=Extension:TemplateData&format=jsonfm
Отримана через API: https://www.mediawiki.org/w/api.php?action=templatedata&titles=Extension:TemplateData

Конфігурація

Змінна	Замовчування	Опис
`$wgTemplateDataUseGUI`	`true`	Експериментальний діалоговий інтерфейс для редагування JSON TemplateData

Див. також

Extension:TemplateWizard – користувацький інтерфейс для обирання та вставлення вікітексту шаблону на ґрунті його TemplateData.
GitHub: jeblad/TemplateData – альтернативна версія із певною функціональністю Lua.
Шаблон для перекладу

Це розширення використовується в одному або декількох проектах Вікімедіа. Це, мабуть, означає, що розширення стабільне і працює досить добре, щоб його могли використовувати веб-сайти з великим трафіком. Шукайте назву цього розширення у файлах конфігурації Wikimedia CommonSettings.php та InitialiseSettings.php, щоб побачити, де це встановлене. Повний перелік розширень, встановлених на певній вікі, можна переглянути на сторінці Special:Version вікі.

TemplateData Статус релізу: стабільний

Реалізація	Tag , API
Опис	Дозволяє зберігати, отримувати та візуалізувати інформацію про шаблони
Автор(и)	Timo Tijhof, Moriel Schottlender, James Forrester, Trevor Pascal, Bartosz Dziewoński, Marielle Volz, ...
Найновіша версія	0.1.2 (Постійні оновлення)
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
MediaWiki	1.25+
PHP	5.4+
Зміни в БД	No
Ліцензія	GNU General Public License 2.0 or later
Завантажити	Download extension Git ^[?]: Download Git master browse repository (Phabricator · GitHub) commit history repository contributors (GitHub) code review
Параметри $wgTemplateDataSuggestedValuesEditor $wgTemplateDataUseGUI
Теги `‎<templatedata>`
Використані hook'и EditPage::showEditForm:fields EditPage::showEditForm:initial MakeGlobalVariablesScript MultiContentSave ParserFetchTemplateData ParserFirstCallInit ResourceLoaderRegisterModules
Translate the TemplateData extension if it is available at translatewiki.net
Переглянути використання
Issues	Open tasks · Report a bug