Уикипедия:TemplateData/Помощ

За Визуалния редактор

Помощ

Какво е TemplateData?

TemplateData е начин за съхраняване на информация за уикитекстов шаблон и параметрите му, така че Визуалният редактор да може да я обработи и покаже в своя редактор на шаблони, като по този начин улесни редактирането на страници, използващи този шаблон.

Разширението TemplateData е инсталирано на всички уикита на Фондация Уикимедия. Ако имате собствено уики, тогава трябва да инсталирате TemplateData.

Синтаксисът на TemplateData позволява на потребителите да записват малки парченца структурирани данни в страницата на шаблона, или да ги вграждат в страницата на шаблона (например в страницата му с документация). След като един шаблон има тези структурирани данни, той може да се покаже правилно във Визуалния редактор. Въпреки, че звучи сложно, в действителност това е много лесно.

TemplateData редактор

Има вграден инструмент за редактиране по прост начин на TemplateData.

За да използвате редактора на TemplateData, отидете на страницата на шаблона (или на подстраницата му с документация) и натиснете бутона Редактиране. Отгоре ще се появи бутон Редактиране данните на шаблона, точно над отворения прозорец за редактиране:

Натиснете този бутон за да влезете в инструмента на графичния потребителски интерфейс за редактиране на TemplateData.

Екранна снимка на инструмента за редактиране на TemplateData — Инструментът за редактиране на TemplateData на страница, която все още не съдържа TemplateData.

Редакторът ви позволява да добавяте шаблонни параметри и да определят най-често използваните атрибути. Ако страницата, която редактирате, вече съдържа блок на TemplateData, тогава вече документираната информация ще се покаже автоматично, когато отворите правилната страница в редактора на TemplateData. В първото поле можете да добавите или актуализирате краткото описание на шаблона в обикновен текст. След това, можете да използвате бутона Добавяне на параметър (или Добавяне на предложени параметри), за да документира имената и атрибутите на параметрите, които използва шаблона.

Можете да сложите име на параметъра; псевдоними, ако има; надпис и описание, които ще се показват на потребителите. Можете също така да дадете пример как да се използва параметъра. Единственото задължително поле е Име (първото поле за всеки ред), където да запишете точното, чувствително към регистъра на буквите (малки или главни) име на параметъра. Във падащото меню Вид можете да изберете вида на съдържанието, което параметърът трябва да получи, например низ (за отговор в обикновен текст), страница (за препратки към други страници), дати и др. Ако шаблонът причинява грешка, понеже този параметър е оставен празен – моля да го маркирате като Задължителен (Required). Ако параметърът се използва често, тогава го маркирайте като Предложен (Suggested). Бутонът Премахване на информацията за параметъра (Remove parameter information) ще изтрие записите на параметъра от TemplateData.

Екранна снимка на редактора на TemplateData, показваща добавянето на втори параметър

Когато приключите с документиране на всички параметри, натиснете Apply, за да вмъкнете предварително форматирания TemplateData в отворения прозорец за редактиране. Накрая трябва да запазите промените по страницата, като използвате бутона Съхраняване под прозореца за редактиране.

Внимание: Редакторът на TemplateData ще го постави или в страницата на шаблона или в подстраницата му с документация. Вие определяте къде ще бъде добавен TemplateData чрез отваряне (редактиране) на страницата, в която искате да бъде поставен. Въпреки това, ако няколко блока на TemplateData са поставени на един и същи шаблон, ще се използва само един от тях. Ако на дадена страница вече има TemplateData, тогава ще трябва да редактирате страницата, на която TemplateData е бил поставен преди това, за да се избегне случайното създаване на няколко блока от TemplateData.

Ограничения и въпроси

Липсващи функции – TemplateData е показателен пример за инструмент, който бе въведен на разположение с малко на брой функции – с надеждата, че потребителите ще спомогнат за развитието на функциите, които желаят. Ако желаете нови функции за TemplateData, моля да ни уведомите.
Забавяне при изобразяване на шаблони – След добавяне на TemplateData към шаблон, метаданните трябва да са видими веднага, когато шаблонът се отваря в режим на Визуален редактор. Въпреки това е възможно процеса да отнеме няколко часа преди показването на метаданните. Можете принудително да го обновите, като направите празна редакция на самата страница на шаблона (но не на подстраницата с документация). За извършване на такава редакция, отворете страницата на шаблона в режим на редактиране и я съхранете без да правите промени и без да добавяте резюме на редакцията.
Текущи проблеми – Списък с текущите грешки и заявки за функции е достъпен на бъг тракера на Уикимедия.

