維基百科:參考文獻工具列/2.0

暫時所有說明圖片均是英文版本，但此工具已完成本地化

參考文獻工具列2.0是僅能用於舊版Vector（2010）中的可擴展編輯工具列。

安裝

要使用此功能，到偏好設定（參數設置）中設定。

小工具
編輯按鈕擴展
選取「在編輯工具欄增加參考文獻「引用」功能，可以快捷地使用文獻引用模板。參考Wikipedia:RefToolbar 2.0（必須在「參數設置」->"編輯"中勾選「啟用增強編輯工具欄」）」
保存更改
完成

已隱藏部分未翻譯內容，歡迎參與翻譯。

Usage

Templates

On the left side of the Cite panel is a dropdown list of all available templates. Clicking one will open a dialog box with the fields for that template. Buttons on the bottom of the dialog are used to insert the ref into the article, preview the ref, reset the form, and close the dialog without changing the article.

Named refs

Clicking the "Named refs" button will open a dialog listing all of the named references in the article. Choosing one will show the wikitext of the reference with an option to preview how the reference looks after parsing. Clicking the "Insert" button will insert the named reference (<ref name=Foo />) into the last cursor position in the article.

Error checking

To use error checking, click the Error check symbol, then select the error checks to run. A panel listing any errors found will be inserted underneath the edit area. Additional error checks can be added, see below for details.

Configuration

Unlike the old version of the script, this version is highly customizable sitewide and on a per-user basis.

Note that while the script is designed to be easily configurable, the configuration options do need to be valid JavaScript code - brackets and parentheses must be matched and strings must be wrapped in quotation marks with quotation marks in the string escaped as necessary.

Configuration is done using a global CiteTB object. Configuration options are stored in CiteTB.Options and CiteTB.UserOptions

Individual users

No customization is required, the script will use the sitewide defaults "out of the box." All user configuation options override the sitewide options.

Sitewide configuration

All global configuration is done in the MediaWiki:RefToolbarLocal.js script file. The script will set a default for all options, but it is recommended that site defaults include a value for all options. For all option sample code shown below, change "UserOptions" to "Options" for site configuration. The initial $j('head').one('reftoolbarbase', function() { line and the final }); are not necessary for changes in RefToolbarLocal.js and should be omitted.

Automatic date insertion

Changing the date format used for automatically added dates (such as accessdate) is done using a simple string replacement system. "Special" words will be replaced with their corresponding date, all other characters will be left as-is.

The current date options available are:

<date> — The day of the month (1-31)
<zdate> — The day of the month (01-31), zero-padded to 2 digits
<month> — The month number (1–12)
<zmonth> — The month number (01–12), zero-padded to 2 digits
<monthname> — The month name
<year> — The 4-digit year

Other options may be available on request. Currently only one format will be used. If there is demand for it, the automatic date system may be extended to allow multiple options in a dropdown selection box. The date is always in UTC.

The fields that have an automatic date option are stored in the "autodate fields" option.

To customize automatic date insertion, options can be set like so:

$j('head').one('reftoolbarbase', function() {
CiteTB.UserOptions['date format'] = "<date> <monthname> <year>";
CiteTB.UserOptions['autodate fields'] = ['accessdate'];
});

Modal dialogs

To set whether the dialogs should be modal, use the "modal" option. If set to true, opening one of the dialogs will block access to the rest of the edit page until the dialog is closed.

$j('head').one('reftoolbarbase', function() {
CiteTB.UserOptions['modal'] = true;
});

Automatic parsing

The script can be set to automatically provide a parsed preview when previewing a citation template through the "autoparse" option. Its not recommended to set this to true as a global setting as it may slow the script down for people with slow connections.

$j('head').one('reftoolbarbase', function() {
CiteTB.UserOptions['autoparse'] = false;
});

Template expansion

