Quelltext der Seite Wikiup:Technik/Text/Edit/CodeEditor

{{../../../!header
|Text=CodeEditor}}
Die MediaWiki-Erweiterung '''CodeEditor''' (basierend auf [[Ace (JavaScript-Texteditor)|Ace]]) dient dazu, bei der Bearbeitung Textsequenzen besser darzustellen, die vollständig in einer formalen Sprache notiert sind. Insbesondere geht es um [[Syntaxhervorhebung]], auch um die Anzeige von Zeilennummern. Daraus folgt gleichzeitig die Meldung von (elementaren) Syntaxfehlern.

Es gibt zwei Anwendungsbereiche:
# Seiten, die vollständig in einer formalen Sprache notiert sind („[[../../../ MediaWiki/Content Model|Content Model]]“).<br /> Zurzeit ist Quellcode in [[JavaScript]], [[Cascading Style Sheets|CSS]] und [[Lua]] von Interesse.
# Berbeitung von Code-Sequenzen, die in der Seite mit <code>[[Hilfe:Syntaxhighlight|&lt;syntaxhighlight>]]</code>  dargestellt werden, mittels [[Hilfe:VisualEditor|VisualEditor]]&nbsp;– siehe dazu [[Hilfe:Syntaxhighlight/VisualEditor]]

Unterstützt werden zurzeit über 130 Syntaxschemata, somit nahezu 200 individuelle Programmiersprachen (mit Varianten und Dialekten) oder genauer: formale Sprachen.

== Geeignete Browser ==
Der CodeEditor wurde zunächst nur für einige Versionen der folgenden Browser erprobt:
* Firefox
* Google Chrome