Локализиране на TemplateData

TemplateData е на страницата, която описва, или е вграден в нея.

В шаблон, той обикновено е поставен между тагове <noinclude>.

При нормалното изобразяване на страница, той показва автоматично генерирана документация, както е показано в примера.

Структура на TemplateData

Структурата на TemplateData е базирана около JSON стандарта. Имайте предвид, че всички описания в TemplateData трябва да са в обикновен текст (без уикитекст, без препратки и т.н.).

Първото нещо, което да направите, е да поставите двойка тагове <templatedata> където и да е на подстраницата с документация на шаблона така:

<templatedata>
{
    ...       // Съдържанието на TemplateData идва тук
}
</templatedata>

Това казва на софтуера, че всичко между таговете е TemplateData и трябва да бъде посочвано, когато се използва шаблона.

Пример

Описанията вътре в TemplateData следват стандартно оформление; да кажем, че имате шаблон, наречен „Общомедия“ за препращане на дадена тема към категория в Общомедия. Той взема един задължителен параметър: името на категорията в Общомедия. TemplateData ще изглежда по следния начин:

<templatedata>
{
    "description": "Шаблон за свързване на статия към категория в Общомедия",
    "params": {
        "1": {
            "label": "Категория в Общомедия",
            "description": "Категорията в Общомедия, към която искате да препратите.",
            "default": "Category:CommonsRoot",
            "type": "string",
            "required": true
        }
    }
}
</templatedata>

Това ще се покаже в шаблона ето така:

Шаблон за свързване на статия към категория в Общомедия

Параметри на шаблона
Параметър		Описание	Тип	Статут
Категория в Общомедия	`1`	Категорията в Общомедия, към която искате да препратите. По подразбиране Category:CommonsRoot	Низ	задължителен

Описание и параметри

