Difference between revisions of "Visual editor"

From Freephile Wiki
Jump to navigation Jump to search
VisualWikitext
(Updated for 2023)
 
(7 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
{{Feature
 
{{Feature
−
|image=QB cube.svg
+
|image=Visual Editor (linking).png
−
|imgdesc=QualityBox
+
|imgdesc=Direct editing
−
|feature title=WYSIWYG Editing
+
|title=
 
}}
 
}}
−
{{#set:feature title = WYSIWYG Editing}}
 
 
{{#set:feature description = A reliable rich-text editor for MediaWiki.  Allows you to just "edit the page you see" while being aware of all the syntactically rich features of templates, extensions etc.}}
 
{{#set:feature description = A reliable rich-text editor for MediaWiki.  Allows you to just "edit the page you see" while being aware of all the syntactically rich features of templates, extensions etc.}}
−
{{#set:feature notes = The Visual Editor is available on WikiPedia.}}
+
{{#set:feature notes = The Visual Editor is available Here and on Wikipedia.}}
−
{{#set:feature tests = [[Special/MyLanguage:Login|Special/MyLanguage:Login]] to the wiki, and make an edit in your [[Special/MyLanguage:Sandbox|personal sandbox]]. }}
+
{{#set:feature tests = [[Special:UserLogin|Login]] to the wiki, and make an edit in your [[Special:MyPage/Sandbox|personal sandbox]]. }}
 
{{#set:feature examples = }}
 
{{#set:feature examples = }}
  
Line 19: Line 18:
 
== Back story ==
 
== Back story ==
 
Wiki markup is a sort of shorthand for more complicated HTML markup designed to create nicely formatted web documents.  Although in the beginning wiki markup simplified the process of creating nicely formatted content, that shorthand can get increasingly complex in order to produce complicated layout and content.  The extension of the markup system over time to include a template subsystem and macros inevitably leads to a tension between ease of use, and power.  This tension was one of the primary factors that the Wikimedia Foundation cited as an impediment to new content collaborators for the Wikipedia. <ref>https://strategy.wikimedia.org/wiki/March_2011_Update</ref><ref>http://strategy.wikimedia.org/wiki/Editor_Trends_Study</ref> <ref>See this October 2013 article in the MIT Technology Review http://www.technologyreview.com/featuredstory/520446/the-decline-of-wikipedia</ref>.  A visual editor was deemed nearly impossible after many early attempts failed, but with the advent of Node.js technology, it became an idea that was plausible again.
 
Wiki markup is a sort of shorthand for more complicated HTML markup designed to create nicely formatted web documents.  Although in the beginning wiki markup simplified the process of creating nicely formatted content, that shorthand can get increasingly complex in order to produce complicated layout and content.  The extension of the markup system over time to include a template subsystem and macros inevitably leads to a tension between ease of use, and power.  This tension was one of the primary factors that the Wikimedia Foundation cited as an impediment to new content collaborators for the Wikipedia. <ref>https://strategy.wikimedia.org/wiki/March_2011_Update</ref><ref>http://strategy.wikimedia.org/wiki/Editor_Trends_Study</ref> <ref>See this October 2013 article in the MIT Technology Review http://www.technologyreview.com/featuredstory/520446/the-decline-of-wikipedia</ref>.  A visual editor was deemed nearly impossible after many early attempts failed, but with the advent of Node.js technology, it became an idea that was plausible again.
 +
 +
Fast-forward to 2016 when VisualEditor was fully working as a Visual WYSIWYG interface for editing MediaWiki content, using a Node.js backend called 'Parsoid' which is a bidirectional runtime wiki parser. This caused a big software architectural problem: there were two parsers to maintain: the 'normal' (now 'legacy') core parser in PHP, and the Visual Editor parser (Parsoid) in JavaScript. So, by the end of 2019, Parsoid was ported to PHP, and distributed with MediaWiki 1.35 as part of the [mw:Parsoid/Parser_Unification|Parser Unification initiative]].
  
 
== Intro ==
 
== Intro ==
Line 24: Line 25:
 
* [https://www.youtube.com/watch?v=M_Ioi1aLAL8 VIDEO] (47 min.) with James Forrester - Product Manager and Roan Kattouw - Sr. Software Engineer presenting Jan 13, 2014 at Linux.conf.au on the contentEditable aspects of the system.
 
* [https://www.youtube.com/watch?v=M_Ioi1aLAL8 VIDEO] (47 min.) with James Forrester - Product Manager and Roan Kattouw - Sr. Software Engineer presenting Jan 13, 2014 at Linux.conf.au on the contentEditable aspects of the system.
  
−
The [http://www.mediawiki.org/wiki/VisualEditor Visual Editor] for MediaWiki relies on the '''[[mw:Extension:Parsoid|Parsoid]]''' extension <ref>[https://git.wikimedia.org/tree/mediawiki%2Fextensions%2FParsoid Parsoid extension]</ref> AND the Parsoid service.  The Parsoid service is a node.js server that interacts with the mediawiki API.
+
The [http://www.mediawiki.org/wiki/VisualEditor Visual Editor] for MediaWiki relies on [[mw:Parsoid|Parsoid]]
  
 
<blockquote>"Parsoid implements a bidirectional wikitext parser and interpreter. It converts and interprets wikitext into an annotated HTML DOM, which can then be edited with HTML editor tools such as the Visual Editor. It also provides the conversion of a (possibly modified) HTML DOM back to wikitext."</blockquote>
 
<blockquote>"Parsoid implements a bidirectional wikitext parser and interpreter. It converts and interprets wikitext into an annotated HTML DOM, which can then be edited with HTML editor tools such as the Visual Editor. It also provides the conversion of a (possibly modified) HTML DOM back to wikitext."</blockquote>
  
 
[http://xml.coverpages.org/ Robin Cover] would be proud.  It round-trips wiki to HTML + RDFa and back.
 
[http://xml.coverpages.org/ Robin Cover] would be proud.  It round-trips wiki to HTML + RDFa and back.
−
 
−
 
−
 
−
== Vendors ==
 
−
MyWikis is one of the few hosting providers that actually offers Visual Editor.  Additionally, you can get a hosted parsoid service for $1/month if you want to run your own wiki with Visual Editor, but don't want to or can't setup the parsoid service.  https://www.mywikis.com/hostedparsoid
 
  
 
== Installation ==
 
== Installation ==
−
You'll need at least [http://www.mediawiki.org/wiki/Release_notes/1.23 MediaWiki v1.23].  This site usually runs the most recent version available. We're using {{CURRENTVERSION}} at the moment. See what version that they're running on mediawiki.org and check yours too for free at https://freephile.org/wikireport
+
VisualEditor is included with MediaWiki. See https://www.mediawiki.org/wiki/Extension:VisualEditor
  
−
See the new [[mw:RESTBase|RESTBase]] caching proxy system usable by VE
 
−
 
−
=== WebFaction ===
 
−
 
−
To install the Visual Editor extension in a Webfaction account, you need to first have node installed and working.  You can do this by using the [http://docs.webfaction.com/software/custom.html installer in your webfaction panel] and associating a path with the app for a domain.  I chose to install 'node' (which is now it's own one-click install).  Once you do that you can [https://freephile.org/node visit the path] you configured for node and you should see the "hello world" app that the installer puts in place.  You'll need to stop that app, plus remove the cron job that respawns it.  Then, in order to reserve and associate a port for the service, you install another 'app'.  You do not need to open this port in the firewall unless you plan to share it with other instances, since HTTP talks to the node server on the backend.  (I had to export the PORT, but this is no longer necessary if you configure it in localsettings.js <ref><code>parsoidConfig.serverPort = 8080</code> if you are running MediaWiki-Vagrant</ref>.)  Depending on the resource constraints of your hosting package, you may need to limit the number of workers spawned by the Parsoid service.  It calculates a number based on the number of processors.  For a shared hosting account, this is guaranteed to exceed your RAM or CPU limits, so specify the <code>--num-workers</code> option unless you're running on a dedicated host or VM.
 
−
 
−
Follow the installation instructions, and remember to edit both LocalSettings.php and localsettings.js  When you setup the "interwiki" link to point to your API endpoint, you can choose pretty much whatever name you want to give it.  The example is 'localhost'.
 
−
 
−
 
−
You'll want to set/update your $NODE_PATH and $PATH environment variables to locate the installed node modules, and to find the node and npm binaries
 
−
<source lang="bash">
 
−
export NODE_PATH="$HOME/webapps/node/lib/node_modules:$NODE_PATH"
 
−
echo 'export NODE_PATH="$HOME/webapps/node/lib/node_modules:$NODE_PATH"' >> $HOME/.bashrc
 
−
which npm
 
−
export PATH="$HOME/webapps/node/bin:$PATH"
 
−
echo 'export PATH="/$HOME/webapps/node/bin:$PATH"' >> $HOME/.bashrc
 
−
</source>
 
−
 
−
Once node (and npm) is available, you of course need to get the parsoid and visual_editor extensions.  A quick <code>npm install</code> in the parsoid directory sets up all the node machinery.
 
−
 
−
To have it run continuously, you might want to use the 'forever' module:
 
−
<source lang="bash">
 
−
npm install -g forever
 
−
</source>
 
−
But that is just a node way of monitoring processes.  You might want to simply use tools built for the purpose like [[tmux]] or [[screen]] plus [[monit]].  If using <code>forever</code>, then you just prefix your call to node with 'forever'
 
−
 
−
At this point you're ready to run the node server.  Note: while installing this, I found a bug which prevented the server from listening on the configured port.  It was awesomely cool that I mentioned the bug in IRC #mediawiki-parsoid and it was fixed before I was done testing my installation!!
 
−
 
−
<source lang="bash">
 
−
cd ~/webapps/wiki/extensions/Parsoid/
 
−
node api/server.js --num-workers=2 &
 
−
</source>
 
−
 
−
The console should print out a list of worker pids, and the port number that the server is listening on.  In your web browser, if you visit that path and port (setup in your WebFaction node mapping), you should see the Parsoid web service API message.
 
−
 
−
There is no stop script for a shared host, but you should be able to do something like
 
−
<source lang="bash">
 
−
for pid in $(/sbin/pidof `which node`); do kill -9 $pid; done
 
−
</source>
 
−
 
−
That's because node is installed under your user account, and the $PATH is set as above to find that instance of node.  To be sure that you're not going to kill everyone's node instances, you could look at all the nodes with ps -ef
 
−
==== Info ====
 
−
* https://docs.webfaction.com/software/nodejs.html
 
−
 
−
=== Digital Ocean ===
 
−
# [https://www.mediawiki.org/wiki/Parsoid/Setup Setup the Parsoid service]
 
−
# Set the <code>/etc/mediawiki/parsoid/settings.js</code> file to [[API]] endpoint (https://freephile.org/w/api.php)
 
−
# sudo service parsoid restart
 
−
# sudo tail -f /var/log/parsoid/parsoid.log
 
−
 
−
* Note that a Visual editor setup (Parsoid service) includes configurations outside of your wiki installation (in /etc and maybe /usr/lib) so you'll want to preserve those files when doing host migrations.
 
−
* See [http://www.mediawiki.org/wiki/Thread:Extension_talk:VisualEditor/Digital_Ocean_Droplet:_Ubuntu_14.04_x64_with_MediaWiki_1.24.0 here]
 
  
 
== Extensions ==
 
== Extensions ==
Line 96: Line 40:
  
 
=== Extensions that hook into VE ===
 
=== Extensions that hook into VE ===
−
Extension authors should [https://codesearch.wmflabs.org/extensions/?q=VisualEditorPluginModules&i=nope&files=&repos= register <code>VisualEditorPluginModules</code>]
+
* https://codesearch-beta.wmcloud.org/things/?q=ve.ui.commandRegistry.register&files=&excludeFiles=&repos=
 +
* https://codesearch-beta.wmcloud.org/extensions/?q=VisualEditorPluginModules&i=nope&files=&repos=
 +
 
 +
Extension authors should register <code>VisualEditorPluginModules</code>
 
# https://www.mediawiki.org/wiki/Extension:Proofread_Page
 
# https://www.mediawiki.org/wiki/Extension:Proofread_Page
 
# https://www.mediawiki.org/wiki/Extension:CodeMirror (syntax highlighting)
 
# https://www.mediawiki.org/wiki/Extension:CodeMirror (syntax highlighting)
Line 110: Line 57:
  
  
−
 
+
== Customizing Visual Editor with custom menus, tools, commands ==
 +
* https://www.mediawiki.org/wiki/VisualEditor/Gadgets
 +
* https://www.mediawiki.org/wiki/VisualEditor/Gadgets/Creating_a_custom_command
 +
* https://www.mediawiki.org/wiki/VisualEditor/Gadgets/Add_a_tool
  
  
Line 121: Line 71:
 
* https://doc.wikimedia.org/VisualEditor/master/ powered by JSDuck
 
* https://doc.wikimedia.org/VisualEditor/master/ powered by JSDuck
 
* http://blog.gmane.org/gmane.science.linguistics.wikipedia.wikitext wikitext-l
 
* http://blog.gmane.org/gmane.science.linguistics.wikipedia.wikitext wikitext-l
−
 
−
I [https://gerrit.wikimedia.org/r/#/c/132479/1/api/ParsoidService.js noticed a bug] and it was fixed about 5 minutes after I mentioned it!  (Thanks C. Scott Ananian)
 
  
 
{{References}}
 
{{References}}

Latest revision as of 22:35, 19 April 2023

Visual editor Dialog-information.svg
Direct editing
Image shows: Direct editing
Summary
Description: A reliable rich-text editor for MediaWiki. Allows you to just "edit the page you see" while being aware of all the syntactically rich features of templates, extensions etc.
More
Notes: The Visual Editor is available Here and on Wikipedia.
Test: Login to the wiki, and make an edit in your personal sandbox.




Visual Editor

Links[edit | edit source]

Back story[edit | edit source]

Wiki markup is a sort of shorthand for more complicated HTML markup designed to create nicely formatted web documents. Although in the beginning wiki markup simplified the process of creating nicely formatted content, that shorthand can get increasingly complex in order to produce complicated layout and content. The extension of the markup system over time to include a template subsystem and macros inevitably leads to a tension between ease of use, and power. This tension was one of the primary factors that the Wikimedia Foundation cited as an impediment to new content collaborators for the Wikipedia. [1][2][3]. A visual editor was deemed nearly impossible after many early attempts failed, but with the advent of Node.js technology, it became an idea that was plausible again.

Fast-forward to 2016 when VisualEditor was fully working as a Visual WYSIWYG interface for editing MediaWiki content, using a Node.js backend called 'Parsoid' which is a bidirectional runtime wiki parser. This caused a big software architectural problem: there were two parsers to maintain: the 'normal' (now 'legacy') core parser in PHP, and the Visual Editor parser (Parsoid) in JavaScript. So, by the end of 2019, Parsoid was ported to PHP, and distributed with MediaWiki 1.35 as part of the [mw:Parsoid/Parser_Unification|Parser Unification initiative]].

Intro[edit | edit source]

  • VIDEO Wikimania 2013
  • VIDEO (47 min.) with James Forrester - Product Manager and Roan Kattouw - Sr. Software Engineer presenting Jan 13, 2014 at Linux.conf.au on the contentEditable aspects of the system.

The Visual Editor for MediaWiki relies on Parsoid

"Parsoid implements a bidirectional wikitext parser and interpreter. It converts and interprets wikitext into an annotated HTML DOM, which can then be edited with HTML editor tools such as the Visual Editor. It also provides the conversion of a (possibly modified) HTML DOM back to wikitext."

Robin Cover would be proud. It round-trips wiki to HTML + RDFa and back.

Installation[edit | edit source]

VisualEditor is included with MediaWiki. See https://www.mediawiki.org/wiki/Extension:VisualEditor


Extensions[edit | edit source]

  1. mw:Extension:VisualEditor
  2. mw:Extension:Parsoid

Extensions that hook into VE[edit | edit source]

Extension authors should register VisualEditorPluginModules

  1. https://www.mediawiki.org/wiki/Extension:Proofread_Page
  2. https://www.mediawiki.org/wiki/Extension:CodeMirror (syntax highlighting)
  3. https://www.mediawiki.org/wiki/Extension:Disambiguator
  4. https://www.mediawiki.org/wiki/Extension:Graph
  5. https://www.mediawiki.org/wiki/Extension:Kartographer (Open Street Maps)
  6. https://www.mediawiki.org/wiki/Extension:LanguageTool
  7. https://www.mediawiki.org/wiki/Extension:Math
  8. https://www.mediawiki.org/wiki/Extension:Score (LillyPond)
  9. https://www.mediawiki.org/wiki/Extension:SyntaxHighlight
  10. https://www.mediawiki.org/wiki/Extension:TemplateData
  11. https://www.mediawiki.org/wiki/Extension:WikiHiero


Customizing Visual Editor with custom menus, tools, commands[edit | edit source]


API / Developer Docs / DevOps[edit | edit source]

References[edit source]

  1. ↑ https://strategy.wikimedia.org/wiki/March_2011_Update
  2. ↑ http://strategy.wikimedia.org/wiki/Editor_Trends_Study
  3. ↑ See this October 2013 article in the MIT Technology Review http://www.technologyreview.com/featuredstory/520446/the-decline-of-wikipedia

HyperText Markup Language = structured text that uses logical links (hyperlinks) between nodes containing text.

PHP is the HyperText Preprocessor = the most popular programming language for the web

Visual Editor

Application Programming Interface

Retrieved from "https://wiki.freephile.org/wiki/index.php?title=Visual_editor&oldid=10149"