Die Personyze-Vorlagensprache (Referenz)

Personyze-Aktionen — Banner, Pop-ups, Empfehlungs-Widgets, E-Mails und mehr — werden normalerweise visuell im Kampagneneditor gestaltet. Hinter jedem visuellen Editor steht aber HTML-Quelltext mit den Template-Direktiven von Personyze, und Sie können dieses HTML direkt bearbeiten, wenn Sie feinere Kontrolle brauchen. Dieser Artikel ist die vollständige Referenz der Vorlagensprache.

Die Sprache ist einfaches HTML und CSS, mit einigen Ergänzungen:

• Präprozessor-Direktiven, eingeschlossen in ${...} — Variablen, Bedingungen, Schleifen und Funktionen, die serverseitig ausgewertet werden, bevor das HTML an die Seite geht.
• Spezielle Klassennamen (mit dem Präfix $), die gewöhnliche Elemente zu Personyze-fähigen Widgets machen — Buttons, Pop-ups, umschaltbare Bereiche, bedingte Formulare und mehr.
• Menü-Direktiven am Ende der Vorlage, die die Steuerelemente des visuellen Editors festlegen, die jemand ohne Entwicklerkenntnisse in der Oberfläche sieht.

Präprozessor-Direktiven

Ein Dollarzeichen gefolgt von geschweiften Klammern kennzeichnet eine Präprozessor-Direktive. Der Inhalt der Klammern wird ausgewertet und durch das Ergebnis ersetzt, bevor das HTML an den Browser geht. In den Klammern können Sie eine Variable, einen Funktionsaufruf auf einer Variablen oder eine der unten beschriebenen Strukturdirektiven verwenden.

${some_variable}

Die Direktive kann Text erzeugen, der selbst wieder eine Direktive enthält — Personyze wertet in zwei Durchläufen aus:

1. Präprozessor-Durchlauf — setzt ${args->...} -Argumentvariablen in die Vorlage ein.
2. Nutzer-Durchlauf — setzt nutzerbezogene Variablen (${first_name}, ${country_code}usw.) für jeden einzelnen Besucher ein.

Variablen zur Präprozessorzeit (args)

Um eine Variable zur Präprozessorzeit anzulegen — die Art, die in der visuellen Oberfläche als bearbeitbares Feld erscheint —, deklarieren Sie sie einmal am Ende der Vorlage mit einer ${menu} -Direktive und verweisen im Vorlagenkörper an beliebiger Stelle darauf mit ${args->name}:

<p title="${args->main_text:html}">
    ${args->main_text}
</p>

