Wikiup:Technik/Skin/Gadgets/Vorlagenmeister

aus Wikipedia, der freien Enzyklopädie
Version Datum
Status: 0.5+ Januar 2015 oder später
Screenshot

Der Vorlagen-Meister ist ein JavaScript-Programm, um die Arbeit mit komplexeren Vorlagen zu erleichtern. Er erlaubt die komfortable Erzeugung und Änderung von Vorlagen über ein eingeblendetes Eingabeformular.

Das Helferlein stammt von 2009. Seit 2016 ist mit der VisualEditor-Werkzeugleiste bei der Quelltextbearbeitung ein offizielles Hilfsmittel mit nahezu vergleichbarer Funktionalität beim Ausfüllen von Vorlagen verfügbar,[1] so dass diese Entwicklungslinie langfristig eingestellt werden wird.

Aktivierung

Der leichteste Weg wäre als angemeldeter Benutzer durch einfaches Ankreuzen. {{Wikipedia:Technik/Skin/Gadgets/!Einstellung|Gruppe=B}}

Wer das Werkzeug im Kontext der deutschsprachigen Wikipedia per JavaScript ansteuern möchte, kann die folgende Anweisung benutzen: 

mw.loader.load( "ext.gadget.Vorlagenmeister" );

Die Methodik sorgt dafür, dass die neuesten Versionen ausgeführt werden; Leeren des Browser-Cache ist nicht erforderlich, und in dringenden Fällen kann eine Aktualisierung abhängiger Skripte zentral gesteuert werden.

Wer die Software außerhalb des Kontextes einer hiesigen Wiki-Seite benutzen möchte, kann die nachfolgende Anweisung verwenden: 

mw.loader.load( "https://de.wikipedia.org/w/index.php?title=MediaWiki:Gadget-Vorlagenmeister.js&action=raw&ctype=text/javascript",
                "text/javascript");

Kompatibilität

Getestet wurde die Anwendung 2009 erfolgreich mit Firefox ab Version 2, Opera 9 und dem Internet Explorer ab Version 7 bei Verwendung des Monobook-Skins.

2014 wurden die Tests wiederholt mit IE8, IE11 sowie Chromium, Opera bis 12, Firefox und Midori in den aktuellen Versionen. Nicht verwendbar ist der Vorlagenmeister mit Konqueror (4.12.3).

Eine gleichzeitige Verwendung mit dem Quelltextbearbeitung-Modus des VisualEditors ist nicht vorgesehen, da dieser ein weitgehend ähnliches Verfahren anbietet.

Anleitung

In der Bearbeitungsansicht einer Seite erscheint in der Toolbar (wo auch die Knöpfe für „Fett“, „Kursiv“, etc. sind) ein zusätzlicher Knopf „VM“ oder „{T}“ (je nach Werkzeugleiste). Dieser dient zum Aufruf des Formulars sowie während der Bearbeitung dem Wechsel zwischen der Formularansicht und der Eingabebox.

Vorlage neu einfügen

Zuerst setzt man den Text-Cursor an die gewünschte Position im Text. Dann gibt es zwei Möglichkeiten:

  1. Man schreibt eine leere Vorlage in den Text: {{Vorlagenname}}, setzt den Text-Cursor darauf und klickt auf den VM-Button.
  2. Oder man drückt gleich den VM-Button, woraufhin die Anwendung ohne Formular erscheint. Im Eingabefeld „Vorlage“ kann man daraufhin den gewünschten Namen der Vorlage eingeben. Nach Betätigung der Eingabetaste wird das Formular für diese Vorlage geladen.

Vorhandene Vorlage bearbeiten

Um eine vorhandene Vorlage zu bearbeiten, setzt man den Text-Cursor irgendwo in den Vorlagentext und drückt den VM-Button. Das Programm ermittelt daraufhin den Vorlagenamen, erzeugt das Formular und füllt die Eingabefelder mit den Werten aus dem Quelltext aus.

Enthält der Vorlagentext unbekannte Parameternamen, zum Beispiel durch Schreibfehler, so erscheint eine Leiste mit grünen Buttons, die als Beschriftung die jeweiligen unbekannten Parameter tragen. Klickt man mit der Maus auf einen solchen Button, so wird der Inhalt des Parameters in das aktuelle Formularfeld eingetragen.

Bearbeitung abschließen

Ist man mit der Bearbeitung der Vorlage fertig und möchte die Änderungen in den Vorlagentext übernehmen, so drückt man den Knopf „Übernehmen“. „Abbrechen“ verwirft sämtliche Änderungen und beendet ebenfalls das Tool.