To be able to retrieve more references on a page, the script can also expand templates and parser functions on the page (except templates inside of ref tags) so that references from templates or references that use the {{#tag:ref}} syntax will be available when inserting named refs or for error checking functions. This can also slow the script down for people with slow connections.

$j('head').one('reftoolbarbase', function() {
CiteTB.UserOptions['expandtemplates'] = false;
});

Month names

The month names used for automatic date insertion are also customizable, for translation to other languages, or to use abbreviations.

$j('head').one('reftoolbarbase', function() {
CiteTB.UserOptions['months'] = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
});

Citation templates

Citation templates can be added using an object syntax. To add a new template, simply create a new citeTemplate object. Each template has 4 required parameters.

The template name (e.g. "cite web")
A short name for the template, used for the template list in the script (this name should be a unique name for each template object, even if 2 template objects are based on the same template)
A list of "basic" template options, using the syntax described below
A list of the the remaining options, any option the template supports that isn't in the "basic" list.

For sitewide settings, templates should be included in the RefToolbarLocal page. Users can also add their own templates with this system by adding them to their user script page. If the script is installed on the user script page (as opposed to using a gadget), the templates must be below where the script is imported.

Object syntax for fields

Each field is described as an object in a list, using JavaScript Object Notation. The available options are:

field – The actual field name as used in the template. This is the only required attribute.
label – The text that will be given as the label on the form. If not provided, the 'field' attribute will be used with the first letter capitalized
tooltip – If given, a ^? will be put after the label that the user can mouse over to see a more detailed description of the field.

The object system allows other options to be added later as the script is modified to support them. Potential future features include automatic fill-in from ISBN/PMID/etc, type checking (require a parameter to be a string, number, date, etc.), and required fields.

Sample code

$j('head').one('reftoolbarbase', function() {
new citeTemplate('cite example', 'Example',
[ // Basic fields
{"field": "last", "label":"Last name"},
{"field": "first", "label":"First name"}, 
{"field": "title"},
{"field": "url", "label":"URL"},
{"field": "work", "tooltip": "If this is part of a larger work"},
{"field": "publisher"},
{"field": "accessdate"}
],
[ // Expanded fields
{"field": "author"},
{"field": "authorlink", "label":"Author's article", "tooltip":"If the author has an article, the name of the article"},
{"field": "coauthors"},
{"field": "page"},
{"field": "pages"},
{"field": "language"},
{"field": "format"},
{"field": "date"},
]);
});

Error checking functions

Error checking functions can be added in a way similar to citation templates. The citeErrorCheck object requires one parameter, an object. This object should contain certain the information as described below. Currently all attributes are required. In the future, optional attributes may be added to support other features.

testname – A short name for the test, should be unique and should not contain spaces
desc – A description for the test
func – The function that will be called to execute the test (see below for details)
type – The type of test, see below for the options

There are currently 3 types of error checks. The differences between them are described below:

refcheck: The function given is passed each ref individually, it should return a single error object or not return.
reflist: The function is passed the entire list of references, it should return an array of error objects.
search: The function is passed the wikitext of the article, it should return an array of error objects.

An error object is a JavaScript object that should contain 2 attributes. The 'msg' attribute should be an error message describing the problem and the 'err' attribute should be a portion of the wikitext showing the error, such as the content of the reference with the problem.

Some example code for a simple function that checks whether each reference uses a template could be:

$j('head').one('reftoolbarbase', function() {
new citeErrorCheck({'type':'refcheck', 'testname':'notemplate', 'desc': "Check for references not using a template",
'func': function(ref) {
  if (!ref.shorttag && ref.content.search('{{') == -1) {
    return {'msg': "Does not use a <a href='http://en.wikipedia.org/wiki/Wikipedia:Citation_templates'>citation template</a>",
      'err': ref.content
    };
  }
}}
);
});

Porting to another wiki

This script is designed to be easily portable to other wikis that use a similar (template-based) reference system. You should not need to copy the script itself. You do need to copy MediaWiki:RefToolbarLocal.js (you can also use the smaller sample configuration) to your wiki (this requires sysop access on the wiki the script is being ported to). Then you can customize the options, templates, error functions, and translate the messages as necessary. Be sure the CiteTB.init(); line is the last line of the RefToolbarLocal script. Note that the script has not yet been tested using RTL languages.

Information for developers

This section covers information relevant for developers that might not be covered above.

Descriptions of the citeTemplate and citeErrorCheck objects are described in detail in above sections.

The CiteTB object:

The CiteTB object is used to reduce the number of variables and functions put into the global scope. It contains all the functions and variables used by the script, except for the citeTemplate/citeErrorFunction object definitions. Most of this object is not loaded except on edit pages.

Reference objects:

Reference objects are created for each reference currently on the page, and whenever a reference is added by the script. Reference objects have several attributes:

refname – The 'name' attribute of the ref tag
refgroup – The 'group' attribute of the ref tag
content – The content inside of the ref tags
shorttag – true or false, whether the ref is a short tag with no content or a full reference tag

The script uses the jQuery library, which is well documented at http://docs.jquery.com. It also uses the WikiEditor code used by the UsabilityInitiative; this is partially documented at usability:Toolbar customization, but is mostly undocumented.

(Possible) future features

Automatic fixing of certain reference errors
Editing of existing references in-place