Share
Il s’agit de la troisième partie d’une série d’articles traitant de la meilleure façon pour votre plugin ou votre thème de s’intégrer à l’interface utilisateur de l’administrateur de WordPress. Dans cette partie, nous allons voir comment utiliser les "pointeurs administratifs" de WordPress dans vos plugins..
Les pointeurs administratifs sont apparus pour la première fois dans la version 3.3 et étaient destinés à mettre en évidence quelques-unes des nouvelles fonctionnalités de chaque version majeure (le personnalisateur de thème dans la version 3.4, par exemple)..
Utilisés correctement, ils peuvent attirer efficacement l'attention sur les dernières fonctionnalités que vous avez ajoutées..
Avertissement: Les pointeurs administratifs en sont encore à leurs débuts - et il est possible qu’ils changent. Si WordPress développe jamais une API publique - vous devriez l’adopter.
Une interface utilisateur décente n'est pas une infobulle gimmicky. En fait, un idéal l'interface utilisateur n'en aurait pas besoin. Ils sont très utiles pour signaler les nouvelles fonctionnalités occasionnelles, en particulier celles que votre utilisateur final a peut-être manquées. En cela, ils peuvent améliorer "l'expérience utilisateur", mais si vous les utilisez à d'autres fins, ou tout simplement en utilisez trop, alors vous le faites mal. Plutôt que d’améliorer le plugin pour l’utilisateur final, vous finirez par les frustrer.
Alors, combien est trop? N'oubliez pas que d'autres plugins seront installés et que chacun d'entre eux peut également utiliser (ou abuser) de ces pointeurs. WordPress aussi (évidemment) les utilise. Il serait intéressant de jauger l'opinion des gens à ce sujet, mais je n'en ajouterais moi-même pas plus de deux dans une mise à jour majeure (aucune sur une mise à jour mineure), et certainement pas plus d'une sur une page donnée..
Il est important de noter qu'en l'absence d'API principale, il n'est pas possible de gérer plusieurs pointeurs: si vingt pointeurs sont ajoutés à une page, vingt s'afficheront. Puisque vous ne savez pas ce que font les autres plugins - veuillez les utiliser avec parcimonie.
Lorsque vous utilisez des pointeurs d'administration dans un plugin ou un thème, il sera utile de pouvoir ajouter facilement et rapidement des pointeurs supplémentaires au fur et à mesure de l'évolution de votre plugin. À cette fin, nous allons créer une fonction d'assistance qui traitera du traitement interne des pointeurs. Il utilisera l’API très prisée de WordPress et déclenchera un filtre de la forme:
wptuts_admin_pointers_ screen-id
Où screen-id est l'ID de la page en cours de visualisation. Pour ajouter un pointeur sur la page d'édition, par exemple, nous attacherions sur le filtre:
wptuts_admin_pointers_post
De cette façon, nous pouvons ajouter des pointeurs supplémentaires, avec un code minimal. Le rôle de cette fonction d'assistance sera de créer un tableau de pointeurs qui sera imprimé sur la page d'administration sous la forme d'un tableau d'objets JavaScript - chaque objet correspondant à un pointeur. Chaque objet pointeur contient les paramètres suivants:
Accentsconagua
pointeur_id - un identifiant unique pour le pointeur. Une bonne idée est d’inclure la version pour laquelle elle est pertinente. Il ne doit contenir que des caractères alphanumériques, des traits de soulignement et des tirets minuscules..cible - un sélecteur pour la cible du pointeur, c'est-à-dire vers quoi il pointe (par exemple. #some_id, ou .une classe)options - Ceci est un tableau d'options. Nous pouvons utiliser cela pour modifier complètement l'apparence et le comportement du pointeur, mais pour nos besoins, nous devons uniquement prendre en compte les éléments suivants: le contenu (le texte qui apparaît dans le pointeur) et la position. La propriété de position est déterminée par:
bord - quel bord (gauche, droite, haut, bas) doit être adjacent à la cible.aligner - comment le pointeur doit être aligné sur ce bord, par rapport à la cible (haut, bas, gauche, droite, milieu).Un objet de pointeur typique pourrait être de la forme:
pointeur_id: 'xyz_v110', cible: '#some_id', options: contenu: 'Nouvelle fonctionnalité: xyz
Lorem ipsum dolor sit amet…
', position: edge:' left ', aligner:' top '
Une fois que les objets de pointeur sont imprimés sur la page d'administration, nous pouvons utiliser le widget de pointeur WordPress défini ici..
Comme indiqué dans la section précédente, l'objectif général de notre fonction est d'imprimer des objets JavaScript sur la page et de charger un script personnalisé. Donc, notre fonction d'assistance sera accrochée à la wp_enqueue_scripts action (bien que nous puissions l'appeler plus tard).
add_action ('admin_enqueue_scripts', 'wptuts_pointer_load'); function wptuts_pointer_load ($ hook_suffix) // La fonction d'assistance va ici Rappelez-vous que si vous utilisez ce code dans un plugin ou un thème, vous devez renommer la fonction en veillant à ce qu'elle soit unique et préfixez-la de préférence avec le nom de votre plugin ou de votre thème. La première partie de cette fonction filtre un tableau vide en utilisant le hook wptuts_admin_pointers- screen_id. Cela nous permet d’ajouter des pointeurs dans ce tableau. Si rien n'est ajouté, nous nous arrêtons.
// Ne pas courir sur WP < 3.3 if ( get_bloginfo( 'version' ) < '3.3' ) return; // Get the screen ID $screen = get_current_screen(); $screen_id = $screen->id; // Récupère les pointeurs pour cet écran $ pointers = apply_filters ('wptuts_admin_pointers-'. $ Screen_id, array ()); // Pas de pointeur? Puis nous nous arrêtons. if (! $ pointers ||! is_array ($ pointers)) return; Désormais, ces pointeurs peuvent inclure ceux que l'utilisateur a vus auparavant et «congédiés». Nous ne souhaitons pas que ces utilisateurs apparaissent à nouveau pour cet utilisateur. Nous allons ensuite obtenir un tableau de pointeurs qu'ils ont déjà vu et fermé et les supprimer de notre tableau. Nous effectuons également des contrôles de cohérence sur nos pointeurs:
// Récupère les pointeurs renvoyés $ licencié = explode (',', (chaîne) get_user_meta (get_current_user_id (), 'licencié_wp_pointers', true)); $ valid_pointers = array (); // Vérifie les pointeurs et supprime ceux qui sont renvoyés. foreach ($ pointeurs comme $ pointer_id => $ pointeur) // Contrôle de santé si (in_array ($ pointeur_id, $ exclu)) || vide ($ pointeur) || vide ($ pointeur_id) || vide ($ pointeur ['cible ']) || empty ($ pointeur [' options '])) continue; $ pointer ['pointer_id'] = $ pointer_id; // Ajoute le pointeur au tableau $ valid_pointers $ valid_pointers ['pointers'] [] = $ pointeur; // Aucun pointeur valide? Arrêtez ici. if (vide ($ valid_pointers)) return; Enfin, nous mettons en file d'attente les scripts et les styles nécessaires, et imprimons les pointeurs valides vers la page, en utilisant wp_localize_script.
// Ajoute un style de pointeurs à la file d'attente. wp_enqueue_style ('wp-pointeur'); // Ajoute un script de pointeurs et notre propre script personnalisé à la file d'attente. wp_enqueue_script ('wptuts-pointer', plugins_url ('js / wptuts-pointer.js', __FILE__), array ('wp-pointer')); // Ajoute des options de pointeur au script. wp_localize_script ('wptuts-pointer', 'wptutsPointer', $ valid_pointer); add_action ('admin_enqueue_scripts', 'wptuts_pointer_load', 1000); function wptuts_pointer_load ($ hook_suffix) // Ne fonctionne pas sur WP < 3.3 if ( get_bloginfo( 'version' ) < '3.3' ) return; $screen = get_current_screen(); $screen_id = $screen->id; // Récupère les pointeurs pour cet écran $ pointers = apply_filters ('wptuts_admin_pointers-'. $ Screen_id, array ()); if (! $ pointers ||! is_array ($ pointers)) return; // Récupère les pointeurs renvoyés $ licencié = explode (',', (chaîne) get_user_meta (get_current_user_id (), 'licencié_wp_pointers', true)); $ valid_pointers = array (); // Vérifie les pointeurs et supprime ceux qui sont renvoyés. foreach ($ pointeurs comme $ pointer_id => $ pointeur) // Contrôle de santé si (in_array ($ pointeur_id, $ exclu)) || vide ($ pointeur) || vide ($ pointeur_id) || vide ($ pointeur ['cible ']) || empty ($ pointeur [' options '])) continue; $ pointer ['pointer_id'] = $ pointer_id; // Ajoute le pointeur au tableau $ valid_pointers $ valid_pointers ['pointers'] [] = $ pointeur; // Aucun pointeur valide? Arrêtez ici. if (vide ($ valid_pointers)) return; // Ajoute un style de pointeurs à la file d'attente. wp_enqueue_style ('wp-pointeur'); // Ajoute un script de pointeurs à la file d'attente. Ajouter un script personnalisé. wp_enqueue_script ('wptuts-pointer', plugins_url ('js / wptuts-pointer.js', __FILE__), array ('wp-pointer')); // Ajoute des options de pointeur au script. wp_localize_script ('wptuts-pointer', 'wptutsPointer', $ valid_pointers); Le script est très simple, car le widget de pointeur effectue la majeure partie du travail. En ce qui concerne ce pointeur, tout ce que nous avons vraiment besoin de définir est ce qui se passe lorsque le pointeur est congédié. En particulier, nous envoyons une requête ajax avec l'action 'licenciement-wp-pointeur'et le pointeur à définir sur l'identificateur unique que nous spécifions lors de l'ajout du pointeur.
jQuery (document) .ready (function ($) wptuts_open_pointer (0); fonction wptuts_open_pointer (i) pointer = wptutsPointer.pointers [i]; options = $ .extend (pointer.options, close: function () $ .post (ajaxurl, pointer: pointer.pointer_id, action: 'rejet-wp-pointer');); $ (pointer.target) .pointer (options) .pointer ('open');) ; C’est tout le code qu’il faut ajouter puisque WordPress gère la requête ajax.
Comme promis, l'ajout de pointeurs est très facile. Pour ajouter un pointeur sur l'écran 'post', par exemple:
add_filter ('wptuts_admin_pointers-post', 'wptuts_register_pointer_testing'); fonction wptuts_register_pointer_testing ($ p) $ p ['xyz140'] = array ('target' => '# change-permalinks', 'options' => array ('content' => sprintf (' % s
% s
', __ (' Title ',' plugindomain '), __ (' Lorem ipsum dolor sit amet, consectetur adipiscing elit. ',' Plugindomain ')),' position '=> array (' edge '=>' top ', 'align' => 'middle'))); retourne $ p; Remarque: Lorsqu’il stocke le pointeur rejeté, WordPress transmet l’ID du pointeur à sanitize_key - Veillez donc à n'utiliser que des caractères alphanumériques, des tirets et des traits de soulignement minuscules..
