L'API Paramètres WordPress, Partie 6 Pages de menus

Dans la troisième partie de cette série, nous avons examiné les différentes fonctions de menu fournies par l’API WordPress. Si vous avez suivi, alors vous savez que nous avons déjà configuré une page de paramètres pour notre thème à l'aide de la add_theme_page une fonction. Bien que l'introduction de menus et de sous-menus ne fasse pas explicitement partie de l'API Settings, ils jouent un rôle dans la création de fonctionnalités personnalisées, de plug-ins et / ou de thèmes..

Dans cet article, nous allons introduire un nouveau menu dans le tableau de bord WordPress qui rendra les options de thème disponibles ailleurs que juste sous les options "Apparence"..

Avant de commencer: Cet article suppose que vous connaissez l’API de configuration et les options de thème. Si vous êtes un développeur WordPress débutant ou même intermédiaire, je vous recommande vivement de rattraper le reste de la série avant de plonger dans ce post..

Un coup d'oeil à l'API

Comme nous avons déjà examiné chacune des fonctions du menu, nous n'avons pas besoin de modifier chacune des fonctions disponibles dans WordPress. Au lieu de cela, nous examinerons celles que nous allons utiliser, puis nous donnerons un exemple pratique illustrant leur utilisation dans notre propre travail..

Avant d'examiner chaque fonction, décrivons en détail ce que nous prévoyons accomplir dans la prochaine phase de cette série:

Introduire un menu de niveau supérieur pour nos options de thème
Ajouter un élément de sous-menu qui mènera à l'onglet "Options d'affichage"
Ajouter un élément de sous-menu qui mènera à l'onglet "Options sociales"

Relativement simple, non? Pour ce faire, nous allons tirer parti des deux fonctions suivantes:

add_menu_page qui est utilisé pour introduire des éléments de menu de niveau supérieur
add_submenu_page qui est utilisé pour introduire des éléments de sous-menu dans les menus de niveau supérieur.

Nous examinerons les paramètres et l'utilisation de chaque fonction lors de leur implémentation dans notre thème..

Notez que le reste de cet article repose sur cette version de la sandbox de paramètres WordPress. Si vous suivez le référentiel, assurez-vous de le vérifier..

Le menu de haut niveau

La première chose que nous souhaitons faire est d’introduire un menu de niveau supérieur. Ce menu apparaîtra directement sous le menu "Paramètres" du tableau de bord WordPress et servira à deux fins. Le menu devrait:

Exposer les options du thème au tableau de bord WordPress
Afficher une page d'options par défaut pour les options de thème

La fonction prend les sept arguments suivants, les cinq premiers sont obligatoires, les deux derniers ne le sont pas:

titre de la page est le texte qui sera rendu dans la barre de titre du navigateur
menu_title est le texte qui sera affiché pour l'élément de menu
aptitude fait référence au rôle que l'utilisateur doit avoir pour accéder à ce menu
menu_slug est une valeur unique qui identifie ce menu. C'est aussi comment les sous-menus s'enregistrent avec ce menu.
nom_fonction appelé lorsque vous cliquez sur le menu pour afficher la page des options.
icon_url est le chemin d'accès à l'icône que vous souhaitez afficher à côté de votre élément de menu.
position est l'endroit où le menu doit être ajouté par rapport aux autres menus du tableau de bord WordPress.

Dans notre travail, nous nous concentrerons uniquement sur les cinq premiers paramètres. Je discute du positionnement de menu dans la conclusion de cet article.

Pour commencer, nous allons devoir lancer un appel vers le add_menu_page une fonction. Selon le codex WordPress, des menus d’administration peuvent être ajoutés à l’aide du admin_menu crochet. Plus tôt dans cette série, nous avons écrit une fonction qui ajoute nos options de thème au menu "Apparence". Plus précisément, nous avons écrit sandbox_example_theme_menu:

function sandbox_example_theme_menu () add_theme_page ('Thème Sandbox', // Le titre à afficher dans la fenêtre du navigateur pour cette page. 'Thème Sandbox', // Le texte à afficher pour cet élément de menu 'Administrateur', // type d'utilisateurs peut voir cet élément de menu 'sandbox_theme_options', // L'ID unique - c'est-à-dire le slug - pour cet élément de menu 'sandbox_theme_display' // Le nom de la fonction à appeler lors du rendu de la page de ce menu);  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Notez dans le code ci-dessus que cette fonction a été enregistrée avec le admin_menu crochet, aussi bien. Vous devez toujours vous efforcer de garder vos fonctions logiquement cohérentes. Puisque nous avons déjà une fonction qui enregistre un menu, qui est enregistré avec le hook approprié, et puisque nous introduisons une fonctionnalité similaire, nous allons ajouter nos nouvelles fonctions de menu à cette fonction..

Ajouter l'appel suivant à add_menu_page directement sous l'appel ci-dessus:

add_menu_page ('Thème Sandbox', // La valeur utilisée pour remplir la barre de titre du navigateur lorsque la page de menu est active 'Thème Sandbox', // Le texte du menu dans la barre latérale de l'administrateur 'administrateur', // Quels rôles sont possibles pour accéder au menu 'sandbox_theme_menu', // L'ID utilisé pour relier les éléments de sous-menu à ce menu 'sandbox_theme_display' // La fonction de rappel utilisée pour rendre ce menu);

Comme vous pouvez le constater, nous enregistrons un menu qui affichera "Thème Sandbox" dans la barre de titre du navigateur et dans l'élément de menu. Nous exposons le menu uniquement aux administrateurs et nous avons attribué au menu l'identifiant unique de "sandbox_theme_parent_menu". Nous allons réutiliser ce paramètre dans la section suivante.

Il y a une chose importante que nous devons clarifier: Avis que nous avons passé 'sandbox_theme_display'en tant que fonction à appeler lorsque cet élément de menu est cliqué. Rappelons que dans la partie 3, nous avons introduit cette fonction (et nous l'avons affinée dans la partie 5). Plus précisément, il est responsable du rendu de notre page d'options de thème à onglets..

En passant ce nom de fonction existant à la add_menu_page fonction, nous profitons du code que nous avons déjà écrit et nous restituons une page d'options par défaut pour l'élément de menu.

À ce stade, nous sommes prêts à ajouter des sous-menus, mais avant de poursuivre, assurez-vous que votre fonction a exactement la même apparence:

function sandbox_example_theme_menu () add_theme_page ('Thème Sandbox', 'Thème Sandbox', 'administrateur', 'sandbox_theme_options', 'sandbox_theme_display'); add_menu_page ('Thème Sandbox', 'Thème Sandbox', 'administrateur', 'sandbox_theme_menu', 'sandbox_theme_display');  // end sandbox_example_theme_menu

Ajouter les sous-menus

Les sous-menus sont très similaires aux menus, sauf qu'ils "appartiennent" à un menu existant. L'API pour l'enregistrement des sous-menus est également relativement similaire. La fonction accepte six arguments, les cinq premiers étant obligatoires, le dernier étant optionnel:

parent_slug fait référence à l'ID unique de l'élément de menu parent. Dans notre cas, "sandbox_theme_menu".
titre de la page est le texte à restituer dans la barre d'outils du navigateur lorsque cet élément de sous-menu est actif
menu_title est le texte de cet élément de sous-menu dans le tableau de bord
aptitude est le rôle qu'un utilisateur doit avoir pour accéder à cet élément de menu
menu_slug est l'identifiant unique pour cet élément de menu particulier
nom_fonction qui est appelé lorsque le menu est cliqué afin d'afficher la page des options

La fonction est simple. Nous avons deux éléments de menu à introduire: un pour "Options d'affichage" et un pour "Options sociales".

Option d'affichage

Commençons par introduire un élément de sous-menu pour les options d’affichage. Ajoutez le bloc de code suivant directement sous le add_menu_page appelons ce que nous avons défini ci-dessus:

add_submenu_page ('sandbox_theme_menu', // ID de la page de menu de niveau supérieur auquel cet élément de sous-menu appartient, 'Options d'affichage', // Valeur utilisée pour remplir la barre de titre du navigateur lorsque la page de menu est active, 'Options d'affichage', // Le libellé de cet élément de sous-menu affiché dans le menu 'administrateur', // Quels rôles peuvent accéder à cet élément de sous-menu 'sandbox_theme_display_options', // L'ID utilisé pour représenter cet élément de sous-menu 'sandbox_theme_display' // La fonction de rappel utilisée rendre les options pour cet élément de sous-menu);

Chacun des paramètres ci-dessus doit être clair, à l'exception du nom de la fonction que nous avons transmis en tant qu'argument final. Notez que c'est le même nom de fonction que nous avons fourni dans le add_menu_page appel. Mais cela a du sens, non? Après tout, l'onglet "Options d'affichage" est l'onglet par défaut qui s'affiche lorsque les options de thème sont sélectionnées. Il est donc logique qu'il soit rendu lorsque le menu de niveau supérieur est sélectionné et que l'élément de menu "Options d'affichage" est sélectionné..

À ce stade, il convient de souligner une caractéristique importante de WordPress: notez qu'une fois que vous avez ajouté votre premier élément de sous-menu, WordPress restituera deux éléments de sous-menu au menu de niveau supérieur - un élément qui duplique la fonction du niveau supérieur. menu et un élément correspondant à l'élément de sous-menu que vous venez de définir. Je soulève cette question parce que, selon mon expérience, les développeurs ont du mal à comprendre comment (et pourquoi) cela se produit. En bref, c'est ce que WordPress fait. Il n'y a aucun problème avec votre code..

Options sociales

L'ajout d'un élément de menu pour les options sociales est presque identique à l'ajout d'un élément de menu pour les options d'affichage. Bien sûr, nous souhaitons simplement modifier les valeurs de la barre de titre, de l’élément de menu et de la page qui s’affiche lorsque le menu est sélectionné. Premièrement, configurons notre appel au add_submenu_page une fonction. Ça devrait ressembler à ça:

add_submenu_page ('sandbox_theme', 'Options sociales', 'Options sociales', 'administrateur', 'sandbox_theme_social_options', 'sandbox_theme_display');

Enregistrez votre code, actualisez votre tableau de bord et vous devriez voir l'élément de menu "Options sociales" maintenant disponible dans le menu "Thème Sandbox"; notez cependant que cliquer sur le nouvel élément de sous-menu rend uniquement les "Options d'affichage". Depuis que nous avons passé le "sandbox_theme_display"en tant que nom de fonction, c'est ce à quoi nous devrions nous attendre, n'est-ce pas? Alors nous sommes maintenant confrontés à un défi: comment sélectionner l'onglet" Options sociales "lorsque vous cliquez sur l'élément de sous-menu?

Refactoriser notre fonctionnalité d'onglet

Nous avons deux options différentes pour lier le nouvel élément de sous-menu à l'onglet approprié sur la page des options de thème:

Nous pouvons définir une nouvelle fonction qui rend les options sociales. Cela nécessiterait un travail supplémentaire lors de l'introduction d'une nouvelle fonction, de la configuration de la fonctionnalité de tabulation afin de ne pas altérer l'expérience de la page existante et de la duplication d'un peu de code..
Nous pouvons refactoriser l'existant sandbox_theme_display fonction pour accepter un paramètre facultatif, puis utiliser une fonction anonyme dans le add_submenu_page appeler pour lui passer un paramètre.

En fin de compte, l’une ou l’autre de ces options vous appartient; Cependant, je préférerais refactoriser ma fonction existante plutôt que dupliquer le code, c'est ce que je ferai tout au long de cet article..

Commençons d’abord par refactoriser notre sandbox_theme_display une fonction. Faisons-le accepter un argument optionnel qui sera utilisé pour indiquer quel onglet nous voulons sélectionner. Localisez la signature suivante dans votre functions.php fichier:

function sandbox_theme_display () / * Consolidée pour cette partie de l'article. * / // end sandbox_theme_display

Mettez à jour la signature pour qu'elle accepte un seul argument et la définisse sur null lorsqu'elle n'est pas définie:

function sandbox_theme_display ($ active_tab = null) / * Consolidée pour cette partie de l'article. * / // end sandbox_theme_display

Si vous débutez en PHP, vous pouvez en savoir plus sur les arguments par défaut sur cette page..

Rappelez-vous du dernier article que notre fonction d’affichage recherche en réalité une valeur de chaîne de requête à définir. Nous souhaitons toujours conserver cette fonctionnalité, mais nous devons également tenir compte du fait que le paramètre peut également être transmis à la fonction. Pour effectuer ce refactoring, localisez d’abord la ligne de code suivante dans sandbox_theme_display une fonction:

$ active_tab = isset ($ _GET ['tab'])? $ _GET ['tab']: 'display_options';

Notez que cette ligne de code particulière concerne uniquement les paramètres de chaîne de requête. Pour prendre en compte le nouveau paramètre facultatif, nous devons introduire une logique qui vérifie d’abord si le paramètre de chaîne de requête est vérifié. Sinon, il vérifiera si l’argument de la fonction est défini pour afficher les options sociales et, dans le cas contraire, il utilisera par défaut les options d'affichage. Remplacez la ligne de code ci-dessus par le conditionnel suivant:

if (isset ($ _GET ['tab']))) $ actif_tab = $ _GET ['tab' '];  else if ($ active_tab == 'options_sociales') $ actif_tab = 'options_sociales';  else $ active_tab = 'display_options';  // fin si / sinon

La version finale de la fonction devrait ressembler à ceci:

fonction sandbox_theme_display ($ active_tab = ") ?>

Options du thème Sandbox

"> Options d'affichage"> Options sociales

Nous n'avons pas encore terminé. Bien que nous ayons effectué le travail nécessaire pour afficher les options sociales si le paramètre approprié a été passé, nous n'avons pas encore appelé la fonction à l'aide d'un paramètre. Pour ce faire, nous devons repenser la add_submenu_page fonctionner d'en haut. Actuellement, l'appel de fonction ressemble à ceci:

add_submenu_page ('sandbox_theme', 'Options sociales', 'Options sociales', 'administrateur', 'sandbox_theme_social_options', 'sandbox_theme_display');

Nous devons mettre à jour le dernier paramètre pour qu'il appelle la fonction display et transmette la valeur appropriée pour le rendu des options sociales. Pour ce faire, nous allons créer une fonction anonyme:

add_submenu_page ('sandbox_theme_menu', 'Options sociales', 'Options sociales', 'administrateur', 'sandbox_theme_social_options', create_function (null, 'sandbox_theme_display ("options_sociales");;));

Si vous débutez en PHP, assurez-vous de lire la create_function fonction et fonctions anonymes. Bien qu'ils sortent du cadre de cet article, ils peuvent être puissants (et utiles!) Lorsqu'ils sont utilisés dans le contexte approprié.

La version finale du sandbox_example_theme_menu la fonction devrait être comme suit:

function sandbox_example_theme_menu () add_theme_page ('Thème Sandbox', // Le titre à afficher dans la fenêtre du navigateur pour cette page. 'Thème Sandbox', // Le texte à afficher pour cet élément de menu 'Administrateur', // type d'utilisateurs peut voir cet élément de menu 'sandbox_theme_options', // L'ID unique - c'est-à-dire le slug - pour cet élément de menu 'sandbox_theme_display' // Le nom de la fonction à appeler lors du rendu de la page de ce menu); add_menu_page ('Thème Sandbox', // La valeur utilisée pour remplir la barre de titre du navigateur lorsque la page de menu est active 'Thème Sandbox', // Le texte du menu dans la barre latérale de l'administrateur 'administrateur', // Quels rôles sont possibles pour accéder au menu 'sandbox_theme_menu', // L'ID utilisé pour relier les éléments de sous-menu à ce menu 'sandbox_theme_display' // La fonction de rappel utilisée pour rendre ce menu); add_submenu_page ('sandbox_theme_menu', // ID de la page de menu de niveau supérieur auquel cet élément de sous-menu appartient, 'Options d'affichage', // Valeur utilisée pour remplir la barre de titre du navigateur lorsque la page de menu est active, 'Options d'affichage', // Le libellé de cet élément de sous-menu affiché dans le menu 'administrateur', // Quels rôles peuvent accéder à cet élément de sous-menu 'sandbox_theme_display_options', // L'ID utilisé pour représenter cet élément de sous-menu 'sandbox_theme_display' // La fonction de rappel utilisée rendre les options pour cet élément de sous-menu); add_submenu_page ('sandbox_theme_menu', 'Options sociales', 'Options sociales', 'administrateur', 'sandbox_theme_social_options', create_function (null, 'sandbox_theme_display ("options_sociales");;));  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Conclusion

À ce stade, notre thème a maintenant son propre élément de menu de niveau supérieur, chacun des onglets de paramètres étant accessible via des éléments de sous-menu. Bien que cela soit utile, je pense qu’il est important de noter qu’il existe des opinions mitigées sur l’introduction de menus dans le tableau de bord WordPress. Bien qu'ils puissent rendre votre travail plus visible et plus accessible, ils peuvent également interférer avec les menus WordPress existants ou d'autres travaux tiers. notamment si vous essayez de placer vos menus quelque part en utilisant le paramètre position. Bien qu’il n’y ait pas de droit absolu ou de mal absolu lorsqu’il s’agit d’introduire des menus, réfléchissez bien à l’endroit où vous exposez vos menus. Si un menu WordPress existant est logique, enregistrez votre travail en tant que sous-menu.

Dans le prochain article, nous commencerons par jeter un coup d'œil sur les différents éléments d'entrée que nous pouvons utiliser pour introduire des options dans notre thème WordPress, ainsi que sur la façon de valider et de purifier les données avant de les sérialiser..

Sources connexes

add_menu_page
add_submenu_page
create_function
fonctions anonymes
Paramètres WordPress Sandbox 0.5

Code