Comment ajouter des paramètres personnalisés à un widget existant dans WordPress

Dans cet article, nous apprendrons comment ajouter votre code HTML personnalisé et vos paramètres à l’un des widgets standard de WordPress ou autres. En utilisant ces paramètres, nous apprendrons différentes astuces pour manipuler le comportement des widgets en conséquence.

La première partie; ajouter et enregistrer vos paramètres personnalisés, est assez facile. La deuxième partie dépend de ce que vous voulez faire spécifiquement, et cela dépend du widget que vous manipulez. Dans ce post, j’ai inclus deux exemples; sauter un widget en fonction d’un paramètre (pour ajouter des paramètres pour contrôler la visibilité du widget dans certains cas) et manipuler les arguments de menu du widget de navigation WordPress. L’exemple donné pour la deuxième partie devrait vous donner une bonne idée de la façon dont vous pouvez gérer ce que vous voulez faire.

Ajout de paramètres personnalisés à n’importe quel widget

Pour ajouter des paramètres personnalisés aux widgets existants, nous utilisons une action appelée [in_widget_form](https://developer.wordpress.org/reference/hooks/in_widget_form/). Cette action est appliquée à la form()fonction de tous les widgets, qui est la fonction responsable du rendu de la partie admin du widget.

Avec ce filtre, nous obtenons trois paramètres, mais seuls le premier et le troisième nous intéressent. La première est l’instance de widget que nous utiliserons pour récupérer les noms de champ et les identifiants appropriés et (éventuellement) vérifier à quel type de widget nous sommes accrochés. Le troisième paramètre est un tableau des paramètres enregistrés du widget, que nous devons utiliser pour vérifier l’état enregistré précédent de nos paramètres.

Le code ci-dessous ajoutera une case à cocher avec le nom du paramètre ‘ awp-custom-setting‘. Ajustez le nom et le code HTML en fonction de l’entrée dont vous avez besoin. Ce qui est important, c’est d’utiliser $widget->get_field_name()pour ajouter des identifiants et namedes attributs appropriés à toutes vos entrées. La valeur de vos entrées doit être remplie avec ce qui a été enregistré précédemment, et c’est quelque chose que vous trouverez dans le paramètre $instance. Pour les cases à cocher, vous pouvez utiliser la fonction de WordPress [checked](https://developer.wordpress.org/reference/functions/checked/)()pour afficher l’attribut coché.

Après avoir ajouté ceci au code de votre thème functions.phpou plugin, tous les widgets devraient maintenant avoir une case à cocher à la fin de leur formulaire dans l’administrateur.

Cibler des widgets spécifiques

Si vous souhaitez appliquer vos paramètres uniquement à un ou plusieurs widgets spécifiques, vous pouvez comparer la propriété id_basedans l’ $widgetobjet. Vous aurez besoin de connaître l’ID de base – si vous n’êtes pas sûr, faites simplement un var_dump($widget->id_base)crochet à l’intérieur, enregistrez et vérifiez la sortie de chaque widget dans l’administrateur. Par exemple, le widget Navigation a la base ID nav_menu, et le widget Archives a archives.

Dans l’exemple ci-dessous, nous vérifions si le widget est un widget de navigation. Si ce n’est pas le cas, la fonction est annulée avec un return. Seuls les widgets de navigation recevront la case à cocher personnalisée :

Vous devriez obtenir le paramètre dans l’administrateur comme suit :

Le paramètre a donc été ajouté, mais pour le moment, vos paramètres ne sont pas enregistrés. Réparons ça.

Enregistrement de vos paramètres personnalisés

Nous devons nous connecter à la update()fonction du widget afin de mettre à jour nos paramètres personnalisés.

Pour cela, nous utilisons le filtre [widget_update_callback](https://developer.wordpress.org/reference/hooks/widget_update_callback/). Le processus d’enregistrement de nos paramètres est exactement comme vous le feriez lorsque vous écrivez une classe de widget. Le filtre fournit trois paramètres ; le premier est le tableau d’instance qui sera enregistré. Le deuxième paramètre est l’état qui a été publié lors de l’enregistrement du widget, et le troisième est l’ancien état. Nous devons nous assurer de récupérer nos nouvelles valeurs à partir du deuxième paramètre et de les ajouter au premier.

C’est ainsi que nous mettrons à jour l’état de notre case à cocher ; comme nous voulons enregistrer une valeur trueou false:

add_filter('widget_update_callback', function($instance, $new_instance, $old_instance) {
    $instance['awp-custom-setting'] = isset($new_instance['awp-custom-setting']);
    return $instance;
}, 10, 3);

N’oubliez pas d’ajuster les noms d’entrée à vos propres noms de paramètres. Si vous ajoutez plusieurs entrées, vous devez répéter cette opération pour chacune.

Vous devriez maintenant voir que vos paramètres personnalisés sont enregistrés dans l’administrateur !

Utilisation des paramètres de widget personnalisés enregistrés

Comme mentionné précédemment, cette partie dépend vraiment de ce que vous voulez que vos paramètres fassent. Ce n’est malheureusement pas aussi simple car la plupart des widgets n’ajoutent pas de filtres ou de crochets dans leurs sorties. Commençons par quelque chose de simple ; évitez de rendre le widget en fonction des paramètres.

Empêcher le rendu du widget en fonction du paramètre personnalisé

Supposons que vous ajoutez des paramètres pour déterminer quand le widget doit être visible ; par exemple en le cachant dans certains modèles (masquer dans le modèle de résultats de recherche, mais afficher en page d’accueil et unique), ou réagir à d’autres états de WordPress.

Pour cela, nous pouvons utiliser le filtre [widget_display_callback](https://developer.wordpress.org/reference/hooks/widget_display_callback/). Tout ce que nous avons à faire est de vérifier le paramètre d’instance fourni pour notre paramètre et de revenir falsesi nous ne voulons pas afficher le widget.

Ce code simple évitera de rendre le widget si la case à cocher personnalisée que nous avons ajoutée ci-dessus est cochée :

add_filter('widget_display_callback', function($instance, $widget, $args) {
    if ($instance['awp-custom-setting']) {
        return false;
    }
    return $instance;
}, 10, 3);

Vous voulez probablement comparer d’autres États. Ceci est un exemple simple où notre case à cocher est une case à cocher pour "Masquer dans les vues de publication unique". Nous vérifions simplement si nous sommes actuellement à une vue de publication unique avec [is_singular](https://developer.wordpress.org/reference/functions/is_singular/)()et si la case est cochée, nous retournons false.

add_filter('widget_display_callback', function($instance, $widget, $args) {
    if (is_singular() && $instance['awp-custom-setting']) {
        return false;
    }
    return $instance;
}, 10, 3);

Modification des paramètres ou de la sortie du widget existant

Un filtre puissant à utiliser pour jouer avec les widgets existants est [dynamic_sidebar_params](https://developer.wordpress.org/reference/hooks/dynamic_sidebar_params/). Jetez un œil à la page de documentation pour voir quels paramètres vous pouvez modifier. Par exemple, vous pouvez ajouter des classes personnalisées, vous pouvez modifier les chaînes before_widget, after_widgetou before_titleet after_titleHTML. Cependant, cela s’applique à tous les widgets, également admin et frontend. Et avec ce filtre, vous n’avez pas accès à l’instance du widget (paramètres enregistrés) ou aux paramètres du widget (par exemple, le type de widget).

Évidemment, nous devons au moins vérifier nos paramètres personnalisés. Nous devons donc faire pas mal de code pour récupérer les valeurs dont nous avons besoin.

La première chose que nous pouvons faire est d’accéder à une variable globale $wp_registered_widgets. Il s’agit d’un tableau qui contient tous les widgets enregistrés et disponibles. En utilisant ce registre, nous pouvons utiliser le paramètre du filtre pour trouver le widget spécifique auquel nous nous trouvons actuellement. Une fois que nous avons trouvé le widget actuel, nous avons accès aux paramètres du widget, tels que id_base– qui, comme nous l’avons vu précédemment, nous indique le type de widget.

Comme vous pouvez le voir en ligne, #9nous pouvons enfin vérifier à quel type de widget nous sommes actuellement. Dans le code ci-dessus, je reviens si le type de widget n’est pas un widget de navigation, car notre paramètre personnalisé n’a été ajouté que pour ces widgets.

Récupération des paramètres de widget enregistrés

Mais nous devons également récupérer les paramètres enregistrés par widget (y compris notre paramètre personnalisé). Tous les paramètres enregistrés des widgets sont stockés dans la base de données d’options regroupés par type de widget. En utilisant une propriété dans le registre des widgets, nous pouvons utiliser [get_option](https://developer.wordpress.org/reference/functions/get_option/)()pour récupérer les paramètres enregistrés pour le type de widget actuel. Le retour sera un tableau indexé où nous devons utiliser encore un autre paramètre du filtre pour trouver l’index actuel (car vous pouvez ajouter plusieurs du même type de widget dans la même barre latérale ou dans des barres latérales différentes). Il est plus facile de montrer avec du code que de l’expliquer :

Enfin, nous mettons la main sur les paramètres enregistrés du widget ! Dans l’exemple de code ci-dessus, à la ligne #9, nous vérifions si notre case à cocher personnalisée est cochée ou non.

Exemples

À ce stade, c’est à vous de décider ce que vous voulez faire. Vous pouvez par exemple afficher une sortie après le titre du widget, mais avant le contenu du widget :

Pour des cas d’utilisation plus réels, vous résoudrez normalement la plupart en ajoutant certains filtres à ce stade, en appelant add_filter()à ce stade.

Vous trouverez ci-dessous un exemple de modification des arguments du menu Navigation en ajoutant un filtre si notre paramètre a été coché. S’il n’était pas coché, nous nous assurons que le filtre est supprimé. Le filtre de modification des arguments de rendu d’un menu de navigation est widget_nav_menu_args. Dans le code ci-dessous, j’ai défini une fonction à appliquer à ce filtre qui ajoute un nouvel argument aux arguments du menu ; un promeneur :

    ...
    if ($saved_settings['my-custom-thing']) {
        add_filter('widget_nav_menu_args', 'awp_add_menu_walker', 10, 3);
    } else {
        remove_filter('widget_nav_menu_args', 'awp_add_menu_walker', 10);
    }
    return $params;
});
function awp_add_menu_walker($nav_menu_args, $nav_menu, $args) {
    $nav_menu_args['walker'] = new AWP_Custom_Walker();
    return $nav_menu_args;
}

Le code ci-dessus est un exemple de cas d’utilisation où la case à cocher personnalisée contrôle s’il faut ou non appliquer un menu walker au menu. Excellent si vous souhaitez que tous les menus s’affichent normalement, mais souhaitez que l’option pour que des widgets de menu spécifiques s’affichent différemment. Ce que le marcheur fait avec la sortie du menu dépend de vous.

Voir ci-dessous le code complet permettant d’ajouter un paramètre personnalisé à tous les menus de navigation, de le mettre à jour et d’appliquer un explorateur de menu.

J’espère que cela vous suffira pour comprendre comment coder ce que vous voulez faire. Cela dépend vraiment de ce que vous voulez faire et du type de widget avec lequel vous travaillez. Comme mentionné ci-dessus, la plupart des modifications peuvent généralement être résolues en ajoutant des filtres pour faire votre travail dans dynamic_sidebar_params.

Exemple complet : paramètre de case à cocher personnalisé sur les widgets de navigation pour l’application d’un explorateur de menu

Voici le code complet pour ajouter une case à cocher personnalisée à tous les widgets de menu de navigation de WordPress pour utiliser un menu walker enregistré. (Code marcheur non inclus)

Conclusion

J’espère que ce message a été utile pour résoudre vos besoins ou vous donner des indications sur la façon dont vous pouvez faire ce que vous devez faire !