Довідка:TemplateData
 |
Зверніть увагу! Коли Ви редагуєте цю сторінку, то погоджуєтесь робити свій внесок під ліцензією CC0. Детальніше про умови ліцензії можна дізнатися на сторінці довідки. | |
TemplateData – це розширення, яке зберігає інформацію та параметри, пов’язані з шаблоном вікітексту, і робить його доступним для інтерфейсу редагування, який може отримати та представити його в редакторі шаблонів – усе це допомагає користувачам додавати та редагувати шаблони на сторінках.
Станом на квітень 2019 року функціональність TemplateData є частиною стандартної роботи користувача для всіх користувачів на всіх вікі Вікімедіа, коли вони додають шаблон, навіть незареєстрованих користувачів. Обидва редактори, текстовий і візуальний, в той чи інший спосіб його використовують, як і багато скриптів, інструментів і гаджетів. Якщо ви хочете, щоб ця функція була у вашій власній вікі, установіть Розширення:TemplateData.
Додавання TemplateData до шаблону для використання цим розширенням передбачає вставку невеликого простого блоку JSON (як пояснено нижче) до сторінки документації шаблону. Ви можете зробити це вручну або за допомогою редактора TemplateData, графічного інтерфейсу користувача, до якого можна отримати доступ на сторінках шаблону «Редагувати»/«Редагувати код» у вікі з установленим розширенням TemplateData. JSON містить список параметрів шаблону й інформацію про ці параметри та про шаблон в цілому (докладніше див. нижче).
Шаблони, які містять TemplateData, відображатимуть цю інформацію в інтерфейсі користувача, коли користувач додасть шаблон. У деяких випадках це змінить поведінку редактора, коли ви використовуєте його для редагування або вставки заданого шаблону, значно полегшивши користувачам виконання кроків, необхідних для додавання заданого шаблону.
Історія
TemplateData було створено на початку 2013 для VisualEditor, який в MediaWiki тоді працював у тестовому режимі. VisualEditor є основним графічним інтерфейсом для редагування вікі Вікімедіа, а TemplateData розширює його можливості при додаванні до сторінки шаблонів. Він одразу мав офіційну підтримку в візуальному редакторі. З розповсюдженням візуального редактора у різних великих вікі Вікімедіа як редактора за замовчуванням упродовж 2013—2016 років, TemplateData розповсюджувався там теж.
У грудні 2016 року в бета-тестовому режимі інтерфейс візуального редактора був прилаштований для редагування коду сторінок вікі. Ця функція отримала згодом назву Редактор вікі-тексту 2017. Тоді функції TemplateData були вперше застосовані при редагуванні коду.
У березні 2018 року Сем Вілсон розробив TemplateWizard, розширення для вставки шаблонів для роботи у звичайному редакторі коду Вікімедіа WikiEditor (знаному як редактор вікітексту 2010), з метою спрощення вставки шаблонів із застосуванням інформації з TemplateData. У квітні 2019 року TemplateWizard увійшов до складу редактора вікітексту 2010 у всіх вікі Вікімедіа. Таким чином TemplateData тепер є складовою частиною обох редакторів, візуального та редактора коду, у всіх вікі Вікімедіа.
Додавання чи редагування інформації в TemplateData
Аби додати чи змінити інформацію в TemplateData якогось шаблону, перейдіть спочатку на його сторінку — на «/Шаблон:Назва шаблону».
Перевірка поточного стану
Перш ніж додавати чи редагувати TemplateData, перевірте, чи має шаблон підсторінку документації. Тоді перевірте, чи шаблон уже містить TemplateData і якщо так, чи розміщені вони на сторінці шаблону або підсторінці документації.
Підсторінки документації
У більшості вікі Вікімедіа є два основні способи зберігання приміток про застосування шаблонів та іншої інформації, яку не варто включати у сам шаблон (як-то категорії, до яких сам шаблон належить):
- Переважна більшість шаблонів зберігає нотатки про використання та інші дані, які не варто розміщувати на самій сторінці шаблону, на підсторінці документації: «/Шаблон:Назвашаблону/документація». На таких сторінках, шаблон {{Documentation}} включає весь вміст сторінки /документація на сторінку шаблону, залишаючи вихідний код шаблону набагато чистішим.
- У шаблонах із підсторінками документації за заголовком «
Документація шаблону» ітимуть такі посилання, як [перегляд], [редагувати], [історія] та [очистити кеш].
- У шаблонах із підсторінками документації за заголовком «
- Деякі сторінки шаблону зберегли цю інформацію на головній сторінці шаблону. Ви можете помітити це на цих сторінках, шукаючи входження
{{Documentation|content=, що охоплено тегом<noinclude>.
Виглядати це може по-різному у різних вікі.
Зрідка головні сторінки шаблонів можуть містити документацію, навіть якщо ви перевірили все вищесказане;
тут користувач додасть іншу назву підсторінки /документація між «{{Documentation|» та «|content=», а потім додав власне вміст за «|content=».
Ви також можете знайти сповіщення внизу сторінки, подібне до цього: «Наведена вище документація включена з Template:Templatename/doc».
Шаблони без підсторінок документації
Якщо шаблон не має підсторінки документації, створіть її та перемістіть документацію шаблону туди (або її заготовку). Тоді можна додавати дані TemplateData до підсторінки документації.
Створення підсторінки /документація та переніс туди вмісту
Для створення підсторінки документації, натисніть «Редагувати»/«Редагувати код» на основній сторінці шаблону й відшукайте теги <noinclude> (зазвичай наприкінці), погляньте на їхній вміст.
Він має виглядати приблизно так:
<noinclude>
{{Documentation|content=
== Usage ==
Information about usage.
== More example headings ==
More example contents
[[Category:Example category]]
[[Category:Example category 2]]
}}
</noinclude>
Ви також можете виявити, що він уже містить TemplateData. Якщо так, це буде виглядати приблизно так:
<noinclude>
{{Documentation|content=
...
<templatedata>
{
"description": "",
"params": {
"1": {
"label": "Example parameter",
"description": "Example parameter description",
"type": "string"
}
}
}
</templatedata>
</noinclude>
Виберіть усе після «|content=» і перед «</noinclude>» і виріжте це в буфер обміну або збережіть у тимчасовому документі. Видаліть «|content=», залишивши лише таке:
<noinclude>
{{Documentation}}
</noinclude>
Збережіть сторінку шаблона.
Now, to create the new subpage, look at your browser's address bar and add /doc to the end of the URL. Press ↵ Enter, then choose the option to create a new page.
В українській вікі є шаблон {{Documentation subpage}}, тому додайте його на початку створюваної сторінки або створіть нову сторінку. Ви також можете додати інші шаблони, наприклад посилання {{Purge button}} або посилання {{Purge}} (якщо це підтримується відповідною вікі).
Insert the text you cut or saved in the previous text (beneath the notice template, if applicable).
Оберніть будь-які категорії в теги <includeonly>, щоб вони застосовувалися лише до головної сторінки шаблону:
<includeonly>
[[Category:Example category]]
[[Category:Example category 2]]
</includeonly>
Багато вікі мають шаблон {{Sandbox other}}.
Використовуйте цей шаблон тут, якщо ймовірно, що шаблон, який ви редагуєте, існує у версії пісочниці (знаходиться за адресою Template:Templatename/sandbox), щоб запобігти застосуванню категорій до пісочниці сторінка:
<includeonly>{{sandbox other||
[[Category:Example category]]
[[Category:Example category 2]]
}}</includeonly>
Нарешті, опублікуйте сторінку.
Тепер ви можете додавати та редагувати TemplateData на підсторінці документації, використовуючи інструкції, описані в #Методи.
Додавання чи редагування TemplateData на основній сторінці шаблону
Якщо ви не хочете чи не можете створити підсторінку /документація, можна додати дані TemplateData на основну сторінку шаблону. Інструкція представлена в #Методи.
Якщо шаблон має підсторінку документації, слід перевірити, чи вона містить дані TemplateData і чи вони знаходяться на підсторінці документації (або на основній сторінці шаблону).
Як альтернатива, розширення TemplateData може виконати цю перевірку замість вас. Натисніть «Редагувати» чи «Редагувати код» на відповідній сторінці. Якщо шаблон уже містить дані TemplateData на тій чи іншій сторінці, ви побачите виділену жовтим примітку нагорі сторінки, де написано таке:
- Будь ласка, зверніть увагу: на пов'язаній сторінці «[[Template:Templatename/doc]]» вже є блок TemplateData.
або
- Будь ласка, зверніть увагу: на пов'язаній сторінці «[[Template:Templatename]]» вже є блок TemplateData.
Якщо шаблон містить дані TemplateData на своїй підсторінці документації
Якщо шаблон має дані TemplateData на своїй підсторінці документації, саме цю сторінку слід редагувати.
Це можна зробити натисканням посилання «[редагувати]» біля заголовку «.svg){kind=icon}
Документація шаблону» (чи подібного), або, якщо ви вже на підсторінці /документація, натисканням «Редагувати» чи «Редагувати код» нагорі сторінки.
Далі слідуйте вказівкам із #Методи для додавання чи редагування даних TemplateData.
Якщо шаблон містить дані TemplateData на своїй основній сторінці
Якщо шаблон містить дані TemplateData на своїй основній сторінці, є два способи дій:
- Перенести їх до підсторінки документації. Це найкращий спосіб.
- Редагувати ці дані на основній сторінці шаблону.
Перенесення даних TemplateData до підсторінки документації
Аби зробити це, натисніть «Редагувати»/«Редагувати код» на основній сторінці шаблону і знайдіть тег <templatedata>, охоплений тегами <noinclude>.
Це має виглядати приблизно так:
<noinclude>
{{Documentation}}
<templatedata>
{
"description": "",
"params": {
"1": {
"label": "Example parameter",
"description": "Example parameter description",
"type": "string"
}
}
}
</templatedata>
</noinclude>
Виріжте до буферу обміну тег <templatedata> з усім вмістом і збережіть сторінку.
Далі відкрийте редагування підсторінки документації натисканням посилання «[редагувати]» після заголовку Документація шаблону" або подібного.
Наберіть заголовок, приміром, «TemplateData», під ним вставте дані з буферу обміну.
Тепер можна редагувати дані TemplateData згідно із вказівками в #Методи.
Редагування даних TemplateData на основній сторінці шаблону
Якщо ви не хочете переносити дані TemplateData до підсторінки /документація, можна редагувати їх просто на основній сторінці шаблону. Див. #Методи щодо редагування даних TemplateData.
Якщо шаблон не має TemplateData, але має підсторінку документації
Якщо шаблон наразі не має TemplateData, цей блок слід додавати до підсторінки документації.
Можна зробити це, натиснувши посилання «[редагувати]» біля заголовку « Документація шаблону» (чи подібного), або, якщо ви вже на сторінці /документація, натиснувши «Редагувати» чи «Редагувати код» нагорі сторінки.
Напишіть заголовок, на кшталт «TemplateData», потім додайте блок даних під ним.
Розділ #Методи пояснює, як додавати блок TemplateData.
Методи
Метод редактора TemplateData
Це простіший спосіб додавання чи змінювання TemplateData, придатніший для недосвідчених користувачів.
Редактор TemplateData — графічний користувацький інтерфейс для додавання та редагування TemplateData. It is part of the TemplateData extension, available on any template's page (or documentation subpage) by clicking "Редагувати" or "Редагувати код".
Після натискання на «Редагувати» чи «Редагувати код» ви побачите кнопку над полем редагування та заголовком сторінки з назвою «Управління TemplateData».
Натисніть цю кнопку для входу в редактор TemplateData. Якщо сторінка, яку ви редагуєте, вже містить блок TemplateData, ці дані будуть відображені тут автоматично.
Функції, доступні в показаному вікні:
- The top item chooses the language of the interface text. It allows you to enter text content in multiple languages, displayed to users based on their settings in Preferences, not based on the wiki's language; different wikis have entirely different template databases.
If no language template data exists, the interface will only offer users the wiki's own language, but users can click "Додати мову" to add more inputs. The language code is displayed in brackets next to the parameters to which it can be applied, such as descriptions and labels.
- Наступне поле містить опис шаблону. Це опис шаблону в цілому, він показується користувачеві в різних місцях при додаванні шаблону. Його функції детально описано тут.
- Далі можна обрати варіант вікітекстового форматування шаблону, що вставляється. Доступні варіанти «Невизначено», «Вбудований» (все на одному рядку), «Блоковий» (розбивка по рядках) і «Нестандартний». Ці параметри детальніше описані тут.
- Якщо користувач обирає «Нестандартний», він зможе описати цей формат набором вікітексту в параметрі «Рядок нестандартного формату», згідно з правилами, описаними тут, і саме з такої розбивкою по рядках вставлятиметься шаблон, коли користувач в редакторі натискатиме «Застосувати».
- The fourth item configures a template's parameters.
If parameters have already been defined in template data, this area displays them in a list. If the template's source code specifies parameters for which no template data exists, you may see a button labeled "Додати 2 пропоновані параметри". The editor extracts these suggestions from the template's source code by looking for {{{parametername}}} or {{{parametername|}}}. Clicking "Додати 2 пропоновані параметри" will add these parameters using their names as defined in the source code. A green notice will also appear at the top, for example, "2 нові параметри імпортовано: names of parameters".
- В нижній частині вікна є кнопка «Додати параметр». Це дозволяє вручну додати параметр з довільною назвою.
Наступним кроком є натискання на один із параметрів у списку. Там можна задати інформацію про параметр.
Всі ці функції та їхню дію описано в підрозділі #Всередині назви параметру.
- The template data editor will not allow you to change a parameter to a blank "Назва".
- Натискання посилання «Вилучити інформацію про параметр» вилучить опис параметру та всю інформацію про нього із даних TemplateData. Ви не зможете відновити чи відкотити цю зміну в TemplateData, якщо лише не натиснули відмову від запису «X» на закінчення редагування. Будь-які зміни, зроблені після натискання посилання «Застосувати», можна відкотити натисканням Ctrl+Z.
- Вихід із редактора TemplateData після зроблених змін демонструє запитання, чи ви певні щодо відміни внесених змін.
Після завершення редагування натисніть «Застосувати».
Це автоматично вставить блок TemplateData внизу сторінки перед тегом </noinclude>, або, якщо такий блок вже існував, замінить інформацію відповідно до редагування, не змінивши положення блоку.
Також блок TemplateData буде виділено після натискання «Застосувати».
Редактор TemplateData створює параметр "paramOrder" наприкінці блоку TemplateData чи оновлює тамтешню інформацію.
Він містить поточний перелік опису параметрів шаблону в TemplateData в тому порядку, в якому вони відображувалися в редакторі TemplateData.
You can change the "paramOrder" by dragging the parameters up and down in the template data editor using the three horizontal bars on the left.
"paramOrder" and its effects are documented below.
Після цього натисніть «Зберегти», аби записати зміни до редагованої сторінки.
Ручний спосіб
Альтернативою використанню візуального редактору TemplateData є додавання цього блоку вручну. В окремих випадках таке може знадобитися.
Структура TemplateData базується на стандартах JSON, але вам не треба опановувати JSON, щоб навчитися додавати TemplateData.
Це робиться за дуже простими правилами й полягає в записі лише кількох десятків значень, майже завжди у вигляді "parameter": "value".
Додавання блока TemplateData вручну
Попередні міркування:
- Якщо ви додаєте блок TemplateData на підсторінку документації шаблону, можете додавати його в будь-якому місці сторінки; перевірте рекомендації власної вікі, аби з'ясувати, чи не обумовлене там рекомендоване положення цього блоку. Приміром, в англомовній вікі блок TemplateData зазвичай наприкінці сторінки, а в німецькомовній — зазвичай нагорі.
- Якщо ви додаєте блок TemplateData на головну сторінку шаблону (що не рекомендовано, див. #Попередні міркування), то маєте пересвідчитися, що він охоплений тегом
<noinclude>...</noinclude>.
Click "Редагувати" or "Редагувати код" on the respective page, then move to the place in the page where you intend to add template data and write a heading: "Template data".
Багато які вікі (зокрема, україномовна; але не всі) містять шаблон {{TemplateData header}}, який додає коротку примітку щодо блоку TemplateData. Додайте його після заголовку.
Для початку запису TemplateData вставте тег <templatedata> і пару фігурних дужок на нових рядках, з порожнім рядком поміж ними:
<templatedata>
{
}
</templatedata>
Далі додайте відступ на порожньому рядку між двома круглими дужками і починайте записувати параметри. Подробиці щодо параметрів подано тут. Більшість параметрів необов'язкові, але декілька настійливо рекомендовані.
Параметри можна записувати в будь-якому порядку, але порядок, що найкраще корелює з порядком в документації щодо TemplateData і з відображенням редакторів TemplateData, такий:
<templatedata>
{
"description": "",
"format": "",
"params": {
"parameter1": {
"aliases": ["",""]
"label": "",
"description": "",
"type": ""
}
},
"paramOrder": [
""
]
}
</templatedata>
Також упевніться, що параметри, прикладом, об'єкту "params" синтаксично залишаються всередині цього об'єкту, інакше при спробі запису отримаєте помилку «Неочікуваний атрибут».
Приклад
Ось приклад блоку TemplateData для гіпотетичного шаблону прибирання. Шаблон має демонструвати сповіщення, а його код запрограмований вміщувати сторінку до відповідної категорії на ґрунті вказаної дати (рік і місяць). Сповіщення також має містити посилання на розділ сторінки обговорення, якщо вказано. Блок TemplateData виглядатиме приблизно так:
<templatedata>
{
"description": "Use this template to indicate that an article is in need of cleanup.",
"format": "inline",
"params": {
"date": {
"label": "Month and year",
"description": "The month and year that the template was added",
"type": "string",
"autovalue": "{{SUBST:CURRENTMONTHNAME}} {{SUBST:CURRENTYEAR}}",
"example": "January 2013",
"suggested": true
},
"reason": {
"aliases": ["1"],
"label": "Reason",
"description": "The reason the article is in need of cleanup",
"type": "string"
},
"talk": {
"aliases": ["talksection"],
"label": "Talk page section",
"description": "The section of the talk page containing relevant discussion",
"type": "string"
}
},
"paramOrder": [
"date",
"reason",
"talk"
]
}
</templatedata>
Відповідна документація TemplateData відображуватиметься так:
Use this template to indicate that an article is in need of cleanup.
| Parameter | Description | Type | Status | |
|---|---|---|---|---|
| Month and year | date | The month and year that the template was added
| String | suggested |
| Reason | reason 1 | The reason the article is in need of cleanup | String | optional |
| Talk page section | talk talksection | The section of the talk page containing relevant discussion | String | optional |
Параметри TemplateData
Усі доступні параметри TemplateData наведено нижче з описом та прикладом. Вони також більш детально перераховані на сторінці Extension:TemplateData#Format.
- Поточна інформація справедлива для лютого 2020 і може змінюватися з розвитком розширення, коли додаються нові параметри чи змінюється інтерфейс вставлення шаблону для підтримки наявних параметрів чи внаслідок зміни їхнього трактування.
- Вікірозмітка не працює в описі та мітках. Вони суто текстові.
- New lines ("
\n") in descriptions, labels, examples or defaults will not show in any of the main editors (TemplateWizard, the visual editor or the 2017 wikitext editor), even though they show in the auto-generated template data documentation. They are replaced by a null string in input forms and by a space elsewhere.
| Параметр | Опис | Приклад |
|---|---|---|
| description |
Параметр Вплив На сторінці документації шаблону цей опис буде показано у вигляді звичайного тексту під заголовком «Дані шаблону для Назва шаблону». Всі поширені редактори (VisualEditor, Редактор вікі-тексту 2017, WikiEditor із TemplateWizard тощо) демонструють цей опис у двох основних місцях:
У VisualEditor та редакторі вікітексту 2017 цей опис обмежений 50 символами під кожним знайденим результатом, за чим слідує ..., але в основному вікні редактора шаблонів відображується повний опис. В обох випадках відображення робиться сірим кольором. В основному вікні редактора шаблонів відображення робиться звичайним (чорним) кольором, а для довгих описів (більших за 540 символів) відображується смужка прокрутки. Якщо не вказано Якщо параметр опису не вказаний чи порожній, натомість буде відображено текст «Немає опису.» в тих самих місцях, зокрема, нижче підзаголовку «Дані шаблону для назва шаблону». Додатково:
|
"description": "Шаблон для посилання на категорію на Вікісховищі за темою статті",
|
| format |
Наступним є Параметр необов'язковий, але рекомендований. The default behavior when this parameter is not provided is preserving the existing formatting for existing parameters, or inline formatting for newly added parameters and templates. Вплив Внутрішній: ( При вставленні шаблону його вікітекст буде вміщено в код сторінки на одному рядку без пропусків між елементами, як-от:
Блок: ( При вставленні параметри шаблону розподіляться по рядках, кожен на новому, з одним пропуском між елементами, як-от: {{Foo
| bar = baz
| longparameter = quux
}}
Нестандартне форматування: Якщо параметр встановлено в особливий рядок вікітексту, згідно з правилами, переліченими в #Нестандартні формати, для шаблону буде відображено таку примітку в його документації TemplateData: |
"format": "inline"
|
| params |
Об'єкт Для кожного із параметрів він має містити назву та набір підпараметрів TemplateData, описаний тут. Якщо шаблон має багато параметрів, відділяйте кожен об'єкт комою поміж ними, після закриваючої фігурної дужки попереднього об'єкту, але не після останнього об'єкту. |
"params": {
"parameter1": {
... // інформація про параметри
}, // тут кома
"parameter2": {
... // інформація про параметри
}, // і тут теж
"parameter3": {
... // інформація про параметри
} // але не тут
}
|
| paramOrder |
Об'єкт Як користуватися Додається параметр Кожен із параметрів може бути написаний в новому рядку для виразності, але це необов'язково (можна й так: Рекомендовано вказувати Список має бути повним, тобто містити назву кожного з параметрів шаблону, що їх описано в блоці TemplateData, інакше отримаємо помилку «Відсутній атрибут». Якщо не вказано Якщо З іншими параметрами У редакторі вікітексту 2010 року з TemplateWizard:
У візуальному редакторі та редакторі вікітексту 2017 |
"paramOrder": [
"date",
"reason",
"talk"
]
|
Всередині params
| Параметр | Опис | Приклад |
|---|---|---|
| Назва параметра |
Єдиним параметром першого рівня в об'єкті Так, якщо в коді шаблону зустрічається Також можна зустріти параметри з іменем
Примітка: параметри з числовими назвами необов'язково нумерувати послідовно; так, можна використати Як користуватися Кожен із цих об'єктів «Назва параметра» має містити всю інформацію щодо цього параметру шаблону в формі параметрів блоку TemplateData. Їх перелічено в наступному розділі, Всередині назви параметру. |
"1": { // назва параметру
... // тут іде інформація про параметр
}
|
Всередині назви параметру
| Параметр | Опис | Приклад |
|---|---|---|
| aliases |
Додатковий параметр
or
Це означає, що назви параметра синонімічні, можна застосувати будь-яку для задання його значення. Така конструкція в коді перекладається дослівно так: «Значення parameter1. Якщо parameter1 невизначений чи його значення порожнє, то значення parameter2.» У другому випадку далі так: «Якщо parameter2 не вказаний чи має порожнє значення, то порожнє значення.» Аби додати синонімічні назви за допомогою |
"aliases": ["1", "talk", "talksection"],
|
| inherits |
Необов'язковий параметр Аби застосувати цей параметр, напишіть |
"params": {
"тема1": {
"label": "Тема",
"description": "Тема, що згадується на цій сторінці неоднозначності",
"type": "string"
},
"тема2": {
"inherits": "тема1"
},
"тема3": {
"inherits": "тема1",
"label" : "A different label"
}
}
|
| label |
Параметр TemplateData |
"label": "Місяць та рік",
|
| description |
Тут |
"description": "Місяць і рік, коли цей шаблон було додано до бази.",
|
| type |
See the #Type parameter section. |
|
| default |
Деякі параметри шаблону мають значення за замовчуванням; значення використовується, якщо воно не перевизначено користувачем.
Елемент Вплив У всіх основних редакторах (візуальний редактор, редактор вікітексту 2017 та редактор вікітексту 2010 із TemplateWizard) текст З іншими параметрами У всіх основних редакторах (візуальний редактор, редактор вікітексту 2017 та редактор вікітексту 2010 із TemplateWizard), якщо вказано |
"default": "Category:CommonsRoot",
|
| autovalue |
Параметру можна призначити This value can be overwritten by the user in the template editor. З іншими параметрами У всіх основних редакторах (візуальний редактор, редактор вікітексту 2017 та редактор вікітексту 2010 із TemplateWizard) |
"autovalue": "{{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}"
|
| example |
Параметр Вплив У всіх основних редакторах (візуальний редактор, вікітекстовий редактор 2017 і редактор вікітексту 2010 з TemplateWizard) ця властивість відображається під описом параметра (і під текстом З іншими параметрами У всіх основних редакторах (візуальний редактор, редактор вікітексту 2017 та редактор вікітексту 2010 із TemplateWizard), значення |
"example": "January 2013",
|
| suggested values |
Атрибут
Інші типи (file, page, template, user, date, boolean, URL) наразі не підтримуються, оскільки вони мають особливу функціональність у візуальному редакторі, як-от автозаповнення, яке створить колізію із випадаючим меню із запропонованими значеннями. Редагування даних TemplateData як JSON у вікітексті Аби додати перелік запропонованих значень для параметра шаблону, додайте новий атрибут "suggestedvalues" в JSON. Значенням атрибуту “suggestedvalues” має бути перелік рядків (ланцюжків). Editing template data with the template data editor
Effects Після цього візуальний редактор відображуватиме запропоновані значення в комбінованому списку (випадаючий список, в якому можна також вводити текст) для типів параметра шаблону, перелічених вище. Користувач обирає потрібне значення натисканням. Якщо цей список довгий, користувач може почати набір в полі вводу, список фільтруватиметься із залишенням лише тих варіантів, які починаються зі введених символів. Цей фільтр можна просто витерти, що поверне повний перелік. Якщо потрібного значення немає в списку, його можна просто набрати вручну. |
"suggestedvalues": [
"Journal",
"Book",
"Newspaper",
"Magazine"
]
|
| Status option | Description | Example |
|---|---|---|
| required |
Також у нас є Він визначає, чи є заповнення заданого параметра обов’язковим для шаблону. Вплив Статус обов'язкового параметра впливає на візуальний редактор та Редактор вікі-тексту 2017 в такий спосіб:
WikiEditor із Розширення:TemplateWizard, як і інші редактори, так само автоматично при використанні шаблону відображує такий параметр, але його неможливо прибрати. Він також пише «Поле є обов'язковим.» в описі параметра, а натомість відображає назву параметра збоку під заголовком «Обов'язкові параметри». В усіма іншому він спрацьовує так само, як і два інших редактори, за винятком того, що попередження пише про «ввод не відповідає очікуваному формату». З іншими параметрами У візуальному редакторі та редакторі вікітексту 2017 статус |
"required": true
|
| suggested |
Статус Використовуйте Вплив У візуальному редакторі та Редактор вікі-тексту 2017 цей статус автоматично відображує параметр, коли користувач застосовує шаблон. Якщо для параметра вказано «автозначення», воно також автоматично відобразиться у полі вводу. Інших ефектів немає, як і додаткового тексту чи вікон попереджень. WikiEditor із TemplateWizard параметр не відображується автоматично при використанні шаблону, але його назва потрапляє збоку в перелік під заголовком «Пропоновані параметри». Далі користувач може натиснути символ «+» поряд з назвою параметра, аби додати його до використання шаблону. З іншими параметрами Статус |
"suggested": true
|
| deprecated |
Нарешті, наявний Це статус параметрів, які більше не повинні використовуватися, але поки що існують. Таке трапляється, коли редагуванням шаблону змінюють набір його параметрів. Вплив Візуальний редактор та редактор вікітексту 2017 під впливом цього параметра відображують сірий знак оклику біля назви параметра шаблону при його вставленні, а в підказці під його описом відображують сірим курсивом текст «Поле застаріло. deprecation reason». На функціональність і застосовність параметра шаблону це не впливає, як і не веде до відображення додаткових попереджень. Попри той факт, що цей параметр блоку TemplateData може набувати текстового значення, з січня 2020 р. жоден із основних редакторів (візуальний, редактор вікітексту 2017 та 2010) не відображує користувачу цього тексту.
Введений текст дає той самий ефект, що й значення Редактор вікітексту 2010 із TemplateWizard не дозволяє бачити чи додавати параметр шаблону, для якого «deprecated» встановлено в З іншими параметрами Якщо разом із цим встановити в Якщо встановити разом із цим у В редакторі вікітексту 2010 із TemplateWizard, навпаки, |
"deprecated": "Натомість використовуйте, будь ласка, «publicationDate»."
|
Примітка: якщо жоден із атрибутів "required", "suggested" чи "deprecated" для параметра шаблону не встановлений true, його статус в документації TemplateData відповідатиме "optional" (необов’язковий).
Після завершення редагування натисніть «Зберегти». Якщо ви десь зробили помилку, система не дозволить Вам зберегти редагування (це трохи дратує, але завдяки цьому Ви нічого не пошкодите у коді). Якщо ж Ви натрапите на помилки у самій програмі, поясніть на сторінці відгуків, що саме Ви намагалися зробити, і ми будемо раді допомогти Вам.
Зауважте, що, якщо ви зловживаєте хакерським шаблоном для динамічної генерації TemplateData, він не може перевірятися на помилки перед збереженням.
Зверніть увагу, що кожна порція інформації береться у лапки (за винятком true та false), і відокремлюється від наступної порції комою (за винятком останньої).
Параметр type
Параметр блоку TemplateData "type" дає інформацію редактору шаблонів щодо природи значення параметра шаблону.
В деяких випадках редактор шаблону отримує інструкції модифікувати користувацький інтерфейс відповідно до цієї природи, зокрема, дозволяти користувачу вводити лише значення, що відповідають вказаному типу.
Цей параметр не справляє функціонального ефекту на параметр шаблону чи його значення, він керує лише відображенням параметра шаблону в редакторі шаблонів.
Як користуватися
Додати параметр "type", за яким двокрапку, пропуск та будь-який із типів, вказаний у першому стовпчику таблиці нижче.
Приклад:
"type": "string",
Вплив
З лютого 2020 р. лише 5 із 13 типів впливають на інтерфейс візуального редактора та редактора вікітексту 2017, а в TemplateWizard таких типів 8.
Вплив певних типів напевне змінюватиметься, коли редактори шаблонів отримуватимуть оновлення для їхньої підтримки. Один із таких проєктів для візуального редактора та редактора вікітексту 2017 відслідковується в задачі Phabricator T55613. Подібний проєкт підтримки логічного типу в TemplateWizard відслідковується в T200664.
Нижче перелічено актуальні ефекти.
| Value | Description | |
|---|---|---|
| unknown |
Значення Вплив Тип | |
| string |
Значення Вплив У всіх основних редакторах (візуальний редактор, редактор вікітексту 2017 та редактор вікітексту 2010 із TemplateWizard) | |
| line |
Значення Вплив
| |
| content |
Тип Вплив
| |
| unbalanced-wikitext |
Тип Вплив
| |
| wiki-page-name |
Тип Вплив У всіх основних редакторах (візуальний, редактор вікітексту 2017 та 2010 із TemplateWizard) | |
| wiki-file-name |
Тип Вплив
| |
| wiki-template-name |
Тип Вплив У всіх основних редакторах (візуальний, редактор вікітексту 2017 та 2010 із TemplateWizard) | |
| wiki-user-name |
Тип Вплив У всіх основних редакторах (візуальний, редактор вікітексту 2017 та 2010 із TemplateWizard) | |
| number |
Значення Вплив
З іншими параметрами
| |
| boolean |
Тип Вплив З лютого 2020 р. жоден із основних редакторів (візуальний, редактори вікітексту 2017 та 2010 із TemplateWizard) не використовує це значення, тобто не дає видимих ефектів. Із | |
| date |
Тип Вплив
З іншими параметрами
| |
| url |
Значення Вплив
required, але користувачу не видається попередження при вставленні шаблону без URL. Це також має місце за будь-якого статусу (як-от «suggested"» чи «deprecated»).
З іншими параметрами
| |
Спеціальні формати
Редагуванням значення "format" можна створити спеціальні формати, якщо ввести набір символів вікітексту, дотримуючись певних наперед заданих правил.
{{- початок шаблону_- вміст (рядок, ціле число, параметр тощо). Символ підкреслювання визначає найменшу довжину значення в символах, його можна повторювати, як-от у_______. Якщо користувач не вичерпав усю довжину, значення буде доповнено пропусками. Це можна застосувати, приміром, для вирівнювання всіх знаків рівності після параметрів на певній позиції (якщо застосовано із\nяк позначкою нового рядка).|- вертикальна риска (розділює параметри)=- знак рівності (передує значенню параметра)\nабо натискання кнопки вводу — новий рядок (відобразить↵у полі вводу)\nдля формування відступу рядків)}}- кінець шаблону
Вікітекст має щонайменше задовольняти мінімуму {{_|_=_}}, інакше буде видано помилку форматного рядку.
| Мета | Рядок формату | Виведення |
|---|---|---|
| Рядкове форматування | {{_|_=_}} inline
|
{{Foo|bar=baz|longparameter=quux}}{{Bar}}
|
| Блокове форматування | {{_\n| _ = _\n}} block
|
{{Foo
| bar = baz
| longparameter = quux
}}{{Bar}}
|
| Без пропуску перед іменем параметру, кожен шаблон на своєму власному рядку | \n{{_\n|_ = _\n}}\n
|
{{Foo
|bar = baz
|longparameter = quux
}}
{{Bar}}
|
| Відступ кожного параметру | {{_\n |_ = _\n}}
|
{{Foo
|bar = baz
|longparameter = quux
}}{{Bar}}
|
| Вирівнювати всі імена параметрів до даної довжини | {{_\n|_______________ = _\n}}\n |
{{Foo
|bar = baz
|longparameter = quux
|veryverylongparameter = bat
}}
{{Bar}}
|
| Pipe-символи наприкінці попереднього рядка | {{_|\n _______________ = _}}
|
{{Foo|
bar = baz|
longparameter = quux}}{{Bar}}
|
| Рядковий стиль із більшою кількість пропусків, повинен бути на початку рядка | \n{{_ | _ = _}}
|
{{Foo | bar = baz | longparameter = quux}}
{{Bar }}
|
| Шаблон на початку рядка, вирівняні відступи параметрів, вертикальна риска завчасно | \n{{_ |\n _______________ = _}}
|
{{Foo |
bar = baz |
longparameter = quux}}
{{Bar}}
|
Порожня заготовка
Ви можете скопіювати порожній макет нижче, аби додати новий блок TemplateData до шаблону. У цей макет включені лише найчастіше вживані теги.
<templatedata>
{
"description": "",
"params": {
"1": {
"label": "",
"description": "",
"type": ""
},
"2": {
"label": "",
"description": "",
"type": ""
}
}
}
</templatedata>
Помилки
Синтаксична помилка в JSON./Неправильний формат JSON
Ці помилки виникають під час збереження TemplateData, зазвичай відредагованих вручну, з недійсним кодом JSON (дубльовані ключі/параметри, кінцеві або відсутні коми тощо) у візуальному редакторі або редакторі вікітексту 2017.
«Синтаксична помилка в JSON.» з’являється у візуальному редакторі та редакторі вікітексту 2017 року; Під час редагування в редакторі TemplateData GUI з’являється повідомлення «Поганий формат JSON».
These errors can be difficult to detect and come in too many forms to list. Найкращий спосіб уникнути їх — редагувати дані шаблону виключно за допомогою редактора TemplateData; найкращий спосіб виявити їх після того, як вони виникли, — це використати зовнішній валідатор JSON, наприклад JSONLint, який виділить помилки та допоможе їх виправити.
Редактор вікітексту 2010 року не перевіряє недійсний JSON завдяки старій невиправленій помилці (завдання T128029). Pages that contain invalid JSON may throw alarming "Внутрішня помилка" messages. To fix these errors, your best bet is to use a JSON validator (see above).
Обов'язкову властивість "paramOrder[number]" не знайдено.
Ця помилка виникає, коли певний параметр введено в "params", але він відсутній в "paramOrder".
Число в квадратних дужках посилається на параметр із "paramOrder", відсутній в подальшому. Це порядковий номер, нумерація починається з 0, тобто перший параметр має номер 0, другий — 1 тощо.
"params": {
"date": { ...
},
"reason": { ...
},
"talk": { ... // <-- This parameter is not stated in "paramOrder", but it should be.
}
},
"paramOrder": [
"date",
"reason"
]
// Error: Required property "paramOrder[2]" not found.
Для усунення помилки упевніться, що всі параметри, визначені в "params", також зібрані в "paramOrder".
Або ж ви можете взагалі прибрати об'єкт "paramOrder" із блоку TemplateData.
Неприпустиме значення властивості "paramOrder[number]".
Ця помилка виникає, коли певний параметр введено в "paramOrder", але він відсутній в "params".
Число в квадратних дужках посилається на параметр у "paramOrder", якого там не має бути. Це порядковий номер, нумерація починається з 0, тобто перший параметр має номер 0, другий — 1 тощо.
"params": {
"date": { ...
},
"talk": { ...
}
},
"paramOrder": [
"date",
"reason", // <-- This parameter is not stated in "params", but it should be.
"talk"
]
// Error: Invalid value for property "paramOrder[1]".
Для усунення помилки упевніться, що всі параметри, визначені в "paramOrder", також зібрані в "params".
Або ж ви можете взагалі прибрати об'єкт "paramOrder" із блоку TemplateData.
Властивість "params.parametername.required" має бути типу "boolean".
Ця помилка виникає, якщо взяти в лапки значення параметрів "required" або "suggested".
"suggested": "true" // <-- These quotation marks shouldn't be here.
Оскільки це логічні змінні, а не рядки, лапки для них зайві.
Аби усунути цю помилку, приберіть всі лапки навколо значень true чи false цих параметрів.
Атрибут «format» очікується як…
Якщо параметр "format" вказаний зі значенням, відмінним від "inline", "block" чи коректного рядка форматування, виникне помилка «Властивість «format» має бути «inline», «block», або дійсний рядок формату.»
"format": "notinline"
// Error : Property "format" is expected to be "inline", "block", or a valid format string.
Аби усунути помилку, перевірте, що значення після "format": дорівнює "inline" чи "block" і що в ньому немає помилок написання. Або ж, якщо робота з вікітекстом, перевірте, що він містить якнайменше {{_|_=_}} і не містить синтаксичних помилок, які зазвичай не дозволять обробити код шаблону, як-от подвійні знаки рівності чи зайві/відсутні фігурні дужки див. розділ #Нестандартні формати за подробицями синтаксису.
Або ж ви можете взагалі прибрати параметр "format", щоб усунути цю помилку.
Неочікувана властивість "parametername".
Ця помилка виникає, якщо створити неприпустимий параметр блоку TemplateData. Радше за все це помилка друку.
<templatedata>
{
"description": "",
"format": "inline",
"params": {
"1": {
"label": "",
"descriptino": "", // <-- spelling mistake
"type": ""
}
}
}
</templatedata>
Вона також трапляється, якщо записати параметр одного блоку з TemplateData в інший його блок. Це також може бути спричинено помилкою друку (розстановка дужок).
Приміром, можна було помилково записати параметр "label" в кореневому блоці об'єкту TemplateData замість всередині "params":
<templatedata>
{
"description": "",
"format": "inline",
"label": "", // <-- incorrectly placed parameter
"params": {
"1": { // ↓ it should be in here
"description": "",
"type": ""
}
}
}
</templatedata>
Або ж, якщо неочікуваний параметр знаходиться всередині параметра parametername шаблону "params", в описі помилки ви побачите його назву як «params.parametername.»
Аби усунути помилку, перевірте, що всі назви параметрів написано правильно, а також що всі параметри записано у відповідному блоці. Ще перевірте, що ви не додали неіснуючий в об'єкті TemplateData параметр. Можна перевірити, які параметри відомі для певного об'єкту, в розділі #Параметри TemplateData.
Обов'язкову властивість "params" не знайдено.
Ця помилка виникає, якщо в блоці TemplateData відсутній об'єкт "params".
Це обов'язковий об'єкт, оскільки він містить всю інформацію про кожен із параметрів шаблону, тож виправте цю помилку, перевіривши, що він доданий без синтаксичних помилок.
Див. вище інструкцію з додавання параметра "params".
Обмеження і запитання
- Відсутні функції – TemplateData є, значною мірою, прикладом інструмента, який було випущено з небагатьма функціями в надії, що користувачі допоможуть спрямувати розвиток функцій у бажане для них русло. Якщо Ви хочете подати запит на нові функції TemplateData, будь ласка, дайте нам знати.
- Затримки у відображенні в шаблонах – Після додавання TemplateData до шаблону, метадані повинні бути видимі миттєво, як тільки шаблон буде відкрито у Візуальному редакторі. Однак існує ймовірність, що оновлення метаданих займе більше часу — навіть до кількох годин. Ви можете пришвидшити оновлення, виконавши нульове редагування сторінки самого шаблону (але не сторінки документації). Для виконання нульового редагування відкрийте сторінку шаблону для редагування, та збережіть її без внесення будь-якої зміни і без додавання будь-якого опису редагування.
- Поточні проблеми – Список поточних баґів та запитів на функції можна переглянути на баґтрекері Вікімедіа.
Інші інструменти
- Довідка:Розширення:TemplateWizard
- Діалогове вікно панелі інструментів для введення вікі-тексту шаблону через форму, що будується з TemplateData.
- TemplateData Wizard
- Інструмент, що генерує TemplateData через інтерактивний інтерфейс.
- Skeleton TemplateData generator
- Інструмент, що зчитує вихідний код шаблона, намагається відшукати усі параметри, що в ньому використовуються, та продукує макет TemplateData із вже занесеними до нього параметрами.
- JSONLint
- Інструмент, що дозволяє перевірити написаний вручну код JSON, відшукуючи помилки у синтаксисі.
- Список усіх шаблонів із TemplateData у цій вікі
- При використанні шаблону TemplateData у німецькій Вікіпедії, дані шаблону відображаються в окремому, графічно оформленому розділі, а сам шаблон додається до категорії шаблонів із TemplateData
- https://query.wikidata.org/ і помічник запитів