Hilfe:Wiki/Beispiele
Inhaltsverzeichnis
Beispiele einfügen
Als angemeldeter Anwender kann man zwar Beispiele in Seiten einfügen, der Code für anklickbare Beispiele muss jedoch in den Namensraum Beispiel eingefügt werden. Um in diesem Namensraum schreiben zu können, wird die Berechtigung Beispiele bearbeiten (editexample) benötigt, für die ein Benutzer Mitglied der Gruppe Beispiele-Administratoren sein muss.
Die für die Anklickbarkeit vorgesehenen Beispiele kann ein angemeldeter Anwender mit einem zeige=dummy kennzeichnen. Die weiteren Schritte führt dann einer der Beispiele-Administratoren aus.
{{Beispiel|zeige=dummy|
{{BeispielCode|...}}
}}
Beispiele-Administratoren
Die Aufgabe eines Beispiel-Administrators ist, den Beispiel-Code auf eine Seite im Namensraum Beispiel zu übertragen. Da der auf einer Artikelseite angezeigte Code mit Formatierungen versehen oder der Einfachheit wegen gekürzt sein kann, obliegt es ihm, die Rohfassung des Codes zu extrahieren und ihn gegebenenfalls für die Anzeige im Browser geeignet umzuschreiben. Das kann beispielsweise enthalten, Elemente zu ergänzen, die für eine Validität des Beispiels notwendig sind.
Beispiel anzulegen. Das ist im Grunde eine Wiki-Seite wie die anderen auch. Der Seitenname muss lediglich mit „Beispiel:“ anfangen und mit .html, .css, .js, .xsl oder .xml enden – je nach Inhalt. Aufgrund dieser Endung wird vom Anzeigescript der dazugehörige Content-Type ausgegeben. Damit stehen auch die für Beispiele verfügbaren Sprachen fest. Für die weitere Benennung der Seite an sich gibt es keine Vorgabe. Um sicherzustellen, dass kein bereits vorhandener Name verwendet wird, kann man die Liste aller Seiten im Beispiel-Namensraum zu Rate ziehen (zu erreichen über „Spezialseiten“ → „Alle Seiten (mit Präfix)“).
Der Seitenname ist im Parameter zeige= der Vorlage:Beispiel einzutragen. Daraufhin sehen die Anwender die Links „ausprobieren“ (öffnet das Beispiel im Frickl), „Quelltext“ (zeigt den [reduzierten] Quellcode) und „Vorschau“ (zeigt das Beispiel im IFrame). Der Beispiel-Administrator sieht zusätzlich auch noch einen Link „bearbeiten“, der zu der Seite führt, auf der der Code bearbeitet werden kann.
Hinweise zum Gestalten von Beispielen
Syntax-Highlighting
Obwohl es die Möglichkeit zur Syntaxhervorhebung mittels <source lang="…">…</source> gibt, sollte solch eine Auszeichnung mit Bedacht gewählt werden. Fortgeschrittene Anwender, die grundlegend mit der Syntax der verwendeten Sprache vertraut sind, finden eine farbliche Auszeichnung des Codes in der Regel recht nützlich, um sich mit dem vorliegenden Code vertraut zu machen. Eine Auszeichnung der für Fortgeschrittene vorgesehenen Code-Beispiele mit <source lang="…">…</source> ist also eine sinnvolle Angelegenheit.
Gestaltung ohne Syntax-Highlighting
Für einen Anfänger wirkt eine farbliche Gestaltung möglicherweise eher verwirrend als helfend, besonders wenn einige Syntax-Elemente auffallend gefärbt sind, die jedoch für ein Verständnis des besprochenen Themas nicht weiter bedeutend sind. Die stattdessen wichtigen Elemente sind dagegen weniger hervorgehoben und damit schlechter auffindbar. Eine automatische Einfärbung kann üblicherweise kaum ein für den Anfänger nützliches Ergebnis bringen.
Sinnvoller wäre es, auf den vorwiegend für Anfänger vorgesehenen Seiten auf die automatische Färbung zu verzichten und nur die jeweils wichtigen Syntax-Elemente angemessen hervorzuheben (zum Beispiel durch Fettdruck oder sparsame Verwendung von Farbe). Dazu kann man zunächst die Vorlage BeispielCode mit der <nowiki></nowiki>-Auszeichnung wählen.
{{Beispiel|
{{BeispielCode|<nowiki>...</nowiki>}}
}}
Für die hervorzuhebenden Stellen muss der <nowiki>-Bereich vorübergehend verlassen werden, um die wiki-üblichen Formatierungselemente verwenden zu können.
{{Beispiel|
{{BeispielCode|
<nowiki>etwas Text oder Code, </nowiki>'''wichtiges Element'''<nowiki>, weiterer Text</nowiki>}}
}}
Um diese Formatierungsarbeit für den Bearbeiter zu erleichtern, gibt es unter dem Editierfenster einige auswählbare Elemente. Die für Beispiele sinnvollen Elemente sind durch Umstellen der Select-Box auf Beispiel erreichbar. (Für diese Funktionalität muss JavaScript im Browser aktiviert sein.)
Verwendungs des Beispiel-Layouts
Die meisten Beispiele haben das Beispiel-Layout eingebunden. Während es im Frickl-Modus nicht geladen wird, öffnet sich bei einem Rechtsklick eine neue Seite im Beispiel-Layout. Durch den immer gleichen Aufbau und Farbgebung wird ein Wiedererkennungswert erzielt und Benutzer können sich in der gewohnten Umgebung zurecht finden:
<!DOCTYPE html> <html lang="de"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0;" /> <link rel="stylesheet" media="screen" href="./Beispiel:SELFHTML-Beispiel-Grundlayout.css" /> <title>Beispiel: Titel</title> </head> <body> <h1>Beispiel: Überschrift</h1> <main> </main> </body> </html>
Frickl
Das Frickl ist ein Parser, der den Code einer Beispielseite in HTML, CSS und JavaScript auftrennt, diesen in einem Editor zur Bearbeitung zur Verfügung stellt und dann das Live-Ergebnis anzeigt. So können Sie herumprobieren, Werte verändern und Code einfügen und gleich testen. Im Erfolgsfall können Sie den so aktualisierten Code kopieren und in ihrem Editor speichern.
Das Selfhtml-Beispiel-Grundlayout und externe Skripte werden dabei nicht geladen.
Ein leeres Frickl erhalten Sie über den Link https://wiki.selfhtml.org/extensions/Selfhtml/frickl.php.
JavaScript im Frickl
JavaScript sollte in Frickl-Beispielen im head-Element eingebunden sein. Der Inhalt eines script-Elements im body wird zwar ausgelesen und auch im Editor angezeigt, beim Ausführen aber wieder durch den im HTML-Markup vorhandenen Original-Code überschrieben, sodass vorgenommene Änderungen nicht wirksam werden.
Die Einbindung im head-Element kann durch eine anonyme Funktion erfolgen
<script>
'use strict';
document.addEventListener("DOMContentLoaded", function () {
});
</script>
Für JavaScript-Beispiele sollten folgende Grundsätze selbstverständlich sein.
- Trennung von Inhalt, Präsentation und Verhalten
- Beachtung des strengen Modus
- sprechende Namen für Variablen und Funktionsnamen
- button- anstatt input-Elemente
- Vermeiden des Pseudoprotokolls
href="javascript: …" - dynamische Anbindung mit addEventListener anstelle von HTML-Eventattributen
- Ausgabe mit DOM-Methoden wie Node.textContent anstelle von alert() oder document.write().
