Share
Questa è la terza parte di una serie di articoli che esaminano come il tuo plugin o il tuo tema possano integrarsi al meglio nell'interfaccia utente di amministrazione di WordPress. In questa parte vedremo come utilizzare WordPress "admin pointers" nei plugin.
I puntatori dell'amministratore sono comparsi per la prima volta in 3.3 e intendevano mettere in evidenza solo alcune delle nuove funzionalità fornite con tutte le versioni principali (ad esempio, il personalizzatore del tema in 3.4).
Se utilizzati correttamente, questi possono essere molto efficaci per attirare l'attenzione sulle ultime funzionalità che hai aggiunto.
Disclaimer: Gli indicatori admin sono ancora nelle prime fasi della loro vita e c'è la possibilità che possano cambiare. Se il core di WordPress dovesse mai sviluppare un'API pubblica, dovresti adottarlo.
Un'interfaccia utente decente non è un suggerimento ingannevole. In effetti, a ideale l'interfaccia utente non ne avrebbe bisogno. Sono molto utili nel sottolineare le nuove funzionalità occasionali, in particolare quelle che il tuo utente finale potrebbe aver perso. In questo possono migliorare "l'esperienza dell'utente", ma se li stai usando per altri scopi o semplicemente ne usi troppi, allora stai sbagliando. Piuttosto che migliorare il plugin per l'utente finale, finirai per frustrarli.
Quindi quanti ne sono troppi? Ricorda che ci saranno altri plugin installati, e ognuno potrebbe usare (o abusare) anche questi puntatori. Anche WordPress (ovviamente) li usa. Sarebbe interessante valutare l'opinione della gente su questo, ma io stesso non aggiungerei più di due in ogni aggiornamento importante (nessuno su quelli minori), e certamente non più di uno su una determinata pagina.
È importante sottolineare che, senza un'API di base, non esiste un modo per gestire più puntatori: se vengono aggiunti venti puntatori a una pagina, verranno visualizzati venti. Dal momento che non sai cosa stanno facendo altri plugin - per favore usateli con parsimonia.
Quando si utilizzano i puntatori dell'amministratore in un plug-in o un tema, sarà utile poter aggiungere facilmente e velocemente dei puntatori extra man mano che il plugin si evolve. A tal fine, creeremo una funzione di supporto che gestirà la gestione interna dei puntatori. Utilizzerà l'API hook molto amata da WordPress e attiverà un filtro del modulo:
wptuts_admin_pointers_ screen-id
Dove Screen-id è l'ID della pagina visualizzata. Per aggiungere un puntatore alla pagina di modifica del post, ad esempio, ci collegheremo al filtro:
wptuts_admin_pointers_post
In questo modo, possiamo aggiungere puntatori extra, con codice minimo. Il ruolo di questa funzione di supporto sarà la creazione di una serie di puntatori che verranno stampati nella pagina di amministrazione come una matrice di oggetti JavaScript, ovvero ogni oggetto corrispondente a un puntatore. Ogni oggetto puntatore contiene i seguenti parametri:
Accentsconagua
pointer_id - un identificatore univoco per il puntatore. Una buona idea è includere la versione per la quale è rilevante. Questo deve contenere solo caratteri alfanumerici, caratteri di sottolineatura e trattini minuscoli.bersaglio - un selettore per il bersaglio del puntatore, cioè a cosa sta puntando (ad es. #some_id, o .un po 'di classe)opzioni - Questa è una serie di opzioni. Possiamo usarlo per modificare completamente il modo in cui il puntatore appare e si comporta, ma per i nostri scopi dobbiamo solo considerare quanto segue: contenuto (il testo che appare nel puntatore) e posizione. La proprietà position è determinata da:
bordo - quale bordo (a sinistra, a destra, in alto, in basso) dovrebbe essere adiacente al bersaglio.allineare - come il puntatore deve essere allineato su questo bordo, rispetto al bersaglio (in alto, in basso, a sinistra, a destra, al centro).Un tipico oggetto puntatore potrebbe essere nella forma:
pointer_id: 'xyz_v110', target: '#some_id', opzioni: contenuto: 'Nuova funzionalità: xyz
Lorem ipsum dolor sit amet…
', posizione: edge:' left ', align:' top '
Una volta che gli oggetti del puntatore vengono stampati nella pagina di amministrazione, possiamo utilizzare il widget del puntatore WordPress qui definito.
Come discusso nella sezione precedente, l'obiettivo generale della nostra funzione è quello di stampare alcuni oggetti JavaScript nella pagina e caricare alcuni script personalizzati. Quindi la nostra funzione di supporto verrà agganciata al wp_enqueue_scripts azione (anche se potremmo chiamarla più tardi).
add_action ('admin_enqueue_scripts', 'wptuts_pointer_load'); function wptuts_pointer_load ($ hook_suffix) // La funzione di supporto va qui Ricorda, se stai utilizzando questo codice in un plug-in o un tema, dovresti rinominare la funzione, assicurandoti che sia unica e preferibilmente pre-fissandola con il tuo plug-in o il tuo nome del tema. La prima parte di questa funzione filtra una matrice vuota, usando il gancio wptuts_admin_pointers- screen_id. Questo ci consente di aggiungere puntatori a quell'array. Se non viene aggiunto nulla, ci fermiamo.
// Non eseguire su WP < 3.3 if ( get_bloginfo( 'version' ) < '3.3' ) return; // Get the screen ID $screen = get_current_screen(); $screen_id = $screen->id; // Ottieni puntatori per questa schermata $ puntatori = apply_filters ('wptuts_admin_pointers-'. $ Screen_id, array ()); // Nessun puntatore? Quindi ci fermiamo. se (! $ puntatori ||! is_array ($ puntatori)) ritorno; Ora questi suggerimenti possono includere quelli che l'utente ha già visto e "respinti". Non vogliamo che vengano visualizzati di nuovo per questo utente, quindi dopo otterremo una serie di puntatori che hanno già visto e chiuso e rimuoverli dal nostro array. Eseguiamo anche alcuni controlli di integrità sui nostri indicatori:
// Ottieni i puntatori ignorati $ dismissed = explode (',', (string) get_user_meta (get_current_user_id (), 'dismissed_wp_pointers', true)); $ valid_pointers = array (); // Controlla i puntatori e rimuovi quelli respinti. foreach ($ puntatori come $ pointer_id => $ pointer) // Sanity controlla if (in_array ($ pointer_id, $ gettato) || vuoto ($ puntatore) || vuoto ($ pointer_id) || vuoto ($ pointer ['target ']) || vuoto ($ pointer [' opzioni '])) continua; $ pointer ['pointer_id'] = $ pointer_id; // Aggiungi il puntatore all'array $ valid_pointers $ valid_pointers ['pointers'] [] = $ pointer; // Nessun puntatore valido? Fermati qui. if return (empty ($ valid_pointers)); Infine accodiamo gli script e gli stili necessari e stampiamo i puntatori validi sulla pagina, usando wp_localize_script.
// Aggiungi lo stile dei puntatori alla coda. wp_enqueue_style ('wp-pointer'); // Aggiungi lo script di puntatori e il nostro script personalizzato da mettere in coda. wp_enqueue_script ('wptuts-pointer', plugins_url ('js / wptuts-pointer.js', __FILE__), array ('wp-pointer')); // Aggiungi le opzioni del puntatore allo script. wp_localize_script ('wptuts-pointer', 'wptutsPointer', $ valid_pointer); add_action ('admin_enqueue_scripts', 'wptuts_pointer_load', 1000); function wptuts_pointer_load ($ hook_suffix) // Non eseguire su WP < 3.3 if ( get_bloginfo( 'version' ) < '3.3' ) return; $screen = get_current_screen(); $screen_id = $screen->id; // Ottieni puntatori per questa schermata $ puntatori = apply_filters ('wptuts_admin_pointers-'. $ Screen_id, array ()); se (! $ puntatori ||! is_array ($ puntatori)) ritorno; // Ottieni i puntatori ignorati $ dismissed = explode (',', (string) get_user_meta (get_current_user_id (), 'dismissed_wp_pointers', true)); $ valid_pointers = array (); // Controlla i puntatori e rimuovi quelli respinti. foreach ($ puntatori come $ pointer_id => $ pointer) // Sanity controlla if (in_array ($ pointer_id, $ gettato) || vuoto ($ puntatore) || vuoto ($ pointer_id) || vuoto ($ pointer ['target ']) || vuoto ($ pointer [' opzioni '])) continua; $ pointer ['pointer_id'] = $ pointer_id; // Aggiungi il puntatore all'array $ valid_pointers $ valid_pointers ['pointers'] [] = $ pointer; // Nessun puntatore valido? Fermati qui. if return (empty ($ valid_pointers)); // Aggiungi lo stile dei puntatori alla coda. wp_enqueue_style ('wp-pointer'); // Aggiungi lo script di puntatori alla coda. Aggiungi uno script personalizzato. wp_enqueue_script ('wptuts-pointer', plugins_url ('js / wptuts-pointer.js', __FILE__), array ('wp-pointer')); // Aggiungi le opzioni del puntatore allo script. wp_localize_script ('wptuts-pointer', 'wptutsPointer', $ valid_pointers); Lo script è molto semplice, dal momento che il widget puntatore fa la maggior parte del lavoro. A questo puntatore tutto quello che dobbiamo veramente definire è cosa succede quando il puntatore viene eliminato. In particolare, inviamo una richiesta Ajax con l'azione 'respingere-wp-pointer'e il puntatore per impostare l'identificatore univoco che specifichiamo quando si aggiunge il puntatore.
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');) ; Questo è tutto il codice che dobbiamo aggiungere dal momento che WordPress gestisce la richiesta Ajax.
Come promesso, aggiungere dei puntatori è molto semplice. Per aggiungere un puntatore alla schermata "post", ad esempio:
add_filter ('wptuts_admin_pointers-post', 'wptuts_register_pointer_testing'); function wptuts_register_pointer_testing ($ p) $ p ['xyz140'] = array ('target' => '# change-permalinks', 'options' => array ('contenuto' => sprintf (' %S
%S
', __ (' Titolo ',' plugindomain '), __ (' Lorem ipsum dolor sit amet, consectetur adipiscing elit. ',' Plugindomain ')),' position '=> array (' edge '=>' top ', 'align' => 'middle'))); ritorno $ p; Nota: Quando si memorizza il puntatore respinto, WordPress passa l'ID del puntatore sanitize_key - quindi assicuratevi di usare solo caratteri alfa minuscoli, trattini e caratteri di sottolineatura.
