Système de Layout et Hooks : Guide Complet

Le système de Layout de Magix CMS 4 est une architecture modulaire puissante qui permet de construire l'interface d'un site web par assemblage de blocs. Grâce aux Hooks (points d'accroche), vous pouvez greffer des fonctionnalités dynamiques (les Widgets) n'importe où sur vos pages, sans modifier une seule ligne de code des fichiers templates.

1. Concepts Fondamentaux

Hook (Zone) : Un emplacement prédéfini dans votre thème (ex: haut de page, colonne gauche, pied de page) capable de recevoir un ou plusieurs widgets.
Widget (Plugin) : Un module autonome (galerie, articles à la une, formulaire) configuré pour s'insérer dans un Hook.
Multi-instance (Slug) : La capacité unique de greffer le même plugin plusieurs fois (ex: deux blocs de "Pages à la une" différents sur la même page) en utilisant des identifiants distincts.

2. Guide de l'Administrateur

L'interface de gestion se trouve dans Apparence > Layout. Elle offre une vision claire et segmentée de la structure de votre site.

Organisation des Zones

Le système regroupe intelligemment les zones pour faciliter votre navigation :

Accueil : Gère les zones spécifiques à la page de destination (ex: displayHomeTop, displayHomeBottom).
Général & Pages : Gère les zones communes et les colonnes (ex: displayLeftColumn).
Pied de page : Gère la structure du footer (ex: displayFooter).

Actions de Gestion

Greffer un Widget : Cliquez sur le bouton d'action pour ouvrir l'interface de greffe. Sélectionnez votre plugin, choisissez sa zone de destination, et confirmez.
Réorganisation par Drag & Drop : L'ordre d'affichage des widgets au sein d'un même Hook se gère par simple glisser-déposer. Utilisez la poignée à gauche de chaque élément pour ajuster sa position.
Activation / Désactivation : Le bouton "Power" permet de masquer un widget instantanément sur le site public tout en conservant sa configuration.
Débranchement : L'icône corbeille retire le widget de sa zone.

Utilisation des Identifiants Uniques (Slugs)

Lors de la greffe d'un widget, le champ "Identifiant unique" (Optionnel) est crucial. Si vous souhaitez utiliser deux fois le même plugin (par exemple pour afficher des "Pages à la une" de catégories différentes), donnez-leur un slug distinct (ex: bloc-services et bloc-actus). Le plugin pourra alors charger des données différentes pour chaque emplacement.

3. Guide du Développeur

Pour qu'un plugin soit reconnu comme un widget par le système de Layout, il doit répondre aux normes de Magix CMS 4.

Configuration du manifest.json

Le fichier manifest.json à la racine de votre plugin doit déclarer ses capacités :

{
  "name": "MagixFeaturedPages",
  "version": "1.0.0",
  "author": "Magix Dev",
  "type": "widget",
  "has_config": true,
  "core_targets": {
    "home": 1,
    "pages": 1
  },
  "default_hooks": [
    "displayHomeBottom"
  ]
}

type : Doit être défini sur "widget".
core_targets : Définit les types de pages où le widget est autorisé à apparaître.
default_hooks : Liste les zones où le widget s'installe par défaut.

Implémentation du Controller

Le moteur du CMS appelle la méthode statique renderWidget de votre FrontendController.php. C'est ici que vous gérez la logique d'affichage.

public static function renderWidget(array $params = []): string
{
    // Récupération du nom du Hook et de l'instance (Slug)
    $hookName = $params['name'] ?? '';
    $instanceSlug = $params['instance_slug'] ?? 'default';

    // Logique métier : Filtrage des données par instance
    // ... votre code ...

    $view = SmartyTool::getInstance('front');
    $view->assign([
        'data' => $myData,
        'instance_slug' => $instanceSlug
    ]);

    return $view->fetch(ROOT_DIR . 'plugins/VotrePlugin/views/front/widget.tpl');
}

4. Maintenance et Cache

Magix CMS 4 intègre une gestion intelligente du cache pour le système de mise en page. Toute modification effectuée dans l'interface Layout (ajout, suppression, déplacement) entraîne automatiquement une purge du cache frontal lié à la mise en page.

Pour les opérations de maintenance profonde, le plugin MagixClear reste votre allié pour réinitialiser les répertoires var/caches/sql et var/tpl_caches.

Navigation

Le système de Layout & Hooks