VisualEditor/Gadgets

DON'T PANIC '''Guide to VisualEditor gadgets - a non formal guide for hacking the VisualEditor. '''


 * Motivation: VisualEditor is a new interface for editing articles in Wikimedia projects. This visual editor will never replace the classic wikitext editor, but it is simple to use and preferred by new editors. Gadgets can extend and customize the visual editor and introduce new functionalities: to let more advanced users to use more complicated options (such as timeline), to introduce work-flows that are project specific (such as deletion proposals), or to easily insert popular templates such as cite templates.
 * Note: VisualEditor is written in JavaScript, in fully object oriented mind - including the UI (dialogs, widgets, tools etc) and the model (which replace the simple Wikitext). If you want to really understand what's going there - read VisualEditor/API (which isn't yet fully written) - but if you just want to create cool gadgets that improve the user experience - read this guide. To access VE object: ve.instances[0]

Read the guide To understand how to hack the VE Go to code snippets For quick hacking

Getting around
First of all you need to access the code with one (or more) of the following options:
 * Download the code from git:
 * (for more information see: mw:Extension:VisualEditor)

You may use add ?debug=1 to the url to get non compressed JS - this is a bad idea for VE since loading may take several minutes
 * Open an article, and edit it with visual editor. Open Web Developer tools (F12 in most browsers), and get to Scripts tab. You should look on "load.php....ext.visualEditor...". since MediaWiki ResourceLoader give you the compressed JS you most use a tool to "Beautify" the code (such option exist in Chrome).
 * If you don't see the JS it may come from local cache - run in console localStorage.clear and reload the page

Debug diving
The Hitchhiker’s Guide to the VisualEditor gadgets has a few things to say on the subject: Good debugger is about the most massively useful thing an gadget writer can have. Since there is no good documentation yet for Visual Editor, and may never be, to understand how this black magic works you will have to dive into debugging. Don't worry - it's simple.

Assume we want to understand how transclusion of templates work inside VE:
 * Since we know (as users) that there is a dialog to insert templates, we should find this dialog in the code (search with ctrl+F). You should find a function called "ve.ui.MWTransclusionDialog.prototype.teardown" - place a breakpoint there
 * As user, open the dialog, select a template, fill some parameters, and then add the template to the page - you will hit the break point.
 * Inspecting the transclusion object we can see how it is looks like under the hood:


 * Now that we know how template code is represented - we can go on with the debugger, step by step and see how it is added to the document:

Now that we understand how templates are represented, let's take a look on an example of UI class - toolbar. There is a configuration object for the toolbar, for example the reference dialog have the following configuration:

Where * includes all the registered tools. (What are those tools? you can take a look/debug the function OO.ui.ToolGroup.prototype.populate to understand how it works - it loads all the registered commands, removed already used, remove the exclude and order using demote/promote).

Registering VE plugin
The above describes how to code a script for VE. Once your script is ready, you would like to publish it so other editors can use it. This can be done by registering your script in MediaWiki:Gadgets-definition, and then editors can turn your gadget on using Special:Preferences (in Gadgets tab).

Since VE is heavy module, you must not create a gadget that depence on ve internals. Instead you should create 2 gadgets:
 * A real gadget - that may be depenent on VE internals, but users shouldn't be able to turn it on (use hidden)
 * Create a "gadget loader" - a small gadget that tells VE to load your real gadget once VE is activated by the user

For example:

running code on VE activation
Use hook:

For proper VE plugin registration:

adding templates
The following code adds Template:cite web as an example for adding template to page:

Real examples for gadgets/scripts that interact with VE
Here are some real world gadgets/scripts for VE. You can use them as is or use them as example for building your own gadgets!
 * en:MediaWiki:Gadget-defaultsummaries.js - Add two new dropdown boxes below the edit summary box with some useful default summaries
 * he:MediaWiki:Gadget-VeExtendedBar.js,he:MediaWiki:Gadget-VeDirectionMarkTool.js - adds a button for inserting common template. (this is also an example of how to use addPlugin)