Share
Detta är del 3 i en serie artiklar som tittar på hur ditt plugin eller tema kan bäst integreras i WordPress admin användargränssnitt. I den här delen ska vi titta på hur du kan använda WordPress "admin pointers" i dina plugins.
Adminpoints uppträdde först i 3.3 och var avsedda att lyfta fram några av de nya funktionerna som följer med varje större version (temat anpassaren i 3.4, till exempel).
När de används ordentligt kan de vara mycket effektiva för att uppmärksamma de senaste funktionerna du har lagt till.
Varning: Adminpekarna är fortfarande i de tidiga stadierna i sitt liv - och det finns möjlighet att de kan förändras. Om WordPress-kärnan någonsin utvecklar ett offentligt API - bör du anta det.
Ett anständigt användargränssnitt är inte gimmicky verktygstips. Faktum är en idealisk användargränssnittet skulle inte behöva någon. De är mycket användbara för att påpeka den tillfälliga nya funktionen, särskilt de som din slutanvändare kanske har missat. Här kan de förbättra användarupplevelsen, men om du använder dem för något annat ändamål, eller helt enkelt använder för många, gör du det fel. I stället för att förbättra plugin för slutanvändaren kommer du bara att bli frustrerande för dem.
Så hur många är för många? Kom ihåg att det kommer att finnas andra plugins installerade, och var och en kan använda (eller missbruka) dessa pekare också. WordPress för (självklart) använder dem. Det skulle vara intressant att mäta människors åsikt om detta men jag själv skulle inte lägga till mer än två i någon större uppdatering (ingen på mindre) och absolut inte mer än en på en viss sida.
Viktigt är att det inte finns något sätt att hantera flera pekare utan att ha ett kärna API: om tjugo pekare läggs till på en sida kommer tjugo att visas. Eftersom du inte vet vilka andra plugins som gör - snälla använd dem.
När du använder adminpekare i ett plugin eller ett tema, kommer det vara användbart att enkelt och snabbt lägga till extra pekare när ditt plugin utvecklas. För detta ändamål kommer vi att skapa en hjälpfunktion som hanterar den interna hanteringen av pekarna. Det kommer att använda sig av WordPress 'mycket älskade krok API, och utlösa ett filter i formuläret:
wptuts_admin_pointers_ screen-id
Var Screen-id är sidans ID som visas. För att lägga till en pekare på sidan för redigering av posten, skulle vi till exempel haka på filtret:
wptuts_admin_pointers_post
På så sätt kan vi lägga till extra pekare, med minimal kod. Denna hjälppunkts roll kommer att vara att skapa en uppsättning tips som kommer att skrivas ut på administratörssidan som en rad JavaScript-objekt - varje objekt som motsvarar en pekare. Varje pekareobjekt innehåller följande parametrar:
Accentsconagua
pointer_id - en unik identifierare för pekaren. En bra idé är att inkludera den version som den är relevant för. Det här får bara innehålla alfanumeriska bokstäver, understreck och bindestreck.mål - en väljare för pekarens mål, dvs vad det pekar på (t.ex.. #some_id, eller .något-klass)alternativ - Detta är en rad alternativ. Vi kan använda detta för att helt ändra hur pekaren ser ut och beter sig, men i vårt syfte behöver vi bara överväga följande: innehåll (texten som visas i pekaren) och positionen. Fastighetsegenskapen bestäms av:
kant - vilken kant (vänster, höger, topp, botten) ska vara intill målet.justera - hur pekaren ska anpassas på denna kant i förhållande till målet (topp, botten, vänster, höger, mitten).Ett typiskt pekarobjekt kan vara av formen:
pointer_id: 'xyz_v110', mål: '#some_id', alternativ: content: 'Ny funktion: xyz
Lorem ipsum dolor sit amet ...
', position: kant:' vänster ', justera:' top '
När pekarobjekten skrivs ut på administratörssidan kan vi använda den WordPress-pekar-widget som definieras här.
Som diskuterats i föregående avsnitt är det övergripande syftet med vår funktion att skriva ut några JavaScript-objekt på sidan och ladda några anpassade skript. Så vår hjälparfunktion kommer att hakas på wp_enqueue_scripts åtgärd (vi kan kalla det senare).
add_action ('admin_enqueue_scripts', 'wptuts_pointer_load'); funktion wptuts_pointer_load ($ hook_suffix) // Helper-funktionen går här Kom ihåg att om du använder den här koden i ett plugin eller tema, ska du byta namn på funktionen, se till att den är unik och helst förinställa den med ditt plugin eller temat namn. Den första delen av den här funktionen filtrerar en tom matris med kroken wptuts_admin_pointers- screen_id. Detta gör det möjligt för oss att lägga till pekare i den uppsättningen. Om ingenting läggs till stoppar vi.
// Kör inte på WP < 3.3 if ( get_bloginfo( 'version' ) < '3.3' ) return; // Get the screen ID $screen = get_current_screen(); $screen_id = $screen->id; // Hämta pekare för den här skärmen $ pointers = apply_filters ('wptuts_admin_pointers-'. $ Screen_id, array ()); // Inga tips? Då slutar vi. om (! $ pekare ||! is_array ($ pointers)) returnera; Nu kan dessa pekare inkludera de som användaren har sett tidigare och "avvisas". Vi vill inte att dessa visas igen för den här användaren, så vi får en rad tips som de redan har sett och stängt och tar bort dem från vår array. Vi utför även några sanitetsprov på våra tips:
// Få avvisade pekare $ avvisas = explodera (',', (sträng) get_user_meta (get_current_user_id (), 'dismissed_wp_pointers', true)); $ valid_pointers = array (); // Kontrollera pekare och ta bort uppsagda. foreach ($ pointers as $ pointer_id => $ pekare) // Sanity check om (in_array ($ pointer_id, $ dismissed) || tom ($ pointer) || empty ($ pointer_id) || tom ($ pointer ['target ']) || tom ($ pekare [' options '])) fortsätt; $ pekare ['pointer_id'] = $ pointer_id; // Lägg pekaren till $ valid_pointers array $ valid_pointers ['pointers'] [] = $ pekare; // Inga giltiga pekare? Stanna här. om (tomt ($ valid_pointers)) returneras; Slutligen skämtar vi de nödvändiga skript och stilar och skriver ut de giltiga pekarna till sidan, med hjälp av wp_localize_script.
// Lägg till pekare stil till kö. wp_enqueue_style ('wp-pointer'); // Lägg till pekskript och vårt eget anpassade skript till kö. wp_enqueue_script ('wptuts-pointer', plugins_url ('js / wptuts-pointer.js', __FILE__), array ('wp-pointer')); // Lägg till pekaralternativ till skript. wp_localize_script ('wptuts-pointer', 'wptutsPointer', $ valid_pointer); add_action ('admin_enqueue_scripts', 'wptuts_pointer_load', 1000); funktion wptuts_pointer_load ($ hook_suffix) // Kör inte på WP < 3.3 if ( get_bloginfo( 'version' ) < '3.3' ) return; $screen = get_current_screen(); $screen_id = $screen->id; // Hämta pekare för den här skärmen $ pointers = apply_filters ('wptuts_admin_pointers-'. $ Screen_id, array ()); om (! $ pekare ||! is_array ($ pointers)) returnera; // Få avvisade pekare $ avvisas = explodera (',', (sträng) get_user_meta (get_current_user_id (), 'dismissed_wp_pointers', true)); $ valid_pointers = array (); // Kontrollera pekare och ta bort uppsagda. foreach ($ pointers as $ pointer_id => $ pekare) // Sanity check om (in_array ($ pointer_id, $ dismissed) || tom ($ pointer) || empty ($ pointer_id) || tom ($ pointer ['target ']) || tom ($ pekare [' options '])) fortsätt; $ pekare ['pointer_id'] = $ pointer_id; // Lägg pekaren till $ valid_pointers array $ valid_pointers ['pointers'] [] = $ pekare; // Inga giltiga pekare? Stanna här. om (tomt ($ valid_pointers)) returneras; // Lägg till pekare stil till kö. wp_enqueue_style ('wp-pointer'); // Lägg till pekskript i kön. Lägg till anpassat skript. wp_enqueue_script ('wptuts-pointer', plugins_url ('js / wptuts-pointer.js', __FILE__), array ('wp-pointer')); // Lägg till pekaralternativ till skript. wp_localize_script ('wptuts-pointer', 'wptutsPointer', $ valid_pointers); Skriptet är mycket enkelt, eftersom pekar-widgeten gör det mesta av arbetet. Vid den här pekaren behöver vi bara definiera vad som händer när pekaren avvisas. I synnerhet skickar vi en ajaxförfrågan med åtgärden "ogilla-wp-pekaren'och pekaren sätter till den unika identifieraren som vi anger när pekaren läggs till.
jQuery (dokument) .ready (funktion ($) wptuts_open_pointer (0); funktion wptuts_open_pointer (i) pekare = wptutsPointer.pointers [i]; options = $ .extend (pointer.options, close: function () $ .post (ajaxurl, pekare: pointer.pointer_id, action: 'dismiss-wp-pointer';) $ (pointer.target) .pointer (alternativ) .pointer (' open ');) ; Det är all kod som vi behöver lägga till eftersom WordPress hanterar ajaxförfrågan.
Som lovat är det väldigt enkelt att lägga till pekare. För att lägga till en pekare på skärmen "post", till exempel:
add_filter ('wptuts_admin_pointers-post', 'wptuts_register_pointer_testing'); funktionen wptuts_register_pointer_testing ($ p) $ p ['xyz140'] = array ('target' => '# förändring-permalinks', 'options' => array ('content' => sprintf % s
% s
', __ (' Titel ',' plugindomain '), __ (' Lorem ipsum dolor sit amet, consectetur adipiscing elit. ',' Plugindomain ')),' position '=> array (' edge '=>' top ' 'align' => 'middle')))); returnera $ p; Notera: Vid lagring av den avvisade pekaren, passerar WordPress pekaren ID genom sanitize_key - så var noga med att använda endast små bokstäver alfanummer, streck och understreck.
