Ajout de champs aux éléments de menu WordPress - La page des paramètres du plugin

Publié: 2021-07-08

Lorsque vous utilisez des plugins WordPress, vous avez probablement remarqué que l'auteur a fourni certains paramètres que vous pouvez utiliser pour personnaliser les fonctionnalités du plugin. Techniquement, l'auteur a créé un élément de menu et une page de paramètres vers lesquels cet élément de menu vous redirige. Dans cet article, vous passerez en revue les étapes à suivre pour faire de même pour votre propre plugin.

L'article nécessite que vous ayez déjà appliqué le code fourni dans l'exemple de l'article Ajout de champs aux éléments de menu WordPress - Plugin personnalisé. Nous reprendrons à partir de là et verrons comment nous pouvons rendre notre plugin plus convivial en ajoutant sa page de configuration dans la zone d'administration afin que vous permettiez aux utilisateurs administrateurs de définir leurs préférences sur le fonctionnement du plugin.

Étapes initiales

Pour les besoins de cet article, nous allons créer un joli menu de paramètres simples. Comme nous l'avons vu dans notre article précédent, en utilisant notre plugin, l'utilisateur administrateur peut ajouter un sous-titre à n'importe quel élément de menu. Dans les prochaines étapes, nous fournirons une option permettant à l'utilisateur de choisir le type d'élément HTML dans lequel le champ de sous-titre sera enveloppé.

À ce stade, le fichier PHP principal de notre plugin ressemble à ceci :

 <?php /* Plugin Name: Menu Item Field Creator Description: My custom plugin to create menu item fields */ class MyCP_Menu_Item_Field_Creator { public function __construct() { add_action( 'wp_nav_menu_item_custom_fields', array( $this, 'menu_item_sub' ), 10, 2 ); add_action( 'wp_update_nav_menu_item', array( $this, 'save_menu_item_sub' ), 10, 2 ); add_filter( 'wp_nav_menu_args', array( $this, 'menu_item_sub_custom_walker' ) ); } public function menu_item_sub( $item_id, $item ) { $menu_item_sub = get_post_meta( $item_id, '_menu_item_sub', true ); ?> <div> <span class="subtitle"><?php _e( 'Subtitle', 'menu-item-sub' ); ?></span><br /> <input type="hidden" class="nav-menu-id" value="<?php echo $item_id; ?>" /> <div class="logged-input-holder"> <input type="text" name="menu_item_sub[<?php echo $item_id; ?>]" value="<?php echo esc_attr( $menu_item_sub ); ?>" /> </div> </div> <?php } public function save_menu_item_sub( $menu_id, $menu_item_db_id ) { if ( isset( $_POST['menu_item_sub'][ $menu_item_db_id ] ) ) { $sanitized_data = sanitize_text_field( $_POST['menu_item_sub'][ $menu_item_db_id ] ); update_post_meta( $menu_item_db_id, '_menu_item_sub', $sanitized_data ); } else { delete_post_meta( $menu_item_db_id, '_menu_item_sub' ); } } public function menu_item_sub_custom_walker( $args ) { if ( class_exists( 'My_Custom_Nav_Walker' ) ) { $args['walker'] = new My_Custom_Nav_Walker(); } else { echo 'DOES NOT EXIST'; } return $args; } } $mycp_menu_item_field_creator = new MyCP_Menu_Item_Field_Creator(); if ( ! class_exists( 'My_Custom_Nav_Walker' ) ) { class My_Custom_Nav_Walker extends Walker_Nav_Menu { public function start_el( &$output, $item, $depth=0, $args=[], $id=0 ) { $menu_item_sub = get_post_meta( $item->ID, '_menu_item_sub', true ); $output .= '<li class="' . implode( ' ', $item->classes ) . '">'; if ( $item->url && $item->url != '#' ) { $output .= '<a href="' . $item->url . '">'; } else { $output .= '<span>'; } $output .= $item->title; if ( $item->url && $item->url != '#' ) { $output .= '</a>'; } else { $output .= '</span>'; } if ( ! empty( $menu_item_sub ) ) { $output .= '<div class="menu-item-sub">' . $menu_item_sub . '</div>'; } } } }

La prochaine chose que nous ferons est de continuer et de créer un élément de menu pour la page des paramètres de notre plugin ainsi qu'un exemple simple de ce que vous pourriez inclure dans la page des paramètres en tant que contenu.

