Cindy di Digital Ramble spiega come creare da zero un plugin WordPress per impostare le favicon di un sito tramite una pagina di opzioni, approfittandone per spiegare in modo semplice e chiaro i concetti basilari della creazione di plugin.

L’articolo originale è disponibile sul blog Digital Ramble, all’indirizzo
http://www.digitalramble.com/2006/06/06/34/

Panoramica

Ho scavato più in profondità nella documentazione di WordPress, perchè volevo che il mio plugin rispettasse alcuni criteri: volevo che avesse un pannello di amministrazione perchè NON volevo che chiunque lo usasse fosse obbligato a fare altro che impostare opzioni tramite il pannello. In altre parole, basta modifiche al codice.

Diverse ragioni per questo. Primo, non tutti gli utenti WordPress sono smanettoni come me. Secondo, è noioso anche per gli smanettoni come me cambiare temi o aggiornare WordPress e dover riapplicare tutte le piccole modifiche. Per questo motivo sto diventando la più grande fan dei plugin plug’n'play.

Per essere onesti, non sempre questo è evitabile. In particolare, gli elementi delle barre laterali non sono facilmente integrabili (credo sia questa l’idea alle spalle dei widget, ma non ho ancora approfondito abbastanza da esserne certa). In ogni caso ho già visto diversi metodi interessanti nel lavoro di altri autori di plugin, e credo sia possibile evitare molti di questi problemi.

Comunque sia, questo plugin riguarda le favicons. Questa era la mia lista dei desideri:

1. Poter inserire una immagine arbitraria come favicon
2. Poter specificare l’immagine rilevante nella mia cartella WordPress anzichè come URI assoluta.
3. Poter modificare questa immagine in qualunque momento.
4. Poter usare files gif/icon/png per la favicon
5. Eventualmente usare l’immagine nel mio feed rss2
6. Eventualmente usare l’immagine nel mio feed atom
7. Tutto questo configurabile nel pannello di amministrazione
8. Un plugin “plug and play” - da installare e attivare, null’altro.

Con mia sorpresa, questo è stato abbastanza semplice. Più o meno un ora per leggere la documentazione rilevante, circa 15 minuti per programmare, un’altra ora per il collaudo, e quasi due ore di scrittura e documentazione :-D Questa è un proporzione abbastanza tipica…

Il plugin completo è disponibile all’indirizzo
http://www.digitalramble.com/favicon-manager-wordpress-plugin/
(date un’occhiata sul lato).

Agganci agli header

Per aggiungere qualcosa agli header, senza obbligare l’utente a modificare i propri files di WordPress, potete usare

// insert favicon into header using hooks add_action('wp_head', 'add_favicon_to_headers');

dove add_favicon_to_headers è una semplice funzione senza parametri che inserisce ciò che volete all’interno degli header. E’ molto semplice. La prima bozza della funzione è in grado di fare ciò che vorremmo facesse, durante i test:

function add_favicon_to_headers() { $favicon_location="http://example.com/example.ico"; $favicon_type="x-icon"; print ' <link rel="icon" href="'. $favicon_location .'" type="image/'. $favicon_type .'" />'; print "\n"; print ' <link rel="shortcut icon" href="'. $favicon_location .'" type="image/'. $favicon_type .'" />'; print "\n"; }

Ovviamente questa è solo una prima stesura, giusto per essere certi che funzioni. E può funzionare, se inserite il codice qui sopra (all’interno dei codici ?php e con un indirizzo corretto al posto di example.ico) in un file con estensione .php nella vostra cartella dei plugin. Esiste infatti un semplice favicon plugin che fa esattamente questo ma non è configurabile come ho detto nella mia lista dei desideri ;-)

Database

Per avere valori persistenti e recuperabili, ho dovuto fare uso delle utilità a livello database offerte in WordPress. Ci sono add_option, update_option e get_option per un interfacciamento semplice. Quindi farò in modo di verificare che sia presente un dato nel database con l’indirizzo della favicon:

// add the saved items to the database if not already there function favicon_mgr_add_options() { add_option('fm_favicon_location', ''); } favicon_mgr_add_options();

A questo punto il database ha ora un nuovo elemento, con un valore vuoto (una stringa di testo) disponibile per questo plugin. Ho provato a usare nomi lunghi e descrittivi (nelle funzioni, N.d.T.) per ridurre l’eventualità di una collisione di name space. Sarebbe stato più semplice per le mie dita usare solo “favicon”, ma ovviamente sarebbe stata più alta la possibilità che qualcuno abbia avuto prima o poi la mia stessa brillante idea.

