API des widgets

Avant l’éditeur de blocs, un thème qui voulait proposer une barre latérale personnalisable devait offrir un moyen d’y glisser des éléments hétérogènes : une liste d’articles récents, un formulaire de recherche, du texte libre. C’est ce que résout cette API, en normalisant la façon dont un composant s’enregistre et se configure.

Créer un widget

Un widget se code classiquement en étendant la classe WP_Widget et en implémentant ses méthodes __construct(), widget() (l’affichage côté site), form() (le formulaire de réglages) et update() (l’enregistrement des réglages) :

class Mon_Widget extends WP_Widget {
  public function __construct() {
    parent::__construct( 'mon_widget', 'Mon widget' );
  }
  public function widget( $args, $instance ) {
    echo $args['before_widget'] . esc_html( $instance['titre'] ) . $args['after_widget'];
  }
}
add_action( 'widgets_init', function () {
  register_widget( 'Mon_Widget' );
} );

Depuis l’éditeur de blocs

Depuis WordPress 5.8, l’écran Apparence > Widgets utilise l’éditeur de blocs : les widgets classiques restent fonctionnels et apparaissent sous forme de bloc « widget hérité », mais de nombreux thèmes modernes privilégient directement des blocs natifs dans les zones de widgets.

Bon à savoir

• Les zones où les widgets peuvent être placés sont déclarées séparément par le thème via register_sidebar().
• Sans thème compatible avec l’éditeur de blocs pour les widgets, WordPress affiche l’ancienne interface de glisser-déposer.
• La méthode form() doit toujours échapper les valeurs affichées avec esc_attr(), faute de quoi une valeur enregistrée contenant un guillemet peut casser l’affichage du formulaire de réglages.