Durch Drücken auf den VM-Button während der Bearbeitung eines Formulars kann man die Formularansicht aus- bzw. wieder einblenden, um zum Beispiel Text aus dem Artikel-Quelltext zu kopieren. Ist die Formularansicht auf diese Weise ausgeblendet, kann im Bearbeitungsfeld zur Änderung des Quelltextes nur Text markiert und kopiert, jedoch nicht geschrieben werden, bis die Formularansicht wieder eingeblendet und die Bearbeitung der Vorlage – entweder durch einen Klick auf die Schaltfläche „Übernehmen“ oder auf die Schaltfläche „Abbrechen“ – abgeschlossen wird. Wird bei der Bearbeitung das Wikitexteditor-Benutzerskript wikEd verwendet, kann bei auf diese Weise ausgeblendeter Formularansicht zwar Text geschrieben werden, jedoch wird der während der Ausgeblendung geschriebene Text bei einer Wiedereinblendung verworfen.

Vorlagen, die mit dem Tool genutzt werden können

  • Ob für eine Vorlage schon eine XML-Beschreibung existiert, findest du über die Kategorie:Vorlage:für Vorlagen-Meister heraus.
  • Bei allen Vorlagen, zu denen TemplateData definiert ist, wird aus diesen Angaben ein Formular erstellt und mit Anleitungstexten und Gültigkeitsprüfungen versehen, falls es keine XML-Definition gibt.

Erweiterungen für einzelne Vorlagen

Erweiterungen zur Transformation von Text in Vorlagen

Diese Erweiterungen dienen speziell dem Zweck, aus normalem formatierten Text (zum Beispiel einer klassischen Literaturangabe oder einer Infobox, die mit Tabellen erstellt wurde) alle Parameter für eine Vorlage zu ermitteln und damit das Formular entsprechend vorauszufüllen.

Dazu markiert man den entsprechenden Text in der Eingabebox und drückt dann den VM-Button. Daraufhin erscheint ein Auswahldialog, aus den man sich die gewünschte Vorlage auswählt.

Für folgende Vorlagen steht solch eine Erweiterung zur Verfügung:

Für Entwickler

Um eine Vorlage optimal mit diesem Tool nutzen zu können, ist ein Abschnitt mit einer XML-Beschreibung auf der Unterseite XML dieser Vorlage notwendig (also Vorlage:Name/XML).

Das Benutzerskript jsonXMLutils@PerfektesChaos generiert aus der Programmierung oder der Kopiervorlage einer Vorlage eine TemplateData-Definition. Aus jeder TemplateData-Definition kann es bequem das Grundgerüst der XML-Vorlagenbeschreibung generieren. Es stellt außerdem die XML-Seite mit Syntaxhervorhebung dar.

Aufbau und Bedeutung der XML-Vorlagenbeschreibung

Die Beschreibung hat folgende Knotenhierarchie (nur mit Pflichtattributen): 

<TemplateUsage>
  <Group>
    <Parameter name="Titel" />

    <Parameter name="ISBN">
      <Help>Die ISBN-Nummer ohne vorangestelltes ISBN.</Help>
    </Parameter>

    <Parameter name="Monat">
      <Value>Januar</Value>
      <Value>Februar</Value>
      ...
    </Parameter>
    ...
  </Group>
  ...
</TemplateUsage>

In eingefügten Texten, zum Beispiel dem Text der Help-, Condition- und Value-Knoten, oder in Attributen zugewiesenen Texten, zum Beispiel zu name oder label, müssen folgende Zeichen ersetzt werden, damit das XML-Dokument gültig bleibt:

Zeichen Ersatz
& &amp;
< &lt;
> &gt;
" &quot;
' &apos;

Folgende Tabelle beschreibt alle Knoten und deren Attribute. Auf die Groß- und Kleinschreibung muss bei der Verwendung geachtet werden. Optionale Knoten bzw. Attribute sind mit (optional) gekennzeichnet. Vorgegebene Attributwerte brauchen nicht explizit angegeben zu werden.

