Розширення:TemplateData
 Статус релізу: стабільний |
|
|---|---|
 |
|
| Реалізація | Тег, 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 |
| Завантажити | |
|
|
<templatedata> |
|
| 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/папці. - Додайте такий код унизу вашого $LocalSettings:
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" |
Тип параметра, для (нечітких) підказок. Одне з:
| ||||||||||||||||||||||||||||
inherits |
рядок | нічого не підставляється |
Ключ-назва іншого параметра шаблону (має існувати в об'єкті params) Поточний об'єкт Parameter наслідуватиме атрибути вказаного об'єкту Parameter, локальне перевизначення атрибутів за наявності перекриває наслідувані.
|
Об'єкт Set
|
Ключ |
Об'єкт або простий тип |
Опис |
|---|---|---|
label
|
InterfaceText | (Дуже) коротка назва для набору параметрів. Намагайтеся утримувати в межах 20 символів. |
params
|
Масив рядків | Одна чи більше назв параметрів, включених до набору (кожна має бути існуючим ключом в об'єкті params). Параметр може належати до кількох наборів водночас. Параметр може не належати до жодного набору.
|
Об'єкт Maps
| Ключ | Тип | Замовчування | Опис |
|---|---|---|---|
| назва споживача | об'єкт | {} | Об'єкт, який зіставляє "назву споживача" даних про шаблон з об'єктом, який у свою чергу зіставляє "назву параметра споживача" з одною чи кількома "назвами параметрів шаблону".
Назви параметрів шаблону можуть бути задані як рядок (одна назва), масив рядків (декілька назв) чи масив масивів рядків (кілька наборів назв); кожен із рядків-компонентів має бути наявним ключем в об'єкті Параметр шаблону може належати до кількох зіставлень, а може бути значенням кількох різних ключей в тому самому асоціативному масиві; параметр також може не зустрічатися в жодному зіставленні. Скорочений приклад із 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.
| ||
| (Мовний код вікі) | рядок | Локалізований рядок для застосування на 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 вікі. |
| This extension is included in the following packages and/or wiki farms: |