Vorlage:Beispiel/Dokumentation

Aus SELFHTML-Wiki
Wechseln zu: Navigation, Suche

Diese Vorlage dient dazu, (Code-)Beispiele mit einem Handgriff in eine einheitliche Form ändern lassen.

Beispiele können drei Formen haben:

  • ohne Live-Beispiel
  • Mit Live-Beispiel auf einer Tab-Anzeige
  • NEU: Mit Live-Beispiel direkt integriert

Ein Live-Beispiel muss im Beispiel-Namensraum des Wiki gespeichert sein und kann, um Missbrauch zu verhindern, nur von Beispiel-Administratoren erstellt oder bearbeitet werden. Es wird über den zeige=…-Parameter der {{Beispiel}}-Vorlage mit dem Beispiel verknüpft.

Anwendung

Diese Vorlage ist modular aufgebaut. Zu ihr gehören weitere Vorlagen, mit der sich in beliebiger Reihenfolge Beispiel-Text- und Erläuterungsmodule zusammenfügen lassen. 

{{Beispiel|
Module
}}

Verfügbare Module sind:

  • {{BeispielCode|…}} für Code aller Art
  • {{BeispielWiki|…}} für alles was sich mit Wiki-Syntax erstellen lässt
  • {{BeispielText|…}} für Erläuterungstext
  • {{LiveBeispiel}} um das Live-Beispiel als iframe in den Wikitext zu integrieren. Die Positionierung über die {{LiveBeispiel}}-Vorlage erlaubt die aus didaktischen Gesichtspunkten beste Anordnung der Beispielbausteine.

Es gibt drei optionale Parameter, die nachfolgend beschrieben werden

  • titel=… für eine Ergänzung der Überschrift
  • zeige=… (optional) für den Verweis auf ein Livebeispiel.
  • vorschau-hoehe=… (optional) um die Höhe des iframes mit dem Livebeispiel vorzugeben. Default ist 25em.

Der Viewport-Emulator, den es früher gab, wird nicht mehr unterstützt. Die modernen Browser haben dieses Tool in ihren Entwicklerwerkzeugen eingebaut.


Parameter

titel - individuelle Überschrift

Der optionale titel-Parameter ersetzt die Standard-Überschrift Beispiel des Beispielrahmens. Früher wurde er dem Wort Beispiel hinzugefügt – das wurde geändert! 

{{Beispiel|titel=Beispiel mit erweiterter Überschrift|
{{BeispielCode|…}}
}}
Beispiel mit erweiterter Überschrift
…

zeige - Verweis auf ein Live-Beispiel

Um ein Beispiel anklickbar zu gestalten ist die Berechtigung Beispiele-Administratoren notwendig. Wer diese Berechtigung nicht hat, und (s)ein Beispiel anklickbar gestaltet haben möchte, sollte zeige=dummy setzen – bitte nicht vorgreifend einen Beispiel:-Dateinamen selbständig vergeben. Derzeit ist vorgesehen, dass sich dann die Beispiele-Administratoren manuell um die Erstellung einer Live-Version kümmern. Siehe auch Hilfe:Wiki/Beispiele‎. 

{{Beispiel|zeige=Beispiel:Beispiel.txt|
{{BeispielCode|…}}
}}
Beispiel ansehen …
…

Achtung!