Knotenname Attribute Beschreibung
TemplateUsage Wurzelknoten, welcher die Beschreibung enthält
output (optional) – Beschreibt die Art des erzeugten Vorlagenquelltextes.
output="collapse" (Vorgabe) – Es werden nur Parameter genutzt, denen ein Wert zugewiesen wurde. Leere Parameter fallen weg. Der Quelltext enthält keine Zeilenumbrüche. Diese Ausgabe eignet sich bei Vorlagen mit wenigen Parametern und intuitiven Namen (zum Beispiel: Vorlage:Literatur).
output="expand" Der Vorlagenquelltext enthält alle, auch leere, Parameter. Jeder Parameter steht auf einer separaten Zeile. Diese Ausgabeart eignet sich für Vorlagen mit einer Vielzahl von Parametern und erleichtert Nutzern ohne Tool-Unterstützung die Arbeit mit der Vorlage (zum Beispiel: Vorlage:Infobox Schienenfahrzeug).
max_value_indentation (optional) – Legt fest bis zu maximal wie viele Zeichen die Werte der Vorlagenparameter nach rechts gerückt werden dürfen, um diese einheitlich auszurichten. Ein Wert von 0 deaktiviert diese Funktion. Vorgabewert ist 32.
Group Gruppiert eine Menge von Parametern. Im Formular werden diese in einem separaten Bereich dargestellt. Ist eine Gruppierung nicht zweckmäßig, so sind alle Parameter in einer einzigen Gruppe zu beschreiben.
name (optional) – Beschreibt den Inhalt der Gruppe. Ist dieses Attribut angegeben, so wird es als Gruppenüberschrift angezeigt.
showempty (optional) – Legt fest, ob im Ausgabemodus „expand“ die Gruppe angezeigt werden soll, wenn keinem Parameter dieser Gruppe ein Wert zugewiesen wurde.
showempty="true" (Vorgabe) – Alle Parameter der Gruppe werden ausgegeben, auch wenn keinem ein Wert zugewiesen wurde.
showempty="false" Alle Parameter dieser Gruppe werden nur ausgegeben, wenn wenigstens einem Parameter ein Wert zugewiesen wurde.
Parameter Beschreibt einen benannten oder numerischen Parameter der Vorlage. Nur als Kindknoten von „Group“ erlaubt. Unbenannte (numerische) Parameter müssen in aufsteigender Reihenfolge angegeben werden.
name Name oder Nummer des Parameters.
label (optional) – Alternative Bezeichnung, die statt des Namens im Formular angezeigt wird. Zum Beispiel: „Chefredakteur“ statt „chefred“.
length (optional) – Länge des Eingabefeldes in Zeichen oder „max“. Letztere Angabe bewirkt, dass der Parameter vollständig über eine ganze Zeile gestreckt wird. Sinnvoll ist die Angabe bei Parametern mit inhaltlich begrenzter Länge, wie Höhen- und Geschwindigkeitsangaben, und bei Parametern, denen in der Regel sehr lange Texte übergeben werden. Vorgabe sind 20 Zeichen.
height (optional) – Höhe des Eingabefeldes in Zeilen. Vorgabe ist eine Zeile.
null (optional) – Legt fest, ob ein Wert für diesen Parameter eingegeben werden muss.
null="true" (Vorgabe) – Ein leeres Feld ist erlaubt – es muss kein Wert eingegeben werden.
null="false" Die Angabe eines Wertes ist Pflicht. Der Parametername ist im Formular unterstrichen. Vor dem Übernehmen der Eingaben prüft das Programm, ob ein Wert eingegeben wurde, und markiert dieses Feld im Fehlerfall.
predefined (optional) – Sagt aus, ob die Vorlage für diesen Parameter einen vordefinierten Wert nutzt, wenn kein Wert übergeben wird.
predefined="true" Es existiert ein vordefinierter Standardwert für diesen Parameter. Dies hat bei der Ausgabe „expand“ die Auswirkung, dass der Parameter, wenn er leer ist, ohne Gleichheitszeichen erzeugt wird. Dadurch bleibt er weiterhin dokumentiert, ist aber trotzdem nicht definiert. Stattdessen erzeugt dies einen unbenannten Parameter (zum Beispiel {{{1}}}) mit dem Parameternamen als Inhalt.
predefined="false" (Vorgabe) – Es existiert kein vordefinierter Wert. Bei der Ausgabeart „expand“ wird der Parameter bei fehlender Eingabe auch mit leerem Inhalt im Vorlagentext erzeugt (zum Beispiel: „ISBN=“).
type (optional) – Datentyp analog zu den type in TemplateData – damit wird automatisch die entsprechende Gültigkeitsregel wirksam:
  • "boolean" – Ausgabe als 1 oder nichts
  • "date" – Datum beliebiger Präzision (ISO 8601)
  • "line" – Keine Zeilenumbrüche erlaubt
  • "number" – Zahl
    • Vorzeichen (einschließlich typografischem Minuszeichen) erlaubt
    • Zahlenformate mit Punkt und/oder Komma als Dezimal- und Tausendertrennzeichen
    • Exponentialnotation (wissenschaftlich)
  • "wiki-file-name" – Geeignet als Titel oder Name einer Mediendatei
  • "wiki-page-name" – Geeignet als Name einer Seite
  • "wiki-user-name" – Geeignet als Benutzername