${menu args->main_text name=\'Main text\'}

Jetzt zeigt die Oberfläche ein bearbeitbares Feld „Main text“. Was der Nutzer dort eintippt, wird sowohl in das <p> -Tag als auch in sein title -Attribut eingefügt (mit maskierten HTML-Sonderzeichen über die :html -Konvertierung, damit der Wert nicht aus dem Attribut ausbrechen und zusätzliche Tags einschleusen kann).

Syntax von Argumentausdrücken

Die allgemeine Form ist das Schlüsselwort args , ein Pfeil, der Variablenname und dann null oder mehr Konvertierungen mit vorangestelltem Doppelpunkt:

${args->variable_name:function1:function2(parameter)}

Variablen des Nutzerprofils

Der zweite Verarbeitungsdurchlauf setzt nutzerbezogene Werte ein. Personyze bringt diese eingebauten Profilvariablen mit:

• first_name
• last_name
• email
• industry

Sie können auch eigene Profilfelder definieren und über Formulare oder die API Werte dafür sammeln. Einmal definiert, stehen sie genauso bereit:

${first_name:default('User')}

Variablen zur Präprozessorzeit können Text erzeugen, der Nutzervariablen des zweiten Durchlaufs enthält. Für verschachtelte Standardwerte nutzen Sie verdoppelte Apostrophe:

<p>
    ${args->main_text:default(\'Dear, ${first_name:default(\'\'User\'\')}\')}
</p>

${menu args->main_text name=\'Main text\'}

Sitzungs- und Seitenvariablen

Variablen, die von der aktuellen Surfsitzung und dem Gerät des Besuchers abhängen:

Funktionen

Funktionen werden mit Doppelpunkt-Syntax auf Variablen angewendet:

${variable:func_name}
${variable:func_name(parameter)}
${variable:func_name(\'parameter\')}
${variable:func_name(\'param1\', \'param2\', \'param3\')}

Enthält ein Parameter Kommas, Apostrophe oder schließende Klammern — oder gibt es mehr als einen Parameter —, muss er in Anführungszeichen stehen. Um ein Apostroph in einer Zeichenkette in Anführungszeichen darzustellen, verdoppeln Sie es: :func_name('I''m a string').

Zeichenketten & HTML

Zahlen- & Preisformatierung

Personyze-Tabellen durchlaufen (${foreach})

Personyze-Tabellen — Ihr Produktkatalog, Ihr Artikelkatalog, berechnete Nutzerinteressen — werden durchlaufen mit ${foreach ... as alias where ... limit N} ... ${end}:

${foreach products as p where p->price_after_discount < p->price_before_discount limit 5}
    <div>
        ${p->title}
    </div>
${end}

Empfehlungs-Widgets nutzen dieses Muster, um die eigentlichen Produkt-/Inhaltskarten zu rendern. Der in der Oberfläche gewählte Empfehlungsalgorithmus bestimmt den Tabellennamen und die Filter, die in der Vorlage erscheinen. Beispiel für „Bestseller im jüngsten Zeitraum“:

${foreach sum_products as p where p->for_period=\'recently\' and p->n_goal>0 order by p->n_goal desc limit 12}
    ...
${end}

Sie können mehrere ${foreach} -Schleifen in einer Vorlage haben, auch verschachtelte. Hat eine davon den Alias main, steuert die Auswahl des Empfehlungsalgorithmus in der Oberfläche diese Schleife. Andernfalls steuert sie die erste gefundene.

Das aktuell angesehene Produkt

Wird auf der aktuellen Seite ein Produktaufruf gemeldet, greifen Sie direkt über viewing_product auf die Details des aktuell angesehenen Produkts zu — kein ${foreach} nötig:

You're interested in ${viewing_product->color} color.

Weitere automatisch verfügbare einzeilige Tabellen:

• viewing_product — das aktuell angesehene Produkt (falls auf dieser Seite ein Aufruf gemeldet wurde).
• last_viewed_product — das zuletzt angesehene Produkt in der Sitzung des Besuchers.
• last_extra_product — das zuletzt in den Warenkorb gelegte Produkt.

Bedingte Direktiven

${if} / ${else if} / ${else}

Teile der Vorlage abhängig von einer Variablen zur Präprozessorzeit, einer Profilvariablen oder einer Tabellenspalte einbinden:

${foreach products as p where p->price_after_discount < p->price_before_discount limit 5}
    <div>
        ${p->title}
    </div>
    <div>
        ${if p->price_after_discount < p->price_before_discount}
            ${p->price_after_discount}
            <strike>${p->price_before_discount}</strike>
        ${else if p->price_after_discount < 10}
            Cheaper than $10.
        ${else}
            ${p->price_after_discount}
        ${end}
    </div>
${end}

Bedingte Ausdrücke können auf args verweisen und so vom Nutzer steuerbare Filter ermöglichen:

${foreach products as p limit 5}
    ${if p->price_after_discount > args->min_price}
        <div>${p->title}</div>
    ${end}
${end}

${menu args->min_price name=\'Show products not cheaper than\', type=\'number\'}

${case}

Zwei Formen — boolesch (jedes when ist eine eigene Bedingung) und Ausdruck (jedes when vergleicht mit dem Case-Ausdruck):

${case}
    ${when known_device_type = \'phone\'}
        On phone
    ${when known_device_type = \'regular\'}
        On desktop
    ${else}
        Not known
${end}

${case known_device_type}
    ${when \'phone\'}
        On phone
    ${when \'regular\'}
        On desktop
    ${else}
        Not known
${end}

Bedingte Blöcke (in der Oberfläche umschaltbar)

Bedingte Blöcke sind HTML-Elemente, markiert mit ${block->block_name}. Die Oberfläche zeigt einen Schalter, der den Block aktiviert oder deaktiviert — nützlich für Optionen im Stil „mit Button / ohne Button“.

${block->with_button:default(0)}
<div>
    <button type="button">See more</button>
</div>

${menu block->with_button name=\'With button\'}

HTML-Struktur & by_id

Vorlagen können beliebiges HTML enthalten — auch <style> -Tags. Einige Umwandlungen werden angewendet:

id -Attribute werden entfernt — sind aber erreichbar über by_id

Hat Ihre Vorlage Elemente mit id -Attributen, werden diese Attribute vor dem Rendern entfernt (um Kollisionen mit anderem Markup auf der Seite zu vermeiden). Sie können diese Elemente aber weiterhin über ein spezielles by_id -Objekt ansprechen, verfügbar in onclick -Handlern und in einem speziellen ontplready -Attribut:

<div style="background-color:transparent; display:flex; align-items:center; gap:0.3em">
    <img id="main_icon" src="https://www.google.com/favicon.ico">
    <button type="button" onclick="by_id.display.textContent = by_id.main_icon.width">Get icon width</button>
    <div id="display"></div>
</div>

ontplready — Skript, wenn die Vorlage eingebunden wird

Jedes Element kann ein ontplready -Attribut mit JavaScript haben, das läuft, sobald die Vorlage ins Dokument eingefügt ist. Darin verweist this auf dieses Element. Nutzen Sie es, um Hilfsfunktionen an das Wurzelelement zu binden, statt den globalen Gültigkeitsbereich zu verschmutzen:

<div id="root" ontplready="this._hide_message = () => by_id.message.style.display = \'none\'">
    <div id="message">Text text text.</div>
    <button type="button" onclick="by_id.root._hide_message()">Hide</button>
</div>

Spezielle Klassennamen

Klassennamen mit dem Präfix $ machen ein Element zu einem Personyze-fähigen Widget. Die $ -Klasse wird aus dem gerenderten HTML entfernt.

Erkannte spezielle Klassen: $responsive, $btn, $flat_btn, $personyze_button_dont_show_again, $a_add_params, $hint, $icon, $popup, $switch-elem, $cform, $info_lines_scroller, $rating, $table_slider, $table_slider_pagination, $button_add_to_cart.

$responsive

Meist auf die Wurzel der Vorlage angewendet. Ermöglicht ein data-style -Attribut, das eine spezielle CSS-Funktion sel(option1, option2) unterstützt — Personyze wählt die Option, die auf dem Gerät des Besuchers weniger Überlauf verursacht.

<div class="$responsive" data-style="background-color:transparent">
    <div data-style="max-width: sel(500px, 80%)">
        ...
    </div>
</div>

Ist eine Pop-up-Vorlage $responsive , läuft aber trotzdem über, wendet Personyze zoom an, um sie zu verkleinern. Gewöhnliche style -Attribute und <style> -Tags funktionieren neben data-style.

$btn

Macht das Element zu einem Button im Personyze-Stil. Nutzen Sie data-icon="..." für ein Symbol vor dem Text oder data-icon_append="..." für danach. Symbolnamen stammen aus Font Awesome 4.

<a class="$btn" data-icon="bullhorn" href="javascript:" onclick="alert(this.dataset.message)" data-message="${args->message:html:default(Hello)}" style="text-decoration:none; padding:0.1em 0.3em">
    Show message
</a>

$personyze_button_dont_show_again

Schließen-Button, der die Aktion für die konfigurierte Zahl von Sitzungen unterdrückt. Die Attribute data-action_id und data-n_sessions verdrahten ihn:

<img src="https://counter.personyze.com/images/close-buttons/black-16x16.png"
     style="width:16px; height:16px"
     class="$personyze_button_dont_show_again"
     data-action_id="${action_id}"
     data-n_sessions="1">

Meist kombiniert mit einem ${menu} -Eintrag vom Typ type='dontshowagain' , damit das Aussehen des Schließen-Buttons in der Oberfläche bearbeitbar ist.

$a_add_params

Fügt allen <a> -Links in der Vorlage URL-Parameter hinzu. Nützlich für Ad-Tracking. Die Parameter geben Sie an in data-json-params:

<div class="$responsive $a_add_params" data-json-params="${args->url_params:html}">
    ...
</div>

${menu name=\'Frame\', icon=\'th-large\'}
    ${menu args->url_params name=\'URL additional parameters\', type=\'external_media_url_params\'}

$hint

Zeigt beim Überfahren einen Tooltip. Der Tooltip-Text stammt aus title="..."oder — für HTML-Inhalte — aus einem verschachtelten Element, markiert mit data-content="1":

<a href="https://example.com/" class="$hint" data-popup_style="background-color:gold; color:purple; padding:1em">
    <span data-content="1">
        This is <b>Example</b> site.
    </span>
    Link
</a>

$icon

Rendert ein Font-Awesome-4-Symbol. Der Symbolname steht im class-Attribut neben $icon:

<i class="$icon envelope"></i>

<i class="$icon ${args->icon_name:html:default(envelope)}" style="font-size:125%; color:crimson"></i>

${menu args->icon_name name=\'Icon\', type=\'icon\'}

$popup

Zeigt ein Pop-up, wenn der Nutzer auf ein Auslöser-Element klickt (oder darüberfährt). Das Pop-up verweist auf seinen Auslöser über id:

<div>
    <a href="javascript:" id="trigger_1">More info</a>
    <div id="popup_1" class="$popup" data-trigger_id="trigger_1" data-is_modal="1"
         data-json-trigger_transit=\'{{"template": "animator_fade"}}\'
         style="max-width:10em; border:solid 1px; border-radius:5px; background-color:lightgreen; padding:1em">
        Blah blah blah blah blah blah blah.
        <div>
            <a href="javascript:" onclick="by_id.popup_1._hide()">Close</a>
        </div>
    </div>
</div>

Attribute, die das Verhalten steuern: data-trigger_id, data-trigger_onmouseover="1", data-trigger_onfocus="1" (für Eingabefelder), data-is_modal="1", data-json-trigger_transit für Animationen (animator_fade, animator_swap_top).

$switch-elem

Ein Bereich, der zwischen alternativen Fällen umschalten kann (z. B. ein mehrstufiges Modal). Jedes Kind hat data-case="case_name"; nur eines ist gleichzeitig eingebunden:

<div id="sw" class="$switch-elem" data-case="step-a" style="position:relative; overflow:hidden">
    <div data-case="step-a">
        <p>Step A.</p>
        <button class="$btn" onclick="by_id.sw._set_case(\'step-b\', null, false, {{template: \'animator_swap_bottom\'}})">Next</button>
    </div>
    <div data-case="step-b">
        <p>Step B.</p>
        <button class="$btn" onclick="by_id.sw._set_case(\'step-a\')">Previous</button>
    </div>
</div>

JavaScript-Methoden des Umschalters: _set_case(name) (oder null , um alle auszublenden), _get_case(), _get_cases().

$cform

Ein Formular, das Daten an Personyze zurücksendet — zur Anreicherung des Besucherprofils, zur Lead-Erfassung oder für an Kampagnen gebundene Formularaktionen. Der Formularname steht im class-Attribut neben $cform:

<div class="$cform form1" ontplsubmit="personyze.push([\'Submit\', \'${action_id:html}\', this._get_value_ex(), arguments[1], arguments[2]]); return true" ontplaftersubmit="alert(\'Success\')">
    <input form="form1" name="Email" type="email" required="1" data-prop-column="email" value="${email:html}">
    <button form="form1" type="submit">Submit</button>
</div>

Formularattribute

• data-required_field_message="..." — Meldung neben einem fehlenden Pflichtfeld.
• data-invalid_value_message="..." — Meldung neben einer ungültigen Eingabe.
• ontplchange="..." — JS, das bei jeder Wertänderung läuft.
• ontplsubmit="..." — JS, das beim Absenden läuft. Muss bei Erfolg arguments[1]() aufrufen oder bei Fehlschlag arguments[2](error) . An Personyze senden mit: personyze.push(['Submit', '${action_id:html}', this._get_value_ex(), arguments[1], arguments[2]]); return true.
• ontplaftersubmit="..." — JS, das nach erfolgreichem Absenden läuft.

Attribute von Formulareingaben

Eingaben, die zum Formular gehören, müssen form="form_name" und name="..."haben. Optionale Attribute:

• required="1" — die Eingabe muss zum Absenden ausgefüllt sein.
• pattern="..." — Validierung per regulärem Ausdruck.
• data-valid_if="..." — JS-Ausdruck, der wahr/falsch liefert. Eine zurückgegebene Zeichenkette wird als Fehlermeldung angezeigt.
• data-prop-prop_name="..." — Eingabeeigenschaften, bereitgestellt über form._get_value_ex(). Die spezielle Eigenschaft column ordnet die Eingabe einem Feld des Personyze-Nutzerprofils zu.
• data-use_hidden="1" — diese Eingabe auch einschließen, wenn sie durch eine Formularfall-Bedingung ausgeblendet ist.
• data-value_if_hidden="..." — fester Wert, wenn das Feld ausgeblendet ist.

Sichtbarkeit nach Formularfall

Fassen Sie optionale Eingabegruppen in einen Container mit data-form_case="..." , um sie abhängig von anderen Formularwerten ein- oder auszublenden:

<div class="$cform form1">
    <input form="form1" name="ContactMe" type="checkbox">
    <div form="form1" data-form_case="v.ContactMe">
        Phone: <input form="form1" name="Phone" type="tel">
    </div>
    <button form="form1" type="submit">Submit</button>
</div>

JavaScript-Methoden des Formularelements

• _get_value() — liefert ein flaches Objekt aus Eingabenamen → Werten.
• _get_value_ex() — liefert Eingabenamen → Objekte mit value plus allen data-prop-* -Eigenschaften.
• _set_value(new_value) — setzt Werte aus einem Objekt.

Menüeinträge (Steuerelemente des visuellen Editors)

Die ${menu} -Direktiven am Ende der Vorlage legen fest, was der Editor in der Oberfläche zeigt. Es gibt zwei Typen:

Abschnittsdirektiven

${menu name='Section name', icon='icon-name'}

Parameter: name (Beschriftung) und optional icon (Font-Awesome-4-Name — häufige: image, envelope, user, check, times-circle, edit, font).

Eintragsdirektiven

${menu args->arg_name name=\'Argument name\', description=\'...\'}
${menu block->block_name name=\'Block name\', description=\'...\'}
${menu table_alias->column_name name=\'Column name\', description=\'...\'}

Drei Formen — zum Bearbeiten eines Argumentwerts, zum Umschalten eines bedingten Blocks oder um den Nutzer eine andere Spalte aus einer Tabelle wählen zu lassen.

Kombiniertes Beispiel

${menu name=\'Text\', icon=\'font\'}
    ${menu args->headline name=\'Headline Text\'}
    ${menu args->headline_style name=\'Headline Style\', type=\'css\'}
${menu name=\'Close Button\', icon=\'times-circle\'}
    ${menu args->close_button_style name=\'Close Button Style\', type=\'css\'}
    ${menu args->close_button name=\'Close Button HTML\', type=\'dontshowagain\'}

Der Standardeditor für ein Argument ist HTML oder reiner Text (je nachdem, ob das Argument die :html -Konvertierung hat). Nutzen Sie type='...' , um einen spezialisierten Editor zu wählen — siehe unten.

Editortypen für Felder

Die meisten Editortypen akzeptieren zusätzliche Parameter über die Schreibweise param='key=value' im Menüeintrag.

type='number'

Numerische Eingabe. Parameter: min, max, placeholder.

${menu args->n_columns name='Number of columns', type='number', param='min=2', param='max=10', param='placeholder=Columns'}

type='checkbox'

Boolescher Schalter. Der eingefügte Wert lässt sich anpassen: value_on (Standard 1) und value_off (Standard 0).

<input name="email" ${args->email_required}>
${menu args->email_required name=\'Required Field\', type=\'checkbox\', param=\'value_on=required="1"\', param=\'value_off=style="opacity:0.5"\'}

type='select'

Dropdown. Optionen als JSON-Array aus [label, value] -Paaren:

${menu args->img_position name='Image Position', type='select', param='options=[["On Top","top"],["On Bottom","bottom"],["On Right Side","right"]]'}

type='textarea'

Mehrzeiliger Text. Parameter: placeholder, autosize (1 zum Mitwachsen mit dem Inhalt), autosize_max_rows.

type='css'

Visueller CSS-Editor. Die Ausgabe ist eine style -Attributzeichenkette. Ergänzen Sie param='with_responsive=1' , um eine data-style-taugliche Ausgabe mit sel() -Funktionen für responsive Vorlagen zu erzeugen.

${menu args->close_button_style name='Close Button Style', type='css', param='with_responsive=1'}

type='color'

Farbwähler. Fügt einen CSS-Farbwert ein:

<div style="background-color: ${args->color}">
    ...
</div>

${menu args->color name=\'Background color\', type=\'color\'}

type='dontshowagain'

Spezialisierter Editor für das HTML des Schließen-Buttons. Kombiniert mit der Klasse $personyze_button_dont_show_again .

type='icon'

Symbolauswahl (Namen aus Font Awesome 4).

type='external_media_url_params'

Editor für die URL-Parameter, die angehängt werden von $a_add_params.

Fertige Beispiele auf GitHub

Personyze pflegt eine Bibliothek vollständig kommentierter Beispielvorlagen für gängige Muster. Sie liegen neben dieser Referenz unter github.com/personyze/personyze-template-language:

Verwandte Leitfäden

• Zentrale für Entwicklerressourcen — REST-API und SDK im Überblick.
• Leitfaden zur JavaScript-Aktion — für Aktionen, bei denen Sie JavaScript direkt schreiben, statt Vorlagen zu nutzen.
• Leitfaden zur Aktion „Popup & Banner“ — eine Anleitung zum visuellen Editor, die diese Referenz ergänzt.
• Inhaltsvarianten — Bedingungen auf Ebene des Zielgruppen-Targetings nutzen (statt auf Vorlagenebene).
• Dynamische CRM-Variablen in Inhalten — CRM-Daten über dieselbe ${variable} -Syntax einfügen.