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

**Довідка про розширення MediaWiki**
TemplateData; Статус релізу: стабільний
Реалізація	Тег, API
Опис	Дозволяє зберігати, отримувати та візуалізувати інформацію про шаблони
Автор(и)	Timo Tijhof, Moriel Schottlender, James Forrester, Trevor Parscal, Bartosz Dziewoński, Marielle Volz, ...
Найновіша версія	0.1.2 (Постійні оновлення)
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
PHP	5.4+
Зміни в БД	Ні
Ліцензія	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;
	Параметри $wgTemplateDataEditorNamespaces; $wgTemplateDataUseGUI;
	Теги ‎<templatedata>
	Використані hook'и EditPage::showEditForm:fields; EditPage::showEditForm:initial; MultiContentSave; OutputPageBeforeHTML; ParserFetchTemplateData; ParserFirstCallInit; ResourceLoaderRegisterModules;
Quarterly downloads	290 (Ranked 15th)
Public wikis using	6,971 (Ranked 24th)
	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 92% complete.

Outdated translations are marked like this.

This extension comes with MediaWiki 1.35 and above. Отже, вам не треба завантажувати його знову. Проте ви все одно повинні дотримуватися інших наданих інструкцій.

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

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

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

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

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

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

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

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

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

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

Зауважте, що не можна використовувати {{#tag:templatedata}} замість Special:MyLanguage/Help:TemplateData#Template data editor method.

Формат

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

Об'єкт TemplateData

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

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

Об'єкт Param

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

label

InterfaceText

null

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

→ For more details see: label

description

InterfaceText

null

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

→ For more details see: description

required

булеве значення

false

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

→ For more details see: required

suggested

булеве значення

false

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

→ For more details see: suggested

deprecated

булеве чи рядок

false

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

→ For more details see: deprecated

aliases

Масив рядків

[]

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

→ For more details see: aliases

default

InterfaceText

null

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

→ For more details see: default

autovalue

рядок

null

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

→ For more details see: autovalue

example

InterfaceText

null

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

→ For more details see: example

type

рядок

"unknown"

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

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

→ For more details see: type

inherits

рядок

нічого
не підставляється

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

→ For more details see: inherits

suggestedvalues

Array containing strings

[]

An optional parameter property. Creates a list of parameter values to help users select the desired value. For the suggested values to be displayed as a combo box in VisualEditor, the parameter’s type must be set to one of the following: content, line, string, number, unknown or unbalanced wikitext.

→ For more details see: suggestedvalues

Об'єкт Set

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

Об'єкт Maps

Maps is a single data structure that goes multiple levels deep. It became common to call the second level a “map object”.

Ключ	Тип	Замовчування	Опис
назва споживача	об'єкт	{}	Об'єкт, який зіставляє "назву споживача" даних про шаблон з об'єктом, який у свою чергу зіставляє "назву параметра споживача" з одною чи кількома "назвами параметрів шаблону". Назви параметрів шаблону можуть бути задані як рядок (одна назва), масив рядків (декілька назв) чи масив масивів рядків (кілька наборів назв); кожен із рядків-компонентів має бути наявним ключем в об'єкті `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"
"fr"	"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[Edit template data]
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`.
(Мовний код вікі)	рядок	Локалізований рядок для застосування на $wkpd з основною мовою відповідно до мовного коду.

Приклад об'єкту 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
`$wgTemplateDataEditorNamespaces`	`[ 10 ]`	The namespaces in which the template data editor appears when creating or editing a page. (завдання T189989)

Див. також

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

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

Це розширення включено до таких вікі-ферм/хостів та/або пакетів:

Це не авторитетний список. Деякі вікі-ферми/хости та/або пакунки можуть містити це розширення, навіть якщо вони не вказані тут. Завжди звертайтеся до своїх вікі-ферм/хостів або комплекту для підтвердження.

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

Реалізація	Тег , API
Опис	Дозволяє зберігати, отримувати та візуалізувати інформацію про шаблони
Автор(и)	Timo Tijhof, Moriel Schottlender, James Forrester, Trevor Parscal, Bartosz Dziewoński, Marielle Volz, ...
Найновіша версія	0.1.2 (Постійні оновлення)
Compatibility policy	Snapshots releases along with MediaWiki. Master is not backward compatible.
PHP	5.4+
Зміни в БД	Ні
Ліцензія	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
Параметри $wgTemplateDataEditorNamespaces $wgTemplateDataUseGUI
Теги `‎<templatedata>`
Використані hook'и EditPage::showEditForm:fields EditPage::showEditForm:initial MultiContentSave OutputPageBeforeHTML ParserFetchTemplateData ParserFirstCallInit ResourceLoaderRegisterModules
Quarterly downloads	290 (Ranked 15^th)
Public wikis using	6,971 (Ranked 24^th)
Translate the TemplateData extension if it is available at translatewiki.net
Issues	Open tasks · Report a bug