Référence du langage de gabarit Personyze

Les actions Personyze — bannières, popups, widgets de recommandation, e-mails, etc. — se conçoivent normalement de façon visuelle dans l’éditeur de campagne. Mais derrière chaque éditeur visuel se trouve un code source HTML avec les directives de gabarit de Personyze, et vous pouvez modifier ce HTML directement quand vous avez besoin d’un contrôle plus fin. Cet article est la référence complète du langage de gabarit.

Le langage, c’est du HTML et du CSS ordinaires, avec quelques ajouts :

• Des directives de prétraitement entourées de ${...} — variables, conditions, boucles et fonctions évaluées côté serveur avant l’envoi du HTML à la page.
• Des noms de classe spéciaux (préfixés par $) qui transforment des éléments ordinaires en widgets Personyze — boutons, popups, zones commutables, formulaires conditionnels, etc.
• Des directives de menu en bas du gabarit, qui définissent les réglages de l’éditeur visuel que voit un non-développeur dans l’interface.

Directives de prétraitement

Un signe dollar suivi d’accolades désigne une directive de prétraitement. Le contenu des accolades est évalué et remplacé par le résultat avant l’envoi du HTML au navigateur. Entre les accolades, vous pouvez utiliser une variable, un appel de fonction sur une variable, ou n’importe laquelle des directives structurelles décrites plus bas.

${some_variable}

La directive peut produire un texte qui contient lui-même une autre directive — Personyze évalue en deux passes :

1. Passe de prétraitement — remplace les variables d’argument ${args->...} dans le gabarit.
2. Passe utilisateur — remplace les variables propres à chaque utilisateur (${first_name}, ${country_code}, etc.) pour chaque visiteur.

Variables de prétraitement (args)

Pour créer une variable de prétraitement — celle qui apparaît comme champ modifiable dans l’interface visuelle — déclarez-la une fois en bas du gabarit avec une directive ${menu} , et référencez-la n’importe où dans le corps du gabarit avec ${args->name}:

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

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

L’interface affiche alors un champ modifiable « Main text ». Ce que l’utilisateur y saisit est inséré à la fois dans la balise <p> et dans son attribut title (les caractères spéciaux HTML étant échappés via la conversion :html pour que la valeur ne puisse pas sortir de l’attribut et injecter des balises supplémentaires).

Syntaxe des expressions d’argument

La forme générale est le mot-clé args , une flèche, le nom de la variable, puis zéro, une ou plusieurs conversions préfixées par deux-points :

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

Variables du profil utilisateur

La seconde passe remplace les valeurs propres à chaque utilisateur. Personyze fournit ces variables de profil intégrées :

• first_name
• last_name
• email
• industry

Vous pouvez aussi définir des champs de profil personnalisés et en recueillir les valeurs via des formulaires ou l’API. Une fois définis, ils sont disponibles de la même façon :

${first_name:default('User')}

Les variables de prétraitement peuvent produire un texte contenant des variables utilisateur de seconde passe. Utilisez des apostrophes doublées pour les valeurs par défaut imbriquées :

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

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

Variables de session et de page

Les variables qui dépendent de la session de navigation en cours et de l’appareil du visiteur :

Fonctions

Les fonctions s’appliquent aux variables avec une syntaxe préfixée par deux-points :

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

Si un paramètre contient des virgules, des apostrophes ou des parenthèses fermantes — ou s’il y a plus d’un paramètre — il doit être entre apostrophes. Pour représenter une apostrophe dans une chaîne entre apostrophes, doublez-la : :func_name('I''m a string').

Chaînes et HTML

Formatage des nombres et des prix

Parcourir les tables Personyze (${foreach})

Les tables Personyze — votre catalogue de produits, votre catalogue d’articles, les centres d’intérêt calculés des utilisateurs — se parcourent avec ${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}

Les widgets de recommandation utilisent ce modèle pour afficher les vraies cartes de produits ou de contenus. L’algorithme de recommandation choisi dans l’interface détermine le nom de la table et les filtres qui apparaissent dans le gabarit. Exemple pour « meilleures ventes de la période récente » :

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

Vous pouvez avoir plusieurs boucles ${foreach} dans un gabarit, y compris imbriquées. Si l’une d’elles a l’alias main, le sélecteur d’algorithme de recommandation de l’interface contrôle cette boucle. Sinon, il contrôle la première trouvée.

Produit actuellement consulté

Si un événement de vue produit est signalé sur la page en cours, vous pouvez accéder directement aux détails du produit consulté via viewing_product — sans ${foreach} nécessaire :

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

