Développeurs

Blocs dans vos modèles

L’éditeur de blocs de PageTree est aussi un widget de formulaire, pagecomponents. Vous pouvez l’ajouter à n’importe quel modèle de vos plugins (produit, article, fiche…) puis afficher ses blocs dans votre thème.

Le principe

• Le widget est enregistré par PageTree sous le code pagecomponents. C’est celui qu’utilise le champ des blocs des pages PageTree.
• Il offre la même bibliothèque de blocs, les mêmes formulaires et le même aperçu.
• Il enregistre les blocs en JSON dans une colonne de votre table.
• Côté thème, la balise Twig {% pagecomponent %} affiche un bloc.

1. La colonne en base

Ajoutez une colonne texte assez grande pour le JSON des blocs. PageTree utilise lui-même un longText pour ses pages.

// plugins/acme/shop/updates/add_content_blocks_to_products.php
use Schema;
use October\Rain\Database\Updates\Migration;

return new class extends Migration
{
    public function up()
    {
        Schema::table('acme_shop_products', function ($table) {
            $table->longText('content_blocks')->nullable();
        });
    }

    public function down()
    {
        Schema::table('acme_shop_products', function ($table) {
            $table->dropColumn('content_blocks');
        });
    }
};

Déclarez la migration dans le updates/version.yaml de votre plugin, comme toute migration October CMS.

2. Le modèle

Déclarez la colonne comme jsonable. C’est obligatoire : le widget renvoie un objet décodé, que le modèle doit réencoder en JSON à l’enregistrement.

class Product extends Model
{
    protected $jsonable = ['content_blocks'];
}

3. Le formulaire

Déclarez le champ dans le fields.yaml du modèle. Cet exemple reprend la configuration du formulaire des pages PageTree : un onglet étiré, sans marge intérieure, qui occupe toute la hauteur.

fields:
    name:
        label: Nom
        type: text

tabs:
    stretch: true
    paneCssClass:
        Contenu: p-0
    fields:
        content_blocks:
            tab: Contenu
            type: pagecomponents
            span: full
            stretch: true

L’aperçu

• Sans layoutField : la barre d’outils du widget affiche Éditer la configuration. Le Mode de prévisualisation permet d’y choisir un layout du thème actif, ou la Configuration manuelle CSS/JS. Ce choix est enregistré avec les blocs.
• Avec layoutField : l’aperçu utilise la valeur de ce champ au chargement du formulaire. Dans vos modèles, un changement de layout est pris en compte après enregistrement et rechargement du formulaire.
• L’aperçu dans un layout passe par le back-office de PageTree : l’administrateur doit avoir la permission Gérer les pages de blocs.

4. L’affichage dans le thème

Les blocs sont rangés dans la clé components de la valeur enregistrée. Parcourez-les et affichez chacun avec {% pagecomponent %}, par exemple dans une page CMS :

title = "Produit"
url = "/produits/:slug"
layout = "default"
==
function onStart()
{
    $this['product'] = \Acme\Shop\Models\Product::where('slug', $this->param('slug'))->first();

    if (!$this['product']) {
        return $this->controller->run('404');
    }
}
==
<h1>{{ product.name }}</h1>

{% for block in product.content_blocks.components|default([]) %}
    {% pagecomponent block %}
{% endfor %}

La balise s’utilise aussi dans un partial ou dans le partial d’un composant.

• Les blocs masqués (Affiché ? décoché) ne sont pas rendus.
• Les feuilles de style des blocs intégrés sont ajoutées avec leur HTML : rien à charger dans le layout.
• Un bloc dont le type n’existe plus est ignoré et signalé dans le journal.

Limites

• Les blocs Composant CMS n’affichent rien hors d’une page PageTree : {% pagecomponent %} ne déclare pas le composant sur la page. Placez plutôt le composant directement dans votre page ou votre layout.
• L’historique des versions, la publication et le SEO appartiennent aux pages PageTree. Pour votre modèle, gérez-les vous-même (champs de statut, de dates, balises méta).

Pour afficher les blocs d’une page PageTree existante dans une page CMS, voir Intégration au thème.