L'API Paramètres WordPress, Partie 3 Menus Tout À Propos

À ce stade, nous avons compris l'importance de l'API des paramètres, des sections, des champs et des paramètres, et nous avons même configuré un thème Sandbox que nous utilisons pour développer des fonctionnalités lors de l'exploration de l'API..

Dans cet article, nous allons examiner comment nous pouvons nous connecter au système de menus WordPress. Il est important de noter que cela ne fait pas vraiment partie de l'API Settings, mais il est si étroitement lié que nous devrions nous familiariser avec son utilisation..

Au fur et à mesure que nos thèmes et / ou plugins deviennent plus complexes, nous devons connaître toutes les manières de les inclure dans le tableau de bord WordPress. Dans cet article, nous allons examiner les différentes fonctions du menu WordPress, savoir quand les utiliser, quand les éviter et les situations dans lesquelles chaque fonction se prête le mieux..

Comprendre les types de menus

WordPress propose quatre manières différentes d'inclure nos propres menus. Ci-dessous, nous examinerons chaque menu, les paramètres acceptés par chacun et des exemples de code pour les utiliser dans les projets. Nous visons à bien comprendre le fonctionnement de l'API, qui peut jeter les bases de nos travaux futurs..

Menus de premier niveau

Les pages de menu font référence aux éléments de menu que vous voyez lorsque vous vous connectez pour la première fois à WordPress. Autrement dit, ce sont les options disponibles dans le menu de gauche qui peuvent contenir une liste de pages de sous-menus..

Pour introduire votre propre page de menu dans le tableau de bord WordPress, vous utilisez la fonction add_menu_page..

Nous examinerons un exemple pratique dans un moment, mais examinons d’abord la fonction - elle accepte sept arguments (cinq obligatoires, deux facultatifs):

Titre de la page fait référence au texte qui apparaît en haut de la fenêtre du navigateur lorsque la page de menu de niveau supérieur est affichée.
Titre du menu est le texte qui apparaît dans le menu actuel. Il est préférable de garder cela un peu court, sinon cela encapsulera l'élément de menu et semblera un peu éloigné du reste des éléments de menu..
Aptitude fait référence aux utilisateurs qui ont accès au menu. C'est simplement une valeur de chaîne qui représente l'un des rôles disponibles..
Menu Limace est un identifiant unique que vous fournissez. Il identifie ce menu dans le contexte de WordPress et renvoie également à la page qui affiche les options associées à ce menu. Il fournit également un crochet avec lequel les éléments de sous-menu peuvent s’inscrire eux-mêmes..
Rappeler est la fonction qui définit le contenu affiché sur la page qui correspond à ce menu. Cela peut être HTML en ligne ou faire référence à un fichier externe.
URL de l'icône est le chemin d'accès à l'icône que vous souhaitez afficher à côté de l'élément de menu dans le menu WordPress. Vous pouvez utiliser l'une des icônes existantes de WordPress ou l'une des vôtres. Cet argument est optionnel.
Position définit la position de ce menu dans la liste des éléments de menu de WordPress. Par défaut, le menu apparaît au bas du menu, mais une position personnalisée placera votre menu au-dessus (ou au-dessous) des éléments de menu WordPress existants..

Jetons un coup d'oeil à un exemple. Localisez functions.php dans la sandbox de paramètres WordPress et ajoutez les deux fonctions suivantes:

function sandbox_create_menu_page ()  add_action ('admin_menu', 'sandbox_create_menu_page'); fonction sandbox_menu_page_display ()

Notez que nous utilisons le hook admin_menu pour enregistrer notre élément de menu. Cette fonction particulière est activée juste après la mise en place du menu d'administration de base. Vous souhaitez donc enregistrer votre menu ici afin que WordPress le restitue lors de l'affichage du reste des menus..

Ensuite, configurons l’élément de menu de base. En cohérence avec les articles précédents de cette série, voici ce que nous prévoyons de faire:

Ajouter un nouveau menu au bas du menu WordPress
Nous allons lui donner le nom de notre thème ("Sandbox")
Il sera disponible pour tous les utilisateurs
Il ne comprendra pas d'icône

Assez facile, non? Allons-y et ajoutons notre menu. Encore une fois, ne copiez pas simplement ce code et ne le collez pas. Lisez-le, notez les commentaires et assurez-vous de bien comprendre ce que nous faisons:

function sandbox_create_menu_page () add_menu_page ('Options du bac à sable', // Le titre à afficher sur la page correspondante pour ce menu 'Bac à sable', // Le texte à afficher pour cet élément de menu actuel 'Administrateur', // Quel type des utilisateurs peuvent voir ce menu 'sandbox', // L'ID unique - c'est-à-dire le slug - pour cet élément de menu 'sandbox_menu_page_display', // le nom de la fonction à appeler lors du rendu du menu pour cette page "); // end sandbox_create_menu_page add_action ('admin_menu', 'sandbox_create_menu_page');

Maintenant, actualisez votre menu d'administration WordPress et vous devriez voir un nouvel élément de menu. Lorsque vous cliquez dessus, vous devriez voir une page vierge.

De toute évidence, ce n'est pas très fonctionnel. Supposons la fonction de rappel que nous avons définie précédemment afin d'afficher quelque chose sur l'écran:

function sandbox_menu_page_display () // Crée un en-tête dans le contenu par défaut de WordPress 'wrap' conteneur $ html = ''; $ html. = 'bac à sable
'; $ html. = '
'; // Envoyer le balisage au navigateur echo $ html;  // end sandbox_menu_page_display

La version finale de votre code devrait ressembler à ceci:

/ ** * Ajoute un nouveau menu de niveau supérieur au bas du menu d'administration de WordPress. * / function sandbox_create_menu_page () add_menu_page ('Options du bac à sable' ', // Le titre à afficher sur la page correspondante pour ce menu' Bac à sable ', // Le texte à afficher pour cet élément de menu actuel' Administrateur ', // Quels types d'utilisateurs peuvent voir ce menu 'sandbox', // L'ID unique - c'est-à-dire le slug - pour cet élément de menu 'sandbox_menu_page_display', // le nom de la fonction à appeler lors du rendu du menu pour cette page ") ; // end sandbox_create_menu_page add_action ('admin_menu', 'sandbox_create_menu_page'); / ** * Rend l'affichage de base de la page de menu du thème. * / function sandbox_menu_page_display () // Crée un en-tête dans le WordPress par défaut wrap 'conteneur $ html =''; $ html. = 'bac à sable
'; $ html. = '
'; // Envoyer le balisage au navigateur echo $ html;  // end sandbox_menu_page_display

Outre l'utilisation de la fonction add_menu_page, le plus subtil est peut-être le fait que dans WordPress, chaque élément de menu a une page de menu correspondante. Nous examinerons cela de manière plus approfondie tout au long de la série, mais il est important de le noter maintenant, car nous commençons à explorer chacun des différents types de menus..

Bien que cela soit en grande partie incomplet, nous y ajouterons le reste de cet article et le reste du didacticiel..

Une note sur le positionnement: De nombreux développeurs considèrent l’argument de position comme une mauvaise étiquette, car il mélange l’expérience utilisateur par défaut avec WordPress. De plus, si vous définissez une position et qu'un autre thème, plug-in ou fonction utilise la même position, l'un des éléments de menu peut être remplacé..

Sous-menus

Les sous-menus ressemblent aux menus, sauf qu'ils appartiennent à un autre menu - ils ont un parent. Donc, évidemment, vous ne pouvez pas créer un sous-menu sans créer d'abord un élément de menu. Bien sûr, comme nous l'avons vu dans le dernier article, les éléments de sous-menu peuvent être introduits dans les éléments de menu existants - pas uniquement dans les éléments de menu personnalisés..

Dans cet article, nous allons introduire une page de sous-menu dans notre propre élément de menu personnalisé. Mais avant cela, jetons un coup d’œil à la fonction add_submenu_page et aux paramètres qu’elle accepte:

Limace parentale fait référence à l'ID de l'élément de menu parent auquel appartiendra ce sous-menu. Dans notre cas, nous utiliserons le slug de menu que nous avons défini ci-dessus.
Titre de la page est le texte qui apparaîtra dans le titre du navigateur lorsque la page sera rendue.
Titre du menu est le texte qui apparaîtra comme élément de menu réel dans le menu WordPress.
Aptitude, comme avec le menu parent, se réfère à quels types d'utilisateurs ont accès à ce menu particulier.
Menu Limace est l'identifiant unique pour cet élément de menu. C'est ce qui est utilisé pour définir ce menu particulier dans le contexte de WordPress.
Rappeler est la fonction utilisée pour rendre la page de ce menu à l'écran.

Si vous souhaitez ajouter un élément de menu à l’un des menus existants, reportez-vous au tableau de l’article précédent..

Commençons par enregistrer un sous-menu pour le menu existant ci-dessus. Nous voulons faire ce qui suit:

Enregistrez un sous-menu à ajouter au menu que nous venons de créer
Il affichera le texte 'Options'
Il sera disponible pour tous les utilisateurs
Il ne comprendra pas d'icône

Vérifiez le code suivant - nous l'ajouterons directement au-dessous de notre appel à add_menu_page:

add_submenu_page ('sandbox', // enregistre ce sous-menu avec le menu défini ci-dessus 'Options du bac à sable', // le texte à afficher dans le navigateur lorsque cet élément de menu est actif, 'Options', // le texte de cet élément de menu ' administrateur ', // Quel type d'utilisateurs peut voir ce menu' sandbox_options ', // L'ID unique - le slug - pour cet élément de menu' sandbox_options_display '// La fonction utilisée pour afficher le menu de cette page à l'écran);

N'oubliez pas de définir le rappel, même s'il est vide. C'est-à-dire, n'oubliez pas d'ajouter cette fonction à votre fichier (nous en ajouterons plus momentanément):

function sandbox_options_display ()  // termine sandbox_options_display

Lorsque vous actualisez votre navigateur, vous devriez maintenant voir deux éléments de sous-menu directement sous le menu "Sandbox". Notez que WordPress crée lui-même un élément de sous-menu - c’est un élément de sous-menu qui correspond à l’élément de menu et à la fonction de rappel définie. La seconde est la nouvelle option de sous-menu que nous venons de définir, bien qu’elle ne rende aucun contenu..

Pour résoudre ce problème, allons de l'avant et introduisons une page de base. Mettez à jour la fonction de rappel du sous-menu afin qu'elle ressemble à ceci:

function sandbox_options_display () // Crée un en-tête dans le 'wrap' par défaut de WordPress 'conteneur $ html =''; $ html. = 'Options de bac à sable
'; $ html. = '
'; // Envoyer le balisage au navigateur echo $ html;  // end sandbox_options_display

Actualisez à nouveau votre navigateur et vous devriez voir un titre de base lorsque vous sélectionnez la nouvelle Les options élément de sous-menu.

Bien que cela ne soit pas obligatoire, notez que vous pouvez avoir l’élément de menu parent et le Les options élément de menu fait référence au même contenu - il suffit de mettre à jour le rappel dans la fonction ad_menu_page au sandbox_options_display fonction que nous venons de définir.

Plugin Pages

Si vous développez un plugin WordPress, votre produit peut s’interfacer de différentes manières avec la plate-forme..

Plus précisément, votre plugin…

Peut fonctionner en arrière-plan et ne nécessite pas de menu.
Peut utiliser les deux ou l'une des fonctions mentionnées ci-dessus pour créer un menu personnalisé
Peut s’inclure dans l’un des menus WordPress existants

Pour aider les développeurs de plugins à inclure leurs options dans les menus WordPress existants, l'API WordPress offre la fonction suivante: add_plugins_page.

Mais attendez. Si vous avez suivi les exemples ci-dessus, vous avez probablement remarqué qu'il ne semble pas y avoir de différence perceptible entre add_plugins_page et add_submenu_page. Tu as raison. add_plugins_page offre les mêmes fonctionnalités que add_submenu_page, mais il existe deux différences principales:

Le plugin est fourni spécifiquement pour une utilisation dans le développement de plugins.
La fonction ajoute l'option de menu des plugins directement à WordPress ' Plugins menu.

Bien que vous puissiez certainement utiliser add_submenu_page pour atteindre le même objectif, je suis toujours partisan d’utiliser des fonctions destinées à un cas d’utilisation spécifique, même s’il existe une autre fonction API qui fait de même. Lorsque vous faites cela, vous montrez que vous utilisez l'API comme le souhaitent les développeurs et que votre code est un peu plus cohérent car votre base de code est plus étroitement alignée sur la manière dont il interagit avec la plate-forme principale..

Le développement de plugins sort du cadre de cette série particulière, mais ce n’est pas complètement hors de propos. Bien qu'il n'y ait aucune modification apportée à notre thème Sandbox, je souhaite fournir un exemple simple montrant comment utiliser cette fonction particulière..

Commençons par les arguments acceptés par add_plugins_page:

Titre de la page est le texte qui apparaîtra dans le titre du navigateur lorsque la page d'option du plugin sera rendue.
Titre du menu est le texte qui apparaîtra comme élément de menu du plugin dans le menu WordPress.
Aptitude comme avec le menu parent, se réfère à quels types d'utilisateurs ont accès à ce menu particulier.
Menu Limace est l'identifiant unique pour cet élément de menu. C'est ce qui a été utilisé pour définir ce menu dans le contexte de WordPress.
Rappeler est la fonction utilisée pour rendre la page de ce menu à l'écran.

Voici un exemple simple qui montre exactement comment l’utiliser. Notez que vous pouvez l’inclure dans votre fichier functions.php mais c’est ne pas partie du thème Sandbox sur laquelle nous travaillons et devrait être utilisée dans le contexte d’un plugin,.

Tout d’abord, configurez l’appel à la fonction API - notez que cela utilise le hook admin_menu:

function sandbox_example_plugin_menu () add_plugins_page ('Sandbox Plugin', // Le titre à afficher dans la fenêtre du navigateur pour cette page. 'Sandbox Plugin', // Le texte à afficher pour cet élément de menu 'administrateur', // le type d'utilisateurs peut voir cet élément de menu 'sandbox_plugin_options', // L'ID unique - c'est-à-dire le slug - pour cet élément de menu 'sandbox_plugin_display' // Le nom de la fonction à appeler lors du rendu de la page pour ce menu);  // end sandbox_example_plugin_menu add_action ('admin_menu', 'sandbox_example_plugin_menu');

Ensuite, configurez la fonction qui rendra l’affichage du plugin:

function sandbox_plugin_display () // Crée un en-tête dans le 'wrap' par défaut de WordPress 'conteneur $ html =''; $ html. = 'Options du plug-in Sandbox
'; $ html. = 'Il n'y a actuellement aucune option. Ceci est juste à des fins de démonstration.
'; $ html. = '
'; // Envoyer le balisage au navigateur echo $ html;  // end sandbox_plugin_display

Actualisez votre tableau de bord WordPress en survolant la Plugins menu et vous devriez remarquer un nouvel élément de menu. Pas mal, hein?

La version finale du code devrait ressembler à ceci:

/ ** * Cette fonction introduit une option de menu à thème unique dans le menu 'Plugins' * de WordPress. * / function sandbox_example_plugin_menu () add_plugins_page ('Sandbox Plugin', // le titre à afficher dans la fenêtre du navigateur de cette page. 'Sandbox Plugin', // le texte à afficher pour cet élément de menu 'administrateur', / / Quel type d'utilisateurs peut voir cet élément de menu 'sandbox_plugin_options', // L'ID unique - c'est-à-dire le slug - pour cet élément de menu 'sandbox_plugin_display' // Le nom de la fonction à appeler lors du rendu de la page pour ce menu) ;  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_plugin_menu'); / ** * Affiche une page simple à afficher pour le menu de thèmes défini ci-dessus. * / function sandbox_plugin_display () // Crée un en-tête dans le contenu par défaut de WordPress 'wrap' conteneur $ html = ''; $ html. = 'Options du plug-in Sandbox
'; $ html. = 'Il n'y a actuellement aucune option. Ceci est juste à des fins de démonstration.
'; $ html. = '
'; // Envoyer le balisage au navigateur echo $ html;  // end sandbox_plugin_display

Encore une fois, cette fonction ne fera pas partie de notre thème Sandbox car elle est davantage orientée vers le développement de plug-ins; cependant, il convient de couvrir ceux d'entre vous qui utiliseront l'API Settings dans le cadre de votre effort de développement de plugin..

Pages thématiques

Comme pour les plugins, WordPress fournit une fonction API permettant d’introduire des menus spécifiques aux thèmes. Il est très similaire à la fonction de menu du plugin en ce sens qu’il fournit un autre moyen d’introduire un sous-menu dans les menus existants. La principale différence est que le sous-menu est ajouté à la liste. Apparence menu.

Comme avec l'exemple de plugin plus haut dans cet article, nous verrons comment utiliser cette fonction, mais nous ne l'inclurons pas dans notre thème Sandbox. Ceci est uniquement destiné à montrer comment utiliser la fonction au cas où vous choisiriez cette voie dans votre travail personnel..

Tout d'abord, nous allons passer en revue les arguments acceptés par add_theme_page. Vous remarquerez qu'elles ressemblent à celles requises pour le menu du plugin et sont très similaires aux fonctions de sous-menu décrites précédemment:

add_theme_page accepte les arguments suivants:

Titre de la page est le texte qui apparaîtra dans le titre du navigateur lorsque la page d'option du thème sera affichée.
Titre du menu est le texte qui apparaîtra comme élément de menu du thème dans le menu WordPress.
Aptitude comme avec le menu parent, se réfère à quels types d'utilisateurs ont accès à ce menu particulier.
Menu Limace est l'identifiant unique pour cet élément de menu. C'est ce qui a été utilisé pour définir ce menu dans le contexte de WordPress.
Rappeler est la fonction utilisée pour rendre la page de ce menu à l'écran.

Comme pour les autres fonctions, nous allons créer quelques exemples de fonctions montrant comment inclure cela dans votre projet. Notez que l'appel à add_theme_page peut être ajouté à functions.php et, contrairement aux appels à add_plugin_page, devrait résider ici lors du développement de votre thème.

Tout d'abord, l'appel pour configurer l'élément de 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 pour ce menu);  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Ensuite, nous allons configurer une fonction pour rendre la page d’options:

function sandbox_theme_display () // Crée un en-tête dans le 'wrap' par défaut de WordPress 'conteneur $ html =''; $ html. = 'Options du thème Sandbox
'; $ html. = 'Il n'y a actuellement aucune option. Ceci est juste à des fins de démonstration.
'; $ html. = '
'; // Envoyer le balisage au navigateur echo $ html;  // end sandbox_theme_display

Maintenant, actualisez le tableau de bord WordPress, survolez la Apparence menu et vous devriez voir votre nouvel élément de menu. Simple!

La version finale du code devrait ressembler à ceci:

/ ** * Cette fonction introduit une option de menu à thème unique dans le menu 'Apparence' * de WordPress. * / 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', / / Quel 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 pour ce menu) ;  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu'); / ** * Affiche une page simple à afficher pour le menu de thèmes défini ci-dessus. * / function sandbox_theme_display () // Crée un en-tête dans le contenu par défaut de WordPress 'wrap' conteneur $ html = ''; $ html. = 'Options du thème Sandbox
'; $ html. = 'Il n'y a actuellement aucune option. Ceci est juste à des fins de démonstration.
'; $ html. = '
'; // Envoyer le balisage au navigateur echo $ html;  // end sandbox_theme_display

Pour ceux d'entre vous qui sont intéressés par un développement de thème plus avancé, vous avez probablement envisagé les différentes manières d'implémenter plusieurs pages d'options pour votre thème..

D'une part, nous pouvons ajouter plusieurs sous-menus à un menu de niveau supérieur, mais il existe est une alternative: la navigation par onglets. Cela se prête bien lorsque vous souhaitez introduire des options à la Apparence menu et ne pas ajouter encore un autre élément de menu au tableau de bord WordPress. Nous en discuterons plus en détail dans le prochain article..

Quand utiliser chaque fonction

Nous avons examiné chacune des quatre méthodes principales pour introduire nos propres pages d’options dans WordPress. Bien que ces fonctions ne fassent pas spécifiquement partie de l'API Settings, il est important de discuter car elles fonctionnent si étroitement ensemble..

Mais connaître ces fonctions n’est que la moitié. En tant que développeur responsable de l'intégration et de l'organisation des paramètres, il est important de savoir quand utiliser chacune des diverses fonctions dans le contexte qui convient..

Bien qu'il n'y ait pas de solution miracle pour l'utilisation de chaque fonction, voici quelques recommandations à prendre en compte lorsque vous travaillez sur vos fonctions personnalisées, plug-ins et / ou thèmes:

Menus de premier niveau peut être ajouté quand un sous-menu peut être logiquement groupé avec ces options. Cela se prête lorsque vous avez un ensemble important de paramètres qui ne correspondent logiquement à aucun des menus WordPress existants..
Sous-menus toujours appartenir à un menu de niveau supérieur - personnalisé ou préexistant. Ils doivent toujours être regroupés dans le menu de niveau supérieur le plus logique. Si WordPress propose un menu pouvant servir de parent à votre sous-menu, utilisez-le; ne polluez pas le menu avec un menu de niveau supérieur redondant.
Plugin Menus doit être utilisé lorsque vous avez des options simples d’une page pour votre plugin. Si vous avez plusieurs pages d'options, envisagez de créer un menu de niveau supérieur ou envisagez d'utiliser la navigation par onglets, que nous explorerons dans le prochain article..
Menus Thématiques doit être utilisé lorsque vous développez votre propre thème qui offre son propre ensemble d’options personnalisées. Si les options peuvent vivre sur une seule page, envisagez d'utiliser la fonction API de WordPress. Si vous avez plus d'options, envisagez d'utiliser la navigation par onglets. Notez que de nombreux développeurs de thèmes élèvent souvent leurs options de thème au menu de niveau supérieur, ce qui est bien aussi..

Un mot sur les menus personnalisés: Bien que WordPress nous donne la possibilité d’ajouter nos propres menus de niveau supérieur, s’ajoute à tout menu existant, et nous donne généralement la possibilité de faire ce que nous voulons avec la configuration par défaut, une partie de la communauté en désapprouvant. Ils estiment que les fonctionnalités personnalisées ne doivent pas interférer avec certains menus de base. Bien que ce soit finalement à vous de décider de mettre en œuvre votre travail avec discernement - il y a peu de chances que vous fassiez quelque chose qui soit plus important que les fonctionnalités de base de WordPress..

Quoi de neuf ensuite?

Dans le prochain article, nous allons appliquer un peu de ce que nous avons appris sur les menus et commencer à présenter des pages d’option pour notre thème Sandbox..

En plus d'ajouter des pages de menu, nous examinerons également la navigation par onglets et la façon dont nous pouvons l'implémenter pour fonctionner en conjonction avec nos propres pages de menu..

En attendant, passez en revue les articles précédents de cette série et n'oubliez pas de commander la version actuelle de WordPress Settings Sandbox sur GitHub..

Ressources associées

Nous avons couvert pas mal de ressources dans cet article. Voici un résumé de tout ce que nous avons utilisé:

add_menu_page
add_submenu_page
add_plugins_page
add_theme_page
Paramètres WordPress Sandbox

Code