Википедия: TemplateData / Учебник

---

• Главная страница
• Отзывы на MediaWiki или местные отзывы
• Песочница (учетная запись не требуется)

---

О

---

• Зачем разработчики это строят?
  • Данные пользовательского тестирования
• Документация:
  • Вводное руководство
  • Гид пользователя
  • Горячие клавиши
  • Часто задаваемые вопросы (или на MediaWiki )
• Разработка:
  • Дорожная карта
  • Обновления
  • Еженедельные отчеты о состоянии

---

Выручить

---

• Обновите справочные страницы
• Добавить TemplateData ( Учебное пособие )
• Перевести и локализовать документацию

---

Исследовать

---

• Главная страница исследования

---

Другой

---

• Настройка
• Известные проблемы
• Запросы комментариев (RFC): июль 2013 г. a , июль 2013 г. b , июль 2015 г. , сентябрь 2015 г.

TemplateData - это способ хранения информации о шаблоне, такой как имена параметров или описание шаблона, чтобы VisualEditor мог получить ее и заполнить ею редактор шаблона. Он ничего не меняет в фактическом шаблоне, с которым он появляется, и ничто, что вы можете сделать с TemplateData, не повлияет на функциональность или «сломает» любой существующий шаблон Википедии (хотя ошибки, которые появляются в TemplateData, могут заставить редакторы использовать связанный шаблон или его параметры некорректны, поэтому уход все равно нужен). TemplateData контролируется расширением MediaWiki TemplateData., который позволяет пользователям записывать небольшие фрагменты структурированных данных на страницу шаблона или включать их в эту страницу шаблона (например, на стандартной странице документации). После того, как шаблон содержит эти структурированные данные, его можно будет правильно отобразить в VisualEditor. Хотя это может показаться сложным, на самом деле это очень просто.

Как использовать TemplateData [ править ]

Структура TemplateData [ править ]

Центральная структура TemplateData закодирована в формате JSON , а схема довольно проста. Первое, что нужно сделать, это ввести пару <TemplateData>тегов непосредственно на самой странице шаблона внутри <noinclude>...</noinclude>тегов или в любом месте подстраницы документации шаблона, если она есть, например:

< TemplateData >TemplateData идет сюда</ TemplateData >

NB. Приведенный выше код является неправильным, если используется как есть, и поэтому при его использовании будет выдана ошибка JSON; см. # Заполнение информации TemplateData ниже для получения дополнительной информации.

Это сообщает программе, что все между двумя тегами является TemplateData и на него следует ссылаться при использовании шаблона. Сам TemplateData следует стандартному макету, который определяет параметры, которые могут быть установлены в шаблоне.

В английской Википедии вы также можете использовать шаблон {{ Format TemplateData }} для создания более "обычного" представления TemplateData, подходящего для использования в документации по шаблонам . Вместо приведенного выше напишите это вверху страницы документации:

{{ Format  TemplateData | 1 = < TemplateData > TemplateData  идет  сюда < / TemplateData > | TOC = 1 }}

TemplateData [ править ]

TemplateData добавляется на саму страницу шаблона внутри <noinclude></noinclude>тегов или где-нибудь на странице документации шаблона, если она есть. В некоторых случаях главная страница шаблона будет заблокирована, чтобы предотвратить редактирование неавторизованными пользователями. В этой ситуации TemplateData можно добавить только на страницу / doc; ссылка на эту страницу находится внизу главной страницы.

TemplateData обычно помещается после описательной информации о шаблоне и перед разделом «См. Также».

Примечание . Вы должны добавить {{ TemplateData header }} непосредственно перед тегом <templatedata>. Это отнесет страницу к категории документации TemplateData и позволит позже организовать шаблоны и их документацию.

Определение параметров [ править ]

Если у шаблона нет параметров, вы можете заполнить его блок TemplateData простой строкой  "params": {}. Если вы не включите эту строку, вы не сможете сохранить страницу. Это завершает TemplateData для шаблона.

Однако у большинства шаблонов есть параметры, такие как даты, URL-адреса, названия статей, изображения, числа или строки. Определите, какие параметры используются или могут использоваться в шаблоне. Параметры могут передаваться знаками равенства. Например, {{cite web}}шаблон передается значения для завершения цитаты, такие как url=, title=, accessdate=, и т.д. Другие параметры могут быть использованы вместо того, чтобы их положением. В этом случае вместо имен параметров используйте числа " 1", " 2" и т . Д.

Документация шаблон на главной или суб-страницы могут обобщать , какие параметры могут быть установлены на шаблоне, и то , что каждый параметр должен включать. Кроме того, TemplateDate должен быть включен на страницу документации шаблона.

Заполнение информации TemplateData [ править ]

