Help:TemplateData

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page Help:TemplateData and the translation is 80% complete.
Outdated translations are marked like this.
Other languages:
Bahasa Indonesia • ‎Cymraeg • ‎Deutsch • ‎English • ‎Ilokano • ‎Lëtzebuergesch • ‎Nederlands • ‎Oromoo • ‎Scots • ‎Tiếng Việt • ‎Türkçe • ‎Zazaki • ‎asturianu • ‎azərbaycanca • ‎català • ‎dansk • ‎emiliàn e rumagnòl • ‎español • ‎euskara • ‎français • ‎føroyskt • ‎galego • ‎hrvatski • ‎italiano • ‎lietuvių • ‎magyar • ‎occitan • ‎polski • ‎português • ‎português do Brasil • ‎română • ‎slovenčina • ‎slovenščina • ‎suomi • ‎svenska • ‎čeština • ‎Ελληνικά • ‎български • ‎македонски • ‎русский • ‎српски / srpski • ‎українська • ‎հայերեն • ‎ייִדיש • ‎עברית • ‎العربية • ‎تۆرکجه • ‎سنڌي • ‎فارسی • ‎پښتو • ‎अङ्गिका • ‎अवधी • ‎मराठी • ‎हिन्दी • ‎বাংলা • ‎ไทย • ‎ქართული • ‎中文 • ‎日本語 • ‎ꯃꯤꯇꯩ ꯂꯣꯟ • ‎한국어
PD Забележка: С редактирането тази страница, вие се съгласявате да предоставите приносите си под лиценз CC0. За повече информация, вижте помощните страници за Обществено достояние.
PD

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

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

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

TemplateData редактор

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

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

Manage template documentation button for TemplateData 2014.png

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

Скрийншот на инструмента за редактиране на TemplateData

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

Ако документацията на шаблона е в подстраница, бутонът "Add suggested parameter(s)" ще се появи само на страницата на шаблона. Възможно решение е да редактирате страницата на шаблона, натиснете върху "Add suggested parameter(s)" в редактора на TemplateData и след това да копирате и поставите съдържанието на TemplateData (между таговете <templatedata> и </templatedata>) в подстраницата за документация.

Ако страницата на шаблона е защитена, можете да копирате и поставите кода на шаблона в подстраницата, да използвате бутона "Add suggested parameter(s)" там, да копирате съдържанието на 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>

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

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

Template parameters

ParameterDescriptionTypeStatus
Категория в Общомедия1

Категорията в Общомедия, към която искате да препратите.

Default
Category:CommonsRoot
Stringrequired

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

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": набор от цифри;
  • "boolean": '0' for false, '1' for true, '' for unknown;
  • "wiki-user-name": набор от символи, които представляват потребителско име;
  • "wiki-page-name": набор от символи, които представлява име на страница;
  • "wiki-file-name": име на файл.

Other types include: "unknown", "date", "url", "wiki-template-name", "content", "unbalanced-wikitext", "line"

"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."

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

Note that if you are abusing a hack template to dynamically generate TemplateData, it cannot be checked for errors before saving.

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

Custom formats

When editing custom format strings in the TemplateData editor you can either type \n or press the enter key to represent a newline; in either case it will display as in the entry field.

Examples of formats you can use
Objective Format string Output
Inline formatting {{_|_=_}}
inline
{{Foo|bar=baz|qux=quux}}{{Bar}}
Block formatting {{_\n| _ = _\n}}
block
{{Foo
| bar = baz
| qux = quux
}}{{Bar
}}
No space before the parameter name,

each template on its own line

\n{{_\n|_ = _\n}}\n
{{Foo
|bar = baz
|qux = quux
}}
{{Bar
}}
Indent each parameter {{_\n |_ = _\n}}
{{Foo
 |bar = baz
 |qux = quux
}}{{Bar
}}
Align all parameter names to a given length {{_\n|_______________ = _\n}}\n
{{Foo
|bar             = baz
|qux             = quux
|veryverylongparameter = bat
}}
{{Bar
}}
Pipe characters at the end of the previous line {{_|\n _______________ = _}}
{{Foo|
  bar             = baz|
  qux             = quux}}{{Bar}}
Inline style with more spaces, must be at start of line \n{{_ | _ = _}}
{{Foo | bar = baz | qux = quux}}
{{Bar }}
Template at the start of a line, indent-aligned parameters, pipe beforehand \n{{_ |\n _______________ = _}}
{{Foo |
  bar             = baz |
  qux             = quux}}
{{Bar}}

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

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

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

За да добавите тази информация в 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>

Errors

Syntax Error in JSON / Bad JSON format

Due to a long standing bug, users using the old wikitext editor are able to save pages which have certain types of invalid JSON, such as duplicate keys or trailing commas (details: task T128029). However if you attempt to save this page in a JavaScript based editor, such as VisualEditor or the 2017 Wikitext editor, you will see an error message "Syntax error in JSON," as the JavaScript parser is stricter and doesn't allow invalid JSON. Additionally, if you attempt to open up such invalid JSON with the Template Data GUI editor, you will see the error message, "Bad JSON format." To fix these errors, you can enter the JSON block into an external JSON validator, such as https://jsonlint.com/, and it will highlight the problematic commas and keys so they can be removed.

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

Help:Extension:TemplateWizard
A toolbar dialog window for entering template wikitext via an form built from TemplateData.
TemplateData Wizard
Инструмент, който генерира TemplateData чрез интерактивен интерфейс.
Skeleton TemplateData generator
Инструмент, който разчита изходния уикикод на шаблон, опитва се да намери всички използвани параметри и изработва схема с изброени параметри.
JSONLint
Инструмент, който ви позволява да валидирате ръчно написан JSON за помагане при откриване на грешки в синтаксиса.