Création d'un plugin d'événements à venir dans WordPress Création du widget

Dans la dernière partie de la série, nous avons envisagé d’enregistrer un type de publication personnalisé pour les événements. Nous avons personnalisé le tableau de bord en ajoutant une métabox personnalisée et des méta-champs personnalisés pour la saisie de données d'événement. Pour faciliter la saisie des dates par l'utilisateur, nous avons également incorporé le contrôle datepicker de l'interface utilisateur jQuery dans le tableau de bord..

Bien que WordPress affiche uniquement le titre et la colonne de date pour le type de message personnalisé dans l'écran de post-administrateur, nous avons ajouté nos propres colonnes personnalisées pour afficher la date de début de l'événement, la date de fin et le lieu de l'événement. Ce faisant, nous avons complété la majeure partie de notre plugin des événements à venir.

Dans la dernière partie de cette série, nous allons:

regardez l'API de widgets WordPress
enregistrer un widget pour afficher une liste des événements à venir
interroger la base de données pour les événements à venir à l'aide de la classe WP_Query
faire une méta-requête pour comparer les dates afin que seuls les événements à venir se présentent

Nous allons plonger dans le processus de construction d'un widget WordPress à partir de zéro.

API WordPress Widgets

Nous pouvons considérer les widgets comme des blocs de code destinés à ajouter certaines fonctionnalités à un site. Cela peut être un calendrier, des boutons de partage social, un système de classement ou un curseur de témoignage. Un utilisateur peut facilement les ajouter ou les supprimer du site en les faisant simplement glisser.

Les widgets WordPress peuvent être créés en étendant la WP_Widget classe fournie par WordPress. Cette classe contient les méthodes et propriétés nécessaires pour faire fonctionner un widget. Cela inclut des fonctions permettant d’initialiser un widget, d’afficher l’interface utilisateur dans l’administrateur, de mettre à jour leurs différentes instances, d’enregistrer les nouveaux paramètres dans la base de données et de les afficher sur la fin de la police..

Nous allons étendre quatre fonctions de la classe de base pour définir les fonctionnalités de notre widget:

__construction()
forme()
mettre à jour()
widget ()

Ayons un aperçu de chacun d'eux:

__construction()

le __construction() La méthode initialise le widget. Il configure le nom du widget, son identifiant de base et d'autres informations telles que la description et la classe du widget, etc..

forme()

C’est la fonction qui sort le formulaire de paramètres dans le tableau de bord. Le formulaire peut inclure des champs pour diverses options afin de personnaliser l'apparence et les fonctionnalités du widget sur le front-end. le forme() méthode accepte un argument pour l'instance du widget.

mettre à jour()

Cette méthode permet de s'assurer que le widget est mis à jour chaque fois qu'un nouveau paramètre est appliqué à une instance du widget. Il accepte deux arguments: un pour l'ancienne instance et un pour la nouvelle instance du widget..

widget ()

Cette méthode renvoie le contenu du widget sur le front-end du site. C’est là que nous définissons ce que les utilisateurs sont censés voir lorsqu’ils visitent le site. Cette méthode accepte deux arguments:

$ widget_args: Ceci est un tableau contenant les informations nécessaires sur le widget
$ instance: L'instance du widget à afficher

Nous examinerons de plus près ces méthodes et leurs arguments dans un instant. Pour l'instant, enregistrons notre classe de widgets.

Enregistrement du widget

Dans le dossier racine du plugin, créez un nouveau répertoire nommé inc pour comprend. Dans ce répertoire, créez un fichier nommé widget-coming-events.php. Nous allons écrire tout notre code de widget dans ce fichier pour garder les choses propres et gérables.

Nous allons commencer par étendre la classe du widget parent comme suit:

Pour enregistrer le widget, nous allons utiliser le register_widget () fonctionner en conjonction avec le widgets_init crochet:

fonction uep_register_widget () register_widget ('Upcoming_Events');  add_action ('widgets_init', 'uep_register_widget');

le register_widget () fonction accepte le nom de la classe étendue comme argument.

À l'intérieur de Évènements à venir classe, nous allons définir nos quatre méthodes sur celles que nous avons examinées dans la section précédente:

Dans la prochaine étape, nous écrirons du code pour chacun d’entre eux et examinerons de plus près leur fonctionnement. Mais avant cela, ajoutez la ligne de code suivante à la fin de coming-events.php fichier plugin principal pour inclure le widget:

include ('inc / widget-coming-events.php');

le `__construction()` Méthode

Si vous avez une formation en programmation orientée objet, vous savez certainement ce que sont les constructeurs. Pour les débutants, les constructeurs sont des fonctions spéciales dans une classe qui sont automatiquement appelées lorsqu'un objet de cette classe est instancié..