Condition (optional) – Erlaubt die Angabe eines regulären Ausdrucks, der für eine gültige Eingabe erfüllt sein muss. Vor dem Übernehmen der Eingaben prüft das Programm die Gültigkeit und markiert dieses Feld im Fehlerfall. Nur als Kindknoten von „Parameter“ erlaubt.
Default (optional) – Über diesen Kindknoten von „Parameter“ lässt sich ein Vorgabewert festlegen, mit dem das Eingabefeld immer vorausgefüllt wird, wenn es leer ist.
Help (optional) – Enthält einen Hilfetext, der die Verwendung des Parameters beschreibt. Im Formular wird dieser in der Statuszeile angezeigt, wenn das dazugehörige Eingabefeld aktiv ist. Des Weiteren wird die Hilfe als Tooltip angezeigt. Nur als Kindknoten von „Parameter“ erlaubt.
Value (optional) – Erlaubt die Angabe von Werten, die der Parameter annehmen darf. Im Formular wird anstatt eines Texteingabefeldes bei mehreren Angaben eine Auswahlliste angezeigt, welche mit allen Value-Elementen des Parameters gefüllt ist. Existiert zu einem Parameter nur ein Value, so wird ein Ankreuzfeld (engl. Checkbox) angezeigt. Nur als Kindknoten von „Parameter“ erlaubt.
AutoValue (optional) – Über diesen Kindknoten von „Parameter“ lässt sich ein Wert festlegen, mit dem die Vorlage ausgefüllt wird, wenn es im Formular leer blieb.
  • Es kann eine konstante Zeichenkette angegeben werden.
  • Wenn die Zeichenkette mit einer Pipe | beginnt, wird statt des konstanten Wertes eine Funktion ausgewertet.
    • Zurzeit ist eine Funktion definiert: |localtime| – momentane lokale Zeit.
      <AutoValue>|localtime|YYYY-MM-DD|</AutoValue>
label (optional) – Alternative Bezeichnung, die statt des Namens im Formular angezeigt wird. Zum Beispiel: „Chefredakteur“ statt „chefred“.

Testen und Einfügen der Beschreibung

Die Vorlagenbeschreibung wird auf der Unterseite XML der Vorlagenseite hinterlegt, also Vorlage:Name/XML. Um auch in der Wikipedia eine gewisse Lesbarkeit der Vorlage zu erhalten, sollten alle Zeilen außer der ersten Zeile mit einem Leerzeichen beginnen. Die erste Zeile darf hingegen so nicht beginnen. 

<?xml version="1.0" encoding="UTF-8"?>
<!--                                                                    -->
<!-- Dies ist die XML-Beschreibung der Vorlage für den Vorlagenmeister. -->
<!-- Mehr Infos unter [[Wikipedia:Helferlein/Vorlagen-Meister]].        -->
<!--                                                                    -->
<?mediawiki "{{XML-Warnung}}"?>
 <TemplateUsage ...>
 ...
 </TemplateUsage>

Die Vorlage selbst wird um die Vorlage:XML-Warnung erweitert. Diese informiert die Autoren der Vorlage von der Existenz der XML-Beschreibung.

Zum Testen von größeren Modifikationen sollte unbedingt eine Unterseite des eigenen Benutzerraumes verwendet werden, da Änderungen, und damit auch Fehler, sich sofort bei anderen Nutzern auswirken können.

Validieren gegen das XML-Schema

Unter Benutzer:Revvar/VM/XML-Schema gibt es ein von Benutzer:Stf erstelltes XML-Schema für die Vorlagenbeschreibung. Damit kann überprüft werden, ob die Vorlagenbeschreibung grammatisch korrekt ist. Die Vorlage:XML-Hinweis bot einen Link zur schnellen Online-Überprüfung der Beschreibung an.

Um die XML-Beschreibung schon offline und komfortabel am heimischen PC zu prüfen, geht man folgendermaßen vor:

Zuerst die Vorlagenbeschreibung als XML-Datei lokal speichern. Im selben Verzeichnis wie die Vorlagenbeschreibung auch das XML-Schema speichern.

  1. Mit Eclipse (IDE) und Web Standard Tools (WST): Dokument im Editor öffnen. XML-Schema in das Wurzelelement eintragen: <TemplateUsage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="Revvar-VM.xsd" .... Dann Rechtsklick/Validieren (vgl. Screenshot). Eventuelle Fehler erscheinen im Probleme-Tab und werden beim Anklicken markiert.
  2. Mit jEdit und XML-Plugin: Dokument im Editor öffnen. XML-Schema in das Wurzelelement eintragen (s.o.). Beim Laden und Speichern validiert jEdit automatisch; die Ergebnisse erscheinen im Fehlerfenster (unter Plugins/Error List/Error List). Beim Klicken auf einen Fehler wird die dazugehörige Stelle im Dokument markiert, vgl. Screenshot.
  3. Online hier: Schema-Datei und XML-Datei auswählen und auf Validate klicken. Auf der folgenden Seite kann das Ergebnis unter Click here abgerufen werden.

