Jump to content

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

From mediawiki.org
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. Отже, вам не треба завантажувати його знову. Проте ви все одно повинні дотримуватися інших наданих інструкцій.
Довідка про розширення 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
Завантажити
  • $wgTemplateDataEditorNamespaces
  • $wgTemplateDataUseGUI
‎<templatedata>
Quarterly downloads 283 (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

Розширення 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' );
    
  • Yes Готово – Перейдіть до 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

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. Додано ключ 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 із попереднього розділу Приклад буде така:

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

Змінна Замовчування Опис
$wgTemplateDataUseGUI true Експериментальний діалоговий інтерфейс для редагування JSON TemplateData
$wgTemplateDataEditorNamespaces [ 10 ] The namespaces in which the template data editor appears when creating or editing a page. (завдання T189989)

Див. також