可视化编辑器/引用工具

This page is a translated version of the page VisualEditor/Citation tool and the translation is 30% complete.

可视化编辑器引用工具允许使用可视化编辑器的用户使用您wiki上的引用模板 To enable the tool, you'll need the following: a working installation of VisualEditor and Parsoid , citation templates on your wiki that use TemplateData to specify how they are invoked, and a special .json message in order to hook VisualEditor and the templates together.

You'll need citation templates in your wiki's database in order to use any citation features. If you do not currently have citation templates on your wiki (for example, in the case of a new installation) you'll need to get them. Copying them from Wikipedia is the easiest way to do this. If you already have citation templates on your wiki, you can skip these steps.

Most citation templates on Wikipedia use the programming language Lua which Scribunto makes available, and they also use the extension's parser functions. The Cite extension allows you to use the ‎<ref> tags. All Wikipedias and other WMF wikis already have all of these things installed.

  1. Export citation templates from Wikipedia: Manual:Using content from Wikipedia . Exporting w:Template:Cite web, w:Template:Cite news, w:Template:Cite journal, w:Template:Cite book is a good place to start.

Recent versions of these templates at the English Wikipedia and some others also require the supporting Lua modules.

  1. Upload your templates using the Special:Import page on your wiki (for example, http://localhost/index.php/Special:Import).

模板数据

You'll need Extension:TemplateData for the citation tool to be able to load the template data into the fields in VisualEditor and each template must have template data defined. For more information on how to define template data for citations, and to see screenshots of how a citation window should look with and without template data defined, see: Wikipedia:VisualEditor/TemplateData

Citation tool definition

要在您的 wiki 中启用可视化编辑器引用工具,您需要创建特定的消息:MediaWiki:Cite-tool-definition.json。这是因为每个 wiki 是不同的,所以需要定制它需要的那些功能,例如您 wiki 中的目标名可能与其他 wiki 中的不同。

配置消息的用途

配置消息:

  • 说明您 wiki 的标准引用中使用那种模板(可以多达 5 个)。
    • 每种模板必须含TemplateData defined or the system will be very difficult for users to understand. If your wiki does not currently use citation templates, it is common to copy the templates from the English Wikipedia as a good general set.
  • 说明您希望在每种引用类型中使用的标签。
    • 标准的有四种:“web”、“book”、“news”和“journal”,它们与 MediaWiki:Visualeditor-cite-tool-name-web 一致
  • 说明您希望在每种引用类型中使用的图标。
    • There are a standard four, "ref-cite-web", "ref-cite-book", "ref-cite-news" and "ref-cite-journal", which correspond to CSS classes with the icon as a background SVG image called oo-ui-icon-ref-cite-news etc.

Once the MediaWiki:Cite-tool-definition.json configuration message is created, the citation tool will be live for all VisualEditor users on your wiki within a few minutes.

更多类型

If you are considering adding an additional type, the development team would really like to talk with you first, to give advice, help create an appropriate icon, and so we can consider whether other wikis might also want this type defined for all wikis.

要添加其他类型,必须:

  1. 确定您要创建的类型
    • 在本例中您要使用数据库引用,所以必须调用“database”类型。
  2. 创建相应标签
    • For the example, you could make the label name "db" and add a label at MediaWiki:Visualeditor-cite-tool-name-db with the value "database". This should be in your wiki's content language. If your wiki uses multiple languages or scripts, you may need to create several of these labels.
  3. 创建一个图标
    • For the example, you could make the icon label "ref-cite-dbase", and create the icon as an SVG file uploaded to commons, create the icon class "oo-ui-icon-ref-cite-dbase" in MediaWiki:Common.css and add the icon you want with "background-image:url(//upload.wikimedia.org/wikipedia/commons/1/12/VisualEditor_-_Icon_-_Ref_db.svg)" or similar.

示例

You can see example definition messages on the English Wikipedia, Polish Wikipedia, French Wikipedia, Italian Wikipedia. Copy the code to your wiki and adapt the names to the local context.

Template type mapping

In addition to MediaWiki:Cite-tool-definition.json, you also need to create MediaWiki:Citoid-template-type-map.json to specify which types of citations map to which templates. You can see an example on the English Wikipedia.

"Citation needed" tool

 
The "citation needed" tool.

"Citation needed" templates can be configured to show an "Add a citation" button in the editor by configuring MediaWiki:Visualeditor-template-tools-definition.json with a citationNeeded key.

The configuration value lists templates (which can contain multiple titles for redirects) and parameter mappings. Currently supported keys are:

  • reason - shows the reason a citation is needed in the context item
  • date - shows the date "citation needed" template was added in the context item
  • encapsulate - text which has been wrapped by the template, and which should be unwrapped when a citation is added

The value of these mappings is the name of the parameter(s) in the local template:

{
	"citationNeeded": [
		// This key is always "citationNeeded" in every language
		// Each item of this list represents a single template
		{
			"title": [
				// Title can be a string, or list of redirects
				"Citation needed",
				"Cn",
				...
			],
			"params": {
				"reason": "reason",
				"date": "date"
			}
		},
		// This template is defined separately as it supports the
		// "encapsulate" param. On some wikis this is the same
		// template as the one above.
		{
			"title": [
				"Citation needed span",
				"Cite needed span",
				...
			],
			"params": {
				// Parameters can be a string or list of aliases
				"encapsulate": [ "1", "text" ],
				"reason": "reason",
				"date": "date"
			}
		}
	]
}

See the example definition on English Wikipedia.

故障排除

If you navigate to Special:Version and TemplateData is installed, but fields aren't showing up in the citation dialog, you may need to open the citation template for editing, make no changes, and save it again. This is due to a bug where TemplateData which is transcluded (i.e. present in Template:Cite_web/doc instead of directly on Template:Cite_web) is not loaded into the database until the parent template is edited; see 工單T52372.

Please note that the user experience will differ slightly when using your own templates other than the standard 4. For instance, a list of fields won't show up initially in the citation dialog, but you will be able to request a list of all possible fields by clicking a button.