Share
Dans ce didacticiel, nous examinerons de près le widget texte WordPress pour découvrir le processus de créer un widget qui peut être ajouté à plusieurs emplacements de widgets.
Si vous connaissez les bases de la programmation en PHP, la création d'un widget WordPress n'est pas du tout difficile. J'ai déjà abordé les bases d'un précédent tutoriel, L'anatomie d'un plugin WordPress - c'est une bonne idée de vérifier celle-ci avant de continuer à lire, si vous n'avez pas encore construit de widget..
Bien que cette méthode de base de création de widget soit suffisante pour de nombreux plug-ins, elle présente toutefois un inconvénient majeur: le widget ne peut être ajouté qu'à un seul emplacement d'un blog..
Si vous ajoutez le widget à l'une des barres latérales, le bouton "Ajouter" du widget disparaît et le widget ne peut pas être ajouté à un autre emplacement avant de le supprimer du premier..
Dans certains cas, ce n'est pas un problème, car la nature du widget est qu'il ne s'affiche qu'une fois. Par exemple, il est tout à fait correct de ne répertorier les archives de blog que dans un seul emplacement de la présentation. Mais il existe de nombreux cas où plusieurs instances peuvent être très utiles. Un de ces exemples est le widget texte fourni avec WordPress..
Le widget Texte est un simple widget qui vous permet de spécifier un en-tête et un texte, autorisant également le format HTML, et en rendant le contenu dans la barre latérale du blog. En raison de cette simplicité, le widget peut être utilisé à diverses fins. Par exemple, dans l'image suivante - une capture d'écran de mon blog personnel - vous pouvez voir comment j'utilise le widget de texte dans la barre latérale en premier pour afficher un texte de bienvenue, puis à nouveau pour afficher des publicités au bas de la barre latérale. Dans la documentation WordPress, de tels widgets sont appelés "multi-widgets."
WordPress étant un projet open source, nous pouvons creuser dans le code source et l'utiliser comme référence pour nos propres projets. Pour ce tutoriel, cela signifie que nous pouvons examiner de plus près le widget Texte et voir comment il a été implémenté, en l’utilisant comme exemple pour transformer nos propres widgets en multi-widgets..
La première étape consiste à rechercher dans le code WordPress et à localiser le widget de texte. C'est une étape intéressante et je vous recommande de consulter d'autres fichiers ici et là pour avoir un aperçu général de ce qui se passe à l'intérieur de la plateforme de blogs..
Mais si vous ne pouvez pas attendre pour passer à l'action, voici où vous trouverez le code du widget:
Accentsconagua
wordpress / wp-includes / widgets.php Ouvrez le fichier et faites défiler l'écran jusqu'à la fin, vers la ligne 1958 (dans la version 2.7.1), puis là, caché au milieu du code source, vous trouverez un exemple de widget commenté et intitulé "Modèle pour plusieurs widgets (autorise plusieurs instances telles que le widget de texte)".
Au début, l'exemple de code peut sembler assez intimidant, nous allons donc le parcourir ligne par ligne, en donnant un sens aux idées autour desquelles le motif est construit. Les extraits de code dans ce didacticiel ont été copiés à partir du modèle d'exemple, mais j'ai apporté quelques petites modifications ici et là pour rendre le code plus facile à suivre (principalement le fractionnement de lignes longues en lignes plus courtes). Mis à part ces petits ajustements, le code source est exactement le même que vous trouverez en ouvrant widgets.php de la base de code WordPress.
Lorsque l'utilisateur appuie sur le bouton "Enregistrer les modifications" dans le menu Widgets, WordPress collecte les paramètres de formulaire de chaque widget répertorié dans les barres latérales et les envoie à chacun des widgets enregistrés. C’est cette fonctionnalité qui rend la création de plusieurs widgets possible: lorsque la fonction de contrôleur de widget est notifiée pour enregistrer une instance de widget, tous les paramètres lui sont transmis et il peut mettre à jour chaque instance de ce type de widget en ajoutant de nouveaux et enlever ceux qui ne sont pas utilisés au besoin.
Nous examinerons les détails du processus de sauvegarde dans un instant, mais tout d’abord, un bon point de départ pour examiner comment les données de widget pour un multi-widget est stockée est d’examiner la partie du code où les données sont utilisées. . Voici le code de la méthode utilisée pour afficher une instance du widget exemple:
$ widget_args); $ widget_args = wp_parse_args ($ widget_args, array ('number' => -1)); extraire ($ widget_args, EXTR_SKIP); // Les données doivent être stockées sous forme de tableau $ options = get_option ('widget_many'); if (! isset ($ options [$ number])) renvoie; echo $ before_widget; // Fait des choses pour ce widget, en tirant des données de $ options [$ number] echo $ after_widget; ?> Le premier paramètre transmis à la fonction de rendu de widget, $ args, contient des paramètres de widget génériques, tels que ce qui doit être imprimé avant et après le widget et la manière dont l'en-tête du widget doit être formaté. Le code de la ligne 3 permet de scinder cette information en variables locales, à partir desquelles $ before_widget et $ after_widget sont utilisés dans l'exemple.
Le second paramètre, $ widget_args est plus intéressant pour nous: il contient l’id de l’instance de widget à restituer. Les lignes 4 à 7 sont là pour s’assurer que le paramètre est dans un format correct, et qu’en fin de compte, extrait appeler sur la ligne 7, on peut trouver l'index du widget dans la variable locale numéro $.
Tout comme les paramètres de widget pour un widget simple et ponctuel, les paramètres d'une instance de widget sont stockés sous la forme d'un tableau contenant des paires clé-valeur pour chaque paramètre. Mais comme nous devons maintenant stocker plusieurs instances, au lieu de sauvegarder chaque tableau avec son propre appel à update_option, nous les mettons tous dans un tableau en utilisant l'identifiant d'instance (numéro $) comme index puis enregistrez le tout avec l'identifiant du type de widget.
Dans l'exemple ci-dessus, nous avons un widget nommé "widget_many", et disons que nous en avons ajouté trois à notre barre latérale de blog. Lors du rendu de l'une d'entre elles, nous obtenons d'abord un tableau contenant toutes les widget_many instances en appelant get_option ('widget_many'); (ligne 10) puis recherchez les données de l'instance actuelle à partir de ce tableau (ligne 16).
L'exemple de code de ne montre pas les spécificités de ce que vous devez faire avec les données. Voyons donc le widget de texte lui-même pour plus d'informations:
$ widget_args); $ widget_args = wp_parse_args ($ widget_args, array ('number' => -1)); extraire ($ widget_args, EXTR_SKIP); $ options = get_option ('widget_text'); if (! isset ($ options [$ number])) renvoie; $ title = apply_filters ('widget_title', $ options [$ number] ['title']); $ text = apply_filters ('widget_text', $ options [$ number] ['text']); ?> Aux lignes 13 et 14, vous pouvez voir comment les deux paramètres nécessaires au widget texte sont lus à partir des options à l'aide de numéro $ comme identifiant d'instance. Et sur les dix lignes suivantes, les paramètres sont affichés à l'écran.
En analysant la fonction de rendu des widgets, nous avons maintenant découvert les bases pour sauvegarder les données d’un multi-widget:
Maintenant, nous allons regarder de plus près et voir les astuces et mises en garde impliquées.
En utilisant la même approche qu'auparavant, nous allons maintenant examiner la fonction utilisée pour afficher et gérer les formulaires de paramètres et la parcourir ligne par ligne. Cette fonction, widget_many_control, est la fonction qui enregistre les paramètres et rend le formulaire de paramètres pour le widget exemple "widget_many". On l'appelle une fois pour chaque widget_many exemple, en passant toujours l'identifiant d'instance dans $ widget_args.
Comme la fonction fait partie du traitement de la soumission du formulaire, le $ _POST tableau contiendra tous les paramètres qui ont été envoyés en utilisant le formulaire d'édition de widget.
$ widget_args); $ widget_args = wp_parse_args ($ widget_args, array ('number' => -1)); extraire ($ widget_args, EXTR_SKIP); Sur les premières lignes de la fonction, vous verrez quelque chose de familier (lignes 6 à 9). Ceci est le même morceau de code qui a été utilisé dans la fonction de rendu pour vous assurer que numéro $ a été initialisé avec l'identifiant numérique de l'instance de widget en cours.
Mais comme vous le remarquerez bientôt, nous n'aurons plus besoin de cet index que de rendre le formulaire d'édition du widget, car nous enregistrons toujours toutes les occurrences du type de widget "widget_many" dans une boucle..
Ensuite, nous allons récupérer les paramètres actuels du widget, en les créant s'ils n'existent pas:
$ options = get_option ('widget_many'); if (! is_array ($ options)) $ options = array (); Lorsque vous implémentez votre propre widget, n'oubliez pas de changer la clé, widget_many à l'identifiant de votre propre widget. En dehors de cela, ce code peut être réutilisé tel quel. Aux lignes 2 et 3, le code prend en charge le cas lorsque nous ajoutons la première instance de widget de ce type en créant un tableau d'options vide à utiliser..
Si les paramètres ont déjà été enregistrés au moins pour une instance, nous les obtenons de get_option et peut continuer à mettre à jour les paramètres si un formulaire a été soumis:
if (! $ updated &&! empty ($ _ POST ['sidebar'])))
La ligne ci-dessus a deux fonctions: Elle vérifie si les données ont été enregistrées ("!vide ($ _ POST ['sidebar'])") et veille à ce que les instances de ce type de widget ne soient gérées qu'une seule fois.
Le système de widgets appelle la fonction de gestion des widgets une fois par instance de widget, mais comme nous devons nous occuper d'éléments tels que l'ajout et la suppression de nouvelles instances de widgets, nous ne pouvons pas le faire sans connaître tous les widgets existants. C’est la raison pour laquelle l’approche consiste à mettre à jour chaque instance de widget de ce type lors de la première occurrence, puis à définir la variable globale. $ mis à jour à true pour que l'instance suivante ne refasse plus la mise à jour.
// nous dit quelle barre latérale mettre les données dans $ sidebar = (chaîne) $ _POST ['sidebar']; $ sidebars_widgets = wp_get_sidebars_widgets (); if (isset ($ sidebars_widgets [$ sidebar])) $ $ this_sidebar = & $ sidebars_widgets [$ sidebar]; else $ this_sidebar = array (); foreach ($ this_sidebar as $ _widget_id) $ widget = $ wp_registered_widgets [$ _ widget_id]; if ('widget_many' == $ widget ['callback'] && isset ($ widget ['params'] [0] ['numéro'])) $ widget_number = $ widget ['params'] [0] [' nombre']; if (! in_array ("many- $ widget_number", $ _POST ['widget-id'])) unset ($ options [$ widget_number]); // Compiler les données de $ widget_many_instance $ widget_data = (tableau) $ _POST ['widget-many']; foreach ($ widget_data as $ widget_number => $ widget_many_instance) if (! isset ($ widget_many_instance ['quelque chose'])) && isset ($ options [$ widget_number])) // utilisateur cliqué annuler, continuer; $ quelque chose = wp_specialchars ($ widget_many_instance ['quelque chose']); $ options [$ widget_number] = array ('quelque chose' => $ quelque chose); update_option ('widget_many', $ options); $ updated = true; // Pour que nous ne passions pas cela plus d'une fois Cet extrait de code recherche d'abord tous les widgets stockés dans la barre latérale en cours de mise à jour (lignes 2 à 8), puis parcourt la liste en supprimant tout ce qui correspond à l'identifiant du widget de ce type de widget (lignes 10 à 18)..
$ _POST ("sidebar") (ligne 2) contient l'identifiant de la barre latérale. Ainsi, si l'utilisateur a supprimé un widget, celui-ci sera également supprimé des données. Et en supprimant tout, nous nous assurons de ne pas laisser accidentellement des doublons, par exemple si l'identifiant d'un widget a changé entre les mises à jour..
Après avoir tout supprimé, nous commençons à ajouter les widgets postés par l'utilisateur. Dans le formulaire posté, il y a un tableau contenant toutes les données pour chaque instance du type de widget. Le tableau est organisé comme ceci:
['widget-many'] => [0] => paramètres pour l'instance de widget 0 (tableau), [1] => paramètres pour l'instance de widget 1 (tableau),…
Sur les lignes 23 à 31, le code parcourt les données d'instance de widget soumises et crée les paramètres pour chaque instance (lignes 29 et 30). Comme il ne s'agit que d'un exemple de code, la partie sauvegarde utilise des données de substitution telles que "quelque chose". Alors, regardons à nouveau le widget texte pour voir comment cela fonctionne avec des données réelles:
$ title = strip_tags (stripslashes ($ widget_text ['title'])); if (current_user_can ('unfiltered_html')) $ text = stripslashes ($ widget_text ['text']); else $ text = stripslashes (wp_filter_post_kses ($ widget_text ['text'])); $ options [$ widget_number] = compact ('title', 'text'); Le widget texte a deux paramètres: Titre et texte. le $ widget_text variable dans ce morceau de code est utilisé de la même manière que $ widget_many_instance dans l'exemple de code que nous avons suivi: il contient les données publiées pour une instance spécifique du widget.
Dans l'exemple de widget texte, vous verrez également certaines fonctionnalités de sécurité intéressantes que vous voudrez peut-être examiner un peu plus lors du développement de vos propres widgets. Pour ce tutoriel, cependant, il suffit de voir que le contenu des variables $ title et $ text sont lus à partir du tableau posté, puis stockés sous forme de tableau dans les options du widget à la ligne 6.
Si vous vous interrogez sur le compact() fonction, c'est l'opposé de extrait(), et prend les variables locales dont les noms ont été passés en tant que paramètres et les transforme en un tableau avec les noms comme clés.
Enfin, la nouvelle $ options tableau est stocké en tant que données pour le widget, widget_many dans l'exemple de code ou widget_text dans le widget de texte, en utilisant le update_option () une fonction.
La dernière chose qui reste dans la fonction des paramètres du widget est de dessiner le formulaire pour cette instance de widget. Ce formulaire n'est pas affiché à l'écran tel quel, mais WordPress le convertit en un formulaire réel ultérieurement, en utilisant un peu de magie JavaScript. Le code ci-dessous provient du code du modèle, il utilise donc $ quelque chose pour représenter les données du widget. Dans le widget texte, il est remplacé par $ title et $ text, et dans votre propre widget avec tout ce dont vous avez besoin pour enregistrer.
Il est important de noter que, bien que la sauvegarde soit effectuée pour chaque instance à la fois, le formulaire présenté ici ne concerne qu'une instance. C’est là que nous utiliserons l’ID d’instance de widget lu au début de la fonction..
if (-1 == $ nombre) $ quelque chose = "; $ nombre = '% i%'; autre $ quelque chose = attribut_escape ($ options [$ nombre] ['quelque chose']);
Sur les lignes ci-dessus, le widget vérifie d'abord si un numéro de widget valide a été attribué ou non. Si non, et numéro $ a été défini sur la valeur par défaut, -1, toutes les données doivent être définies sur les valeurs par défaut. Sinon, nous obtiendrons les données du $ options tableau et utilisez-le pour remplir le formulaire avec les paramètres actuels. C'est une bonne chose à faire pour que l'utilisateur n'ait pas à toujours commencer à éditer le widget à partir d'une ardoise vide..
Et puis, le formulaire lui-même est construit de manière à pouvoir être lu dans un tableau lorsqu'il est envoyé au code de gestion du widget: Les entrées de formulaire sont nommées en fonction du modèle widget-many [$ number] [quelque chose] où numéro $ est le numéro de cette instance de widget et quelque chose est le nom du paramètre à sauvegarder. WordPress analyse ensuite cela dans la structure de tableau décrite précédemment lorsque l'utilisateur soumet le formulaire.
Le formulaire ne comporte pas de bouton d'envoi, car tous les widgets sont enregistrés à l'aide du même bouton d'envoi fourni par WordPress..
Pour que WordPress affiche un widget dans la liste des widgets, vous devez l'enregistrer en indiquant à WordPress quelles fonctions utiliser pour rendre le widget et son formulaire de paramètres. La façon dont cela est fait pour les multi-widgets n'est pas si différente des widgets ordinaires. La seule différence réside dans la définition de l'identifiant du widget: $ control_ops (ligne 7), nous demandons à WordPress d'activer plusieurs instances et d'attacher toutes les instances de widgets avec un identifiant commençant par "beaucoup" à ce type de widget.
fonction widget_many_register () if (! $ options = get_option ('widget_many')) $ options = array (); $ widget_ops = array ('classname' => 'widget_many', 'description' => __ ('Widget permettant plusieurs instances')); $ control_ops = array ('width' => 400, 'height' => 350, 'id_base' => 'many'); $ name = __ ('Many'); $ registered = faux; foreach (array_keys ($ options) comme $ o) // Les anciens widgets peuvent avoir des valeurs nulles pour une raison quelconque si (! isset ($ options [$ o] ['quelque chose'])) continue; // $ id devrait ressembler à $ id_base - $ o $ id = "many- $ o"; // Jamais jamais jamais traduire un identifiant $ registered = true; wp_register_sidebar_widget ($ id, $ name, 'widget_many', $ widget_ops, array ('number' => $ o)); wp_register_widget_control ($ id, $ name, 'widget_many_control', $ control_ops, array ('number' => $ o)); // S'il n'y en a pas, nous enregistrons // l'existence du widget avec un modèle générique if (! $ Registered) wp_register_sidebar_widget ('many-1', $ name, 'widget_many', $ widget_ops, array ('number' = > -1)); wp_register_widget_control ('plusieurs-1', $ nom, 'widget_many_control', $ control_ops, array ('nombre' => -1); // C'est important add_action ('widgets_init', 'widget_many_register'); Dans la fonction ci-dessus, nous enregistrons d’abord tous les widgets existants de ce type, en ignorant ceux qui n’ont pas de données valides (lignes 11 à 23), puis s’il n’ya pas d’instance disponible, en enregistrons une par défaut pour nous assurer que le widget est enregistré et disponible dans la barre latérale (lignes 27 à 32).
Dernière étape cruciale, à la ligne 34, nous associons la fonction d’initialisation du widget à la widgets_init afin que WordPress l’appelle au moment de l’initialisation de tous les widgets. Sans cette fonction, nous ne verrions aucune des fonctionnalités du widget que nous venons d'analyser car aucune partie du code ne serait appelée.
Dans les extraits ci-dessus, j'ai délibérément laissé une partie du code pour rendre les choses plus lisibles. Vous ne pourrez donc pas simplement copier les éléments et les assembler. Au lieu de cela, vous devriez aller copier ce même code à partir de votre installation WordPress.
Après cela, il vous suffit de mettre votre propre fonctionnalité, et voilà: votre propre multi-widget.