Nous devrons travailler avec deux crochets WordPress. Le crochet admin_menu pour enregistrer le ou les éléments du menu admin et le crochet admin_init pour enregistrer les options du plugin plus tard lorsque nous ajouterons la page des paramètres du plugin avec ses formulaires. Bien sûr, nous tirerons également le meilleur parti des API fournies par WordPress et utiliserons certaines fonctions intégrées. Plongeons plus profondément.

Créer l'élément de menu de la page Options

Afin d'ajouter l'élément de menu, nous ajouterons le crochet admin_menu correspondant dans la méthode __construct() sous les crochets actuellement ajoutés.

 class MyCP_Menu_Item_Field_Creator { public function __construct() { add_action( 'wp_nav_menu_item_custom_fields', array( $this, 'menu_item_sub' ), 10, 2 ); add_action( 'wp_update_nav_menu_item', array( $this, 'save_menu_item_sub' ), 10, 2 ); add_filter( 'wp_nav_menu_args', array( $this, 'menu_item_sub_custom_walker' ) ); add_action( 'admin_menu', array( $this, 'plugin_settings_menu_page' ) ); } . . .

Nous avons utilisé le crochet admin_menu et défini la méthode plugin_settings_menu_page() (que nous décrirons ci-dessous) pour spécifier les informations pour l'élément de menu et la page de paramètres du plugin.

 public function plugin_settings_menu_page() { add_menu_page( __( 'Page Title Attribute Text', 'oop-menu-item-sub' ), __( 'Menu Item Field Creator', 'oop-menu-item-sub' ), 'manage_options', 'menu-item-field-creator', array( $this, 'plugin_settings_page_content' ) ); }

La méthode doit également être placée dans la classe principale du plugin. Notez que dans notre méthode plugin_settings_menu_page() , nous avons utilisé la fonction add_menu_page() fournie par WordPress. Cette fonction accepte les arguments suivants :

 add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position )

Le $page_title doit être défini et il s'agit essentiellement de la première partie des balises de titre de la page vers laquelle vous êtes redirigé lors de la sélection de cet élément de menu.
Le $menu_title est le texte à utiliser pour le menu.
$capability est la capacité requise pour que ce menu soit affiché par l'utilisateur. Dans notre cas, nous avons choisi l'autorisation manage_options car elle n'est accordée qu'aux super utilisateurs et aux administrateurs. Si vous souhaitez comprendre quel rôle ou quelle capacité correspond à vos besoins, vous pouvez consulter la documentation officielle associée.
Le $menu_slug est également requis et doit être unique. C'est le nom du slug par lequel se référer à ce menu. N'oubliez pas que vous ne devez utiliser que des caractères alphanumériques minuscules, des tirets et des traits de soulignement compatibles avec sanitize_key() .
Le $icon_url est un argument facultatif et est l'URL qui renvoie au fichier d'icône qui sera utilisé pour l'élément de menu.
L'argument $function est l'endroit où vous définissez la fonction de rappel qui créera le contenu de la page des paramètres. Dans notre cas, il s'agit de plugin_settings_page_content() , qui n'a pas encore de fonctionnalité. Nous l'avons ajouté à notre code en utilisant la méthode plugin_settings_menu_page() .

 public function plugin_settings_page_content() { $html = "<p>Test content for our custom plugin</p>"; echo $html; }

À ce stade, vous devriez voir l'élément de menu "Créateur de champ d'élément de menu" et le contenu de test de la page de contenu et reconnaître l'URL de menu que vous avez définie dans les arguments.

Nous aimerions également noter que si vous souhaitez inclure l'option de votre plugin dans le menu Paramètres intégré et non comme un élément de menu de niveau supérieur séparé, vous pouvez facilement le faire en utilisant la fonction add_options_page() à la place. Dans ce cas, vous devriez remplacer ceci :

 public function plugin_settings_menu_page() { add_menu_page( __( 'Page Title Attribute Text', 'oop-menu-item-sub' ), __( 'Menu Item Field Creator', 'oop-menu-item-sub' ), 'manage_options', 'menu-item-field-creator', array( $this, 'plugin_settings_page_content' ) ); }

avec ça:

 public function plugin_settings_menu_page() { add_options_page( __( 'Page Title Attribute Text', 'oop-menu-item-sub' ), __( 'Menu Item Field Creator', 'oop-menu-item-sub' ), 'manage_options', 'menu-item-field-creator', array( $this, 'plugin_settings_page_content' ) ); }

Cela se traduira par un emplacement de menu ici :