Ansonsten funktioniert er nicht oder zerstört den Seiteninhalt. Die Fehlfunktion ist den Entwicklern durchaus über Jahre bekannt –
{{Phab|project=mediawiki/extensions/CodeEditor|file=modules/ext.codeEditor.js|branch= b7b54e6c7d96e633a14ae9f69f5bfd076650e9cb|line=14}} – 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'''. :(
Der aktuelle Stand (2017) ist nicht bekannt.

== Bearbeitung einer Seite ==
=== Aktivierung ===
''Wichtig:''
* Konkurrierende Editoren müssen deaktiviert sein, namentlich [[../wikEd|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 <code>wikitext</code> ist, sondern die Variable <code>[[../../../Skin/JS/Variablen#wgPageContentModel|wgPageContentModel]]</code> einen der folgenden Werte hat:
{| class="wikitable"
! wgPageContentModel
! Automatische Zuweisung nach Regeln
|-
| <code>css</code>
|rowspan="2"|
* Benutzer-Namensraum oder MediaWiki-Namensraum
* Letzte drei bzw. vier Buchstaben des Seitennamens sind <code>.css</code> oder <code>.js</code> (Kleinschreibung empfohlen)
|-
| <code>javascript</code>
|-
| <code>Scribunto</code>
| Scribunto steht zurzeit nur für [[Hilfe:Lua|Lua]] (könnten aber auch weitere Sprachen sein).
# Namensraum <code>Modul:</code>
#* Seitenname erfüllt nicht das für die Dokumentationsseite vorgegebene Schema
# (???) Benutzer-Namensraum und Seitenname enthält <code>/Spielwiese/Modul:</code>
|}
Die Aktivierung berücksichtigt '''nicht''', [[#Geeignete Browser|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 [[#disableCodeEditor|siehe unten]].

==== Individuell ====
Die Programmierung wird in die benutzerdefinierten JavaScript-Seiten eingefügt; meist [[Special:Mypage/common.js|common.js]] (siehe [[../../../Skin/JS#Einbindung|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 <code>/Spielwiese/Modul:</code>  (wgTitle).
* Zu den Variablen siehe [[../../../Skin/JS/Variablen|hier]].

Ist die Situation festgestellt worden, dass eine Quellcode-Seite bearbeitet wird, ist das entsprechende Schlüsselwort zuzuweisen; hier <code>lua</code> als Beispiel. Danach werden die erforderlichen Module eingebunden ([[../../../Skin/JS/ResourceLoader|ResourceLoader]]).
<syntaxhighlight lang="javascript">
mw.config.set("wgCodeEditorCurrentLanguage", "lua");
mw.loader.load( [ "ext.codeEditor",
                  "ext.codeEditor.ace",
                  "jquery.ui.resizable",
                  "jquery.wikiEditor" ] );
</syntaxhighlight>

=== Verfügbare Sprachen ===
[[Datei:Standard WikiEditor interface.png|mini|Normales Bearbeitungsfeld (Screenshot)]]
Standardmäßig werden zurzeit Syntaxdefinitionen der [[Programmiersprache|Programmier-]] und anderer Sprachen entsprechend der folgenden Schlüsselwörter zugeladen:
* <code>javascript</code>
* <code>json</code>
* <code>css</code>
* <code>lua</code>
Es lassen sich weitere Typen aktivieren, für die in einer Wikipedia bislang keine regulären Seiten bekannt sind:
* <code>c_cpp</code>
* <code>clojure</code>
* <code>csharp</code>
* <code>coffee</code>
* <code>groovy</code>
* <code>html</code>
* <code>java</code>
* <code>ocaml</code>
* <code>perl</code>
* <code>php</code>
* <code>python</code>
* <code>ruby</code>
* <code>scala</code>
Dazu ist auch die Ressource <code>ext.codeEditor.ace.modes</code> zu laden.

Weitere Sprachen lassen sich aktivieren; ''Beispiel:''
* Um für [[Extensible Markup Language|XML]] den Typ <code>xml</code> zu bearbeiten, muss zusätzlich das folgende spezifische Skript geladen werden:
<syntaxhighlight lang="javascript">
mw.loader.load( "https://git.wikimedia.org/raw/" +
                "mediawiki%2Fextensions%2FCodeEditor" +
                "/HEAD/" +
                "modules%2Face%2Fmode-xml.js" );
</syntaxhighlight>

Eine weitere Anwendungsmöglichkeit wäre Wikitext; hierzu gibt es Experimente ([[../AceWikiEditor|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;
* <code>/* Kommentare */</code>

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|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.

=== Cookie ===
Die Extension setzt den [[Cookie]] <code>wikiEditor-0-codeEditor-enabled</code> – wird diesem der Wert <code>0</code> zugewiesen, ist die Grundeinstellung „geladen, aber keine Hervorhebung“.

Ein Klick auf die Schaltfläche [[Datei:Code-selected.png]] aktiviert (<code>1</code>) bzw. deaktiviert die Hervorhebung und ändert den Wert des Cookies.

== Bedienung ==
[[Datei:CodeEditor interface.png|mini|Bearbeitungsfeld des CodeEditor (Screenshot)]]
* Es wird die „neue“ Werkzeugleiste benutzt ([[Hilfe:Symbolleisten]]).
* Mit der vorangestellten Schaltfläche [[Datei:Code-selected.png]] 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.
* {{Taste|Einfg}} schaltet den Modus zwischen „Einfügen“ (Vorgabe) und „Überschreiben“; die Gestalt des Cursors ändert sich von <span style="background-color: #87CEFA;">|</span> auf&nbsp;<span style="background-color: #87CEFA;">_</span>.
* Drag&Drop möglich (erst nach einer Verzögerung bei gedrückter linker Maustaste; Veränderung des Cursors erfolgt mit unüblichem Icon)<ref>[http://ace.c9.io/#nav=api&api=editor setDragDelay] – Verzögerung einstellbar</ref>
* Ausblenden eines mehrzeiligen auskommentierten Bereichs <code style="white-space: nowrap">/* ... */</code> und Code-Blocks <code style="white-space: nowrap">{ ... }</code> 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 ===
[https://github.com/ajaxorg/ace/wiki/Default-Keyboard-Shortcuts 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|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 <code>function</code> 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.

== Tools ==
* Ein [[Wikipedia:Technik/Skin/Benutzerskripte/Hinweise|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]].

=== {{Anker|disableCodeEditor}} Code: CodeEditor deaktivieren ===
Der nachstehende Code wartet darauf, dass der CodeEditor gestartet wurde, und entfernt ihn anschließend wieder.

<syntaxhighlight lang="javascript">
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 );
       }
} );
</syntaxhighlight>

=== 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.

<syntaxhighlight lang="javascript">
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 );
              }
                                                               } );
         }
      }
   );
}
</syntaxhighlight>

=== API des ace ===
Siehe [http://ace.c9.io/#nav=howto ace Website] – das dort benannte Objekt ''editor'' kann wie folgt gebildet werden:
<syntaxhighlight lang="javascript">
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
       }
} );
</syntaxhighlight>

Die [http://ace.c9.io/#nav=api&api=edit_session ''session''] des Editors kann wesentlich einfacher bezogen werden:
<syntaxhighlight lang="javascript">
mw.hook( "codeEditor.configure" ).add( function ( editSession ) {
       "use strict";
       // editSession kann jetzt verwendet werden
} );
</syntaxhighlight>

Alternativ kann man sicherstellen, dass das HTML-Dokument geladen wurde, und danach
<syntaxhighlight lang="javascript">
$( 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();
      }
   } );
</syntaxhighlight>
Dabei ist <code>ace.document</code> das [http://ace.c9.io/#higlighter=&nav=api&api=document ''Document''] und <code>ace.editor</code> der ''editor'' wie oben.

== Weitere Informationen ==
{{MediaWiki|Extension:CodeEditor}}
{{Phabricator|Engage=MediaWiki-extensions-CodeEditor|ICON=1|ENGL=1}}
:* {{Phab|project=mediawiki/extensions/CodeEditor|title=ECED}}
:** {{Phab|project=mediawiki/extensions/CodeEditor|file=CodeEditor.php}}
:** {{Phab|project=mediawiki/extensions/CodeEditor|dir=modules/ace}} – Plug-Ins für Syntaxschemata
* [[meta:CodeEditor/de]] – deutschsprachige Kurzbeschreibung im Meta-Projekt
* [[../AceWikiEditor|WP:AceWikiEditor]] – experimentell, für Wikitext
* [[Wikipedia:Fragen zur Wikipedia/Archiv/2013/Woche 35 #Weiterer Fehler im Code-Editor|Fzw Herbst 2013]] – Probleme mit Browsern

== Anmerkungen ==
<references />

{{SORTIERUNG:CodeEditor}}
[[Kategorie:Wikipedia:Technik/Text/Edit]]