Questo significa che l’aggancio ora può recuperare valori dal database:

function add_favicon_to_headers() { $favicon_location=get_option('fm_favicon_location'); $favicon_type=get_favicon_type($favicon_location); print ' <link rel="icon" href="'. $favicon_location .'" type="image/'. $favicon_type .'" />'; print "\n"; print ' <link rel="shortcut icon" href="'. $favicon_location .'" type="image/'. $favicon_type .'" />'; print "\n"; }

Ora potete vedere perchè ho usato le variabili fino ad ora :-). La funzione get_favicon_type è un’altra funzione che ho scritto (e non ho incluso sopra per chiarezza) che restituisce il tipo corretto (x-icon, gif, jpg, png) a seconda del nome della favicon. In questo modo la funzione è pronta qualunque sia l’input dell’utente (dovrei aggiungere un controllo nel caso l’estensione sia sconosciuta, ma ancora una volta sto cercando di rendere le cose più semplici possibile).

Pannello di amministrazione

WordPress offre anche un set diretto di funzioni per crare un pannello di amministrazione. E’ stato decisamente semplice. Per prima cosa è presente un aggancio per inserire un nuovo menù sotto il menu Opzioni (potete fare anche altro, ma per cose basilari come queste, Opzioni è più che sufficiente).

// create hook for new submenu add_action('admin_menu', 'favicon_mgr_admin_menu'); // title of page, name of option in menu bar, which function lays out the html function favicon_mgr_admin_menu() { add_options_page(__('Favicon Manager Options'), __('Favicons'), 5, basename(__FILE__), 'favicon_mgr_options_page'); } // html layout for option page, plus detection/update on new settings function favicon_mgr_options_page() { ... }

Quindi, tutto ciò che questo produce è l’inserimento di un oggetto menu. L’oggetto specifica a sua volta la funzione che definirà la pagina. Quindi, la funzione inserirà il codice necessario a permettere gli input e il resto. Questa pagina dovrà inoltre poter aggiornare i record nel database in modo che gli agganci della testata possano ricevere i valori corretti da inserire nella stessa. In questo modo le cose iniziano a essere collegate. Una prima stesura della pagina di opzioni:

function favicon_mgr_options_page() { $updated = false; if (isset($_POST['fm_favicon_location'])) { $fm_favicon_location = $_POST['fm_favicon_location']; update_option('fm_favicon_location', $fm_favicon_location); $updated = true; } $fm_favicon_location = get_option('fm_favicon_location'); if ($updated) { ?> <div class="updated"><p><strong>Options saved.</strong></p></div> <?php }

Prendiamo una pausa rinfrescante. Ricordiamoci che questa pagina verrà mostrata solo quando l’utente entrerà nella pagina di opzioni, oppure dopo aver modificato le opzioni stesse. Quindi la prima cosa da verificare è se l’elemento input del modulo è stato modificato o meno. Nel primo caso, verrà inserito nel database, e verrà impostato update su true.

?> <div class="wrap"> <h2>Favicon Settings</h2> <form name="form1" method="post" action="<?php echo $_SERVER['REQUEST_URI']; ?>"> <fieldset class="options"> <legend>Favicon in WordPress Pages</legend> <table width="100%" cellspacing="2" cellpadding="5" class="editform"> <tr valign="top"> <th width="33%" scope="row">Location:</th> <td><input name="fm_favicon_location" type="text" width="60" value="<?php echo $fm_favicon_location; ?>"/> </td> </tr> </table> </fieldset> <p class="submit"> <input type="submit" name="Submit" value="Update Options »" /> </p> </form> </div> <? php }

Questa parte restituisce la pagina del modulo, con i valori nel campo imput se sono già impostati. La presentazione è già controllata tramite i fogli di stile e le classi usate, quindi verrà usato il familiare tema bianco e blu.

E’ tutto qui! In pratica gli unici elementi non inseriti sono la posizione abitraria o relativa della favicon (voglio che gli utenti abbiano la possibilità di inserire entrambe) e l’opzione RSS2/Atom. La prima è risolta facilmente con una ulteriore funzione:

function create_favicon_uri($favicon_location) { // if an absolute location entered, don't try to add the site url... if (preg_match("/^http/", $favicon_location)) { $favicon_url=$favicon_location; } else { $favicon_url= get_settings('siteurl') . '/' . $favicon_location; } return $favicon_url; }

Ora aggiornerò le istanze in cui richiamo $favicon_location per processare i risultati tramite questa funzione prima di usarli. Non userò comunque questa funzione prima di memorizzare la posizione nel database. Per evitare confusioni da parte dell’utente, preferisco tenere ciò che hanno inserito.

L’opzione Feed

Spiegherò solamente l’aggiunta per RSS, in quanto l’opzione Atom è identica, eccetto l’output nell’aggancio.

A partire da WordPress 2.0, sono forniti agganci per gli RSS2:

function add_image_to_rss2_feed() { // do this or not depending on user settings in panel! if (get_option('fm_rss2_feed_option')=="Y") { $favicon_location=create_favicon_uri(get_option('fm_favicon_location')); echo "<image>\n"; echo " <link>". get_bloginfo_rss('url') ."</link>\n"; echo " <url>". $favicon_location ."</url>\n"; echo " \n"; echo "</image>\n"; } } // insert image into rss2 feed add_action('rss2_head', 'add_image_to_rss2_feed');

Quindi inserirò nel mio database:

// add the saved items to the database if not already there function favicon_mgr_add_options() { add_option('fm_favicon_location', ''); add_option('fm_rss2_feed_option', ''); }

Questo verrà aggiunto alla pagina di opzioni prima dell’output, a prescindere dal fatto che le nuove opzioni siano già salvate.

// checkboxes flip on/off if ($_POST['fm_rss2_feed_option']!=get_option('fm_rss2_feed_option')) { $fm_rss2_feed_option = $_POST['fm_rss2_feed_option']; update_option('fm_rss2_feed_option', $fm_rss2_feed_option); $updated = true; } $fm_rss2_feed_option = get_option('fm_rss2_feed_option');

Le caselle di selezione funzionano in modo leggermente differente dai campi di input testuale. Se deselezionate una casella, NON avrete un input. Dal momento che è un selettore acceso/spento, la soluzione è controllare se il valore è lo stesso di quello memorizzato, dal momento che solo due valori sono possibili.

Ora aggiungerò del codice HTML per chiedere all’utente di scegliere se usare la favicon nei propri feed RSS2:

<legend>Images in Feeds</legend> <table width="100%" cellspacing="2" cellpadding="5" class="editform"> <tr valign="top"> <th width="33%" scope="row">Add to RSS2 Feed?</th> <td><input name="fm_rss2_feed_option" type="checkbox" value="Y" <?php if ($fm_rss2_feed_option=="Y") echo "checked"; ?> > </td> </tr> </table>

Questo è inserito nel contenitore fieldset della pagina di opzioni.

Atom è identico, ma l’immagine è inserita tramite un tag e il valore è semplicemente l’indirizzo della favicon.

Le immagini dei feed sono gestite in modo differente dalle favicon della testata. Non devono essere per forza 16×16, ma possono essere un po’ più grandi. Di solito appaiono accanto al campo della testata in un aggregatore, e se date un’occhiata al feed delle previsioni del tempo su Bloglines, potrete notare una icona relativamente grande in cima ai suoi articoli. Ma (usando per esempio ancor Bloglines), le immagini possono anche essere usate sulla destra, nei bookmarks di Bloglines (le informazioni su Bloglines possono essere variate, N.d.T. ). Può valere la pena offrire un campo opzionale per l’immagine dei feed: se è lasciato vuoto verrà usata la favicon, altrimenti verrà usata questa immagine solo per i feed. Non ho ancora deciso…

Files di supporto

Anche se il codice è scritto e collaudato, non ho ancora finito. Devo aggiungere a questo alcune cose:

• Un file readme.txt da allegare con il file php del plugin
• Una versione compressa con le cartelle e i files corretti da mettere nella mia cartella pubblica
• Una pagina di aiuto e supporto dove i potenziali utenti potranno trovare informazioni sul plugin, istruzioni per l’installazione, e dove sarà disponibile l’archivio stesso.

Ci sono alcune azioni facoltative che potreste voler intraprendere, come registrare il plugin su Codex, nel database dei plugin WP, e in altri forum che raccolgono informazioni sui plugin.

Alcuni pensieri

Potrei essere in grado di rendere questo plugin funzionante con versioni precedenti di WordPress, proteggendo l’opzione dei feed con un controllo sulll’esistenza dell’aggancio ai feed. Se non è presente, allora evita tutti gli elementi feed. In questo modo il plugin dovrebbe degradare in modalità favicon-solo-header, tenendo conto che nessuna delle altre funzioni è stata modificata. Ma dato che ho scritto questo ben dopo l’aggiornamento alla versione 2.0, non sono particolarmente invogliata a farlo… specialmente visto che non ho i mezzi necessari per fare i test.

L’articolo originale è disponibile sul blog Digital Ramble, all’indirizzo
http://www.digitalramble.com/2006/06/06/34/