description	Първият таг е `"description"`, който описва какво прави шаблона.	"description": "Шаблон за свързване към категория в Общомедия",
format	Следващият е `"format"`, който описва как да бъде показан уикитекста на шаблона. Това може да бъде зададен като `"inline"` (по подразбиране) или `"block"`. Ако параметърът е зададен на `"inline"`, той ще показва уикитекста без празни пространства, ето така: `{{Foo\|bar=baz\|qux=quux}}` Ако е зададен на `"block"`, ще показва уикитекста с редове и интервали между частите, ето така: {{Foo \| bar = baz \| qux = quux }}	"format": inline
params	След това е тагът `"params"`, който показва, че следващите секции обхващат всеки параметър в шаблона. Всички параметри, които следват, са включени в секцията `"params"`.	"params": { ... // параметрите идват тук }
	Във всяка подсекция на параметър, първият таг е името на шаблонния параметър в рамките на самия шаблон. Ако параметърът има име като `{{{категория-препратка}}}`, този таг ще бъде `"категория-препратка"`. Ако параметърът е "неназован", което означава, че е просто число като `{{{1}}}`, този таг ще бъде `"1"`. Битовете информация относно този параметър се включват в секцията, която започва с името на параметъра.	"1": { // име на параметъра ... // информацията за параметъра идва тук }
label	После е `"label"`, в което да поставите видимото от човек заглавие на параметъра, което ще бъде показано в рамките на редактора на шаблона.	"label": "Категория в Общомедия",
description	След това е `"description"`: този път, това е описанието на параметъра, не на шаблона като цяло.	"description": "Категорията в Общомедия, към която искате да препратите.",
default	Следващият е `"default"`. Някои шаблони имат стойност по подразбиране, която да се използва, освен ако не я промените. Този елемент показва на потребителя какво е стойността по подразбиране за параметъра. Можете да игнорирате този параметър, ако няма стойност по подразбиране.	"default": "Category:CommonsRoot",
type	После е `"type"`, който контролира как шаблонния редактор да интерпретира параметъра. Може да бъде: `"string"`: набор от символи, като това изречение; `"number"`: набор от цифри; `"wiki-user-name"`: набор от символи, които представляват потребителско име; `"wiki-page-name"`: набор от символи, които представлява име на страница; `"wiki-file-name"`: име на файл.	"type": "string",
required	След това е `"required"`, който може да бъде зададен като `true` или `false`. Той просто контролира дали попълването на параметъра е задължително за този шаблон. Ако това не е указано, за зададено се приема `false`.	"required": true
suggested	После е `"suggested"`, който може да бъде зададен като `true` или `false`. Това е статута на параметри, които не са "необходими", но се препоръчва да имат голяма стойност (но не и задължителна) за потребителите на шаблони. Ако това не е указано, за зададено се приема `false`.	"suggested": true
deprecated	Накрая е `"deprecated"`, който може да се зададе като `true`, `false` или низ, който описва какво трябва да направят потребителите вместо това. Това е статута на параметри, които не би трябвало повече да се използват, но все още съществуват. Причината би могла да бъде поради преместването на употребата на шаблона от един набор от параметри към друг. Ако това не е указано, за зададено се приема `false`.	"deprecated": "Please use 'publicationDate' instead."

След като сте готови, натиснете "Съхраняване". Ако сте направили грешка, тя няма да ви позволи да запишете промените (което е смущаващо, но означава, че не може да се счупи нещо). Ако се сблъскате с грешка, обяснете на страницата за обратна връзка какво сте опитали да направите, и ще се радваме да ви помогнем.

Имайте предвид, че всяка част от информацията се поставя между кавички (с изключение на true и false), и се отделя от следващата част със запетая (освен ако не е последната).

Други имена (псевдоними) на параметър

Някои шаблони позволяват на един параметър да има различни имена.

Например, {{Общомедия|категория=Ябълки}} също би могъл да бъде записан като {{Общомедия|Ябълки}} или {{Общомедия|линк=Ябълки}}.

За да добавите тази информация в TemplateData, просто трябва да добавите другите имена (псевдонимите) в информацията на параметъра:

    "params": {
        "категория": {
            ...
            "aliases": ["1", "препратка"]
        }

Автоматична стойност

Можете да посочите "autovalue" (автоматична стойност) за даден параметър. Когато потребителите добавят шаблона към страница, тази стойност ще бъде добавяна автоматично. Например, много почистващи шаблони трябва да имат дата на добавянето им; ако определите "автоматична стойност" за параметъра за дата в шаблона, датата ще бъде попълвана автоматично.

За да добавите тази информация в TemplateData, просто добавете автоматичната стойност в информацията на параметъра. Вероятно ще искате да използвате subst:, за да придържате стойностите:

    "params": {
        "дата": {
            ...
            "autovalue": "{{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}"
        }

Множество параметри

Ако имате няколко параметри, просто повторете всяка секция (като се започне от тага "1") и я попълнете, както намерите за добре. Имайте предвид, че ако един шаблон има множество параметри, трябва да ги разделяте със запетая в Templatedata ето така:

"params": {
    "1": {
        ...
    },      // забележете запетаята тук
    "2": {
        ...
    },      // и тук
    "3": {
        ...
    }
}

Подобни параметри

Когато един шаблон има множество параметри, понякога някои от тях могат да бъдат от един и същи вид. В този случай, само трябва да попълните пълните свойства за първия, а останалите могат да "получат" свойствата си от него.

    "params": {
        "тема1": {
            "label": "Тема",
            "description": "Тема, спомената на тази пояснителна страница",
            "type": "string"
        },
        "тема2": {
            "inherits": "тема1"
        },
        "тема3": {
            "inherits": "тема1"
        },
    }

Празен модел

Може да копирате празния стандартен текст по-долу за да добавите нов TemplateData към шаблон. Включени са само най-често използваните тагове.

<templatedata>
{
    "description": "",
    "params": {
        "1": {
            "label": "",
            "description": "",
            "type": ""
        },
        "2": {
            "label": "",
            "description": "",
            "type": ""
        }
    }
}
</templatedata>

Други инструменти

TemplateDataEditor – Потребителски скрипт, който улеснява процеса на добавяне на TemplateData. В момента той съществува на френски (съдържа английски, италиански, японски и корейски превод), и лесно може да бъде преведен на други езици.
TemplateData Wizard – Инструмент, който генерира TemplateData чрез интерактивен интерфейс.
Skeleton TemplateData generator – Инструмент, който разчита изходния уикикод на шаблон, опитва се да намери всички използвани параметри и изработва схема с изброени параметри.
JSONLint – Инструмент, който ви позволява да валидирате ръчно написан JSON за помагане при откриване на грешки в синтаксиса.
Списък на всички шаблони с TemplateData на това уики
При dewiki шаблона TemplateData, той е показан в кутия, и шаблонът се добавя към категория на шаблони с TemplateData