Dans notre prochaine section, nous mettrons un contenu simple dans la page des paramètres que l'utilisateur administrateur peut utiliser pour définir le comportement du plugin.

Ajouter des fonctionnalités à notre page de paramètres

Ce que nous avons fait jusqu'à présent est d'ajouter notre élément de menu et de définir la fonction qui affichera la page de contenu des paramètres. Si nous voulons des fonctionnalités dans notre page de paramètres, nous devrons enregistrer certains champs, puis les afficher dans la page de paramètres du plugin. À titre d'exemple, nous allons créer un formulaire dans lequel l'utilisateur peut définir le type d'élément HTML avec lequel envelopper le champ de sous-titre.

Le résultat

Remplacez le code plugin_settings_page_content par ceci :

 public function plugin_settings_page_content() { ?> <form action="options.php" method="post"> <?php do_settings_sections( 'options_page' ); settings_fields( 'option_group' ); submit_button( __( 'Save Subtitle', 'oop-menu-item-sub' ) ); ?> </form> <?php }

Dans ces lignes, nous utilisons les do_settings_sections() et settings_fields() . Le do_settings_sections() imprimera toutes les sections et champs de paramètres qui sont enregistrés. Τhe settings_fields() affichera les champs d'entrée masqués nonce, action et option_page pour la page des paramètres.

Continuons maintenant et enregistrons nos paramètres.

Enregistrez vos paramètres