Autres tables à une ligne disponibles automatiquement :

• viewing_product — le produit actuellement consulté (si un événement de vue a été signalé sur cette page).
• last_viewed_product — le produit vu le plus récemment pendant la session du visiteur.
• last_extra_product — le produit ajouté au panier le plus récemment.

Directives conditionnelles

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

Incluez des parties du gabarit selon une variable de prétraitement, une variable de profil ou une colonne de table :

${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}

Les expressions conditionnelles peuvent faire référence aux args, ce qui permet des filtres réglables par l’utilisateur :

${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}

Deux formes — booléenne (chaque when est sa propre condition) et par expression (chaque when est comparé à l’expression du case) :

${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}

Blocs conditionnels (activables dans l’interface)

Les blocs conditionnels sont des éléments HTML marqués avec ${block->block_name}. L’interface affiche un interrupteur qui active ou désactive le bloc — utile pour des options du type « avec bouton / sans bouton ».

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

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

Structure HTML et by_id

Les gabarits peuvent contenir n’importe quel HTML — y compris des balises <style> . Quelques transformations sont appliquées :

id les attributs sont supprimés — mais accessibles via by_id

Si votre gabarit contient des éléments avec des attributs id , ces attributs sont supprimés avant l’affichage (pour éviter les collisions avec le reste du balisage de la page). Mais vous pouvez toujours faire référence à ces éléments via un objet spécial by_id disponible dans les gestionnaires onclick et un attribut spécial ontplready :

<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 — script exécuté quand le gabarit est monté

N’importe quel élément peut avoir un attribut ontplready contenant du JavaScript qui s’exécute une fois le gabarit inséré dans le document. À l’intérieur, this désigne cet élément. Utilisez-le pour rattacher des fonctions utilitaires à l’élément racine plutôt que d’encombrer la portée globale :

<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>

Noms de classe spéciaux

Les noms de classe préfixés par $ transforment un élément en widget Personyze. La classe $ est retirée du HTML affiché.

Classes spéciales reconnues : $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

S’applique généralement à la racine du gabarit. Active un attribut data-style qui prend en charge une fonction CSS spéciale sel(option1, option2) — Personyze choisit l’option qui provoque le moins de débordement sur l’appareil du visiteur.

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

Si un gabarit de popup est $responsive mais déborde quand même, Personyze applique zoom pour le réduire. Les attributs style ordinaires et les balises <style> fonctionnent en parallèle de data-style.

$btn

Transforme l’élément en bouton au style Personyze. Utilisez data-icon="..." pour une icône avant le texte, ou data-icon_append="..." pour une icône après. Les noms d’icônes viennent de 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

Bouton de fermeture qui supprime l’action pendant le nombre de sessions configuré. Les attributs data-action_id et data-n_sessions le relient :

<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">

Généralement associé à un élément ${menu} de type='dontshowagain' pour que l’apparence du bouton de fermeture soit modifiable dans l’interface.

$a_add_params

Ajoute des paramètres d’URL à tous les liens <a> du gabarit. Utile pour le suivi publicitaire. Indiquez les paramètres dans 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

Affiche une info-bulle au survol. Le texte de l’info-bulle vient de title="...", ou — pour un contenu HTML — d’un élément imbriqué marqué 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

Affiche une icône Font Awesome 4. Le nom de l’icône figure dans l’attribut class, à côté de $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

Affiche une popup quand l’utilisateur clique sur un élément déclencheur (ou le survole). La popup fait référence à son déclencheur par 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>

Attributs qui contrôlent le comportement : data-trigger_id, data-trigger_onmouseover="1", data-trigger_onfocus="1" (pour les champs de saisie), data-is_modal="1", data-json-trigger_transit pour l’animation (animator_fade, animator_swap_top).

$switch-elem

Une zone qui peut basculer entre plusieurs cas (par exemple une fenêtre modale en plusieurs étapes). Chaque enfant a data-case="case_name"; un seul est monté à la fois :

<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>

Méthodes JavaScript de la zone commutable : _set_case(name) (ou null pour tout masquer), _get_case(), _get_cases().

$cform

Un formulaire qui renvoie des données à Personyze pour enrichir le profil visiteur, capturer des prospects ou alimenter des actions de formulaire rattachées à une campagne. Le nom du formulaire figure dans l’attribut class, à côté de $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>

Attributs du formulaire