Помните, что информация TemplateData - это только информация о том, как шаблон предназначен для использования редакторами. Ничто из того, что вы здесь делаете, не повлияет на соответствующий шаблон, хотя создание записи TemplateData, содержащей информационные ошибки, может вызвать проблемы у редакторов, пытающихся использовать этот шаблон в статье.

Первая часть информации, которую необходимо заполнить, - это "description"общий шаблон, который не требует пояснений; в нем кратко описывается, что делает шаблон, и объясняется, где и как пользователь может захотеть его использовать. Если шаблон был создан и получил какое-то описание кем-то до вас, вы можете использовать информацию, которую вы почерпнули из верхней части главной или дополнительной страницы шаблона, которую вы можете скопировать и вставить сюда. Поместите его в кавычки и поставьте запятую :) "description": "This template generates an information box for Croatian football players",. Обратите внимание, что любой викитекст, набранный где-либо в таблице TemplateData, например [[Croatian football]], не сохранит никаких своих функций и будет отображаться как простой несвязанный текст, символ за символом.

Затем вы должны создать "params"блок с фигурными скобками ( {и }). Внутри этого блока вам необходимо создать подблок для каждого параметра, используемого шаблоном, с некоторыми из следующих записей. По большей части это необязательно, но чем больше информации вы дадите, тем легче будет другим повторно использовать шаблон.

• Создайте или используйте короткое произвольное значение "name"для параметра, который будет считываться программой-шаблоном Википедии. Если вы используете или в шаблоне есть имя параметра, содержащее более одного слова, они всегда должны быть разделены подчеркиванием: _например: ocean_size(т. Е. Имена параметров не содержат пробелов). Поместите его в двойных кавычках, следовать двоеточие, и создать блок с некоторыми более одиночными скобками {и }так: "ocean_size": { }или "range_map": { }. Обратите внимание, что во многих шаблонах, таких как {{ Infobox Fabergé egg }}, есть переменная, которая сама называется "name", и поэтому код JSON для этого параметра будет записан"name": { }. Следующий код теперь помещается в эти фигурные скобки, разделенные запятой в конце каждой, но ни одной после последней, и без дополнительных фигурных скобок (обратите внимание, что порядок этих записей не имеет значения: они будут упорядочены в соответствии с последовательным шаблоном, когда Читается код JSON TemplateData):
  • Запись является читаемым человеком названием параметра , которое будет отображаться в редакторе шаблонов. Прописными первый символ метки (так как это будет самое левое значение в результирующей таблице), и поместить его в кавычки, например: ."label""Ocean size":
  • Введите параметр (т. Е. Описание конкретного параметра, а не шаблона в целом). Возможно, это уже было написано на главной странице шаблона или странице документации, и его можно скопировать и вставить на место. Поместите эту информацию в кавычки. Если вы хотите , чтобы ваше описание также отобразить слово или фразу в кавычки, вы должны бежать кавычки, поставив обратную косую черту прямо перед тем им , как это:"description"\"This parameter indicates the \"size\" of the ocean". Если вы не укажете обратную косую черту непосредственно перед кавычкой, программное обеспечение JSON будет интерпретировать ее как конец блока параметров - обратная косая черта говорит JSON: «Не считайте кавычки, следующие непосредственно за мной - отображайте их как видимые. кавычки и ищите кавычки в конце параметра далее ". Если слово, которое вы хотите отобразить в кавычках, находится в самом конце описания вашего параметра, вам просто нужно будет ввести \""следующее: "This parameter indicate the ocean \"size\"" вы можете включить любую другую пунктуацию (запятую, точку с запятой, двоеточие, фигурную скобку, скобку, двойную скобку и т. Д. ) между двумя кавычками, как хотите. Однако следует отметить, что если вам нужен фактический обратный слеш \как часть текста, вам придется бежать , что тоже с другой обратной косой черты, например: \\.
  • При желании вы можете установить флаг статуса параметра:
    • "required"говорит, что заполнение параметра обязательно для этого шаблона. Устанавливайте это trueзначение только в том случае, если значение требуется для шаблона, и не установка значения приведет к поломке шаблона (например, URL-адрес для Cite web ). Записи для этого флага должны быть либо словом, trueлибо falseбез кавычек.
    • "suggested" говорит, что это одна из переменных, которую большинство пользователей шаблона, вероятно, захотят заполнить (например, дата источника для цитирования). У вас почти всегда должен быть хотя бы один предлагаемый параметр в шаблоне. Например required, используйте слово trueили falseбез кавычек.
    • "deprecated"можно установить, чтобы указать, используется ли этот параметр регулярно - а также, задав значение true, вы можете написать краткое описание того, что пользователи должны делать вместо этого. Редкий.
  • Группа позволяет перечислить другие названия для этого параметра , которые были установлены для работы одинаково хорошо, и его запись заключена одним кронштейна, то есть . Псевдоним - это альтернативное имя для параметра, который шаблон готов принять вместо (не в дополнение к) основного имени. Псевдонимы не документируются в отдельном объекте параметра."aliases""aliases": [ "2", "Caption", "imagecaption" ]
