Développeurs

Blocs personnalisés

Les blocs personnalisés se créent depuis le back-office, sans écrire de plugin : un formulaire, des sources de données facultatives et un template Twig. Ils sont réservés aux super utilisateurs.

Pourquoi les super utilisateurs uniquement

Le template d’un bloc personnalisé est compilé par le moteur Twig du CMS. Il s’exécute donc sur le serveur.

• Sans le mode sécurisé d’October (cms.safe_mode), un template peut exécuter des commandes sur le serveur et lire ses secrets. Gérer les blocs personnalisés revient alors à pouvoir exécuter du code, comme modifier les templates du CMS.
• Même avec le mode sécurisé, le bac à sable de Twig bloque une liste de méthodes dangereuses mais n’isole pas complètement le template. Les auteurs de templates doivent être de confiance.

C’est pourquoi :

• la permission lucaspalomba.pagetree.manage_custom_blocks n’est proposée à aucun rôle : seuls les super utilisateurs y ont accès ;
• l’éditeur et le contrôleur refusent toute autre personne ;
• le formulaire affiche l’avertissement « Le mode sécurisé est désactivé » quand cms.safe_mode est désactivé.

Les éditeurs qui ont seulement Gérer les pages de blocs utilisent les blocs personnalisés dans leurs pages, mais ne peuvent pas les modifier.

Créer un bloc personnalisé

1. Ouvrez Block Pages. Dans le navigateur, section Blocs personnalisés, cliquez sur Créer puis Nouveau bloc personnalisé.
2. Dans l’en-tête, saisissez le Nom (affiché dans la bibliothèque). Le Code est proposé à partir du nom.
3. Construisez le formulaire dans l’onglet Champs.
4. Ajoutez des sources de données dans l’onglet Données si besoin.
5. Écrivez le HTML dans l’onglet Template.
6. Complétez l’onglet Réglages, puis enregistrez.

Le bloc apparaît dans la bibliothèque, dans sa catégorie (« Blocs personnalisés » par défaut).

Le code du bloc

Le code est l’identifiant du bloc : lettres minuscules, chiffres et tirets, en commençant par une lettre. Le type enregistré dans les pages est custom.<code>.

• Le nom peut changer à tout moment.
• Le code ne peut plus changer une fois le bloc utilisé par une page : le champ est désactivé et indique les pages concernées.

L’onglet Champs

Le constructeur de formulaire s’inspire de celui de RainLab.Builder (sans en dépendre) :

• chaque liste de champs se termine par Ajouter un contrôle, qui ouvre une palette groupée en Standard, Widgets et Interface ;
• cliquez sur un champ pour modifier ses propriétés dans l’inspecteur, à droite ;
• faites glisser un champ sur un autre pour le placer avant lui ;
• la croix d’un champ le supprime, après confirmation.

Le type d’un champ ne peut pas être changé : supprimez-le et ajoutez-en un autre.

Types de champs

Un répéteur ne peut pas contenir d’autre répéteur. Les noms de champs isActive, id, type, children et cells sont réservés. Les onglets de formulaire ne sont pas proposés.

La case Affiché ? est ajoutée automatiquement, comme pour tous les blocs.

L’onglet Données

Une source de données liste des enregistrements dans le template : les derniers articles du blog, les membres d’une équipe, etc. Chaque source devient une variable Twig.

L’onglet affiche un exemple d’utilisation et les attributs disponibles pour chaque source.

Sources autorisées

• Sections Tailor de type entrée, flux, structure ou unique. Les sections de soumission sont exclues : elles contiennent des données envoyées par les visiteurs. Seules les entrées visibles sur le site sont listées (activées, publiées, non expirées, site courant).
• Modèles des plugins activés, situés dans leur dossier models/. Les modèles du cœur d’October et les modèles de réglages sont exclus.

Une source illisible (source supprimée, colonne invalide, erreur de base) donne une liste vide et une ligne dans le journal : la page n’est jamais cassée.

L’onglet Template

Le template est écrit en Twig dans un éditeur de code. Variables disponibles :

• data : les valeurs des champs (data.title, data.items…) ;
• id : l’identifiant du bloc dans la page ;
• une variable par source de données ;
• les fonctions PageTree pagetreeLink(), pagetreeIsBackend(), pagetreeBlockAssets() et les filtres d’October (|media, |page, |trans, |raw…).

{% set items = data.items is iterable ? data.items : [] %}
<section class="team team--{{ data.style ?: 'light' }}">
    {% if data.title %}<h2>{{ data.title }}</h2>{% endif %}
    {% for item in items %}
        <figure>
            {% if item.image is defined and item.image %}
                <img src="{{ item.image|media }}" alt="">
            {% endif %}
            <figcaption>{{ item.text ?? '' }}</figcaption>
        </figure>
    {% endfor %}
</section>

Avec une source de données posts :

{% for post in posts %}
    <a href="{{ 'blog/post'|page({ slug: post.slug, id: post.id }) }}">{{ post.title }}</a>
{% else %}
    <p>Aucun article pour le moment.</p>
{% endfor %}

• Twig échappe les valeurs par défaut. Les champs Texte enrichi doivent être affichés avec |raw, volontairement.
• Le filtre pagetreeEditable rend un champ modifiable en place, dans l’aperçu et sur le site : {{ data.title|pagetreeEditable('title') }}. Voir Édition sur le site.
• Le code PHP n’est pas exécuté : <?php dans un template est affiché comme du texte.
• À l’enregistrement, la syntaxe est vérifiée : une erreur est signalée avec son numéro de ligne.
• Une erreur à l’exécution n’empêche pas la page de s’afficher : le bloc ne rend rien sur le site, un court message apparaît dans l’aperçu et l’erreur est journalisée.

L’onglet Réglages

Supprimer ou désactiver un bloc

• La suppression est refusée tant qu’une page utilise le bloc, y compris dans une section, une cellule de grille ou une traduction. Le message liste les pages concernées.
• Pour retirer un bloc sans toucher aux pages, désactivez-le (Actif décoché). Il est alors marqué comme inactif dans le navigateur.

Multisite et traductions

• La définition d’un bloc est commune à tous les sites.
• Les libellés sont du texte simple. Une clé de traduction (auteur.plugin::lang.cle) fonctionne aussi.
• Le contenu du bloc est traduit avec la page, si RainLab.Translate est installé.