Ressourcen

Es sind drei Seiten vorhanden, die zusammen als Helferlein genutzt werden:

  • MediaWiki:Gadget-Vorlagenmeister.js
    • Konfiguriert als Gadget.
    • Stellt lediglich fest, ob auf der momentanen Seite der Einsatz sinnvoll wäre.
    • Kurz und effizient gehalten.
    • Durch Auswertung künftiger Konfigurationsbedingungen erweiterbar.
    • Ansonsten nur selten zu verändern.
    • Kann auch in beliebigen anderen Projekten als Gadget konfiguriert oder von Benutzern eingebunden werden.
  • MediaWiki:Gadget-Vorlagenmeister/core.js
    • Eigentliches Arbeitsskript.
    • Wird erst nachgeladen, wenn der Einsatz sinnvoll wäre (umfangreich; Vermeidung überflüssigen Ladens).
    • Kann auch ohne Gadgets-Infrastruktur im stand-alone-Modus eingebunden werden.
    • Voraussichtlich häufiger Anpassungen erforderlich; die dann von zentraler Stelle abgerufen werden und auch für andere Projekte verfügbar sind.
  • MediaWiki:Gadget-Vorlagenmeister.css
    • Zentrale CSS-Deklarationen für sämtliche Projekte.
  • Bei den beiden letztgenannten gibt es nur zwei Orte für eine gültige Kopie:
    1. de.wikipedia.org – geteste Produktivversion
    2. de.wikipedia.beta.wmflabs.org – Erprobungs- und Entwicklungsversion, nicht für den produktiven Einsatz

Benutzer- oder Projektkonfigurationen werden in folgendem JavaScript-Objekt verwaltet:

  • mw.libs.vorlagenmeister

Einsatz in anderen Projekten

Um den Vorlagenmeister in einem anderen MediaWiki-Projekt als Gadget zu benutzen, ist nur

  1. die Seite MediaWiki:Gadget-Vorlagenmeister.js zu kopieren und nach Belieben zu modifizieren
  2. in der MediaWiki:Gadgets-definition zu spezifizieren:
    • Vorlagenmeister[ResourceLoader|dependencies=jquery.client]|Vorlagenmeister.js
  3. ein geeigneter Eintrag MediaWiki:Gadget-Vorlagenmeister zu schreiben.

Die Aktualisierung der eigentlichen Programmierung erfolgt regelmäßig vom zentralen Original.

Usage in other wiki projects

If you want to use „Vorlagenmeister“ in another wiki by mw:Extension:Gadgets, make the following steps:

  1. Copy contents of MediaWiki:Gadget-Vorlagenmeister.js into your project.
    • You may use a different name there, say, exchange “Vorlagenmeister” by “TemplateMaster”.
    • Modify that JS, if you like to predefine any project wide local configuration.
  2. In your MediaWiki:Gadgets-definition it is expected to specify then:
    • TemplateMaster[ResourceLoader|dependencies=jquery.client]|TemplateMaster.js
  3. Write some descriptive words in your MediaWiki:Gadget-TemplateMaster page.

That is only the head section, still loading most recent main code from dewiki.

The GUI is multi-lingual, see next section.

Internationalisierung (I18N)

Abhängig von der Sprache des momentanen Benutzers wird die Bedienoberfläche in einer der folgenden Sprachen dargestellt: Englisch, Deutsch, Ungarisch.

Depending on the current user language the interface is presented in one of the following languages: English, German, Hungarian. More translations may be added.

Entwickler

  • Benutzer:Revvar – 2007 bis 18. Juli 2013 – Hauptautor
  • Benutzer:PerfektesChaos – Sommer 2014 komplette JS-syntaktische Überarbeitung; Anpassung an veränderte MediaWiki-Funktionen sowie zeitgenössische Browser

Anmerkungen

  1. ↑ und mit TemplateWizard sogar noch ein weiteres für die Werkzeugleiste 2010.
Abgerufen von „https://de.wikiup.org/index.php?title=Wikiup:Technik/Skin/Gadgets/Vorlagenmeister&oldid=213472382“