Puisque nous avons une classe pour un widget, nous avons besoin d’une fonction qui configure certaines choses comme l’id et le nom du widget chaque fois que ce widget est instancié et c’est là que le __construction() la méthode entre en jeu.

le __construction() La méthode de la classe parente accepte trois arguments:

$ base_id: L'identifiant unique du widget
$ title: Le titre du widget dans la zone d'administration. Devrait être marqué pour traduction
$ widget_ops: Un tableau contenant d'autres options de widget telles que la classe de widget et sa description, etc.

Maintenant que nous savons quoi __construction() et ce qu’il accepte comme arguments, écrivons du code pour cela:

fonction publique __construct () $ widget_ops = array ('class' => 'uep_upcoming_events', 'description' => __ ('Un widget pour afficher une liste des événements à venir', 'uep')); parent :: __ construct ('uep_upcoming_events', // id base __ ('Evénements à venir', 'uep'), // title $ widget_ops);

dans le __construction() méthode de notre widget, nous avons fait un appel à la __construction() méthode de la classe parente notée par parent :: __ construct () et passé trois arguments pour les options de base id, title et widget. Notez également que les chaînes sont marquées pour la traduction en utilisant le __ () une fonction.

le `forme()` Méthode

le forme() La méthode consiste à définir le corps de notre widget à afficher dans l’administrateur de WordPress. Il accepte un argument $ instance pour l'instance du widget.

Nous devons fournir à l'utilisateur un champ de texte pour saisir le titre du widget. En outre, il devrait pouvoir choisir entre le nombre d'événements qu'il souhaite afficher sur le site. Mais ces champs doivent aussi avoir des valeurs par défaut au cas où l'utilisateur ne voudrait pas entrer ses propres.

Tout d'abord, nous allons définir les valeurs par défaut pour nos champs:

$ widget_defaults = array ('title' => 'Evénements à venir', 'number_events' => 5); $ instance = wp_parse_args ((tableau) $ instance, $ widget_defaults);

Nous avons défini nos valeurs par défaut dans un tableau avec des clés comme noms de champs. Nous avons ensuite utilisé le wp_parse_args () fonction utilitaire qui fusionne un tableau d'arguments (dans notre cas - $ instance) avec un tableau de valeurs par défaut (dans ce cas - $ widget_defaults). Notez également que nous avons typecast le $ instance comme un tableau.

Il est temps de rendre les champs de formulaire pour le titre et le nombre d'événements. Commençons par créer un champ de texte pour le titre:

Tout d’abord, nous avons créé un paragraphe en tant qu’élément conteneur (bien que vous puissiez tout aussi facilement div). Ensuite, nous avons créé une étiquette pour le champ de saisie. Nous n'avons pas besoin de lui attribuer un identifiant manuellement, car WordPress s'en occupera tout seul. Il nous fournit des fonctions utilitaires pour mieux travailler avec les noms de champs et les identifiants. Il générera un identifiant et un nom uniques pour chaque champ du formulaire chaque fois que nous créerons une instance du widget, nous permettant ainsi de créer autant d'instances que du même widget..

La méthode utilisée pour générer l'identifiant de champ est get_field_id () précédé d'un $ this->, ce qui est une façon de dire que cette méthode appartient à la même classe. Cette méthode est déjà définie dans la base WP_Widget classe et depuis que nous l'avons étendue avec notre propre classe, il devient facilement disponible. La méthode accepte un argument pour le champ pour lequel nous générons un identifiant..

Nous avons marqué le texte de l'étiquette pour traduction en utilisant le _e () une fonction.

La méthode suivante que nous avons utilisée est get_field_name () qui fonctionne de la même manière que get_field_id () sauf qu'il génère une valeur pour l'attribut name du champ.

La classe large gras nous avons donné au champ de saisie une classe WordPress par défaut qui met en forme les champs de saisie dans l'administrateur WordPress.

Ensuite, pour l’attribut value du champ de saisie, nous avons simplement répercuté le contenu de $ instance ['title'] en passant par le esc_attr () fonction pour encoder les caractères indésirables.

Pour que la liste déroulante select spécifie le nombre d’événements à afficher, ajoutez le code suivant dans forme() méthode:

Le code est à peu près le même que celui du champ de titre, sauf que nous avons exécuté une boucle pour créer les balises option. Pour vérifier si une option est actuellement sélectionnée, nous avons utilisé une autre fonction de l'utilitaire WordPress. choisi() qui compare deux valeurs données (dans ce cas - $ i et $ instance ['number_events']) et ajoute ensuite le choisi attribut à la balise d'option actuelle si les valeurs sont égales.

C'est tout sur le forme() méthode. Nous devons maintenant nous assurer que notre widget est mis à jour chaque fois qu'une nouvelle modification lui est appliquée.

le `mettre à jour()` Méthode

le mettre à jour() méthode permet de mettre à jour les valeurs gérées par un widget. Il accepte deux arguments $ old_instance et $ new_instance et retourne l'instance mise à jour du widget.

Le code est assez simple:

mise à jour de la fonction publique ($ new_instance, $ old_instance) $ instance = $ old_instance; $ instance ['title'] = $ new_instance ['title']; $ instance ['number_events'] = $ new_instance ['number_events']; return $ instance;

Ainsi, chaque fois que l'utilisateur modifie une instance du widget, le mettre à jour() méthode mettra à jour les paramètres dans la base de données afin de garder le widget mis à jour avec les nouveaux paramètres.

le `widget ()` Méthode

C’est la méthode la plus importante car elle affiche le contenu prévu sur le front-end du site. Il accepte deux arguments $ args et $ instance. le $ args tableau contient les éléments suivants:

$ name: Le nom de la barre latérale dans laquelle le widget est affiché
$ id: L'id de la barre latérale respectée
$ description: La description de la barre latérale
$ classe: La classe sidebar
$ before_widget: Le code HTML qui précéderait le widget. Pourrait être une balise d'ouverture de l'élément contenant
$ after_widget: Le code HTML qui viendrait après le widget. Généralement une balise de fermeture de l'élément conteneur
$ before_title: Le HTML qui sera placé avant le titre du widget
$ after_title: Le HTML précédé du titre du widget
$ widget_id: L'identifiant de cette instance particulière du widget. Ce n'est pas l'identifiant de base du widget
$ widget_name: Nom du widget tel que transmis lors de l'enregistrement du widget

Si vous avez déjà enregistré une barre latérale pour un thème WordPress, les huit premiers éléments du $ args tableau devrait vous sembler familier. Les deux derniers éléments sont spécifiques au widget.

Extraire le $ args tableau et appliquer le Titre du Widget filtrer vers le titre du widget:

widget de fonction publique ($ args, $ instance) extract ($ args); $ title = apply_filters ('widget_title', $ instance ['title']);

Il est maintenant temps de préparer la requête pour récupérer une liste d'événements. Nous allons utiliser le WP_Query classe à cet effet avec la méta requête:

$ query_args = array ('post_type' => 'event', 'posts_per_page' => $ instance ['number_events'], 'post_status' => 'publish', 'ignore_sticky_posts' => true, 'meta_key' => 'event -start-date ',' orderby '=>' meta_value_num ',' order '=>' ASC '); $ coming_events = new WP_Query ($ query_args);

Puisque nous voulons trier nos événements par ordre croissant en fonction de leur date de début, nous avons défini le meta_key au date de début de l'événement méta valeur de nos événements. Parallèlement à cela, nous avons dit à WordPress que nous comparons les chiffres ici (pas les chaînes) en définissant le commandé par à meta_value_num. Si vous définissez commandé par pour juste meta_value, WordPress fera la comparaison comme s'il comparait des chaînes et ce n'est pas ce que nous voulons.

La requête ci-dessus va extraire le nombre donné d'événements par ordre croissant par rapport à leurs dates de début. Mais nous voulons aussi filtrer les événements qui ont déjà passé, c'est-à-dire leur date de fin de l'événement La méta valeur est inférieure à l'horodatage actuel. Pour cela, nous allons passer une méta requête qui vérifiera leurs dates de fin:

$ meta_quer_args = array ('relation' => 'AND', array ('key' => 'event-end-date', 'value' => time (), 'compare' => '> =')); $ query_args = array ('post_type' => 'event', 'posts_per_page' => $ instance ['number_events'], 'post_status' => 'publish', 'ignore_sticky_posts' => true, 'meta_key' => 'event -start-date ',' orderby '=>' meta_value_num ',' order '=>' ASC ',' meta_query '=> $ meta_quer_args); $ coming_events = new WP_Query ($ query_args);

Dans le code ci-dessus, nous avons comparé le date de fin de l'événement la méta valeur doit être supérieure ou égale à l'horodatage actuel. Maintenant, seuls les événements avec leurs date de fin de l'événement méta valeurs supérieures à l’horodatage actuel, c’est-à-dire que les événements à venir seront récupérés.

Maintenant que nous avons récupéré les événements, commençons à cracher le contenu de notre widget:

echo $ before_widget; if ($ title) echo $ before_title. $ titre. $ after_title; ?>

"> à
-

"> Voir tous les événements

Le code ci-dessus doit être explicite: nous avons d’abord répété le contenu de $ before_widget comme une balise d'ouverture de l'élément contenant. Ensuite, nous avons vérifié si le widget avait un titre. Dans l'affirmative, nous l'avons imprimé en le passant entre $ before_title et $ after_title.

Après cela, nous avons parcouru en boucle les événements que nous avions récupérés - en imprimant leurs titres, extraits et autres informations telles que les dates et les lieux. À la fin, nous avons ajouté un lien vers leur page d’archive en utilisant la fonction get_post_type_archive_link () qui renvoie un lien permanent vers la page d'archive du type de message donné. Nous avons ensuite terminé notre widget en faisant écho à la $ after_widget balise de fermeture.

Écrivons quelques styles de base pour notre widget dans le css / style.css fichier:

.uep_event_entry margin-bottom: 21px;  .uep_event_entry h4 margin-bottom: 3px;  .uep_event_entry h4 a text-decoration: none; couleur: hériter;  .uep_event_entry .event_venue font-size: 0.9em; couleur: # 777777; poids de police: normal; style de police: italique;  .uep_event_entry p margin-bottom: 3px! important;  .uep_event_entry .uep_event_date taille de la police: 0.9em; couleur: # 777777;

Nous devons maintenant inclure ce fichier sur le serveur frontal, mais uniquement lorsque notre widget est actuellement activé. Nous allons vérifier si notre widget est actuellement affiché sur le front-end en utilisant le is_active_widget () fonction qui accepte quatre arguments et tous sont optionnels:

$ callback: Le rappel du widget à vérifier
$ widget_id: Identifiant du widget. Nécessaire pour vérifier
$ id_base: L'identifiant de base du widget tel que transmis dans le __construction() méthode
$ skip_inactive: S'il faut ignorer les widgets inactifs

Ajoutez le code suivant sous le uep_admin_script_style () fonctionner dans le coming-events.php fichier plugin principal:

function uep_widget_style () if (is_active_widget (",", 'uep_upcoming_events', true)) wp_enqueue_style ('événements-à venir', STYLES. 'événements-à-venir.css', faux, '1.0', 'tous');  add_action ('wp_enqueue_scripts', 'uep_widget_style');

Par conséquent, nous avons d'abord vérifié si le widget est actuellement actif. Si tel est le cas, nous avons mis la feuille de style dans la file wp_enqueue_style () une fonction.

C'est tout sur le widget () méthode. Nous avons créé avec succès un widget qui affiche une liste des événements à venir avec les autres informations associées..

Rinçage des règles de réécriture

Nous avons presque terminé notre plugin et le widget, mais nous avons toujours un petit problème - cliquez sur l'un des titres de l'événement et vous obtiendrez peut-être une "erreur de page introuvable". En effet, chaque fois que nous enregistrons un type de message via un plugin, nous devons effacer les règles de réécriture lors de l'activation du plugin pour que la structure permalink fonctionne correctement..

Vous pouvez faire fonctionner vos liens en modifiant la structure de permalien, mais ce n'est pas la solution idéale. donc, nous allons vider les règles de réécriture chaque fois que notre plugin a été activé.

Ajoutez le code suivant dans votre coming-events.php fichier:

fonction uep_activation_callback () uep_custom_post_type (); flush_rewrite_rules ();  register_activation_hook (__FILE__, 'uep_activation_callback');

Nous avons donc enregistré le crochet d’activation de notre plugin en utilisant le register_activation_hook () fonction qui accepte deux arguments:

fichier $: Le chemin du fichier de plugin principal
$ fonction: La fonction de rappel à exécuter chaque fois que le plugin est activé

Dans la fonction de rappel de notre hook, nous avons d’abord ajouté le type d’événement personnalisé à la base de données à l’aide de la fonction uep_custom_post_type () nous avions défini précédemment dans notre précédent tutoriel.

Nous avons ensuite vidé les règles de réécriture en utilisant le flush_rewrite_rules () une fonction. Maintenant, vous voudrez peut-être désactiver le plug-in et le réactiver pour vous assurer que les règles de réécriture ont été purgées. Ainsi, vos liens devraient maintenant fonctionner correctement et vous rediriger vers la page unique de l'événement..

Conclusion

Cela a été un autre long tutoriel dans lequel nous avons écrit beaucoup de code et examiné diverses fonctions de WordPress. Nous avons créé un widget WordPress à partir de zéro en étendant le parent WP_Widget et regardé les fonctions membres que cette classe fournit pour définir les fonctionnalités de notre widget. Nous avons également écrit une requête exploitant la puissance de WP_Query classe pour récupérer une liste d'événements filtrés par leurs méta-valeurs.

Avec cela, nous concluons également notre série en trois parties. J'espère que cette série aidera de nouveaux lecteurs qui débutent avec WordPress et ceux qui souhaitent améliorer leurs connaissances du développement de plugins et de widgets WordPress.

Vous pouvez accéder au code complet du plugin sur ma page GitHub. Vous trouverez ci-dessous des liens permettant d'explorer plus en profondeur les sujets abordés dans ce didacticiel:

API WordPress Widgets
Référence de classe: WP_Query
Maîtriser les métadonnées WordPress: Introduction aux métadonnées
Programmation orientée objet dans WordPress: Une introduction

Code