„Wikipedia:Technik/Text/Edit/CodeEditor“ – Versionsunterschied

Vorlage:Überschriftensimulation 1 Die MediaWiki-Erweiterung CodeEditor (basierend auf Ace) dient dazu, bei der Bearbeitung Seiten besser darzustellen, die vollständig in einer formalen Sprache notiert sind („Content Model“). Insbesondere geht es um Syntaxhervorhebung, auch um die Anzeige von Zeilennummern. Daraus folgt gleichzeitig die Meldung von (elementaren) Syntaxfehlern.

Zurzeit ist Quellcode in JavaScript, CSS und Lua von Interesse.

Geeignete Browser

Der CodeEditor wurde nur für einige Versionen der folgenden Browser erprobt:

• Firefox
• Google Chromium

Ansonsten funktioniert er nicht oder zerstört den Seiteninhalt. Die Fehlfunktion ist den Entwicklern durchaus über Jahre bekannt – modules/ext.codeEditor.js – ohne dass daraus irgendeine bekannt gewordene Konsequenz gezogen wurde.

• Opera 11.10 / Linux: copy fails, paste sometimes crashes
• IE 8.0.6001.18702 / Win XP: some newlines mysteriously removed, corrupting data; insertion point keeps resetting back to the top of the page after a click (arrow keys ok)
• Safari / iPad 4.3 (8F190): renders ok, but can’t set focus or scroll vertically. No focus means no typing. :(

Aktivierung

Wichtig:

• Konkurrierende Editoren müssen deaktiviert sein, namentlich wikEd.
• Die „neue“ oder „erweiterte“ Werkzeugleiste muss aktiviert sein (Hilfe:Symbolleisten), weil darauf die Benutzerführung aufbaut.

Automatisch

Seit 29. August 2013 wird der CodeEditor automatisch beim Bearbeiten jeder Seite zugeschaltet, deren Content Model nicht wikitext ist, sondern die Variable wgPageContentModel einen der folgenden Werte hat:

wgPageContentModel	Automatische Zuweisung nach Regeln
css	Benutzer-Namensraum oder MediaWiki-Namensraum Letzte drei bzw. vier Buchstaben des Seitennamens sind .css oder .js (Kleinschreibung empfohlen)
javascript
Scribunto	Scribunto steht zurzeit nur für Lua (könnten aber auch weitere Sprachen sein). Namensraum Modul: Seitenname erfüllt nicht das für die Dokumentationsseite vorgegebene Schema (???) Benutzer-Namensraum und Seitenname enthält /Spielwiese/Modul:

Die Aktivierung berücksichtigt nicht, ob der momentane Browser überhaupt für den CodeEditor geeignet ist (obwohl dies mit Leichtigkeit festzustellen wäre).

Eine einfache Konfiguration, um die automatische Aktivierung des CodeEditor zu unterbinden, gibt es nicht. Zu einer Lösung siehe unten.

Individuell

Die Programmierung wird in die benutzerdefinierten JavaScript-Seiten eingefügt; meist common.js (siehe Skin/JS).

• CSS und JavaScript
  • Die automatische Zuweisung berücksichtigt nur den Benutzer-Namensraum.
  • Es gibt auch Quellcode-Seiten im Wikipedia-Namensraum.
• Lua
  • Benutzernamensraum, also Nummer 2 (wgNamespaceNumber).
  • Seitenname enthält /Spielwiese/Modul: (wgTitle).
• Zu den Variablen siehe hier.

Ist die Situation festgestellt worden, dass eine Quellcode-Seite bearbeitet wird, ist das entsprechende Schlüsselwort zuzuweisen; hier lua als Beispiel. Danach werden die erforderlichen Module eingebunden (ResourceLoader).

mw.config.set("wgCodeEditorCurrentLanguage", "lua");
mw.loader.load( [ "ext.codeEditor",
                  "ext.codeEditor.ace",
                  "jquery.ui.resizable",
                  "jquery.wikiEditor" ] );

Verfügbare Sprachen

Normales Bearbeitungsfeld (Screenshot)

Standardmäßig werden zurzeit Syntaxdefinitionen der Programmier- und anderer Sprachen entsprechend der folgenden Schlüsselwörter zugeladen:

• javascript
• json
• css
• lua

Es lassen sich weitere Typen aktivieren, für die in einer Wikipedia bislang keine regulären Seiten bekannt sind:

• c_cpp
• clojure
• csharp
• coffee
• groovy
• html
• java
• ocaml
• perl
• php
• python
• ruby
• scala

Dazu ist auch die Ressource ext.codeEditor.ace.modes zu laden.

Weitere Sprachen lassen sich aktivieren; Beispiel:

• Um für XML den Typ xml zu bearbeiten, muss zusätzlich das folgende spezifische Skript geladen werden:

mw.loader.load( "https://git.wikimedia.org/raw/" +
                "mediawiki%2Fextensions%2FCodeEditor" +
                "/HEAD/" +
                "modules%2Face%2Fmode-xml.js" );

Eine weitere Anwendungsmöglichkeit wäre Wikitext; hierzu gibt es Experimente (AceWikiEditor), aber noch keine tragfähige Abbildung der vieldeutigen Wikisyntax.

JavaScript

Neben den Zeilennummern stehen bei JavaScript kleine Pfeile mit Spitze nach unten, wenn ein Einklappen eines Zeilenbereichs möglich ist. Das wären:

• durch geschweifte Klammern begrenzte Blöcke, auch ganze Funktionsdefinitionen;
• /* Kommentare */

Es erfolgt auch eine Syntaxinterpretation mit Fehlermeldung in der Statuszeile; die beanstandeten Zeilennummern werden bei fatalen Fehlern rot mit weißem Diagonalkreuz markiert, mit einem i bei nicht fatalen aber nicht empfehlenswerten Praktiken.

Das erfolgt bereits während der Eingabe auf jeden Tastendruck. Die Fehleranzahl steht in der Statuszeile.

Weiterhin wird beim Öffnen der Seite, Seitenvorschau oder Diffpage automatisch eine Analyse mit JSHint vorgenommen, in der Statuszeile wird neben einem gelben Dreieck die Gesamtzahl beanstandeter Stellen aufgeführt; an jeder betroffenen Zeilennummer steht ebenfalls ein gelbes Dreieck.

Bedienung

Bearbeitungsfeld des CodeEditor (Screenshot)

• Es wird die „neue“ Werkzeugleiste benutzt (Hilfe:Symbolleisten).
• Mit der vorangestellten Schaltfläche lässt sich die Hervorhebung ein- und ausschalten.
• Veränderungen an relevanten Syntaxelementen (etwa Kommentar) verändern sofort die umgebende Syntaxhervorhebung.
• Markierung (Doppelklick) einer öffnenden oder schließenden Klammer markiert den umschlossenen Bereich.
• Cursorposition hinter öffnender oder schließender Klammer hebt die zugehörige Klammer hervor.
• Einfg schaltet den Modus zwischen „Einfügen“ (Vorgabe) und „Überschreiben“; die Gestalt des Cursors ändert sich von | auf _.
• Drag&Drop möglich (erst nach einer Verzögerung bei gedrückter linker Maustaste; Veränderung des Cursors erfolgt mit unüblichem Icon)
• Ausblenden eines mehrzeiligen auskommentierten Bereichs /* ... */ und Code-Blocks { ... } ist möglich: Im Zeilennummern-Bereich werden winzige Buttons mit Pfeil nach unten sichtbar, wenn dort der Cursor steht; diese blenden den Block ab dieser Zeile aus. Ein Klick auf den nach rechts gedrehten Pfeil im Button oder auf den Doppelpfeil für den ausgeblendeten Bereich macht dies wieder sichtbar.

Tastenkombinationen

github.com

(wird hier eingepflegt, sobald in Wiki-Kontext erprobt und dauerhafter Verbleib als Standard entschieden)

Zeilennummern

Die Zeilennummern sind hilfreich im Zusammenhang mit der Diffpage; die Diffpages und die gesamte Wikitext-Versionsverwaltung entstammen ursprünglich zeilenorientierten Quelltexten von Programmen.

Statuszeile

Am unteren Rand des Bearbeitungsfeldes werden Fehlermeldungen aller Sprachen (etwa nicht ausgeglichene Klammeranzahl) sowie weitergehende Analysen für JavaScript angezeigt.

Die Symbole (jeweils mit Häufigkeit des Auftretens) sind

• rot mit weißem Diagonalkreuz bei fatalen Syntaxfehlern,
• gelbes Dreieck bei Warnungen vor verdächtigen Stellen mit mutmaßlichen Fehlern
• i bei nicht fatalen aber nicht empfehlenswerten Praktiken.

Schreibschutz

Die Aktivierung ist auch auf schreibgeschützten Seiten möglich. Das ist begrenzt sinnvoll; Syntaxhighlight erfolgt in der Regel bereits bei der Seitendarstellung, und Kopieren ist dort auch möglich. Mehrwert ist allerdings die Nummerierung der Zeilen.

Probleme

• Die Warnung vor Datenverlust beim Verlassen der Seite / Schließen des Fensters ohne Speicherung erfolgt nicht.

Verbesserungspotenzial

• Werkzeugleiste:
  • Suchen (und Ersetzen) steht nicht zur Verfügung.
  • Ansicht temporär begrenzen (filtern) auf Zeilen, die bestimmte Kriterien erfüllen, etwa function enthalten
  • Häufige Syntax-Elemente einfügen; etwa Funktionsrumpf, switch-Gerüst, CSS-Gerüst
• Rotfärbung bei schweren Syntaxfehlern (Syntax nicht erkennbar) – Upstream
• Sahnehäubchen: Über die Prüfung des Syntaxformats hinaus weitergehende JS-Analyse mit JSHINT etc. zu veranlassen; bei diversen Greasemonkey-Editoren bereits gebräuchlich.

Cookie

Die Extension setzt den Cookie wikiEditor-0-codeEditor-enabled – wird diesem der Wert 0 zugewiesen, ist die Grundeinstellung „geladen, aber keine Hervorhebung“.

Ein Klick auf die Schaltfläche aktiviert (1) bzw. deaktiviert die Hervorhebung und ändert den Wert des Cookies.

Tools

• Ein Benutzerskript, das den CodeEditor automatisch auf allen dafür geeigneten Seiten startet und sonst nicht, ist Benutzer:PerfektesChaos/js/editorContent.
• Eine alternative Methodik verwendet Benutzer:Schnark/js/syntaxhighlight.

Code: CodeEditor deaktivieren

Der nachstehende Code wartet darauf, dass der CodeEditor gestartet wurde, und entfernt ihn anschließend wieder.

mw.hook( "codeEditor.configure" ).add( function () {
       "use strict";
       var context = mw.util.$content.find( "#wpTextbox1" )
                                     .data( "wikiEditor-context" );
       if ( context && context.codeEditor && context.api && context.fn ) {
          context.fn.disableCodeEditor();
          context.api.removeFromToolbar( context,
                                         { "section": "main",
                                           "group":   "format",
                                           "tools":   "codeEditor" } );
          jQuery.cookie( "wikiEditor-0-codeEditor-enabled", null );
       }
} );

Code: CodeEditor nur bei geeignetem Browser

Der nachstehende Code setzt das Beispiel aus dem vorangehenden Abschnitt ein: Wenn es sich nicht um Wikitext handelt, wird der Browser überprüft, und bei fehlender Eignung des aktuellen Browsers der CodeEditor deaktiviert.

if ( mw.config.get( "wgPageContentModel" ) !== "wikitext" ) {
   mw.loader.using( [ "jquery.client" ],
      function () {
         "use strict";
         var profile = jQuery.client.profile();
         if ( "chrome firefox".indexOf( profile.name ) < 0 ) {
            mw.hook( "codeEditor.configure" ).add( function () {
               var context = mw.util.$content.find( "#wpTextbox1" )
                                             .data( "wikiEditor-context" );
               if ( context &&
                    context.codeEditor && context.api && context.fn) {
                  context.fn.disableCodeEditor();
                  context.api.removeFromToolbar( context,
                                                 { "section": "main",
                                                   "group":   "format",
                                                   "tools":   "codeEditor"
                                                 } );
                 jQuery.cookie( "wikiEditor-0-codeEditor-enabled", null );
              }
                                                               } );
         }
      }
   );
}

API des ace

Siehe ace Website – das dort benannte Objekt editor kann wie folgt gebildet werden:

mw.hook( "codeEditor.configure" ).add( function () {
       "use strict";
       var context = mw.util.$content.find( "#wpTextbox1" )
                                     .data( "wikiEditor-context" ),
       var editor = null;
       if ( context && context.codeEditor ) {
          editor = context.codeEditor;
          // editor kann jetzt verwendet werden
       }
} );

Die session des Editors kann wesentlich einfacher bezogen werden:

mw.hook( "codeEditor.configure" ).add( function ( editSession ) {
       "use strict";
       // editSession kann jetzt verwendet werden
} );

Alternativ kann man sicherstellen, dass das HTML-Dokument geladen wurde, und danach

$( function() {
      "use strict";
      var domNode = $( ".ace_editor" ).get( 0 );
      var ace;
      if ( domNode ) {
         ace = domNode.env;
         ace.document.setValue( "// Hier JavaScript-Code eingeben." );
         ace.editor.selectAll();
      }
   } );

Dabei ist ace.document das Document und ace.editor der editor wie oben.

Implementierung

• mw:Extension:CodeEditor (englisch)
• gerrit:extensions/CodeEditor
  • CodeEditor.php
  • modules/ace

Weitere Informationen

• meta:CodeEditor/de – deutschsprachige Kurzbeschreibung im Meta-Projekt
• WP:AceWikiEditor – experimentell, für Wikitext
• Fzw Herbst 2013 – Probleme mit Browsern