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

From mediawiki.org
Jump to navigation Jump to search
This page is a translated version of the page Extension:TemplateData and the translation is 100% complete.
Other languages:
Deutsch • ‎English • ‎Türkçe • ‎dansk • ‎español • ‎français • ‎lietuvių • ‎magyar • ‎polski • ‎português • ‎svenska • ‎čeština • ‎русский • ‎українська • ‎עברית • ‎ߒߞߏ • ‎अवधी • ‎हिन्दी • ‎বাংলা • ‎中文 • ‎日本語
Це розширення постачається з MediaWiki 1.35 і вище. Отже, вам не треба завантажувати його знову. Проте ви все одно повинні дотримуватися інших наданих інструкцій.
Довідка про розширення MediaWiki
OOjs UI icon advanced.svg
TemplateData
Статус релізу: стабільний
Screenshot of TemplateData extension.png
Реалізація 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 backwards compatible.
MediaWiki 1.25+
PHP 5.4+
Зміни в БД No
Ліцензія GNU General Public License 2.0 or later
Завантажити
  • $wgTemplateDataSuggestedValuesEditor
  • $wgTemplateDataUseGUI
‎<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.php:
    wfLoadExtension( 'TemplateData' );
    
  • Yes Готово – Перейдіть до Special:Version вашої вікі, щоб переконатися, що розширення встановлено успішно.

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

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

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

  1. Вміст повинен бути дійсним JSON;
  2. Кожен елемент структури JSON повинен бути очікуваного типу, як зазначено нижче (наприклад, об'єкт, масив або примітив); і
  3. Для елементів із визначеним списком можливих значень (наприклад, 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

Ключ Тип Замовчування Опис
Масив масивів [] Тип параметра, для (нечітких) підказок. Одне з:
Об'єкт 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

ParameterDescriptionTypeStatus
User's nameuser 1

User name of person who forgot to sign their comment.

Userrequired
Datedate 2

Timestamp of when the comment was posted, in YYYY-MM-DD format.

Auto value
{{subst:#time:Y-m-d}}
Unknownsuggested
Yearyear

no description

Numberoptional
Monthmonth

no description

Numberoptional
Dayday

no description

Numberoptional
commentcomment

no description

Unknownoptional

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:

  • Додає два охоплюючі об'єкти:
    1. Загальний об'єкт Pages, який містить один чи більше об'єктів Page.
    2. Об'єкт із числовим ключем: об'єкт Page
  • Доповнення/зміни до самого об'єкта TemplateData
    1. Додано ключ title з назвою сторінки, звідки було запитано дані шаблону (приміром, "Template:Cite web").
    2. Додано ключ paramOrder із масивом значень, в якому назви параметрів зустрічаються в тому самому порядку, як і в об'єкті params всередині об'єкта TemplateData на сторінці шаблону.
    3. Додано ключ sets
    4. Змінено всі зустрінуті TemplateText, які були рядковими параметрами, на об'єкти з єдиним ключем для основної мови вікі
    5. Прибрано всі ключі inherits.
      • Додано всі атрибути параметрів, для яких визначено наслідування і значення яких не перевизначено безпосередньо атрибутом параметра-спадкоємця в його об'єкті Parameter.
    6. Додано значення за замовчуванням для всіх ключей в об'єктах 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.
paramOrder Масив, який містить рядкові назви параметрів Логічний порядок, в якому мають бути відображені параметри. Масив, який містить кожен параметр-ключ точно один раз. Кожний рядок має бути правильним ключем до об'єкту params.
Якщо цього атрибута немає у структурі ‎<templatedata>‎</templatedata> на сторінці шаблону чи його документації, він додається API із використанням того порядку параметрів, який має місце в об'єкті TemplateData.
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 із попереднього розділу Приклад буде така:

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

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

Див. також