# PluginDocumentSettingPanel : un panneau à côté d’Extrait

> Besoin d'un réglage propre à chaque article, rangé au bon endroit dans la colonne latérale ? La réponse tient dans un seul composant natif, souvent ignoré.

- Auteur : Clément Hadrot
- Publié le : 2021-02-09
- Mis à jour le : 2021-02-09
- Catégorie : Blocs Gutenberg
- URL : https://wpmoderne.dev.wordpress-developpement.fr/blocs/plugindocumentsettingpanel-panneau-extrait/

## L’essentiel

- Le panneau s'insère dans l'onglet Document natif
- name doit être unique par plugin
- Les données se lisent et s'écrivent via les entités de post

Sur un site vitrine pour un cabinet d'avocats, chaque article de blog devait porter un champ « Domaine de compétence » choisi parmi une liste fermée, utilisé ensuite pour filtrer les articles sur la page d'accueil et générer un fil d'Ariane cohérent. Le premier réflexe du développeur junior en charge du projet avait été de créer un bloc dédié à insérer en haut de chaque article, une solution fonctionnelle mais maladroite : le réglage n'avait rien à voir avec le contenu affiché, il s'agissait d'une métadonnée d'article, pas d'un élément éditorial.

Le bon outil pour ce genre de besoin s'appelle `PluginDocumentSettingPanel`, un composant du package `@wordpress/edit-post` qui ajoute un panneau personnalisé directement dans la colonne latérale native de l'éditeur, aux côtés des panneaux existants comme Extrait, Catégories ou Étiquettes, plutôt que dans un bloc distinct au milieu du contenu.

## Un panneau, pas un bloc

La distinction est fondamentale : un bloc fait partie du contenu de l'article et apparaît dans `post_content`, visible potentiellement sur le front du site selon son rendu. Un `PluginDocumentSettingPanel`, lui, vit exclusivement dans l'interface d'édition, aux côtés des réglages natifs du document. Il est le bon choix pour toute métadonnée qui ne doit jamais apparaître comme un élément de contenu à part entière, mais influencer l'affichage ou le comportement de l'article d'une autre manière.

```
import { registerPlugin } from '@wordpress/plugins';
import { PluginDocumentSettingPanel } from '@wordpress/edit-post';
import { SelectControl } from '@wordpress/components';
import { useSelect, useDispatch } from '@wordpress/data';
import { __ } from '@wordpress/i18n';

const DomainePanel = () => {
    const domaine = useSelect(
        ( select ) =>
            select( 'core/editor' ).getEditedPostAttribute( 'meta' )
                ?.domaine_competence,
        []
    );
    const { editPost } = useDispatch( 'core/editor' );

    return (
        <PluginDocumentSettingPanel
            name="domaine-competence"
            title={ __( 'Domaine de compétence', 'cabinet' ) }
        >
            <SelectControl
                label={ __( 'Choisir un domaine', 'cabinet' ) }
                value={ domaine }
                options={ [
                    { label: __( 'Droit du travail', 'cabinet' ), value: 'travail' },
                    { label: __( 'Droit des affaires', 'cabinet' ), value: 'affaires' },
                ] }
                onChange={ ( value ) =>
                    editPost( { meta: { domaine_competence: value } } )
                }
            />
        </PluginDocumentSettingPanel>
    );
};

registerPlugin( 'domaine-competence-panel', { render: DomainePanel } );
```

## Un name unique, un piège discret

La prop `name` doit être unique à l'échelle de tout le site, tous plugins confondus. Sur un projet où plusieurs extensions internes de l'agence coexistaient, deux panneaux distincts partageant par accident le même `name` ("options" par exemple, un choix bien trop générique) ont fini par se substituer l'un l'autre dans l'interface sans qu'aucune erreur ne soit levée, un bug particulièrement difficile à diagnostiquer puisque tout semblait fonctionner du point de vue de React.

> L'essentiel à retenir : Le panneau s'insère dans l'onglet Document natif ; name doit être unique par plugin ; Les données se lisent et s'écrivent via les entités de post

## Préparer la métadonnée côté PHP

Avant qu'un panneau ne puisse lire ou écrire une métadonnée, celle-ci doit être enregistrée avec `register_post_meta` et exposée à l'API REST, faute de quoi `editPost` échouera silencieusement à persister la valeur choisie.

```
function cabinet_enregistrer_meta_domaine() {
    register_post_meta( 'post', 'domaine_competence', array(
        'show_in_rest'  => true,
        'single'        => true,
        'type'          => 'string',
        'auth_callback' => function() {
            return current_user_can( 'edit_posts' );
        },
    ) );
}
add_action( 'init', 'cabinet_enregistrer_meta_domaine' );
```

## Organiser plusieurs réglages avec des icônes

Quand plusieurs panneaux personnalisés cohabitent sur un même projet, chacun peut recevoir une icône propre via la prop `icon`, ce qui aide visuellement à distinguer les réglages internes des réglages natifs de WordPress dans une colonne qui peut vite devenir dense.

- Regrouper les réglages liés dans un seul panneau plutôt que d'en multiplier de minuscules.
- Nommer le panneau avec un préfixe lié au projet pour éviter toute collision future.
- Toujours vérifier que la métadonnée cible est bien exposée via `show_in_rest`.

## Quand préférer un bloc malgré tout

Si l'information doit être positionnée librement dans le flux de contenu, dupliquée à plusieurs endroits d'un même article, ou visible directement dans l'aperçu de l'éditeur au fil de la rédaction, un bloc reste le bon choix. `PluginDocumentSettingPanel` convient uniquement aux données qui concernent l'article dans son ensemble, sans position précise dans le texte.

## Ce qu'il faut retenir

Face à un réglage propre à un article, le réflexe de créer un bloc dédié mène souvent à une solution bancale qui mélange contenu éditorial et métadonnée technique. PluginDocumentSettingPanel, associé à `register_post_meta`, offre une place naturelle à ce type de réglage, dans une colonne que les rédacteurs connaissent déjà et savent où chercher.