De:PHx
From MODx Wiki
| Dieser Artikel ist eine Übersetzung aus dem englischen Wiki.
Vielleicht gibt es noch Übersetzungsfehler oder andere Ungereimtheiten. Wenn du gut Englisch versteht vergleiche doch mal die beiden Artikel. |
| Dieser Artikel kann noch eine Rechtschreibprüfung vertragen. Wenn du gut Deutsch kannst, schau mal drüber. |
Contents |
Einleitung
PHx (Platzhalter Xtended) geben dir die Möglichkeit, die Ausgabe zu beeinflussen, wenn du Platzhalter, Templatevariablen und Einstellungs-Tags benutzt. Der rekursive Parser erlaubt auch verschachtelte Tags. Eigene Modifikatoren können erstellt werden, indem du "Mini-Snippets" im MODx Resource-Manager anlegst.
Auf dieser Beispiel-Seite kannst du PHx in Aktion sehen.
PHx bekommen
Lade dir die aktuellste Version von PHx aus dem MODx-Repository. Die hier beschriebene Version ist 2.0.1
Installation
Frische Installation
- Lade das Archiv runter und entpacke es.
- Erstelle einen Ordner namens "phx" in deinem [MODx Directory]/assets/plugins Ordner.
- Lade die Dateien per FTP hoch oder kopiere sie per SSH in [MODx Directory]/assets/plugins/phx
- Erstelle ein neues Plugin namens "PHx" im Manager und kopiere den Inhalt von phx.plugin.txt in das Code-Feld.
- Aktiviere "OnParseDocument" im Tab "Systemereignisse".
Update
- Lade das Archiv runter und entpacke es.
- Mach eine Sicherheitskopie von den Dokumenten in [MODx Directory]/assets/snippets/phx und lösche sie.
- Erstelle einen Ordner namens "phx" in deinem [MODx Directory]/assets/plugins Ordner.
- Lade die Dateien per FTP hoch oder kopiere sie per SSH in [MODx Directory]/assets/plugins/phx
- Ersetze den Inhalt vom "PHx"-Plugin im Manager mit den Inhalt von phx.plugin.txt.
- Prüfe ob "OnParseDocument" im Tab "Systemereignisse" aktiviert ist.
Konfiguration
Gib im Tab "Konfiguration" -> Plugin-Konfiguration folgendes ein:
&phxdebug=Log events;int;0 &phxmaxpass=Max. Passes;int;50
Erfahrene Benutzer
Du kannst einige Standardeinstellungen von PHx ändern:
- Ereignisse protokollieren
- 0 = Deaktiviert
- 1 = Protokolliere PHx-Ereignisse
- Wenn aktiviert, wird PHx ein detailliertes Verarbeitungsprotokoll im MODx-Systemereignis-Log (Manager->Berichte->Systemereignisse) anlegen
- Max. Durchläufe
- Gib eine Zahl für die max. Tiefe an, bis zu der verschachtelte Tags verarbeitet werden sollen.. Ich empfehle den Wert auf 50 zu belassen.
Beschreibung
PHx (Platzhalter Xtended) erweitert Platzhalter, Template-Variablen und Einstellungs-Tags - das gibt dir die Möglichkeit, die Darstellung des Endergebnisses auf einfache Weise zu beeinflussen. Wenn aktiviert, klemmt es sich in den MODx-Parser, erweitert diesen mit Modfikatoren und Bedingungen und als Bonus macht es ihn wirklich rekursiv. PHx macht außerdem die wenig-Parameter-Snippets überflüssig, die nur dazu benutzt werden, einen Wert für die Ausgabe zu formatieren.
Spitze für Templates!
Einen Wert zu modifizieren ist so einfach wie :modifikator hinzufügen.
Unterstützte Tags
PHx kann folgende MODx-Tags erweitern:
[+platzhalter+] [*variablen*] [(einstellungen)]
Snippets, die PHx unterstützen
- Ditto (as of 1.1 Beta 2)
- Jot
- MaxiGallery
Du kannst PHx außerdem in Chunks von anderen Snippets benutzen, die nicht oben aufgelistet sind - vielleicht musst du sie davor aber geringfügig anpassen (schau dir die Tipps & Tricks an).
Benutzung
Ein normaler Platzhalter wie [+platzhalter+] kann leicht zu einem PHx-Platzhalter erweitert werden: [+platzhalter:modifikator+]. Dasselbe gilt für Template-Variablen wie:
[*erstelltvon*]
Einige Modifikatoren akzeptieren auch Argumente wie
[*erstelltvon:date=`%a %B %d, %Y um %H:%M`*]
Du kannst auch mehrere Modifikatoren hintereinander anwenden. Diese werden der Reihe nach von links nach rechts verarbeitet.
irgendwas:esc:nl2br:strip
Erweiterte Benutzung
Es gibt einen Dummy-Platzhalter namens 'phx' mit dem du eine Sequenz ohne eine wirkliche Variable starten kannst.
[+phx:if=`[+das+]`:is=`[+jenes+]`:then=`mache irgendwas`:else=`mache sonstwas`+]
Mit einigen Modifikatoren wird der Dummy automatisch einen Wert als Standard setzen. Beim "userinfo" Modifikator wird z.B. der Name des aktuellen Benutzers eingesetzt.
[+phx:userinfo=`benutzername`+]
Bekannte Probleme
Es scheint logisch, aber ich erwähne es als ein Problem, weil es einfach zu beachten ist. Versuche folgende Zeichenkombinationen in deinem Template zu vermeiden, wenn sie nicht als MODx-Tags gedacht sind:
[+ [* [( +] *] )]
Sie könnten unter Umständen den Parser und MODx verwirren. Normalerweise sollte das zwar kein Problem sein. Wenn du aber Javascript in deinem Template verwendest sieht das ganze so aus:
array[zaehler++]
Das könnte wegen dem +] aber ein komisches Verhalten hervorrufen.
Merk dir einfach, dass du deine Website nicht mit einer kaputten PHx-Syntax beschädigen kannst - im schlimmsten Fall sieht das Layout aus als würdest du eine XHTML-Website in Netscape 4 angucken.
Modifikatoren
String (Zeichenketten)
lcase
Gibt den aktuellen Wert mit allen alphabetischen Zeichen in Kleinschreibung zurück.
- Beispiel:
[+string:lcase+]
- Eingabe:
Das ist ein String
- Rückgabe:
das ist ein string
ucase
Gibt den Wert mit allen alphabetischen Zeichen in Großschreibung zurück.
- Beispiel:
[+string:ucase+]
- Eingabe:
Ich hab schlechte Laune
- Rückgabe:
ICH HAB SCHLECHTE LAUNE
ucfirst
Wandelt das erste Zeichen des übergebenen Werts in Großbuchstaben um-
- Beispiel:
[+string:ucfirst+]
- Eingabe:
das ist ein satz
- Rückgabe:
Das ist ein Satz
length | len
Gibt die Länge des aktuellen Werts zurück
- Beispiel:
[+string:len+]
- Eingabe:
Lorem Ipsum dolor sit amet
- Rückgabe:
26
Notags
Löscht alle HTML-Tags aus dem aktuellen Wert.
- Beispiel:
[+string:Notags+]
- Eingabe:
das <b>ist</b> ein <i>string</i>
- Rückgabe:
das ist ein string
esc
Escapet HTML-Zeichen und eckige Klammern
htmlent
Wandelt HTML-Zeichen im Wert in die entsprechenden Entitäten um.
nl2br
Wandelt Zeilenumbrüche im Wert (\n) in HTML-Breaks um (<br/>)
- Beispiel:
[+string:nl2br+]
- Eingabe:
- das ist
- ein kleiner
- Mehrzeiler
- Rückgabe:
das ist <br />ein kleiner <br /> Mehrzeiler
strip
Löscht Zeilenumbrüche (\n), Tabs (\t) und mehrfache Leerzeichen-
- Beispiel:
[+string:strip+]
- Eingabe:
- das ist
- ziemlich
- chaotisch
- formatiert
- Rückgabe:
das ist ziemlich chaotisch formatiert
Anderes
- reverse
- Gibt den aktuellen Wert rückwärts aus.
- wordwrap(=`laenge`)
- laenge - zeichen
- Unterbricht Wörter im aktuellen Wert, die mehr als die angegebene Länge an Zeichen haben, mit einem Leerzeichen.
- Standard: 70 Zeichen.
- limit(=`laenge`)
- Gibt die ersten X Zeichen vom Wert aus.
- Standard: 100 Zeichen.
Spezielles
date(=`datumsformat`)
- Formatiert ein Datum wie mit PHPs strftime-Funktion.
- Wandelt UNIX-Timestamps in das angegebene Format um.
md5
- Erstellt einen MD5-Hash vom aktuellen Wert.
userinfo=`feld`
- feld: ähnlich der Spaltennamen in der Datenbank. Wie: username, useremail
Gibt das angegebene Feld zur übergegeben Benutzer-ID zurück.
math=`berechnung`
- Macht einfache Rechnungen mit - * + /.
- Das "?" wird mit dem aktuellen Wert ersetzt.
- Beispielrechnung: ?+1+(2+3)+4/5*6
ifempty=`anderer wert`
- Gibt "anderer wert" aus wenn der übergebene Wert leer ist.
select=`optionen`
Gibt den aktuellen Wert formatiert nach den angegeben Optionen aus
- Optionen wie: wert1=ausgabe1&wert2=ausgabe2
Beispiel:
- Eingabe: 1
[+placeholder:select=`0=AUS&1=AN&2=UNBEKANNT`+]
- Rückgabe: AN
Bedingungen
is
- gleichbedeutend: eq
ist gleich (==)
ne
- gleichbedeutend: isnot, isnt
ist ungleich (!=)
eg
- gleichbedeutend: isgt
ist gleich oder größer (>=)
el
- gleichbedeutend: islt
ist gleich oder kleiner (<=)
gt
ist größer (>)
lt
ist kleiner (<)
mo=`Webgruppen`
- gleichbedeutend: isinrole, ir, memberof
Nimmt eine Liste von Webgruppen - durch Komma getrennt - und gibt TRUE oder FALSE zurück, je nachdem ob der übergebene Benutzer in der Gruppe ist oder nicht (ersetzt den "inrole" Modifikator, der zusammen mit einer Bedingung benutzt werden musste)
- Beispiel:
[+phx:mo=`neueBenutzer`:then=`Ich bin ein neuer Benutzer`:else=`Ich bin entweder schon ein älterer Benutzer oder gar keiner`+]
if =`wert`
Nimmt einen neuen Wert. Normalerweise benutzt vor :or oder :and
or
Letzter ODER nächster Befehl
and
Letzter und NÄCHSTER Befehl
then =`template`
template : dieses Template wird angezeigt, wenn die Bedingung wahr ist Template kann ein { {chunk} }, [ [ snippet] ] oder einfach HTML sein.
else =`template
template : dieses Template wird angezeigt, wenn die Bedingung falsch ist. Template kann ein { {chunk} }, [ [ snippet] ] oder einfach HTML sein.
show
Ähnlich then mit dem Unterschied, dass es den Originalwert ausgibt und nicht ein Template, wenn die Bedingung wahr ist.
[+meinplatzhalter:len:gt=`3`:show+]
- Wenn "meinplatzhalter" länger als 3 Zeichen ist, wird er angezeigt.
Noch mehr Beispiele
Beispiel 1
meinplatzhalter ist definiert als meinenwert
- [+meinplatzhalter:is=`meinenwert`:then=`Richtig`:else=`Falsch`+]
- Wird "Richtig" ausgeben, weil "meinplatzhalter" "meinenwert" hat.
- [+meinplatzhalter:isnot=`meinenwert`:then=`Richtig`:else=`Falsch`+]
- [+meinplatzhalter:is=`andererwert`:then=`Richtig`:else=`Falsch`+]
- Wird in beiden Fällen Falsch ausgeben.
Beispiel 2
- meinplatzhalter ist definiert als 2
- irgendeinplatzhalter ist definiert als 3
- andererplatzhalter ist definiert als 1
Wird den Inhalt vom Chunk ChunkGut anzeigen.
- [+meinplatzhalter:gt=`1`:then=`Ja`:else=`Nein`+]
- [+meinplatzhalter:lt=`3`:and:gt=`1`:then=`Ja`:else=`Nein`+]
- [+meinplatzhalter:lt=`[+irgendeinplatzhalter+]`:then=`Ja`:else=`Nein`+]
- [+meinplatzhalter:islt=`2`:then=`Ja`:else=`Nein`+]
- [+meinplatzhalter:isnot=`2`:or:lt=`3`:then=`Ja`:else=`Nein`+]
Werden alle Ja zurückgeben.
- [+meinplatzhalter:isnot=`2`:then=`Ja`:else=`Nein`+]
- [+meinplatzhalter:gt=`[+irgendeinplatzhalter+]`:then=`Ja`:else=`Nein`+]
- [+meinplatzhalter:lt=`2`:then=`Ja`:else=`Nein`+]
- [+meinplatzhalter:gt=`2`:then=`Ja`:else=`Nein`+]
- [+meinplatzhalter:lt=`1`:then=`Ja`:else=`Nein`+]
Werden alle Nein zurückgeben.
Eigene Modifikatoren
Ein Modifikator ist praktisch nur ein Ersatz für ein einfaches Snippet, um einen übergebenen Wert auf irgendeine Weise zu verarbeiten. Du kannst ganz einfach eigene Modifikatoren/Mini-Snippets anlegen, indem du Snippets im MODx-Resource-Manager hinzufügst.
Weil Modifikatoren keinen komplizierten Code brauchen, gibt es nur zwei Parameter, die der PHx-Parser übergeben wird:
- $output
- der aktuelle Wert der Variable die modfiziert werden soll
- $options
- (optional) ein String mit zusätzlichen Parametern die ein Modifikator evtl. benötigt.
Um das ganze ein bisschen zu vertiefen, hier noch ein paar kurze Beispiele. Wir gehen davon aus, dass meinplatzhalter als "test" definiert ist:
[+meinplatzhalter:meinmodifikator+]
- $output ist jetzt "test"
- $options enthält Nichts weil keine angegeben wurden.
[+meinplatzhalter:meinmodifikator=`meine optionen`+]
- $output ist immer noch "test"
- $options enthält jetzt "meine optionen".
Andere Variablen (für erfahrene Benutzer)
- $input enthält den ersten Wert, der übergeben wurde.
- $condition ist ein Array, der die Bedingungen enthält, aus denen ein Ausdruck aufgebaut ist (0, 1, || und &&)
Eigene Modifikatoren anlegen
Beispiel: Ich liebe MODx
Mit dem, was wir bisher gelernt haben, werden wir jetzt einen eigenen Modifikator anlegen. Wir machen es mal ganz einfach: Alles was der Modifikator können soll, ist "weil ich MODx liebe" an einen übergeben Wert anzuhängen.
- Melde dich am Manager an
- Gehe zu Ressourcen -> Ressourcen verwalten -> Snippets
- Klick auf "Neues Snippet"
- Als Snippet-Namen geben wir "'phx:herzchen'" ein
- damit PHx weiß, dass ein Snippet als Modifikator angelegt wurde, müssen diese mit "phx:" beginnen. Der nachfolgende String (keine Leerzeichen) ist der Name des Modifikators. In unserem Fall müssen wir also :herzchen an den Platzhalter anhängen [+meinplatzhalter:herzchen+].
- Jetzt legen wir den Code für den Modifikator im Snippet an. Folgendes sollte funktionieren:
- <?php
- $neuerWert = $output. " weil ich MODx liebe";
- return $neuerWert;
- ?>
- Klick Speichern und schon sind wir fertig.
Beispiel: I liebe MODx noch mehr
Ähnlich wie in Beispiel 1 werden wir jetzt einen Modifikator anlegen, der das selbe macht, AUSSER wenn wir Optionen angeben, dann sollen diese hinzugefügt werden.
- Melde dich am Manager an
- Gehe zu Ressourcen -> Ressourcen verwalten -> Snippets
- Klick auf "Neues Snippet"
- Als Snippet-Namen geben wir "'phx:verlobt'" ein
- damit PHx weiß, dass ein Snippet als Modifikator angelegt wurde, müssen diese mit "phx:" beginnen. Der nachfolgende String (keine Leerzeichen) ist der Name des Modifikators. In unserem Fall müssen wir also :herzchen an den Platzhalter anhängen [+meinplatzhalter:herzchen+].
- Jetzt legen wir den Code für den Modifikator im Snippet an. Folgendes sollte funktionieren:
- <?php
- $standardWert = " weil ich MODx liebe";
- $neuerWert = $output . $options;
- } else {
- $newvalue = $neuerWert . $standardValue;
- }
- return $neuerWert;
- ?>
- Klick Speichern und schon sind wir fertig.
Gespendete
In De:PHx/GespendeteModifikatoren findest du eine Liste von Modifikatoren, die andere Benutzer programmiert haben und die du verwenden kannst.
Tipps und Tricks
PHx in Nicht-PHx-Snippet-Templates verwenden
Die meisten Snippets verarbeiten ihre Templates intern, bevor sie das Ergebnis an MODx weitergeben. Solange in der Snippet-Beschreibung nicht steht, dass es PHx verwendet, ist es nicht möglich die Modifikatoren direkt zu verwenden. Du kannst PHx trotzdem benutzen, indem du einen speziellen Modifikator namens phx:input einsetzt.
Das hier wird nicht mit einem Nicht-PHx-Snippet funktionieren:
[+meinplatzhalter:modifikator1:modifikator2+]
Versuchs mal so:
[+phx:input=`[+meinplatzhalter+]`:modifikator1:modifikator2+]
Das wird auch mit einem Nicht-PHx-Snippet funktionieren. Eventuell gibt es einige Einschränkungen - das hängt von der Programmlogik des Snippets ab.
Technische Dokumentation
Dieser Teil der Dokumentation ist nicht für normale MODx-Benutzer gedacht sondern soll einmal kurz aufzeigen wir PHx funktioniert.
PHx benutzt das OnParseDocument Ereignis (MODx API), um die Ausgabe zu verarbeiten. OnParseDocument wird vor allen normalen MODx-Elementen aufgerufen - PHx arbeitet also mit der Rohfassung des Templates und der Ausgabe und durchläuft dabei die folgenden Etappen:
- wir starten nur, wenn wir noch nicht die maximale Anzahl an Durchläufen erreicht haben
- ein Hash wird aus dem Inhalt des Dokuments erstellt, um zu prüfen ob sich im späteren Verlauf etwas verändert
- Das Dokument wird mit einigen Filtern vorbereitet, z.B. um eckige Klammern zu escapen, die nicht zu MODx gehören
- Jetzt geht es in den Haupt-Parser
- ein Hash wird aus dem Inhalt des Dokuments erstellt, um zu prüfen ob sich im späteren Verlauf etwas verändert
- Chunks werden zusammengeführt mergeChunkContent (MODx API)
- Snippets werden mit einem hochkomplexen regulären Ausdruck erkannt, der auch verschachtelte Tags verarbeiten kann
- Snippet-Aufrufe, die nicht verschachtelt sind, werden verarbeitet
- Alle zutreffenden Aufrufe werden auf (nicht-)gecachte Ausgabe geprüft, verarbeitet und an evalSnippets (MODx API) übergeben
- Die Ausgabe wird in das Dokument eingesetzt
- Snippets werden mit einem hochkomplexen regulären Ausdruck erkannt, der auch verschachtelte Tags verarbeiten kann
- Dokument/Template-Variablen werden mit mergeDocumentContent (MODx API) geholt
- Einstellungs-Variablen werden mit mergeSettingsContent (MODx API) geholt
- Die Ausgabe von Platzhaltern wird in folgender Reihenfolge geholt: PHx, MODx.
- Wenn der gewünschte Platzhalter nicht belegt ist, wird er für den aktuellen Durchlauf ignoriert (Original wird wieder eingesetzt)
- Jeder erkannte Tag, die mit Modifikatoren, werden an den Filter übergeben und entsprechend ersetzt
- Das Endergebnis aller Tags wird jetzt in das Dokument eingesetzt
- ein Hash wird aus dem Inhalt des Dokuments erstellt, um zu prüfen ob sich im späteren Verlauf etwas verändert
- Wenn wir noch nicht die maximale Anzahl an Durchläufen erreicht haben und sich der Hash verändert hat, wird die aktuelle Ebene wiederholt (Durchläufe+1)
- Die vorher escapten Klammern werden wieder zurückgewandelt
- Die Tags, die immer noch unersetzt vorhanden (also gar nicht aufgelöst werden konnten) sind, werden von der Ausgabe entfernt
- ein Hash wird aus dem Inhalt des Dokuments erstellt, um zu prüfen ob sich etwas verändert hat
- Wenn sich etwas verändert hat wird die aktuelle Ebene komplett wiederholt
- Falls aktiviert die Parser-Schritte in das Protokoll schreiben
- Die neue Ausgabe an MODx zurückgeben
Nachdem PHx alles abgearbeitet hat kann man zu 99% sicher sein, dass für MODx nicht ein einziger Tag zum verarbeiten übrig ist. Man könnte also sagen, dass PHx die Kernfunktionalität von MODx ersetzt (mit einer noch flexibleren Technik, die sich um das Zusammenführen kümmert). Trotzdem werden die einzelnen Elemente immer noch von den entsprechenden MODx-Funktionen verarbeitet.
