Page MenuHomePhabricator

Update documentation for VE gadgets to include information about NWE
Closed, ResolvedPublic8 Estimated Story Points

Description

Once the NWE API is stable, https://www.mediawiki.org/wiki/VisualEditor/Gadgets (and/or other documentation) should be updated to help gadget developers to work with it.
Use cases:

  • A user developped a gadget to add a button to the VE toolbar that inserts some template.
    • What is requiered to make this code work with NWE?
    • How can he decide which parts go before and which ones after the input cursor?
  • A user developped a gadget for the classic wikitext editor.
    • How can he tell apart the visual mode of VE and NWE to only run in NWE mode?
    • How can he get/set the complete wikitext? The position of the cursor? The current selection? (I.e. the stuff that the jquery.textSelection module handles for a plain textarea.)

Event Timeline

  1. Nothing :)
  2. We don't go into detail about selection manipulation on that page, but SurfaceFragment has some well documented methods, so it shouldn't be hard to add.
  3. ve.init.target.mode ('visual' or 'wikitext'), however we have a general principle that tools should be at least visible (if not available) in all modes to maintain UI consistency.
  4. See 2.
  1. Nothing :)

Nice! Though of course it seems a bit strange to have a visible delay to get the wikitext of your stuff, when you know that wikitext in advance anyway.

But ve.ui.MWWikitextCommandRegistry.js contains enough examples to answer most of the questions.

I'm not really sure if somebody who has the first contact with VE internals because he wants to port his gadget to NWE will be happy with https://doc.wikimedia.org/VisualEditor/master/#!/api/ve.dm.MWWikitextSurfaceFragment, so some examples would be nice, but for me this is probably enough, and T142523: Provide a second version of a beta modern wikitext editor integrated into the visual editor has "Successful proof of concept for a few gadgets" on the roadmap, which should help other developers.

Jdforrester-WMF moved this task from To Triage to TR1: Releases on the VisualEditor board.
Jdforrester-WMF set the point value for this task to 8.

I just created https://www.mediawiki.org/wiki/VisualEditor/Gadgets/Add_a_tool. I didn't yet link it anywhere, as I hope somebody can review it a bit first.

Since nobody complained I guess that example is ready to remove the "draft" tag and link it in the lead of https://www.mediawiki.org/wiki/VisualEditor/Gadgets.

I also started https://www.mediawiki.org/wiki/VisualEditor/Gadgets/Creating_a_custom_command. I do need help there from others: The command should operate on the complete text when nothing is selected, but I can't find a good way to get a SurfaceFragment covering the whole document.
Also the code to insert the wikitext doesn't look very elegant, but again I can't find a better working alternative.

Additionally it would be really nice to make this command work in visual mode, too, but that's beyond the scope of this task.

Uh, I more or less forgot about this.
I'd be really happy if someone could just have a look at https://www.mediawiki.org/wiki/VisualEditor/Gadgets/Creating_a_custom_command, whether I should just remove the "draft" tag. It should be read by someone else first, after all, I accidentally had unpaired tags in the code on https://www.mediawiki.org/wiki/VisualEditor/Gadgets/Add_a_tool for quite some time.

Well, okay, nobody wants to comment on it, so I just linked it.

From my perspective, this task is now fully resolved, if somebody else prefers some other form of documentation, he should open a new task for this write it himself.