Розширення:TemplateData
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 |
Завантажити | |
|
|
<templatedata> |
|
Quarterly downloads | 275 (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 виконує наступні перевірки при збереженні сторінки.
- Вміст повинен бути дійсним 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" |
Тип параметра, для (нечітких) підказок. Одне з:
→ 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”.
Ключ | Тип | Замовчування | Опис |
---|---|---|---|
назва споживача | об'єкт | {} | Об'єкт, який зіставляє "назву споживача" даних про шаблон з об'єктом, який у свою чергу зіставляє "назву параметра споживача" з одною чи кількома "назвами параметрів шаблону".
Назви параметрів шаблону можуть бути задані як рядок (одна назва), масив рядків (декілька назв) чи масив масивів рядків (кілька наборів назв); кожен із рядків-компонентів має бути наявним ключем в об'єкті Параметр шаблону може належати до кількох зіставлень, а може бути значенням кількох різних ключей в тому самому асоціативному масиві; параметр також може не зустрічатися в жодному зіставленні. Скорочений приклад із 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.
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.
| 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. Приклад виклику (форматований задля кращого розуміння людиною):
Повертає дані шаблону для Template:Cite web.
Блок <templatedata>...</templatedata>
цього шаблону знаходиться на сторінці його документації, en:Template:Cite web/doc, і включається трансклюзією.
Додатки та зміни структури JSON, отриманого від API
Структура JSON, отримуваного у відповідь на API HTTP запит get, суттєво відрізняється від тієї, що притаманна блоку <templatedata>...</templatedata>
.
У відповіді на запит API розширення TemplateData вносить такі зміни до об'єкта JSON:
- Додає два охоплюючі об'єкти:
- Загальний об'єкт Pages, який містить один чи більше об'єктів Page.
- Об'єкт із числовим ключем: об'єкт Page
- Доповнення/зміни до самого об'єкта TemplateData
- Додано ключ
title
з назвою сторінки, звідки було запитано дані шаблону (приміром, "Template:Cite web"). - Додано ключ
sets
- Змінено всі зустрінуті TemplateText, які були рядковими параметрами, на об'єкти з єдиним ключем для основної мови вікі
- Прибрано всі ключі
inherits
.- Додано всі атрибути параметрів, для яких визначено наслідування і значення яких не перевизначено безпосередньо атрибутом параметра-спадкоємця в його об'єкті Parameter.
- Додано значення за замовчуванням для всіх ключей в об'єктах Parameter, які не було визначено безпосередньо чи успадковано.
- Додано ключ
Наочно відображені відмінності в об'єкті JSON TemplateDataЮ отриманому через API
| ||||||
|
Ключ | Тип | Опис |
---|---|---|
title
|
рядок | Номер сторінки шаблону (приміром, "Template:Cite web"). Цього ключа немає в структурі JSON на сторінці шаблону. Він додається до структури програмою MediaWiki при отримуванні цих даних через API. |
sets
|
Масив, що містить об'єкти Set | Масив, який містить опис набору. Набір є групою параметрів, які слід застосовувати разом. Якщо цього немає на сторінці шаблону чи його документації, він додається API у вигляді порожнього масиву. |
Ключ | Тип | Опис |
---|---|---|
label |
InterfaceText | перетворено на об'єкт InterfaceText, якщо спочатку не було в такому форматі. |
required |
булеве значення | Якщо не визначене, додано значення за замовчуванням false. |
description |
InterfaceText або null |
Якщо було визначено як рядок, перетворюється на об'єкт InterfaceText. Якщо не було визначено, додано ключ зі значенням null .
|
deprecated |
булеве чи рядок | Якщо не визначене, додано значення за замовчуванням false. |
aliases |
Масив рядків | Якщо не було визначено, за замовчуванням подано порожній масив (приміром, []). |
default |
рядок | Якщо не визначене, додано значення за замовчуванням "". |
type |
рядок | Якщо не визначене, додано значення за замовчуванням "unknown". |
inherits |
(removed) | Цей ключ прибрано, натомість в явному вигляді додано всі успадковані атрибути. Атрибути, визначені в поточному параметрі, мають пріоритет, а атрибути, не визначені ні в поточному параметрі, ні в параметрі, який було наслідувано, отримують значення за замовчуванням. |
Ключ | Об'єкт або простий тип |
Опис |
---|---|---|
Об'єкт (містить локалізовані рядки відповідно до мовного коду) Якщо поле 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
Це розширення використовується в одному або декількох проєктах Вікімедіа. Це, мабуть, означає, що розширення стабільне і працює досить добре, щоб його могли використовувати веб-сайти з великим трафіком. Шукайте назву цього розширення у файлах конфігурації Wikimedia CommonSettings.php та InitialiseSettings.php, щоб побачити, де це встановлене. Повний перелік розширень, встановлених на певній вікі, можна переглянути на сторінці Special:Version вікі. |
Це розширення включено до таких вікі-ферм/хостів та/або пакетів: Це не авторитетний список. Деякі вікі-ферми/хости та/або пакунки можуть містити це розширення, навіть якщо вони не вказані тут. Завжди звертайтеся до своїх вікі-ферм/хостів або комплекту для підтвердження. |