JavaScript

Le JavaScript du projet est centralisé dans le dossier resources/scripts.
Il est organisé par responsabilité afin de garantir une structure claire, maintenable et évolutive.

L’objectif est de séparer :

• les composants interactifs (principalement Alpine.js),
• les extensions de l’éditeur Gutenberg,
• les outils et fonctions utilitaires.

Organisation du dossier

resources/
└─ scripts/
    ├─ app.js
    ├─ components/
    ├─ filters/
    └─ utils/

Components

Le dossier components contient les composants JavaScript, utilisés principalement avec Alpine.js.

Ces composants encapsulent :

• des interactions complexes ou réutilisables,
• des comportements partagés entre plusieurs vues ou blocs.

Exemples de composants

• accordéon
• slider

Les composants Alpine sont déclarés et enregistrés dans des fichiers dédiés, puis utilisés dans le HTML via x-data.

Exemple

Déclaration et enregistrement du composant

// resources/scripts/components/accordion.js
import Alpine from 'alpinejs'

Alpine.data('accordion', () => ({
  open: false,

  toggle() {
    this.open = !this.open
  }
}))

Dans le HTML

<div x-data="accordion">
  <button @click="toggle">
    Toggle
  </button>

  <div x-show="open">
    Contenu affiché
  </div>
</div>

Filters

Le dossier filters regroupe les scripts destinés à filtrer ou étendre le comportement des blocs Gutenberg.

Il est notamment utilisé pour :

• modifier ou enrichir les attributs des blocs existants
• étendre le comportement de l’éditeur sans modifier les blocs natifs

Ces scripts s’appuient sur les hooks JavaScript de WordPress (wp.hooks) et sont chargés uniquement dans le contexte de l’éditeur.

Chaque fichiers du dossier scripts/filters doit exporter les constantes suivantes : hook, name et le callback.

Exemple

// resources/scripts/filters/embed.filter.js
export const hook = 'blocks.registerBlockType';

/**
 * Filter handle
 */
export const name = 'sage/embed';

/**
 * Filter callback
 *
 * @param {object} settings
 * @param {string} name
 * @returns modified settings
 */
export const callback = (settings, name) => {
    if (name !== 'core/embed') return settings;

    const allowedVariations = ['youtube'];

    settings.variations = settings.variations.filter(v => allowedVariations.includes(v.name));

    return settings;
}

Utils

Le dossier utils contient les fonctions utilitaires JavaScript partagées dans l’ensemble du projet.

On y place :

• des helpers génériques
• des fonctions de formatage
• des utilitaires DOM
• des fonctions réutilisables sans dépendance UI

Ces scripts ne doivent contenir aucune logique métier et rester indépendants des frameworks utilisés.

Point d’entrée : app.js

Le fichier app.js est le point d’entrée principal du JavaScript.

Il est responsable de :

• l’initialisation d’Alpine.js
• l’import des composants
• le chargement des filtres Gutenberg
• l’enregistrement des utilitaires globaux si nécessaire

Bonnes pratiques

• ✔ Respecter la séparation des responsabilités
• ✔ Utiliser Alpine.js pour les interactions UI légères
• ✔ Extraire toute logique complexe dans des composants
• ✔ Limiter le JavaScript dans les templates
• ✔ Garder les utilitaires indépendants et réutilisables

Résumé

L’organisation du dossier resources/scripts permet de structurer efficacement le JavaScript du projet.
En séparant composants, filtres Gutenberg et utilitaires, elle garantit une base claire, scalable et facile à maintenir.

📌 Un script doit être placé dans le dossier correspondant à sa responsabilité, jamais par commodité.