Comment un plugin s'intègre à l'éditeur : destinations et aperçu¶
Cette page explique pourquoi le bloc « Destinations » de l'éditeur d'article est conçu pour accueillir n'importe quel plugin de diffusion — et comment un plugin déclare qu'il sait prévisualiser un article, sans qu'aucune ligne du cœur ne soit modifiée. Elle prolonge Architecture des plugins de diffusion, dont elle applique le fil conducteur : on doit pouvoir ajouter une destination sans toucher au cœur. Pour le comment faire côté utilisateur, voir le guide Choisir les destinations et prévisualiser un article.
Web est le premier de plusieurs canaux¶
Une seule destination est disponible dans l'éditeur : Web. Mais Web n'est pas un cas particulier câblé en dur — c'est le premier d'une liste ouverte (RSS, API, ActivityPub/Mastodon, et demain Telegram, LinkedIn, Discord). Le bloc « Destinations » ne connaît pas ces canaux par leur nom : il itère le registre de plugins et produit une carte par plugin actif pour l'auteur. Ajouter un canal, c'est ajouter un plugin ; sa carte apparaît d'elle-même.
Chaque carte réunit deux choses qui « vont ensemble » : l'interrupteur qui active le canal comme destination, et le bouton d'aperçu de ce canal. Ce regroupement est délibéré — l'aperçu appartient à la destination, pas à la barre d'outils. C'est aussi ce qui rend l'empilement homogène : quand un deuxième canal arrivera, sa carte se glissera sous la première, avec exactement la même structure.
Le problème : tous les plugins ne savent pas prévisualiser¶
Prévisualiser un article « dans le cadre du plugin » a un sens évident pour le Web (le rendu tel qu'il apparaîtra sur le site public) et pour un flux RSS ou un pouet Mastodon. Il en a beaucoup moins pour un plugin qui pousse vers une API sans surface visuelle propre. Forcer tous les plugins à répondre « voici ma route d'aperçu » — quitte à retourner null — pollue le contrat commun avec une méthode que la moitié des plugins n'ont rien à remplir.
C'est un cas d'école de ségrégation d'interface (le « I » de SOLID) : une capacité que seuls certains plugins possèdent ne doit pas alourdir l'interface que tous implémentent.
La solution : une capability optionnelle¶
L'aperçu est donc une capability séparée, Kirexo\Plugin\Contracts\ArticlePreviewablePluginInterface (src/Plugin/Contracts/ArticlePreviewablePluginInterface.php), distincte du contrat de base DiffusionPluginInterface :
- Un plugin qui sait prévisualiser l'implémente en plus de
DiffusionPluginInterface. Le plugin web le fait :WebDiffusionPlugin implements DiffusionPluginInterface, ArticlePreviewablePluginInterface(src/Plugin/Web/src/WebDiffusionPlugin.php). - Un plugin qui ne sait pas prévisualiser ne la déclare simplement pas. Il n'a rien à retourner, pas de
nullimposé — et sa carte n'affichera aucun bouton d'aperçu.
L'interface tient en une seule méthode : previewRouteName(): string. Le plugin ne rend pas lui-même le HTML de l'aperçu ; il désigne la route vers laquelle l'éditeur pointera. C'est le plugin qui reste maître de son propre rendu (le plugin web sert son aperçu dans le décor du site, derrière la frontière de sécurité du rendu personnalisé), le cœur ne fait que construire le lien.
Le contrat de route : {id} = UUID de l'article¶
Pour que l'éditeur puisse fabriquer l'URL sans rien savoir du plugin, une convention partagée est gravée dans l'interface : la route désignée par previewRouteName() doit accepter le paramètre {id}, où {id} est l'UUID rfc4122 de l'article. Le plugin web déclare la route web_plugin_article_preview (GET /u/web/articles/{id}/apercu), conforme à cette convention.
Ce contrat minimal est ce qui permet au cœur de générer l'URL de façon uniforme, quel que soit le plugin :
Tout plugin prévisualisable respecte le même contrat {id} ; l'éditeur n'a donc jamais à connaître le nom concret de la route ni sa forme.
La détection : instanceof au rendu, pas d'autoconfiguration¶
Le composant App\Twig\Components\ArticleDestinations (src/Twig/Components/ArticleDestinations.php) — un Live Component qui itère déjà le registre pour produire une carte par destination active — teste la capability au moment du rendu :
$previewUrl = $plugin instanceof ArticlePreviewablePluginInterface
? $this->urls->generate($plugin->previewRouteName(), ['id' => $this->article->getId()->toRfc4122()])
: null;
Chaque ligne de destination porte alors un previewUrl : une URL si le plugin est prévisualisable, null sinon. Le template n'affiche le bouton d'aperçu que lorsque previewUrl existe, et ne le rend cliquable que si la destination est activée (interrupteur ON) ; désactivée, le bouton est grisé et non focalisable.
Le choix d'un instanceof à l'exécution — plutôt qu'un tag de conteneur autoconfiguré — est délibéré. Les plugins sont déjà agrégés par le registre ; les tester un par un avec instanceof est robuste et trivialement testable. Kirexo a par ailleurs constaté qu'un #[AutoconfigureTag] posé sur une interface ne se propage pas de façon fiable aux plugins packagés en bundles ; s'appuyer sur des services déjà collectés évite entièrement cet écueil.
Ce que l'extensibilité garantit concrètement¶
Le bénéfice se mesure à ce qu'un futur plugin n'a pas à faire. Pour qu'un canal RSS, API ou Mastodon apparaisse dans l'éditeur avec son interrupteur et son bouton d'aperçu, il suffit que le plugin :
- implémente
DiffusionPluginInterface(il apparaît alors comme destination) ; - implémente en plus
ArticlePreviewablePluginInterfaces'il sait se prévisualiser, en déclarant une route qui accepte{id}.
Aucune modification de ArticleDestinations, de son template, ni d'aucun fichier du cœur n'est requise. Un plugin sans la capability reste une destination pleinement valide — il n'expose simplement pas d'aperçu. C'est la même promesse que le reste de l'architecture des plugins, appliquée à l'éditeur : le cœur ne cite jamais un plugin par son nom.
Voir aussi¶
- Architecture des plugins de diffusion — pourquoi un plugin est un bundle isolé, un contrat neutre, un registre par tag.
- Référence : contrat de plugin — les signatures du contrat de base et de la capability
ArticlePreviewablePluginInterface. - Choisir les destinations et prévisualiser un article — le geste côté utilisateur : interrupteur par canal, bouton d'aperçu associé.
- Écrire un plugin de diffusion — mettre en œuvre le contrat pas à pas.