Der zeige-Parameter braucht unbedingt ein gültiges Argument. Entweder dummy, oder einen Wiki-Artikel im Beispiel-Namensraum. Andernfalls beschwert sich die {{#BeispielURL}}-Funktion aus den Selfhtml-Extensions.

vorschau-hoehe - Höhe des Livebeispiel-iframes

Der <iframe>, der für das Live-Beispiel erstellt wird, hat standardmäßig eine Höhe von 25em. Wenn das nicht passt, kann über diesen Parameter eine individuelle Höhe eingestellt werden. 

{{Beispiel|zeige=Beispiel:Beispiel.txt|vorschau-hoehe=10em|
{{BeispielCode|…}}
}}
Beispiel ansehen …
…

Viewport-Emulator

Da die heutigen Browser einen Viewport-Emulator in ihren Entwicklerwerkzeugen eingebaut haben, unterstützen wir diese Option nicht mehr.

Module

Code-Modul

Der anzuzeigende Code sollte entweder in <pre>, <nowiki> oder <syntaxhighlight> eingefasst werden. {{Achtung|Die für das Syntaxhighlighting genutzte Extension verwendete ursprünglich das <source>-Tag zum Markieren von Highlight-Bereichen. Das Tag hat in HTML eine ganz andere Bedeutung, deshalb ist es seit 2020 missbilligt. Es gibt bereits seit 2009 das <syntaxhighlight>-Tag als Ersatz.

Wenn das Beispiel im SELFHTML-Design dargestellt werden soll, kann das Grundlayout einfach eingebunden werden.

Beispiel ansehen …
<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>…</title>
    <link rel="stylesheet" href="./Beispiel:SELFHTML-Beispiel-Grundlayout.css">
    <style>
        /* Styleangaben für das Beispiel */
    </style>
  </head>
  <body>
    <h1>Überschrift</h1>
    <main role="main">
        <p>Inhalt</p>
    </main>
  </body>
</html>


<pre>

Es kann nur einfacher Text eingegeben werden. Alle HTML-eigenen Zeichen können normal geschrieben werden. Wenn ein </pre> Bestandteil des anzuzeigenden Codes ist, so ist es als &lt;/pre> zu notieren. 

{{Beispiel|titel = mit <pre>|
{{BeispielCode|

<pre>
<!-- Quelltext -->
  <p class="foo">bar baz</p>
  <pre> … &lt;/pre>
</pre>

}}
}}
mit <pre> 
<!-- Quelltext -->
  <p class="foo">bar baz</p>
  <pre> … </pre>

<nowiki>

Im Gegensatz zu <pre> kann man <nowiki> problemlos verlassen, um Wiki-Formatierungen einzubauen. 

{{Beispiel|titel = mit <nowiki>|
{{BeispielCode|

<nowiki><!-- Quelltext -->
  <p class="foo">bar baz </nowiki>'''und ein fett hervorgehobener Teil'''<nowiki></p>
</nowiki>

}}
}}
mit <nowiki>
<!-- Quelltext --> <p class="foo">bar baz und ein fett hervorgehobener Teil</p>

<syntaxhighlight>

Mit diesem Element kann man Code automatisch mit Syntaxhervorhebung anreichern lassen. Verwendbare Parameter:

  • lang="??": Sprache des Codes. Eine Liste der Werte bekommt man bei Eingabe eines falschen Wertes angezeigt (Vorschau-Funktion verwenden!)
  • line: schaltet die Zeilennummerierung ein.
  • line start="??": Zeilennummerierung beginnt ab …
  • highlight="??": welche Zeilen sollen hervorgehoben werden. Zählung beginnt immer mit 1, auch bei Verwendung von line start=…. Die Zeilennummern können kommagetrennt entweder einzeln oder als Bereich mit Bindestrich angegeben werden.
{{Beispiel|titel = mit <syntaxhighlight>|
{{BeispielCode|
<syntaxhighlightlang="html"><!-- Quelltext -->
  <p class="foo">bar baz</p>
</syntaxhighlight>

}}
}}
mit <syntaxhighlight> 
<!-- Quelltext -->
  <p class="foo">bar baz</p>

Wiki-Modul

Es kann beliebige Wiki-Syntax verwendet werden. Allerdings sind zwei Besonderheiten zu beachten. Wenn der Inhalt ein Gleichheitszeichen (=) enthält, muss wie beim nachfolgenden Tabellen-Beispiel (wegen border=1) am Anfang ein 1= eingefügt werden. Ansonsten gibt es eine Warnmeldung. Problematisch ist auch das Pipe-Zeichen (|) für das eine Ersatzschreibweise verwendet werden muss: Hilfe:Wiki/MediaWiki/Vorlagen#Problem:_Senkrechter_Strich_in_Parametern. 


{{Beispiel|
{{BeispielWiki|titel=mit Einrückung|
vorn
 ein-
  ge-
   rückt
}}
}}
mit Einrückung
vorn 
ein-
 ge-
rückt
{{Beispiel|titel=mit Liste|
{{BeispielWiki|
* auf-
* ge-
* zählt
}}
}}
mit Liste
  • auf-
  • ge-
  • zählt
{{Beispiel|titel=mit Tabelle|
{{BeispielWiki|1=
<table border="1"><tr>
  <td>Orangen</td>
  <td>Äpfel</td>
</tr><tr>
  <td>Brot</td>
  <td>Kuchen</td>
</tr><tr>
  <td>Butter</td>
  <td>Eiskrem</td>
</tr></table>
}}
}}
mit Tabelle
Orangen Äpfel
Brot Kuchen
Butter Eiskrem 
{{Beispiel|titel=mit Tabelle in Pipe-Syntax|
{{BeispielWiki|1=
{{(!}} border="1"
{{!}}Orangen
{{!}}Äpfel
{{!-}}
{{!}}Brot
{{!}}Kuchen
{{!-}}
{{!}}Butter
{{!}}Eiskrem
{{!)}}
}}
}}
mit Tabelle in Pipe-Syntax
Orangen Äpfel
Brot Kuchen
Butter Eiskrem

Text-Modul

Dient zum Beispiel zur Erläuterung eines Beispiels. Das Modul kann aber auch für allgemeinen Text verwendet werden, ohne dass dieser ein Kommentar zum Beispiel darstellt. Eine Anwendung dafür wäre, es für die Benennung einzelner Abschnitte von mehrteiligen Beispielen zu benutzen. (Deswegen heißt es BeispielText (ist auch etwas kürzer zu tippen) und nicht BeispielKommentar.)

Bezüglich Gleichheitszeichen (=) und Pipe-Symbol (|) gelten die selben Hinweise wie beim Wiki-Modul. 

{{Beispiel|titel=mit Erklärung|
{{BeispielCode|…}}
{{BeispielText|Kommentar zum Code}}
}}
mit Erklärung
…
Kommentar zum Code

Inline-Modul für das Live-Beispiel

Wenn das Live-Beispiel nicht über einen Tab-Reiter, sondern zusammen mit den übrigen Beispielmodulen angezeigt werden soll, dann markiere die dafür gewünschte Position mit der Vorlage {{LiveBeispiel}}. Den Artikelnamen des Beispiels selbst musst Du weiterhin im zeige-Parameter notieren!

Die LiveBeispiel-Vorlage kann auch als einziger Inhalt eines Beispiel verwendet werden! 

{{Beispiel|titel=mit inline-Beispiel|zeige=Beispiel:Beispiel.txt|
{{BeispielCode|…}}
{{LiveBeispiel}}
}}

Mehrfache Modulanwendung

Module können in beliebiger Reihenfolge und Anzahl eingefügt werden. Zwischen den Modulen kann eine Leerzeile eingefügt werden, mehr als eine zerreißt allerdings die Box. Das {{LiveBeispiel}} kann nur einmal verwendet werden! 

{{Beispiel|titel=– mehrteilig|

{{BeispielCode|<pre><!-- erster Code-Teil --></pre>}}

{{BeispielText|Text zum ersten Code-Teil}}

{{BeispielCode|<pre><!-- zweiter Code-Teil --></pre>}}

{{BeispielText|Text zum zweiten Code-Teil}}

{{BeispielWiki|
* eine
* Liste
}}

{{BeispielText|Text zur Liste}}

}}
– mehrteilig 


<!-- erster Code-Teil -->
Text zum ersten Code-Teil
<!-- zweiter Code-Teil -->
Text zum zweiten Code-Teil
  • eine
  • Liste
Text zur Liste


Abgerufen von „http://wiki.selfhtml.org/index.php?title=Vorlage:Beispiel/Dokumentation&oldid=97284“