Share
Dit is deel 3 van een reeks artikelen waarin wordt gekeken hoe uw plug-in of thema het best kan worden geïntegreerd in de gebruikersinterface van WordPress admin. In dit deel gaan we bekijken hoe u WordPress "admin pointers" in uw plug-ins kunt gebruiken.
Adminpointers verschenen voor het eerst in 3.3 en waren bedoeld om slechts een paar van de nieuwe functies te markeren die bij elke belangrijke release horen (bijvoorbeeld de themaspeciaalmaker in 3.4).
Bij correct gebruik kunnen deze zeer effectief zijn om de aandacht te vestigen op de nieuwste functies die u hebt toegevoegd.
Disclaimer: De beheerders wijzen nog steeds in de vroege stadia van hun leven - en er is de mogelijkheid dat ze kunnen veranderen. Als WordPress core ooit een openbare API ontwikkelt, moet u dat aannemen.
Een fatsoenlijke gebruikersinterface is geen zinvolle tooltip. Sterker nog, een ideaal gebruikersinterface zou dit niet nodig hebben. Ze zijn erg handig om te wijzen op de occasionele nieuwe functie, met name die waarvan uw eindgebruiker mogelijk heeft gemist. Hierin kunnen ze de 'gebruikerservaring' verbeteren, maar als je ze voor een ander doel gebruikt, of gewoon te veel gebruikt, dan doe je het verkeerd. In plaats van de plug-in voor de eindgebruiker te verbeteren, zult u ze uiteindelijk frustreren.
Dus hoeveel zijn er te veel? Vergeet niet dat er andere plug-ins zullen zijn geïnstalleerd en dat deze mogelijk ook deze aanwijzingen gebruiken (of misbruiken). WordPress gebruikt ze ook (uiteraard). Het zou interessant zijn om de mening van mensen hierover te peilen, maar ik zou er zelf niet meer dan twee toevoegen aan een belangrijke update (geen voor kleine), en zeker niet meer dan één op een gegeven pagina..
Belangrijk is dat zonder een kern-API er geen manier is om meerdere aanwijzers te beheren: als er twintig aan één pagina worden toegevoegd, worden er twintig weergegeven. Omdat je niet weet wat andere plug-ins doen - gebruik ze alstublieft spaarzaam.
Wanneer u admin pointers gebruikt in een plug-in of een thema, is het handig om gemakkelijk en snel extra verwijzingen toe te voegen terwijl uw plug-in evolueert. Hiertoe gaan we een helperfunctie maken die zich bezighoudt met de interne afhandeling van de aanwijzers. Het maakt gebruik van de populaire hook API van WordPress en activeert een filter van het formulier:
wptuts_admin_pointers_ screen-id
Waar Screen-id is de ID van de pagina die wordt bekeken. Als u bijvoorbeeld een aanwijzer aan de pagina voor het bewerken van berichten wilt toevoegen, nemen we het filter op:
wptuts_admin_pointers_post
Op deze manier kunnen we extra verwijzingen toevoegen, met minimale code. De rol van deze hulpfunctie is om een reeks aanwijzers te maken die naar de beheerpagina worden afgedrukt als een reeks JavaScript-objecten - waarbij elk object overeenkomt met één aanwijzer. Elk pointer-object bevat de volgende parameters:
Accentsconagua
pointer_id - een unieke ID voor de aanwijzer. Een goed idee is om de versie op te nemen waarvoor deze relevant is. Dit mag alleen alfanumerieke tekens, onderstrepingstekens en streepjes bevatten.doelwit - een selector voor het doelwit van de aanwijzer, d.w.z. waarnaar het wijst (bijv. #some_id, of .sommige-klasse)opties - Dit zijn een reeks opties. We kunnen dit gebruiken om volledig te veranderen hoe de aanwijzer eruitziet en zich gedraagt, maar voor onze doeleinden moeten we alleen het volgende in overweging nemen: inhoud (de tekst die in de aanwijzer verschijnt) en positie. De eigenschap position wordt bepaald door:
rand - welke rand (links, rechts, boven, onder) naast het doel moet zijn.richten - hoe de wijzer op deze rand moet worden uitgelijnd ten opzichte van het doel (boven, onder, links, rechts, midden).Een typisch pointer-object kan de volgende vorm hebben:
pointer_id: 'xyz_v110', doel: '#some_id', opties: content: 'Nieuwe functie: xyz
Lorem ipsum dolor sit amet…
', positie: edge:' left ', align:' top '
Nadat de aanwijzerobjecten zijn afgedrukt naar de beheerpagina, kunnen we gebruik maken van de hier gedefinieerde WordPress-aanwijzingswidget.
Zoals besproken in de vorige sectie, is het algemene doel van onze functie om enkele JavaScript-objecten naar de pagina te printen en wat aangepast script te laden. Dus onze helperfunctie zal worden gekoppeld aan de wp_enqueue_scripts actie (hoewel we het later zouden kunnen noemen).
add_action ('admin_enqueue_scripts', 'wptuts_pointer_load'); functie wptuts_pointer_load ($ hook_suffix) // Helper-functie gaat hier Onthoud dat als u deze code gebruikt in een plug-in of een thema, u de functie moet hernoemen, zodat deze uniek is en bij voorkeur vooraf wordt gefixeerd met uw plug-in of themanaam. Het eerste deel van deze functie filtert een lege array met behulp van de haak wptuts_admin_pointers- screen_id. Dit stelt ons in staat om pointers toe te voegen aan die array. Als er niets wordt toegevoegd, stoppen we.
// Loop niet op WP < 3.3 if ( get_bloginfo( 'version' ) < '3.3' ) return; // Get the screen ID $screen = get_current_screen(); $screen_id = $screen->ID kaart; // Krijg verwijzingen voor dit scherm $ pointers = apply_filters ('wptuts_admin_pointers-'. $ Screen_id, array ()); // Geen aanwijzingen? Dan stoppen we. als (! $ pointers ||! is_array ($ pointers)) terugkeren; Nu kunnen deze verwijzingen die bevatten die de gebruiker eerder heeft gezien en zijn 'verwijderd'. We willen niet dat deze opnieuw verschijnen voor deze gebruiker, dus we krijgen hierna een aantal aanwijzingen die ze al hebben gezien en gesloten en verwijderen deze uit onze array. We voeren ook een aantal sanitaire controles uit op onze aanwijzingen:
// Krijg verworpen aanwijzers $ dismissed = ontploffen (',', (string) get_user_meta (get_current_user_id (), 'dismissed_wp_pointers', true)); $ valid_pointers = array (); // Controleer wijzers en verwijder verwijderde. foreach ($ pointers als $ pointer_id => $ pointer) // Sanity check if (in_array ($ pointer_id, $ dismissed) || empty ($ pointer) || empty ($ pointer_id) || empty ($ pointer ['target ']) || leeg ($ pointer [' options '])) ga verder; $ pointer ['pointer_id'] = $ pointer_id; // Voeg de aanwijzer toe aan $ valid_pointers array $ valid_pointers ['pointers'] [] = $ pointer; // Geen geldige verwijzingen? Stop hier. als (leeg ($ valid_pointers)) terugkomt; Ten slotte houden we de nodige scripts en stijlen in en drukken we de geldige verwijzingen naar de pagina af met behulp van wp_localize_script.
// Voeg pointers-stijl aan de wachtrij toe. wp_enqueue_style ('wp-pointer'); // Voeg pointers-script en ons eigen aangepaste script toe aan de wachtrij. wp_enqueue_script ('wptuts-pointer', plugins_url ('js / wptuts-pointer.js', __FILE__), array ('wp-pointer')); // Aanwijzeropties toevoegen aan script. wp_localize_script ('wptuts-pointer', 'wptutsPointer', $ valid_pointer); add_action ('admin_enqueue_scripts', 'wptuts_pointer_load', 1000); function wptuts_pointer_load ($ hook_suffix) // Niet uitvoeren op WP < 3.3 if ( get_bloginfo( 'version' ) < '3.3' ) return; $screen = get_current_screen(); $screen_id = $screen->ID kaart; // Krijg verwijzingen voor dit scherm $ pointers = apply_filters ('wptuts_admin_pointers-'. $ Screen_id, array ()); als (! $ pointers ||! is_array ($ pointers)) terugkeren; // Krijg verworpen aanwijzers $ dismissed = ontploffen (',', (string) get_user_meta (get_current_user_id (), 'dismissed_wp_pointers', true)); $ valid_pointers = array (); // Controleer wijzers en verwijder verwijderde. foreach ($ pointers als $ pointer_id => $ pointer) // Sanity check if (in_array ($ pointer_id, $ dismissed) || empty ($ pointer) || empty ($ pointer_id) || empty ($ pointer ['target ']) || leeg ($ pointer [' options '])) ga verder; $ pointer ['pointer_id'] = $ pointer_id; // Voeg de aanwijzer toe aan $ valid_pointers array $ valid_pointers ['pointers'] [] = $ pointer; // Geen geldige verwijzingen? Stop hier. als (leeg ($ valid_pointers)) terugkomt; // Voeg pointers-stijl aan de wachtrij toe. wp_enqueue_style ('wp-pointer'); // Script pointers toevoegen aan wachtrij. Voeg aangepast script toe. wp_enqueue_script ('wptuts-pointer', plugins_url ('js / wptuts-pointer.js', __FILE__), array ('wp-pointer')); // Aanwijzeropties toevoegen aan script. wp_localize_script ('wptuts-pointer', 'wptutsPointer', $ valid_pointers); Het script is heel eenvoudig, omdat de pointer-widget het meeste werk doet. Bij deze aanwijzer hoeven we alleen maar te definiëren wat er gebeurt als de aanwijzer wordt verwijderd. In het bijzonder sturen we een ajax-verzoek met de actie 'ontslaan-wp-pointeren de aanwijzer om in te stellen op de unieke ID die we opgeven bij het toevoegen van de aanwijzer.
jQuery (document) .ready (function ($) wptuts_open_pointer (0); function wptuts_open_pointer (i) pointer = wptutsPointer.pointers [i]; options = $ .extend (pointer.options, close: function () $ .post (ajaxurl, pointer: pointer.pointer_id, action: 'dismiss-wp-pointer');); $ (pointer.target) .pointer (options) .pointer ('open');) ; Dat is alle code die we moeten toevoegen sinds WordPress het ajax-verzoek afhandelt.
Zoals beloofd, is het toevoegen van verwijzingen heel eenvoudig. Een aanwijzer toevoegen aan het 'bericht'-scherm, bijvoorbeeld:
add_filter ('wptuts_admin_pointers-post', 'wptuts_register_pointer_testing'); functie 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'))); return $ p; Notitie: Wanneer de ontslagen pointer wordt opgeslagen, geeft WordPress de pointer-ID door sanitize_key - gebruik daarom alleen alfanumerieke tekens, streepjes en underscores in kleine letters.