• Эта запись позволяет вам указать VisualEditor и другим инструментам предварительно заполнить этот параметр стандартным значением (в wikitext); этот текст будет отображаться в поле параметра при редактировании пользователями и будет добавлен к вызову шаблона при сохранении. Это может быть полезно для шаблонов очистки, чтобы автоматически устанавливать дату добавления шаблона пользователем. Например, добавьте в качестве автоматического значения, чтобы соответствующая дата автоматически добавлялась «Май 2021», когда редактор использует шаблон ( пример редактирования ). Редактор может изменить автоматические значения, просто удалив указанное значение в диалоговом окне шаблона. Обратите внимание , что этот метод Подстой основой делает не работу"autovalue""autovalue": "{{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}"для любых шаблонов, которые используются внутри тегов <ref>, тегов галереи или других тегов, связанных с расширением. Независимо от того, установлено ли человеком, создающим код TemplateData, эта запись, какой бы она ни была, будет отображаться как запись в результирующей таблице TemplateData; если он не создан вручную, за ним будет стоять слово «Пусто».
• Этот параметр позволяет вам показать, что будет делать шаблон, если этот параметр не установлен (или установлен, но оставлен пустым); этот текст будет отображаться как светло-серый текст в поле параметра, когда пользователи редактируют, но не будет добавлять значение к вызову шаблона при сохранении, если пользователь вручную не переопределит его. Редкий. Эта запись всегда будет отображаться в результирующей таблице TemplateData, и, если она не создана вручную человеком, пишущим код TemplateData, за ней будет следовать слово «Пустой»."default"
• Запись позволяет отображать пример записи о том , что человек может сделать для этой переменной, написанной так же , как человек может ввести его, символ-для-символа; если тип записи уже был установлен с параметром (см. ниже), тогда пример должен отражать это (т. е. если тип был установлен на «wiki-page-name», то ваш пример не должен включать префикс типа « Файл: »или« Изображение: »). Обязательно заключите весь текст примера в кавычки. Очевидно, это означает, что фактический пример может не содержать кавычек. Если он не создан человеком, пишущим код TemplateData, за ним следует слово «Empty»."example""type"
• The "type", which controls how the template editor will interpret that parameter. This can be one of a few values, any of which used must be enclosed in double quotation marks:

• "inherits". This is a key to another parameter. The current parameter will inherit from that one, with local properties overriding the inherited ones. Very rare. Currently, the inclusion of this parameter in a templatedata sub-block will cause the page to produce a Required property "params." not found. error and will fail to generate the expected table.

Where more than one parameter sub-blocks is passed to the template, you must add a comma after the close brace, },, between the sub-blocks. Do not place a comma after the last sub-block in your set, but do make sure that there is a final close brace, }.

A further option "format" determines how the wikitext code for the template will be formatted when it is saved by the VisualEditor. This can have the options "format": "inline" (the default) or "format": "block". With the inline option the wikitext of the template will be formatted as single line {{Sister project|project = commons|text = page in commons}} with the block option each parameter will take a single line

{{Infobox television| show_name = Father Ted| genre = Comedy}}

This option may be preferable for very complex templates like infoboxes which have multiple parameters. The documentation page indicated the format with the line "This template prefers inline formatting of parameters." or "This template prefers block formatting of parameters."

Save[edit]

Once you're done, hit "save". If you've made errors, it will not let you save – which can be a little frustrating, as the resulting error message will not tell you where JSON encountered the first code error, but means you cannot "break" anything or put up a table that is accidentally malformed. If you find you are unable to save because of a code error, some common problems to look for include:

