Images or galleries have a caption attribute where Wikitext can be used that will be rendered on the page. You can define new references in there or re-use references that where defined outside of the caption. VisualEditor should support both directions.
One part of this seems to be working already:
- I am an editor using visual editor.
- I open the image/gallery dialog to add a new or edit an exiting image/gallery.
- I add a reference to the caption.
- I close the dialog and want to re-use that reference in the article.
- The reference shows up in the re-use dialog and I can add it to the article
The other way does not though:
- I am an editor using visual editor.
- I directly add references to the article or there are already references that were directly added there.
- I open the image/gallery dialog to add a new or edit an existing image/gallery.
- I'm trying to re-use a reference that's defined in the article in the caption.
- The reference does not show up in the re-use dialog if it's defined on the article.
There seems to be a good way to fix the second part though, by pointing the re-use dialog to the root document of the article when used from of the image dialog.
See also:
- T62919: VisualEditor: "Use an Existing Reference" option remains disabled for a reference inside Media Settings while there is a reference available to re-use in the page
T87134: References generated by a template in media captions do not appear in Re-Use Reference list(unrelated)
Acceptance criteria
As a visual editor,
I want to reuse existing references in the image caption dialog so that it's more like editing text anywhere else in the document.
Preconditions: Article fixtures are composed of these optional sections which will be mentioned in the scenario:
- Existing references - an unnamed ref, a named ref and a references list are included in the document.
- Existing caption references - document includes an image with a caption having existing named and unnamed references.
Scenario 1: An existing reference is available for reuse in the caption
Action: Add a new image and caption.
Result: The citation "re-use" menu item is enabled.
Scenario 2: List existing references (and caption refs, and newly staged caption refs) for re-use
Action: Click the re-use menu item in the image caption dialog.
Result: A menu lists all existing references from the document and from the caption, in the order they would appear if the document were saved.
Scenario 3: Reused reference has the correct number
Action: Re-use an existing reference with number > 1 in the image caption dialog.
Result: Inserted ref has the same number. Ref content appears in a popped-up preview. The preview includes a warning about reused references.
Scenario 4: New reuses are rendered in the document
Action: Add an image caption which reuses an existing citation. Exit the dialog successfully and insert into the document.
Result: The reused reference appears in the reference list with two backlinks, and both the existing and new references include a reuse warning.
Scenario 5: New caption reference is numbered correctly
Action: Add a new caption reference after an existing document reference.
Result: The new footnote marker has a number > 1, the same in the caption preview and in the document after saving the dialog.
Scenario 6: Newly-deleted reference is not reusable
Action: Delete an existing caption reference and click on the re-use menu item.
Result: The deleted reference doesn't appear in the ref reuse dialog.
Draft implementation plan
- Media dialog uses "staging" mode to make provisional changes to the full document. (patch)
- Reference dialog sees refs from the full document. (patch)
- Trigger to apply image caption changes before any reference dialogs are opened. Tricky because toggling the "reuse" menu could change after every character typed. (patch)