Pour enregistrer les champs requis, nous utiliserons le crochet admin_init car il se déclenche lorsqu'un écran d'administration est en cours d'initialisation.

 class MyCP_Menu_Item_Field_Creator { public function __construct() { add_action( 'wp_nav_menu_item_custom_fields', array( $this, 'menu_item_sub' ), 10, 2 ); add_action( 'wp_update_nav_menu_item', array( $this, 'save_menu_item_sub' ), 10, 2 ); add_filter( 'wp_nav_menu_args', array( $this, 'menu_item_sub_custom_walker' ) ); add_action( 'admin_menu', array( $this, 'plugin_settings_menu_page' ) ); add_action( 'admin_init', array( $this, 'plugin_register_settings' ) ); } . . .

Nous allons insérer la méthode plugin_register_settings() dans notre classe comme ceci :

 public function plugin_register_settings() { register_setting( 'option_group', 'option_name' ); add_settings_section( 'section_id', __( 'Settings Page Title', 'oop-menu-item-sub' ), array( $this, 'render_section' ), 'options_page' ); add_settings_field( 'html_element', __( 'Choose HTML Element:', 'oop-menu-item-sub' ), array( $this, 'render_field' ), 'options_page', 'section_id' ); }

Revenons maintenant en arrière et regardons à nouveau ce que nous avons fait jusqu'à présent.

Pour enregistrer un paramètre et ses données, nous avons utilisé la fonction register_setting () qui selon la documentation est structurée comme ceci :

 register_setting( $option_group, $option_name, $args )

Le $option_group est un paramètre obligatoire et doit correspondre au nom de groupe utilisé dans settings_fields() .
Le $option_name est également requis et est le nom de l'option à nettoyer et à enregistrer. Il s'agit de la valeur sous la colonne option_name dans la table de base de données des options.
Le $args n'est pas nécessaire ici. Il s'agit d'un tableau de données facultatif qui décrit le paramètre lors de son enregistrement. Ce que vous pouvez spécifier ici est son type, sa description, une fonction sanitize_callback() pour la valeur de l'option, une option " show_in_rest " qui définit si les données actuelles doivent être incluses dans l'API REST et une option par défaut où vous pouvez définir la valeur par défaut lors de l'appel get_option() .
Nous avons également introduit les add_settings_section() et add_settings_field() qui nous aideront à terminer cette étape.
La fonction add_settings_section() est utilisée pour enregistrer une section avec un certain nom de slug avec WordPress. Ici, le $id est le nom de slug pour identifier la section et est utilisé dans l'attribut 'id' des balises.

 add_settings_section( $id, $title, $callback, $page )

Le $title est le titre formaté de la section qui sera affiché comme en-tête de la section, $callback est la fonction qui fera écho au contenu en haut de la section et $page est le slug-name de la page qui devrait correspond à l'argument $page de do_settings_sections() , qui dans notre cas est "options_page".

Tous les paramètres ci-dessus sont requis.

La fonction add_settings_field () fournie par WordPress vous permet d'ajouter un nouveau champ à une section.

 add_settings_field( $id, $title, $callback, $page, $section, $args )

Les $id , $title , $callback et $page sont utilisés comme expliqué précédemment. La $section est le nom slug de la section de la page des paramètres dans laquelle afficher la boîte et les $args sont utilisés lors de la sortie du champ. $section et $args sont facultatifs.

Aux fins de cet article, nous n'introduirons pas de fonction supplémentaire pour assainir nos valeurs. Nous noterons cependant qu'il est fortement recommandé de toujours désinfecter vos champs de formulaire.

Nous avons maintenant deux méthodes publiques qui doivent être introduites, le render_section() et le render_field() .

Pour la méthode render_section() , nous n'afficherons qu'un en-tête pour notre section :

 public function render_section() { ?> <h2><?php _e( 'Section #1', 'oop-menu-item-sub' ); ?></h2> <?php }

Pour la méthode render_field() nous afficherons 3 boutons radio avec nos choix pour l'élément HTML :

 public function render_field() { $stored_option = get_option( 'option_name' )['html_element']; ?> <input type="radio" name="option_name[html_element]" value="div" <?php checked( $stored_option, 'div' ); ?> /> div <input type="radio" name="option_name[html_element]" value="p" <?php checked( $stored_option, 'p' ); ?> /> p <input type="radio" name="option_name[html_element]" value="span" <?php checked( $stored_option, 'span' ); ?> /> span <?php }

Cela devrait être le résultat que vous voyez maintenant :

Si vous choisissez un autre élément, comme span par exemple, et enregistrez, il devrait également fonctionner correctement.

Refléter les changements de page d'options sur votre site Web

La dernière étape restant à expliquer est de savoir comment appliquer l'élément HTML que les utilisateurs administrateurs choisiront à l'élément de sous-titre sous l'élément de menu sur le front-end du site Web.

Cette étape est très simple car la seule chose dont nous avons besoin est de récupérer le champ sélectionné dans la table des options de la base de données et de modifier la classe " My_Custom_Nav_Walker " dans notre code. Plus précisément, nous devrons remplacer la partie de code où nous ajoutons l'entrée menu_item_sub à la variable $output .

 $output .= '<div class="menu-item-sub">' . $menu_item_sub . '</div>';

Nous allons d'abord récupérer l'élément avec get_option( 'option_name' )['html_element']; et conservez-le dans une variable $stored_option puis appliquez-le à la ligne ci-dessus. La classe finale devrait ressembler à ceci :

 if ( ! class_exists( 'My_Custom_Nav_Walker' ) ) { class My_Custom_Nav_Walker extends Walker_Nav_Menu { public function start_el( &$output, $item, $depth=0, $args=[], $id=0 ) { $menu_item_sub = get_post_meta( $item->ID, '_menu_item_sub', true ); $output .= '<li class="' . implode( ' ', $item->classes ) . '">'; if ( $item->url && $item->url != '#' ) { $output .= '<a href="' . $item->url . '">'; } else { $output .= '<span>'; } $output .= $item->title; if ( $item->url && $item->url != '#' ) { $output .= '</a>'; } else { $output .= '</span>'; } $stored_option = get_option( 'option_name' )['html_element']; if ( ! empty( $menu_item_sub ) ) { $output .= '<'. $stored_option .' class="menu-item-sub">' . $menu_item_sub . '</'. $stored_option .'>'; } } } }

Il est parfois utile de visualiser le fonctionnement des fonctions de WordPress lors de la construction d'une page de paramètres tout en regardant le code de notre plugin. Voici à quoi cela ressemble dans notre exemple :

Conclusion

Comme vous l'avez compris, l'API WP Settings est l'outil principal ici qui nous permet de créer les os de la page d'options de notre plugin. En dehors de cela, c'est à vous de décider si vous utiliserez une approche plus orientée objet avec les classes ou si vous utilisez la route plus simple où vous collez simplement les fonctions et les crochets dans le fichier PHP principal du plugin.

Précisons ici que la route que nous avons suivie pour reconstruire le plugin n'est pas vraiment POO mais a définitivement fait un pas dans cette direction. Dans une prochaine série d'articles sur la POO, nous approfondirons les autres fonctionnalités qui peuvent améliorer la gestion de notre plugin.

La création d'une page de paramètres pour notre plugin personnalisé peut devenir un peu déroutante, mais j'espère qu'après avoir lu cet article, vous comprenez ce qui est requis. Bon codage !

A lire aussi

Ajout de champs personnalisés aux éléments de menu WordPress
Ajout de champs aux éléments de menu WordPress – Plugin personnalisé