• Is every opening quote (") matched with a closing quote in the correct place of the code?
• Does a string, such as a description of a parameter, contain a " that is not at the end of the entry? If so, consider replacing it with a '.
• Is every opening brace({) matched with a closing brace(}) in the correct place?
• Are there commas between params blocks? (There should be one).

Manually searching through the program for these errors can be tiresome and difficult. Fortunately, a number of program checking websites for JSON exist which will at least identify the line on which the program first encounters an error. [1] is one of these which seems to work quite well. Simply copy and paste the problematic JSON code into the corresponding box on the website and ask it to check the code— it will not itemize every error in the document, but it will indicate the first error it encounters, if any, which should be immensely helpful in correcting your code.

Once you successfully save the page, it may take a few minutes after saving for the TemplateData to be integrated into VisualEditor. If it doesn't come through after a few minutes, you can make a null edit on the main template to fix this. As many templates are protected, you may need to request a null edit using {{editprotected}} or leaving a note on Wikipedia talk:VisualEditor/TemplateData tutorial.

Worked example[edit]

The {{Str left}} template is a simple template used like {{Str left|<string>|<count>}} to show the first few characters of an input. It has two parameters, neither of which are named (they are only recognised by their position in the template), and both of which are required. Thus the TemplateData for this template might be:

<templatedata>{"description": "Give the first few characters from the start of the input","params": {"1": {"label": "Input","description": "The string to be trimmed and counted","required": true,"type": "string"},"2": {"label": "Length","description": "How many characters of the input should be returned","required": true,"type": "number"}}}</templatedata>

... which would display in the template like so:

Complete empty TemplateData block[edit]

You can just copy and paste this to use when creating your own.

<templatedata>{"description": "zzzzz","params": {"first parameter": {"label": "x","description": "xxx","required": false,"suggested": false,"example":"x","deprecated": false,"aliases": [],"autovalue": "auto value","default": "default value","type": "string"},"second parameter": {"label": "y","description": "yyy","required": false,"suggested": false,"example": "x","deprecated": false,"aliases": [],"autovalue": "auto value","default": "default value","type": "number"}}, "sets": { }}</templatedata>

Shared documentation[edit]

Many templates share the same documentation. Putting TemplateData on a subpage has the advantage that the documentation page is generally not protected so all editors can update the documentation. However, if the TemplateData is included in a shared documentation page then this will cause some of the templates to pick up the wrong template data section.

This can be resolved by putting the TemplateData in an individual subpage (Template:col-begin/doc uses Template:Col-begin/TemplateData) or in the template page itself (as in {{collapse top}}). An alternative technique is to use {{#switch: {{PAGENAME}} | ...}} in the document page with the different templatedata sections in each switch block.

Help[edit]

Should you run into errors, explain on the feedback page what you were trying to do, and we'll be happy to help.

Examples[edit]

A template which takes no parameters: {{fixed}}. Note the params must be give as an empty list.

<templatedata>{ "description": "Displays a tick mark and the word fixed. It takes no parameters.", "params": { }
}</templatedata>

A template with aliases {{quote}}:

<templatedata>{ "description": "Adds a block quotation.", "params": { "text": { "label": "text", "description": "The text to quote", "type": "string", "required": false, "aliases": [ "1", "quote" ] }, "sign": { "label": "sign", "description": "The person who quote it is", "type": "string", "required": false, "aliases": [ "2", "cite" ] }, "source": { "label": "source", "description": "A source for the quote", "type": "string", "required": false, "aliases": [ "3" ] } }
}</templatedata>

A template with default values {{col-6}}. Note default values are the values used by a template when the parameter is not specified. This example uses the "format": "block" option.

<templatedata>
{ "description": "Starts a new column, for use with {{col-begin}} when there are six columns.", "params": { "width": { "label": "width", "description": "Width of the column.", "type": "string", "default": "16.66%", "aliases": ["w"], "required": false }, "align": { "label": "align", "description": "Horizontal alignment.", "type": "string", "default": "left", "required": false }, "valign": { "label": "valign", "description": "Vertical alignment.", "default": "top", "type": "string", "required": false } }, "format": "block"
}
</templatedata>

Limitations and questions[edit]

TemplateData is great for editing existing templates, but does not currently automatically pull in parameters when you create a new template. The ability to have it do that is being worked on now. There is some delay between the implementation and it showing up in existing templates - which makes debugging slightly difficult. There is also a slight delay after TemplateData is created before it appears in the VisualEditor.

Template data was previously limited to 65,535 bytes (Phabricator: T53740). This limit could be exceeded for some templates which use many parameters, such as {{Infobox officeholder}}, but the code is now compressed, increasing the limit.

Tools[edit]

• TemplateDataEditor A user script that makes the process of adding TemplateData easier.
• Yet another template data editor
• TemplateData Skeleton — Read the source of a template and tries to find all the parameters used and output a skeleton document with all the parameters listed. Javascript toolbox popup.
• Module:TemplateDataGenerator‎ - Skeleton generator as a template to subst.
• {{Format TemplateData}} and Module:TemplateData help format the appearance of template data sections on documentation pages.
• ru:Модуль:TemplateDataDoc allows to create blank copy and usage example from TemplateData. The module is in Russian.

External links[edit]

MediaWiki has documentation related to: Extension:TemplateData#Defining a TemplateData block

• Jsonlint a JSON validator to help spot errors in the template data syntax.