Développeurs

Créer un bloc en PHP

N’importe quel plugin peut fournir ses propres blocs. Un bloc est une classe PHP, un formulaire YAML et un template Twig.

Générer le bloc

La commande create:block crée les fichiers dans un plugin existant :

php artisan create:block Acme.Blog Testimonial

Elle crée, dans le plugin Acme.Blog :

Le premier argument est au format Auteur.Plugin. Le nom du bloc est converti en nom de classe (my-block donne MyBlock) et son dossier porte le nom de la classe en minuscules (blocks/myblock). Il ne peut contenir que des lettres, des chiffres, - et _.

Enregistrer le bloc

Déclarez le bloc dans la méthode registerBlocks() du Plugin.php de votre plugin :

// plugins/acme/blog/Plugin.php
public function registerBlocks()
{
    return [
        'blog.testimonial' => \Acme\Blog\Blocks\Testimonial::class,
    ];
}

Le bloc apparaît dans la bibliothèque, dans le groupe portant le nom de votre plugin.

La classe du bloc

<?php namespace Acme\Blog\Blocks;

use LucasPalomba\PageTree\Classes\ComponentBase;

class Testimonial extends ComponentBase
{
    public $config_fields = 'config_fields.yaml';

    public $uniqueKey = 'blog.testimonial';

    public function componentDetails()
    {
        return [
            'label' => 'Témoignage',
            'description' => 'Citation d’un client avec son auteur',
            'icon' => 'ph ph-quotes', // icône Phosphor
        ];
    }

    // Options de la liste déroulante "style"
    public function getStyleOptions()
    {
        return ['light' => 'Clair', 'dark' => 'Sombre'];
    }

    // Variables supplémentaires pour le template, $data contient les valeurs des champs
    public function prepareVars($data = null)
    {
        $this->vars['authorUpper'] = strtoupper($data->author ?? '');
    }
}

Le formulaire (config_fields.yaml)

Les champs de formulaire standard d’October sont pris en charge, y compris les répéteurs, les sélecteurs de médias et les éditeurs riches.

fields:
    quote:
        label: Citation
        type: textarea
    author:
        label: Auteur
        type: text
        span: left
    style:
        label: Style
        type: dropdown
        span: right

La case Affiché ? (champ isActive) est ajoutée automatiquement à la fin du formulaire. Déclarez un champ isActive vous-même uniquement pour changer son libellé ou sa position.

Les valeurs default des champs sont appliquées aux nouveaux blocs, et aux champs absents des blocs existants. Les valeurs déjà enregistrées, même false, sont conservées.

Le template (default.php)

Malgré son extension, le template est écrit en Twig. Les valeurs des champs sont dans data, les variables de prepareVars() sont directement accessibles.

<blockquote class="testimonial testimonial--{{ data.style|default('light') }}">
    <p>{{ data.quote }}</p>
    <footer>{{ authorUpper }}</footer>
</blockquote>

• Le contenu saisi par les éditeurs n’est jamais évalué comme du Twig sur le site.
• Pour qu’un champ texte soit modifiable en place, dans l’aperçu et sur le site, affichez-le avec le filtre pagetreeEditable : {{ data.quote|pagetreeEditable('quote', 'multiline') }}. Voir Édition sur le site.
• Pour un champ de lien (pagefinder), utilisez pagetreeLink(data.link) : la fonction n’accepte que les liens relatifs, http(s), mailto: et tel:.
• Pour un média, utilisez le filtre |media.

Sans écrire de plugin

Pour un bloc simple, un super utilisateur peut aussi créer un bloc personnalisé depuis le back-office.