Vorlage:Transclude-Doku/doc: Unterschied zwischen den Versionen
Thomas (Diskussion | Beiträge) Keine Bearbeitungszusammenfassung |
Thomas (Diskussion | Beiträge) Keine Bearbeitungszusammenfassung |
||
| (Eine dazwischenliegende Version desselben Benutzers wird nicht angezeigt) | |||
| Zeile 1: | Zeile 1: | ||
Dieses [[Hilfe:MediaWiki Transcludes|Transclude]] wird von Transcludes verwendet, um ihre Dokumentation von der Implementierung getrennt zu halten. Dies ist sinnvoll, da Transcludes meist erheblich komplizierter sind als "normale" Seiten im MediaWiki. | |||
Die Abspaltung von Implementierung und Dokumentation hat auch zur Folge, dass das empfindliche Transclude gesperrt und damit vor Bearbeitung geschützt werden kann, die Doku aber dennoch bearbeitbar bleibt. | |||
==Grundlagen zur Nutzung== | ==Grundlagen zur Nutzung== | ||
Ein Transclude <tt>A</tt> kann dieses Transclude wie folgt benutzen: | Ein Transclude <tt>A</tt> kann dieses Transclude wie folgt benutzen: | ||
''$Implementierungstext''<nowiki><noinclude>{{Transclude-Doku}} | ''$Implementierungstext''<nowiki><noinclude>{{Transclude-Doku}}</noinclude></nowiki> | ||
Meist will man dabei noch den ''$Implementierungstext'' in <tt><nowiki> | Meist will man dabei noch den ''$Implementierungstext'' in <tt><nowiki><includeonly>...</includeonly></nowiki></tt> einbetten (mehr dazu weiter unten). | ||
Auf der Seite <tt>Vorlage:A</tt> des Transclude <tt>A</tt> wird dann von diesem Transclude ein Kasten eingeblendet, in dem der Inhalt der Seite <tt>Vorlage:A/doc</tt> eingebunden wird. Auf diese Weise wird die Dokumentation dennoch nah an der Implementierung dargestellt. | Auf der Seite <tt>Vorlage:A</tt> des Transclude <tt>A</tt> wird dann von diesem Transclude ein Kasten eingeblendet, in dem der Inhalt der Seite <tt>Vorlage:A/doc</tt> eingebunden wird. Auf diese Weise wird die Dokumentation dennoch nah an der Implementierung dargestellt. | ||
== | ==best practises== | ||
Häufig stellen Transcludes Banner dar, die Informationen enthalten, die natürlich nicht für das Transclude selbst gelten (wenn <tt>Vorlage:A</tt> einen "momentan in Arbeit" Banner erzeugt, heisst das noch lange nicht, dass <tt>Vorlage:A</tt> selbst in Arbeit ist). Manchmal ist die Darstellung eines Transcludes auf seiner eigenen Seite auch einfach verwirrend. In diesen Fällen wird man wie oben angedeutet den eigentlichen Implementierungsteil des Transcludes in <tt><nowiki> | Häufig stellen Transcludes Banner dar, die Informationen enthalten, die natürlich nicht für das Transclude selbst gelten (wenn <tt>Vorlage:A</tt> einen "momentan in Arbeit" Banner erzeugt, heisst das noch lange nicht, dass <tt>Vorlage:A</tt> selbst in Arbeit ist). Manchmal ist die Darstellung eines Transcludes auf seiner eigenen Seite auch einfach verwirrend. In diesen Fällen wird man wie oben angedeutet den eigentlichen Implementierungsteil des Transcludes in <tt><nowiki><includeonly>...</includeonly></nowiki></tt> einbetten (siehe [[Hilfe:MediaWiki Transcludes]] für dieses Feature). | ||
Von einem Transclude gelangt man über den Speziallink "Links auf diese Seite" (links im Navigationskasten) zu einer Liste aller einbettenden Seiten (diese tragen dort die Info "Vorlageneinbindung", um sie von tatsächlich verlinkenden Seiten zu unterscheiden). Mit einem weiteren Klick sieht man dan also, wie das Transclude beispielhaft genutzt werden könnte. Geschickter ist es allerdings, für diesen Zweck eine Unterseite anzulegen, also etwa <tt>Vorlage:A/Demo</tt>. Gegebenfalls ist auch eine Seite wie <tt>Vorlage:A/Testcases</tt> sinnvoll (die Wikipedia nutzt dies gern). Auch eine eigene Sandbox <tt>Vorlage:A/Sandbox</tt> kann sinnvoll sein. In all diesen Fällen sollte auf diese Seiten auf der Dokumentationsseite <tt>Vorlage:A/doc</tt> hingewiesen werden. | Von einem Transclude gelangt man über den Speziallink "Links auf diese Seite" (links im Navigationskasten) zu einer Liste aller einbettenden Seiten (diese tragen dort die Info "Vorlageneinbindung", um sie von tatsächlich verlinkenden Seiten zu unterscheiden). Mit einem weiteren Klick sieht man dan also, wie das Transclude beispielhaft genutzt werden könnte. Geschickter ist es allerdings, für diesen Zweck eine Unterseite anzulegen, also etwa <tt>Vorlage:A/Demo</tt>. Gegebenfalls ist auch eine Seite wie <tt>Vorlage:A/Testcases</tt> sinnvoll (die Wikipedia nutzt dies gern). Auch eine eigene Sandbox <tt>Vorlage:A/Sandbox</tt> kann sinnvoll sein. In all diesen Fällen sollte auf diese Seiten auf der Dokumentationsseite <tt>Vorlage:A/doc</tt> hingewiesen werden. | ||
==Warnungen (caveats)== | |||
In einem Beispielcode kommt es gelegentlich vor, dass man <tt><nowiki><nowiki></nowiki></tt> und <tt><nowiki><noinclude></nowiki></tt> benutzen möchte. Dies kann dann beim Transkludieren zu unerwünschten Effekten führen (siehe auch [https://bugzilla.wikimedia.org/show_bug.cgi?id=9584 diesen Bug]). Man kann dies umgehen, indem man für die spitzen Klammern innerhalb des <tt><nowiki><nowiki></nowiki></tt> HTML Entitäten (also <tt>&lt;</tt> und <tt>&gt;</tt>) benutzt. Die Dokumentationsseite sollte nach dem Bearbeiten stets mit der Transclude-Seite, wo die Doku transkludiert wird, verglichen werden! | |||
==sonstiges== | ==sonstiges== | ||
''Dieses Transclude benötigt sich selbst nicht, da sein Inhalt ja bereits genau das Gewünschte leistet.'' | ''Dieses Transclude benötigt sich selbst nicht, da sein Inhalt ja bereits genau das Gewünschte leistet.'' | ||
Aktuelle Version vom 28. Juli 2008, 17:40 Uhr
Dieses Transclude wird von Transcludes verwendet, um ihre Dokumentation von der Implementierung getrennt zu halten. Dies ist sinnvoll, da Transcludes meist erheblich komplizierter sind als "normale" Seiten im MediaWiki.
Die Abspaltung von Implementierung und Dokumentation hat auch zur Folge, dass das empfindliche Transclude gesperrt und damit vor Bearbeitung geschützt werden kann, die Doku aber dennoch bearbeitbar bleibt.
Grundlagen zur Nutzung[Quelltext bearbeiten]
Ein Transclude A kann dieses Transclude wie folgt benutzen:
$Implementierungstext<noinclude>{{Transclude-Doku}}</noinclude>
Meist will man dabei noch den $Implementierungstext in <includeonly>...</includeonly> einbetten (mehr dazu weiter unten).
Auf der Seite Vorlage:A des Transclude A wird dann von diesem Transclude ein Kasten eingeblendet, in dem der Inhalt der Seite Vorlage:A/doc eingebunden wird. Auf diese Weise wird die Dokumentation dennoch nah an der Implementierung dargestellt.
best practises[Quelltext bearbeiten]
Häufig stellen Transcludes Banner dar, die Informationen enthalten, die natürlich nicht für das Transclude selbst gelten (wenn Vorlage:A einen "momentan in Arbeit" Banner erzeugt, heisst das noch lange nicht, dass Vorlage:A selbst in Arbeit ist). Manchmal ist die Darstellung eines Transcludes auf seiner eigenen Seite auch einfach verwirrend. In diesen Fällen wird man wie oben angedeutet den eigentlichen Implementierungsteil des Transcludes in <includeonly>...</includeonly> einbetten (siehe Hilfe:MediaWiki Transcludes für dieses Feature).
Von einem Transclude gelangt man über den Speziallink "Links auf diese Seite" (links im Navigationskasten) zu einer Liste aller einbettenden Seiten (diese tragen dort die Info "Vorlageneinbindung", um sie von tatsächlich verlinkenden Seiten zu unterscheiden). Mit einem weiteren Klick sieht man dan also, wie das Transclude beispielhaft genutzt werden könnte. Geschickter ist es allerdings, für diesen Zweck eine Unterseite anzulegen, also etwa Vorlage:A/Demo. Gegebenfalls ist auch eine Seite wie Vorlage:A/Testcases sinnvoll (die Wikipedia nutzt dies gern). Auch eine eigene Sandbox Vorlage:A/Sandbox kann sinnvoll sein. In all diesen Fällen sollte auf diese Seiten auf der Dokumentationsseite Vorlage:A/doc hingewiesen werden.
Warnungen (caveats)[Quelltext bearbeiten]
In einem Beispielcode kommt es gelegentlich vor, dass man <nowiki> und <noinclude> benutzen möchte. Dies kann dann beim Transkludieren zu unerwünschten Effekten führen (siehe auch diesen Bug). Man kann dies umgehen, indem man für die spitzen Klammern innerhalb des <nowiki> HTML Entitäten (also < und >) benutzt. Die Dokumentationsseite sollte nach dem Bearbeiten stets mit der Transclude-Seite, wo die Doku transkludiert wird, verglichen werden!
sonstiges[Quelltext bearbeiten]
Dieses Transclude benötigt sich selbst nicht, da sein Inhalt ja bereits genau das Gewünschte leistet.