VisualEditor/Design/Reference Dialog

This document describes the proposed design for a reference and citation insertion dialog for use within VisualEditor.

Goals
Improve the experience of adding references to an article using Visual Editor.


 * Decrease the amount of time spent navigating the reference wizard
 * Surface the common types of reference templates for easy selection
 * Use data such as ISBN or links to autofill parameters if capable

Existing user flow
Here is a guide on how to insert a reference. The existing flow involves at least 10 steps.

Problems
The initial steps are a barrier to new editors, especially finding a template to use.

“There is no obvious way of inserting a reference from the list.” Arson McFire (talk)

More feedback here.

Easy selection of reference template
There will be a per-wiki (locally defined) set of up to 6(?) templates that are displayed on the first screen for easy selection; below are shown an example of how the English Wikipedia might wish to configure it for their needs, with the following types used for the example: Book (auto fill on ISBN), Web, News, Journal (autofill on DOI? PMID? JSTOR?), Media (w:Template:Cite AV media ?)

A search box will be available for the user to find other reference templates. The search results will be filtered to only include templates that useful for citation and footnoting purposes, and the search parameters will match against any fields in the TemplateData. The search results will display a short name rather than the template name. (e.g. w:template:cite PMID will display 'Pubmed' or 'PMID' rather than 'cite PMID')

Design Iteration 1
'''Step 1: Click reference icon under “more” toolbar. Enter Reference wizard.'''

'''Step 2: Choose from a list of common templates. '''In this example a user selects the Book template.

The list of templates will show a few commonly used templates, or the user may search for more. The user may also enter a reference manually here.

'''Step 3: Enter reference information into the form. '''

The parameters will appear in the form in the same order they appear in the reference result, except in the case there is a parameter that can autofill the rest.

Step 3 b: Autofill parameters.

In this case, ISBN field appears first. The user enters the ISBN and clicks the search button. The ISBN is searched and the other fields are autofilled.

Step 4: Review and insert reference.

The user may view the reference result as it will appear in the article. The user may also edit the reference here if they wish.

Adding parameters:

The option to add more parameters from a template is visible after the user scrolls to the bottom of the form.

Design Iteration 2
'''Step 1: Click reference icon under “more” toolbar. Enter Reference wizard.'''

'''Step 2: Choose an option to get started. '''In this example a user selects the Book from the reference templates.

The list of templates will show a few commonly used templates (decided by the community), or the user may search for more. The user may also use an existing reference from the article. Or the user can choose to go to the original template dialog, what we will call "advanced dialog" or something similar.

'''Step 3: Enter reference information into the form. '''

The title of the dialog also serves as navigation, users may get back to the options page by clicking on Reference. The parameter titles are shown like a table of contents on the left, and the fields are on the right. A user may tab or scroll through each field on the right, or may click the titles on the left to get to the next field.

Step 3 b: Autofill parameters.

In this case, ISBN field appears first. The user enters the ISBN number, it is searched and the other fields are autofilled. There is a visual indication next to the titles on the left to show that the fields are being searched and filled.

Step 4: Preview.

The user may view the reference preview at the bottom and click "Add reference" to finish. If the user has used the ISBN autofill feature, they may undo the autofill by clicking "clear autofill" at the bottom. The user may also edit any field they wish to change individually.

Adding parameters:

The user may add more parameters to the template here.

Adding another author:

In the author section, the user can see the author first name and last name fields next to each other. The user may also add another author in this section.

Design Iteration 3
1 Place cursor where reference will be added

2 Hover over reference icon on toolbar

3 Select book

4a Enter reference dialog

4b Fill forms: enter ISBN

4c ISBN is searched and forms are filled. User clicks Add Reference

5 Return to Visual Editor. Reference is highlighted in text and pop up says “Reference added”.

Add Authors In the author section, the user can see the author first name and last name fields next to each other. The user may also add another author in this section.

Add parameters The user may add more parameters to the template here.

Changes in this version

 * Initial choices in toolbar simplified to "Book", "Web" and "More types"
 * Navigation on left removed to reduce clutter
 * Recommended fields only appear after required fields are completed
 * Preview removed from dialog, instead visible after reference is added
 * Visual design updated