• data-required_field_message="..." — message affiché à côté d’un champ obligatoire manquant.
• data-invalid_value_message="..." — message affiché à côté d’une saisie invalide.
• ontplchange="..." — JS qui s’exécute à chaque changement de valeur.
• ontplsubmit="..." — JS qui s’exécute à l’envoi. Doit appeler arguments[1]() en cas de succès ou arguments[2](error) en cas d’échec. Envoi à Personyze avec : personyze.push(['Submit', '${action_id:html}', this._get_value_ex(), arguments[1], arguments[2]]); return true.
• ontplaftersubmit="..." — JS qui s’exécute après un envoi réussi.

Attributs des champs du formulaire

Les champs appartenant au formulaire doivent avoir form="form_name" et name="...". Attributs facultatifs :

• required="1" — le champ doit être rempli pour pouvoir envoyer.
• pattern="..." — validation par expression régulière.
• data-valid_if="..." — expression JS qui renvoie vrai ou faux. Renvoyer une chaîne affiche cette chaîne comme message d’erreur.
• data-prop-prop_name="..." — propriétés du champ exposées via form._get_value_ex(). La propriété spéciale column associe le champ à un champ du profil utilisateur Personyze.
• data-use_hidden="1" — inclut ce champ même quand il est masqué par une condition de cas de formulaire.
• data-value_if_hidden="..." — valeur fixe à utiliser quand le champ est masqué.

Visibilité par cas de formulaire

Placez les groupes de champs facultatifs dans un conteneur avec data-form_case="..." pour les afficher ou les masquer selon d’autres valeurs du formulaire :

<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>

Méthodes JavaScript de l’élément formulaire

• _get_value() — renvoie un objet plat noms de champs → valeurs.
• _get_value_ex() — renvoie noms de champs → objets avec value plus toutes les propriétés data-prop-* propriétés.
• _set_value(new_value) — définit les valeurs à partir d’un objet.

Éléments de menu (réglages de l’éditeur visuel)

Les directives ${menu} en bas du gabarit définissent ce qu’affiche l’éditeur de l’interface. Il en existe deux types :

Directives de section

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

Paramètres : name (libellé) et, facultativement, icon (nom Font Awesome 4 — les plus courants : image, envelope, user, check, times-circle, edit, font).

Directives d’élément

${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=\'...\'}

Trois formes — pour modifier la valeur d’un argument, pour activer un bloc conditionnel, ou pour laisser l’utilisateur choisir une autre colonne d’une table.

Exemple combiné

${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\'}

L’éditeur par défaut d’un argument est HTML ou texte simple (selon que l’argument a ou non la conversion :html ). Utilisez type='...' pour choisir un éditeur spécialisé — voir ci-dessous.

Types d’éditeur de champ

La plupart des types d’éditeur acceptent des paramètres supplémentaires via la notation param='key=value' dans l’élément de menu.

type='number'

Saisie numérique. Paramètres : min, max, placeholder.

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

type='checkbox'

Interrupteur booléen. La valeur insérée peut être personnalisée : value_on (par défaut 1) et value_off (par défaut 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'

Liste déroulante. Options sous forme de tableau JSON de paires [label, value] :

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

type='textarea'

Texte multiligne. Paramètres : placeholder, autosize (1 pour s’agrandir avec le contenu), autosize_max_rows.

type='css'

Éditeur CSS visuel. Le résultat est une chaîne d’attribut style . Ajoutez param='with_responsive=1' pour produire une sortie compatible data-styleavec des fonctions sel() pour les gabarits responsives.

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

type='color'

Sélecteur de couleur. Insère une valeur de couleur CSS :

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

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

type='dontshowagain'

Éditeur spécialisé pour le HTML du bouton de fermeture. S’associe à la classe $personyze_button_dont_show_again .

type='icon'

Sélecteur d’icône (noms Font Awesome 4).

type='external_media_url_params'

Éditeur des paramètres d’URL ajoutés par $a_add_params.

Exemples prêts à l’emploi sur GitHub

Personyze maintient une bibliothèque de gabarits d’exemple entièrement annotés couvrant les cas courants. Ils se trouvent à côté de cette référence, sur github.com/personyze/personyze-template-language :

Guides associés

• Centre de ressources pour développeurs — présentation de l’API REST et des SDK.
• Guide de l’action JavaScript — pour les actions où vous écrivez directement du JavaScript au lieu d’utiliser des gabarits.
• Guide de l’action Popup et bannière — la présentation de l’éditeur visuel, complémentaire de cette référence.
• Variations de contenu — utiliser des conditions au niveau du ciblage d’audience (plutôt qu’au niveau du gabarit).
• Variables CRM dynamiques dans le contenu — insérer des données CRM avec la même syntaxe ${variable} .