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

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

Довідка про розширення 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.
MediaWiki	>= 1.43
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
Параметри $wgTemplateDataUseGUI
Теги ‎<templatedata>
Використані hook'и EditPage::showEditForm:fields EditPage::showEditForm:initial MultiContentSave OutputPageBeforeHTML ParserFetchTemplateData ParserFirstCallInit ResourceLoaderRegisterModules
Quarterly downloads	279 (Ranked 18th)
Public wikis using	6,971 (Ranked 24th)
Translate the TemplateData extension if it is available at translatewiki.net
Issues	Open tasks · Report a bug

Розширення 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 виконує наступні перевірки при збереженні сторінки.

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

1. Для елементів із визначеним списком можливих значень (наприклад, 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

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, отриманого через API
Їх немає в об'єкті JSON поміж тегів ‎<templatedata> на сторінці шаблону чи документації шаблону.

Корінь 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

Див. також

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