7 cose che avrei voluto sapere prima di scrivere un plugin

Questo articolo si propone come una piccola guida sui 7 punti che avrei voluto leggere prima di iniziare lo sviluppo di plugin WordPress, ma anche come vademecum da tenere sott’occhio nelle varie fasi, dal debugging alla pubblicazione.

La cosa che mi piace di WordPress è la sua estensibilità, sopratutto tramite i plugin. Tutti sappiamo dove andare a cercare quando ne abbiamo bisogno, ci rivolgiamo al repository su WordPress.org. Il problema sorge quando non troviamo la cosa che ci soddisfa in pieno e dobbiamo provvedere in prima persona sederci a scrivere il codice per realizzarne uno, come è recentemente successo al sottoscritto.

Questa pratica però può portare alcuni problemi perché generalmente non si inizia a correre quando abbiamo ancora camicia e mocassini, ovvero non iniziamo una qualsiasi attività prima di aver pensato un attimo ai suoi vari aspetti.

Riprendendo infatti l’esempio della corsa, prima di iniziare questa attività è necessario avere gli indumenti adatti, fare un po’ di riscaldamento, assicurarsi di avere il tempo a disposizione e soprattutto ricordarci di fare lo stretching alla fine della sessione perché altrimenti il giorno dopo ci troveremo pieni di dolori.

Nel campo dello sviluppo i dolori sono sicuramente differenti ma ti posso assicurare che non per questo sono più piacevoli!

Proprio per questo motivo ti invito a leggere con attenzione i seguenti punti nei quali affronto i vari passaggi che dovrebbero essere presi in considerazione ancor prima di iniziare a programmare, se poi hai qualche suggerimento o pensiero che vuoi condividere la sezione dei commenti è aperta ai tuoi contributi!

1.  L’idea è fondamentale. Ancora più importante è come la realizzi!

Il primo punto l’ho voluto dedicare completamente alla filosofia e alla preparazione degli strumenti necessari, perchè se è vero che l’idea è la chiave più importante per il successo è anche vero che senza i mezzi e la mentalità giusti non si va molto lontano.

Ora magari stai sbavando in maniera idrofoba e ti starai domandando:

“Perchè parli di filosofia? Dove vuoi andare a parare? Io ho fretta di scrivere il mio codice!!”

Bene! E’ proprio questa la reazione che vorrei farti evitare. Mettiti l’anima in pace, come dicevo anche in apertura: correre non porta da nessuna parte. Prendi un bel respiro e adotta un atteggiamento di calma Zen nei confronti delle difficoltà che incontrerai.

Molto spesso si incappa in errori facilmente evitabili ricontrollando più volte il codice e tenendo sotto mano la pagina principale del Codex, la Bibbia dei programmatori WordPress. Oltre alla documentazione principale di WordPress un’altra fonte di ispirazione per la realizzazione del proprio plugin provenire da codice scritto da altri. Quindi non sentirti un ladro se scarichi plugin o navighi su GitHub alla ricerca di soluzioni ingegnose.

La potenza di questo CMS è anche quella di essere totalmente Open Source e di richiedere una licenza GPL 2.0 o superiore per poter risiedere nel loro repository, quindi tutto il codice dei vari plugin che troverai ospitato al suo interno sarà liberamente consultabile e integrabile nel tuo entro i termini della licenza stessa.

Cerca tra i numerosissimi plugin disponibili se c’è qualcosa di simile a ciò che desideri realizzare, dai liberamente un’occhiata al codice. In moltissimi casi risparmierai ore tra ricerche e progettazione.

[clickToTweet tweet=”La licenza #GPL di #WordPress mi consente di studiare il codice di altri sviluppatori liberamente!” quote=”La licenza GPL di WordPress mi consente di studiare il codice di altri sviluppatori liberamente!”]

Ora manca solo un piccolo passo prima di potersi sedere tranquilli davanti al proprio text editor preferito con una bella tazza di tè caldo in mano e Bach a risuonare nelle cuffie: il preziosissimo strumento di debug di WordPress.

Questo ci permetterà non solo di vedere gli errori critici ma anche di individuare eventuali funzioni deprecated. Attivarlo è semplicissimo, ci basta aprire il file wp-config.php del sito che intendiamo utilizzare come piattaforma di test e cambiare questa riga da:

define('WP_DEBUG', false);

in:

define('WP_DEBUG', true); 

// Abilita il salvataggio del log degli errori in /wp-content/debug.log 
define('WP_DEBUG_LOG', true); 

// Disabilita la visualizzazione degli errori nel sito 
define('WP_DEBUG_DISPLAY', false); 
@ini_set('display_errors',0);

Gli ultimi due parametri sono consigliatissimi, poichè leggere gli errori da un log è molto meglio che vederseli stampati a video nel sito. Ricordati però che il log potrebbe contenere informazioni sensibili. Visto che WordPress non ci offre la possibilità di cambiare cartella per questo file e /wp-content è pubblica, cerca almeno di tenerlo il meno possibile online, usalo solo per il debug e poi cancellatelo.

Anche nel caso del debugging però dovremmo applicare la filosofia di cui sopra cercando di utilizzare gli strumenti migliori che possiamo trovare. Armatomi di pazienza sono andato a dare un’occhiata al Codex e spulciando tra i plugin disponibili mi sono accorto dell’esistenza di Debug Bar.  Che siate amanti dell’ottimizzazione oppure semplicemente pigri, troverete in questo plugin uno strumento sorprendentemente utile e comodo da usare.

Fa praticamente tutto quello di cui c’è bisogno ed è in grado di mostrare anche l’influenza in termini di tempo di risposta delle chiamate al database. Un must-have per uno sviluppatore WordPress.

2. La prima riga che scriverai sarà la più importante

“Scommettiamo che indovino quali saranno le prime righe di codice che scriverete?”

A questo punto i più smaliziati di voi avranno capito che in realtà le prime righe del file principale di un plugin sono un’ intestazione standard che WordPress ci impone di utilizzare e che risultano utili per molti aspetti.

Andiamole ad analizzare partendo dal codice, che in realtà è un commento.

/**
 * Plugin Name: Qui va il nome del plugin 
 * Plugin URI: http://qui_va_l_url_della_pagina_documentazione_del_plugin 
 * Description: Una breve descrizione che verrà visualizzata nel backend. 
 * Version: 1.0 
 * Author: Nome dell'autore del plugin 
 * Author URI: http://url_del_vostro_sito_personale 
 * License: GPL2 (o anche 3 va bene) 
 */

Cerchiamo di anticipare qualche concetto che ci potrà tornare utile dopo.

Tutti i parametri che inseriremo in questo header verranno poi visualizzati all’interno della pagina Plugin nel pannello di amministrazione di WordPress. È quindi importante fornire tutti i link utili per gestire al meglio l’installazione e i parametri del tuo plugin aggiornando di conseguenza la versione dello stesso ad ogni modifica.

Infatti WordPress prende il parametro Version dalla pagina principale del plugin e lo confronta con il tag Stable del file readme.txt presente nel loro repository (trattato in seguito) per stabilire se la versione del plugin è aggiornata.

[clickToTweet tweet=”Popolare il file #readme del proprio #plugin #WordPress è molto importante per farlo trovare!” quote=”Popolare il file readme del proprio plugin WordPress è molto importante per farlo trovare!”]

Dimenticarsi di modificare il numero di versione ad ogni rilascio potrebbe causare moltissimi problemi a chi in futuro vorrà aggiornare il plugin.

Il parametro Author URI non è necessario ma, per esperienza personale, posso dirti che porta parecchio traffico sull’indirizzo specificato e la possibilità di ricevere feedback diretti, che è sempre cosa gradita! Per completare l’introduzione ti consiglio di inserire un piccolo estratto della licenza utilizzata, sempre sotto forma di commento, per dare subito l’idea di cosa si può e non si può fare con il vostro codice.

/**
 * imaGenius (WordPress Plugin) 
 * Copyright (C) 2017 Eugenio Petullà 
 * 
 * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. 
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. 
 *
 * You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>. 
 */

3. Lavorare con i percorsi/path in maniera corretta

WordPress ci mette a disposizione parecchie funzioni per ricavare automaticamente i percorsi ed è indispensabile usarli per rendere il proprio plugin “universale”, delegandogli il compito di capire dove è installato. Il problema è che sono veramente tanti e bisogna capire bene come usarli. Iniziamo ad elencarli:

plugins_url($path, $plugin);

Questa funzione ci restituirà la URL del plugin, solitamente viene impiegato quando si vuole ricevere l’URL di una risorsa che vogliamo includere. Un esempio chiarificherà il tutto:

$file = dirname(__FILE__) . '/mioplugin.php'; 
plugins_url($file); // Restituisce http://www.esempio.com/wp-content/plugins/mioplugin/ 
plugins_url('images/image.jpg' , $file); // Restituisce http://www.esempio.com/wp-content/plugins/mioplugin/images/image.jpg

Un’altra funzione utile che possiamo utilizzare durante lo sviluppo dei nostri plugin è:

plugin_dir_url( $file );

Questo ci restituirà la URL della cartella contenente il plugin con uno slash finale esattamente come se non specificassimo una risorsa nella funzione precedente. Personalmente lo chiamo “metodo rapido” perché è quello che di solito si ricorda meglio e si utilizza di più quando la risorsa all’interno della cartella deve essere una variabile della funzione che stiamo costruendo. Esempio di utilizzo:

$file = dirname(__FILE__) . '/mioplugin.php'; 
plugin_dir_url($file); // Restutisce http://www.esempio.com/wp-content/plugins/mioplugin/

Come avrai notato in realtà con qualche piccolo adattamento ai due metodi, possiamo tirare fuori gli stessi percorsi. Comprendere al meglio le differenze e le potenzialità ci offre il vantaggio di saper sempre scegliere la funzione che ci permetta di scrivere il minor codice possibile che funzioni al meglio per le nostre esigenze.

[clickToTweet tweet=”#WordPress offre moltissime funzioni che ci permettono di includere i file del nostro #plugin” quote=”#WordPress offre moltissime funzioni che ci permettono di includere i file del nostro #plugin”]

Altra funzione comodissima è quella che ci fa tornare il filesystem path, senza http per capirci.

$file = dirname(__FILE__) . '/mioplugin.php'; 
$plugin_path = plugin_dir_path($file); // Restituisce /home/mysite/www/wp-content/plugins/mioplugin/

Buttando un’occhiata rapida, capirai che in realtà sarebbe molto meglio usare il path assoluto per richiamare una risorsa, sopratutto internamente alla funzione che stiamo sviluppando. Nei casi in cui la risorsa verrà poi stampata a video (tramite echo ad esempio) io preferisco comunque usare la URL, in modo da far passare il link al webserver e generarne uno che se verrà esplorato avrà la sua URL fissata da me.

La cosa importante da sapere è che è assolutamente ininfluente ai fini della ricerca della risorsa. Dobbiamo immaginare il puntatore dir_url e quello dir_path come due frecce distinte che puntano allo stesso bersaglio! Altra piccola osservazione va fatta se lavori su sotto-cartelle, in quel caso puoi usare comodamente due dirname(), uno dentro l’altro, in questo modo:

$file = dirname(dirname(__FILE__)) . '/mioplugin.php'; 
$plugin_path = plugin_dir_path($file); // Restituisce /home/mysite/www/wp-content/plugins/mioplugin/sotto-cartella/

4. Problemi di lingua: ovvero come ho dovuto riscrivere un plugin perchè risultava intraducibile.

Ti sei mai chiesto come si fa a tradurre o a rendere disponibile un plugin WordPress in più lingue?

Nelle mie prime esperienze non mi ero mai posto questa domanda, volevo soltanto pubblicare il mio plugin.

[clickToTweet tweet=”È importante preparare il proprio #plugin #WordPress alla traduzione, è un #CMS internazionale!” quote=”È importante preparare il proprio #plugin #WordPress alla traduzione, è un #CMS internazionale!”]

Questo però si tratta di un errore banalissimo che ci fa piangere quando dobbiamo rimettere mano ad un codice funzionante. Per evitare questi problemi basta fare attenzione e applicare delle piccole accortezze in fase di programmazione. Il nostro amato WordPress utilizza dei file con estensione .mo, contenenti le varie traduzioni dei plugin.

Un file .mo non è altro che un file .po o .pot “compilato” da poedit .

Per rendere compatibile il nostro plugin con la stesura di un file .po e successivamente di quello .mo dovremmo studiare come dotare il nostro plugin di “ancore” per la traduzione. Iniziamo con l’incorporare nel plugin questa funzione:

function plugin_text_start() { 
	load_plugin_textdomain( 'mioplugin', false, 'mioplugin/languages' ); 
} 
add_action('init', 'plugin_text_start');

Cosa abbiamo appena fatto? Semplicemente, abbiamo associato la cartella /languages (che dovrai creare all’interno del tuo plugin) al textdomain con handle ‘mioplugin’, che per comodità è utile chiamarlo con lo stesso nome del plugin, questa è una cosa che ti consiglio di fare poiché dovrai richiamarlo spesso e usare un nome facile da ricordare aiuterà molto.

Ora andiamo ad operare sul codice, sarebbe meglio iniziare con questo approccio ancor prima di iniziare a scrivere il tutto, ma se come il sottoscritto hai mancato l’appuntamento con il destino e stai già rimpiangendo di non averlo fatto sappi che dovrai rinunciare a stampare con le comode echo e sostituirle con le funzioni di WordPress _e()  / __().

Cosa?? Non eri a conoscenza dell’esistenza di funzioni specifiche per stampare i testi che poi andranno tradotti??

Consolati perché sei in buona compagnia, più della metà dei plugin che uso regolarmente non adottano minimamente questo approccio, quindi applicando questo metodo sarai un passo più avanti persino dei migliori programmatori WordPress!!

Finita l’ora della consolazione e della gloria personale andiamo a conoscere meglio queste due funzioni.

Usandole siamo costretti ogni volta a specificare l’handle del texdomain. Poco male, se ricordi prima ti ho consigliato di chiamarlo come il plugin stesso proprio per facilitarti nel compito. Gli approcci, come è buona norma nella programmazione, possono essere di vario tipo e non c’è niente di meglio di un esempio dinamico per spiegarli:

$numero = '5'; 

//Qui la prassi solita con cui lo stamperemmo 
echo "Numero $numero"; 

// Possiamo stamparlo direttamente tramite una printf 
printf(__('Numero %s', 'mioplugin'), $numero); 

// Oppure stamparlo con una echo tramite variabile 
$tuonumero = sprintf(__('Numero %s', 'mioplugin'), $numero); 
echo $tuonumero;

A questo punto gli utenti Mac e Windows dovranno scaricare poedit da questo indirizzo e installarlo. Per gli utenti Linux sarà ancora più facile perchè si trova in praticamente tutti i repo delle distribuzioni più famose. Per Fedora:

$ su -c 'yum -y install poedit'

Per Debian e Ubuntu

$ sudo apt-get install poedit

Aperto il programma basterà andare su  File -> Nuovo Catalogo per ritrovarci un’altra bella lista da compilare. Scegli la lingua in cui il plugin è ORIGINARIAMENTE scritto (nel mio caso inglese) e riempi gli altri campi con i vostri contatti, fatto ciò spostatevi nella scheda Percorsi e lasciate il Percorso di Base con un punto mentre dovrete aggiungere sotto un altro percorso semplicemente aggiungendo due punti consecutivi (..) perché abbiamo bisogno anche di una sotto-directory che sarà proprio languages.

Nella scheda Parole chiavi (Orridamente tradotta in un programma di traduzioni, permettetemi un LOL)dobbiamo cancellare tutto e inserire le nostre funzioni relative a WordPress, quindi inseriamo __(), _e(), ovviamente tutto senza parentesi. Ora salviamo nel percorso del plugin (es. /test-wordpress/wp-content/plugins/mioplugin/languages/mioplugin.pot).

[clickToTweet tweet=”Generare un file #pot per un #plugin può sembrare difficile, ma non più grazie a questi consigli!” quote=”Generare un file #pot per un #plugin può sembrare difficile, ma non più grazie a questi consigli!”]

Fatto ciò dovrai far aggiornare il programma per fagli ricercare le corrispondenze all’interno dei vostri file. A questo punto puoi anche chiudere la schermata delle opzioni, tanto non avrai più bisogno di editare quel file a meno che non farai future modifiche.

“Ma chi me l’ha fatto fare!! Maledetto te con queste traduzioni sto perdendo tempo!! Avrei potuto fare tutto in inglese, se lo imparassero tutti!”

Amico idrofobo, come darti torto? Cerca però di riportare alla mente alla calma Zen e alla tazza di tè fumante! Prova a rilassarti e a pensare che alla fine chiunque potrà tradurre nella propria lingua il tuo capolavoro. Quello che stai facendo, lo fai per farti aiutare! 😉

Andiamo avanti con il lavoro e passiamo a creare il primo file necessario alla traduzione in una lingua specifica. Per fare questo basta andare su File -> Nuovo catalogo da file POT e navigare fino a trovare il file precedentemente creato.

A questo punto puoi lasciare le cose come sono tranne per la lingua e il paese (anche se ovvio ho preferito specificarlo), controlla che le Parole chiave siano identiche a prima e che i percorsi siano rimasti inalterati, poi salva tutto nella cartella languages/ rispettando la nomenclatura che prevede una struttura simile: textdomain-lingua_LOCALE.po (es. poniamo il caso abbia scelto di tradurre in italiano, /test-wordpress/wp-content/plugins/mioplugin/languages/mioplugin-it_IT.po)

Ora tu o i tuoi collaboratori potete tradurre tutto senza problemi e salvare nuovamente il file. Così facendo si genererà in automatico anche il file .mo e finalmente il nostro plugin sarà automaticamente multilingua!

5. Registrare gli script e gli stili

Questa parte me la sarei risparmiata volentieri ma il problema è che in questo caso il Codex non ci offre una documentazione chiara e fornisce esempi piuttosto nebulosi!! L’unica cosa facile da capire è che come avviene nei temi anche nei plugin gli script si inseriscono con wp_enqueue_script(), ma prima devono essere registrati con wp_register_script() in questo modo:

wp_register_script( $handle, $src, $deps, $ver, $in_footer );

Se ha già avuto modo di usare questa funzione nei temi sei avvantaggiato ma ti spiegherò comunque il necessario tutto partendo dai parametri che possiamo passare a questa funzione:

$handle //questo è il nome univoco che assegniamo allo script ed è obbligatorio 
$src //questo è invece l'url dello script da incorporare, obbligatorio anche questo 
$deps //qui vanno listate opzionalmente le dipendenze di cui lo script ha bisogno, è un array quindi dentro ci vanno tutti gli handle e non il path o l'url 
$ver //opzionalmente potete assegnare un numero di versione allo script 
$in_footer //true per assegnare lo script a wp_footer(), false per assegnarlo a wp_head()

Ora possiamo usare wp_enqueue_script() per richiamarlo senza troppi problemi, tramite l”handle che abbiamo registrato. Un esempio spicciolo di funzione per includere script, come al solito, pacificherà le irrequiete menti:

function registra_mioscript() { 

	//Questo script dipende da jquery e da jquery-ui 
	wp_register_script( 'mioscript', plugins_url( '/js/mioscript.js', __FILE__ ), array( 'jquery', 'jquery-ui-core' ) ); 

	// ora che lo script è registrato possiamo includerlo sempre richiamandolo comodamente tramite il suo handle 
	wp_enqueue_script( 'mioscript' ); 

} 
add_action( 'wp_enqueue_scripts', 'registra_mioscript' );

Anche per gli stili succede esattamente la stessa cosa, con l’unica differenza che a volte mi riservo la scelta di non registrare lo stile ma di includerlo solamente, un paio di esempi più avanti vi chiariranno la cosa. Partiamo dalle due funzioni wp_register_style() e wp_enqueue_style():

wp_register_style( $handle, $src, $deps, $ver, $media ); 
wp_enqueue_style( $handle, $src, $deps, $ver, $media );

I parametri sono del tutto simili a quelli usati prima per gli script, con l’unica differenza che qui possiamo scegliere il tipo di media a cui assegnare lo stile, in accordo con le specifiche css, passandolo alla variabile $media e che non possiamo scegliere dove caricarlo,andrà nel wp_head().

In realtà, un modo per farlo finire nel footer c’è, basterebbe usare il wp_enqueue_style() nel mezzo di qualche porzione HTML di una pagina nel frontend. Purtroppo questo è l’unico hack che sono riuscito a trovare per aggirare il problema, ovviamente se qualcuno conosce anche altri modi usi tranquillamente il modulo per i commenti e mi faccia sapere!

Andiamo avanti e vi mostro ben due modi per includere i vostri stili:

//Partiamo dal metodo classico, quello che vi fa registrare lo stile per includerlo comodamente tramite l'handle 
function mioplugin_aggiungi_stile() { 
	wp_register_style( 'mioplugin-style', plugins_url('style.css', __FILE__) ); 
	wp_enqueue_style( 'mioplugin-style' ); 
} 
add_action( 'wp_enqueue_scripts', 'mioplugin_aggiungi_stile' );

Questo è il metodo corretto e anche quello che vi permetterà poi di includere ed escludere gli stili da porzioni di codice. Riguardo questo c’è la funzione opposta a wp_enqueue_style() che è wp_dequeue_style() che vi consiglio di guardare perché permette parecchi giochetti interessanti. Questa cosa di includere ed escludere gli stili tramite funzioni apposite è sia un vantaggio che uno svantaggio, poiché a volte vorremmo poter solo mettere un’ inclusione rapida, magari per un plugin con una pagina sola e 3 funzioni per generare shortcode che poggiano la loro esistenza su un CSS e stop!

“Quindi posso o no includere il mio stile senza starmi a sbattere con questa storia della registrazione?!?!”

Caro amico tranquillizzati, lo puoi fare senza alterarti! Basta ricorrere al parametro opzionale $src di wp_enqueue_style() in questo modo:

wp_enqueue_style( 'mioplugin-style', plugins_url( 'style.css', __FILE__ ) );

Per raggiungere lo scopo si può accettare senza problemi questa seconda soluzione, però ricordiamoci cosa distingue un vero Maestro del Bushido da un comune spadaccino, l’onore.

“Vi è un solo giudice dell’onore del Samurai: lui stesso. Le decisioni che prendi e le azioni che ne conseguono sono un riflesso di ciò che sei in realtà. Non puoi nasconderti da te stesso.”

Quindi ponetevi sempre le domande: “La risorsa che sto usando mi servirà nuovamente? Prevedo di aggiornare in futuro il plugin includendo nuove parti che potrebbero richiedere la medesima? Ho veramente bisogno di registrarla?” Dalle risposte che vi darete saprete con chiarezza quale metodo approcciare!

6. Facciamo amicizia con il file Readme

Arrivati a questo punto potresti aver avuto l’idea di smettere di leggere, in fondo perchè scrivere un README se il plugin serve solo a noi che l’abbiamo costruito?

Qui però ti invito a pensare all’onore del samurai e a porti altre domande che ritengo fondamentali: “Lo utilizzerò solo io? Intendo pubblicarlo nel repository di WordPress? Questo plugin può tornare utile a qualcun’altro?”

In fondo se siamo stati “costretti” a estendere le funzionalità di WordPress vorrà dire che queste aggiunte potranno tornare utili anche a qualcun’altro, giusto? Bene! Armiamoci di pazienza, rimettiamo su il vinile della Penguin Cafè Orchestra e capiamo cos’è questo file e perchè è così importante.

WordPress richiede obbligatoriamente la presenza del file readme.txt nella cartella principale del tuo plugin. Questo file deve essere formattato in maniera particolare, poiché i dati inseriti nel suddetto serviranno a popolare le schede descrittive del plugin nella pagina rispettiva sul sito wordpress.org. Il codex ci offre una splendida demo di come deve essere realizzato il file readme.txt.

Visto che il prossimo argomento trattato riguarderà proprio il sistema di caricamento che sfrutta WordPress per mantenere aggiornate le versioni del plugin (subversioning o svn) ti invito a capire ora come scrivere il readme, per essere pronti a caricare tutto al primo colpo senza intoppi e per farlo useremo come esempio uno dei nostri plugin. Di seguito c’è il mio readme.txt che potrete confrontare con la rispettiva pagina su wordpress.org

=== Glossary === 
Contributors: codeat, iGenius, mte90 
Donate link: http://codeat.com/ 
Tags: glossary, vocabulary, dictionary, tooltip, terms, lexicon, knowledgebase, knowledge base, reference, terminology, catalog, directory, index, listing, literature, appendix, 
Requires at least: 4.6 
Tested up to: 4.8 
Stable tag: 1.4.11 
License: GPLv2 or later 
License URI: http://www.gnu.org/licenses/gpl-2.0.html 

Easily add and manage a glossary with auto-link, tooltips and more. Improve your internal site link building for a better SEO. 

== Description == 
If you are looking for a plugin that provides the definitive Glossary Section for WordPress this is the right one! 

Write a glossary or a dictionary section in your WordPress website. Every term of the glossary and every variation of them (E.g. "Call To Action" and "CTA" also) will occur in posts, pages or custom post types will became automatically a link to the Term page or even an external URL. 

If you are looking for a solid strategy to improve your internal site link building and improve your SEO this is one of the best method we've tried and we incourage you to try this: it's for free! 

You can also choose to put some tooltips on the referenced words and improve your website user experience, we provided 3 beautiful tooltip's templates in order to make it fit your design. 

Are you an affiliate marketing specialist? 
Using this plugin you can also use some affiliations URL in your terms and write a description of them for the tooltip area that will popup on hover so you'll be able to convert more users. 

Shortcode list: http://codeat.co/glossary/shortcodes/ 

[PLUGIN DEMO SITE](http://codeat.co/glossary) 

/ ----- FREE VERSION ----- / 

* Term Post Type 
* Capabilities system for post type and taxonomy 
* Glossary Archive 
* Automatic Link Engine 
* 3 Tooltip Templates 
* Internal or External Linking 
* Optional External link icon 
* Tooltip Mode: Link and tooltip, Only Link 
* Widgets: Latest Glossary Terms, Glossary Categories, Alphabet Categories 
* Standard Widgets Template 
* Standard Shortcodes 
* YARPP plugin support 
* Crayon Syntax Highlighter, Ninja Forms, Yoast SEO, YARPP plugin Supported 
* Migration from CM Glossary Tooltip supported 
* No Direct Support 

/ ----- PRO VERSION ------ / 

* All Free Feature 
* Pro Shortcodes 
* 7 Tooltip Templates 
* Tooltip Template Customizer 
* Disable Tooltip on mobile 
* Terms Custom Fields 
* Tooltip Mode: Only Tooltip 
* Case Sensitive Terms Matching 
* Widget Alphabet Categories with 5 themes 
* Search Widget for terms 
* Case sensitive term match 
* Support for RSS Feed 
* Prevent term link to appear in the same term page 
* Archive/Category order also by alphabetic 
* ACF plugin support 
* Mobile tooltip on click 
* Direct Support 

/ ----- ULTIMATE VERSION ------ / 

* All Pro Feature 
* Media support for Youtube, Vimeo, Soundcloud 

== Installation == 

= Using The WordPress Dashboard = 

1. Navigate to the 'Add New' in the plugins dashboard 
2. Search for 'glossary' 
3. Click 'Install Now' 
4. Activate the plugin on the Plugin dashboard 

= Uploading in WordPress Dashboard = 

1. Navigate to the 'Add New' in the plugins dashboard 
2. Navigate to the 'Upload' area 
3. Select `glossary.zip` from your computer 
4. Click 'Install Now' 
5. Activate the plugin in the Plugin dashboard 

= Using FTP = 

1. Download `glossary.zip` 
2. Extract the `glossary` directory to your computer 
3. Upload the `glossary` directory to the `/wp-content/plugins/` directory 
4. Activate the plugin in the Plugin dashboard 

== Frequently Asked Questions == 

= Could I use more than a term title pointing to the same term page? = 
Yes, you are able to use how many term titles you want using the "Related search terms" field into your WordPress Glossary Editor Page. In this way you'll be able to auto-link more than one term to the same page (E.g. Call To Action, CTA, Action Button) 

= Could I use your auto-link engine for affiliation purposes? = 
Yes, and we encourage you to do it. E.g. Amazon Glossary Term links to your Amazon affiliation URL. Everytime one of your users hover on the Amazon link is able to see your tooltip but if they clicks suddenly will redirected on your affiliate link. 

= Is it Glossary Genesis Compatible? = 
Yes, we love Genesis Framework and we care about other Genesis fans. SEO, Layout and Archive section are fully integrated. 

== Screenshots == 

1. Glossary general settings 
2. Glossary Single auto-link setting 
3. Glossary Terms list in WordPress Dashboard 
4. Tooltip Line template 
5. Tooltip Box template 
6. Tooltip Classic template with featured image 
7. Tooltip Classic template without featured image 
8. Glossary features 

== Changelog == 

= 1.4.11 = 
* Bugfix for older php versions 
* Tested now with php7cc and PHP Compatibility to check support for PHP 5.2+ 

= 1.4.10 = 
* Improved: Yoast SEO detection 

= 1.4.9 = 
* Fix: Adding capabilities for website with removed default rols was getting an error 
* Enhancement: Description to Glossary Terms and Glossary Category slug fields cannot use the same slugs

Se vuoi semplificarti la vita ti consiglio di ricopiare questo stesso file e usarlo come base per il prossimo README che creerai, ma voglio comunque soffermarmi su alcuni particolari.

Il campo Contributors deve rispecchiare uno o più username registrati a WordPress mentre i tag sono completamente arbitrari, potrai sbizzarrirti come meglio credi. Il consiglio è quello di cercare i tag di plugin simili al tuo in modo da farti un’idea di quelli da usare. Questo passo spesso è snobbato, a mio avviso è invece importantissimo! Il sito di WordPress non presenta categorie e menù multilivello per orientarsi nella ricerca dei plugin, quindi se vuoi essere trovato dovrai fare un uso saggio del sistema di tag.

Tra License URI e Description troviamo la short description, purtroppo dovrai limitarla veramente tanto perché oltre un tot di caratteri, in fase di pubblicazione, verrà chiesto ripetutamente di accorciarla. Per evitare da subito le scocciature e i ritardi nella pubblicazione del plugin creala essenziale e concentra gli sforzi nella descrizione completa che può essere lunga quanto desideri e sarà la prima pagina con cui gli utenti si confronteranno.

Dalle FAQ in poi, nulla è obbligatorio, potrai decidere se riempirlo o meno; come al solito consiglio di farlo perché ti risparmierà una miriade di domande e potrai tenere traccia di tutti i cambiamenti che applicherai al plugin nel tempo, accrescendo il readme con ulteriori informazioni che scoprirai utili per gli utenti stessi.

Lo Stable Tag indicherà quale versione del plugin dovrà essere considerata stabile da WordPress e dal sistema di aggiornamenti, quindi la prima volta che compilerai questo campo fallo con in mente anche una numerazione per le versioni. Quella classica suggerisce almeno un decimale, ma se il plugin è molto corposo e comprende più files e risorse forse conviene adottarne anche due, per le patch.

Parti da una bella 1.0 oppure 1.0.0 e sarai apposto nella maggior parte dei casi! Altra nota va spesa per la formattazione speciale del testo:

**Questo è un testo BOLD** 
*Questo è un testo corsivo* 
`Questo è codice` 

[Questo è un link a SkillsAndMore](https://skillsandmore.org) 

* Questa è una lista non ordinata 
* Questa è una lista non ordinata 
* Questa è una lista non ordinata 

1. Questa è una lista ordinata 
2. Questa è una lista ordinata 
3. Questa è una lista ordinata

Questa sintassi in realtà è molto diffusa nell’ambiente della programmazione e si chiama Markdown, puoi usare tutte le specifiche che trovate sul sito del progetto per rendere la pagina che realizzerai ancora più bella.

Finito di redigere il readme possiamo usare questo comodo strumento del sito di WordPress, che come al solito ci viene incontro. Permette di validare il txt e controllare che tutto sia al giusto posto.

7. Pubblichiamo il plugin usando il sistema di subversioning SVN di WordPress.org

Se non l’hai ancora fatto, questo è il momento giusto per iscriversi a WordPress.org e volendo anche a Gravatar per ottenere un immagine del profilo più carina del classico profilo anonimo da associare alla mail che userai durante la registrazione.

Ora è giunto il momento di chiedere a WordPress.org di fornirvi uno spazio e le credenziali per accedere in SVN al loro repository. Prima che questo avvenga però vorranno revisionare (a mano) il vostro plugin.

Collegateti al developer center di WordPress e clicca su “Add Your Plugin”. Ti verrà chiesto un link da cui scaricarlo e di fornirne una piccola descrizione, se hai inserito correttamente il file readme non avrai problemi ad effettuare rapidamente questo passaggio.

Appena il plugin è stato revisionato (in genere ci vuole qualche giorno) riceverai una mail con tutti i dati relativi allo spazio che ti è stato concesso nel repository! Prima di andare avanti voglio ricordarti le poche regole per poter essere ospitati su WordPress.org:

1.  Il plugin deve essere rilasciato sotto licenza GPL2.0 o successive
2.  Non inserire materiale offensivo o illegale, anche se difficilmente lo farai è sempre meglio ricordarlo
3. Non inserite link nel codice nella speranza di ottenere backlink senza l’esplicito consenso dell’utente o senza dargli la possibilità di rimuoverlo facilmente. Nel caso in cui vogliate scegliere di metterlo di default e dare la possibilità all’utente di toglierlo, SPECIFICATELO BENE sia nella documentazione sia nel readme
4. Il resto, come ci dice anche WordPress.org, è solo una serie di regole che spiegano come non essere uno spammer.

Appena riceverai conferma della revisione del plugin, ti verrà fornito il link al tuo repository e le credenziali per accedervi. A questo punto cerca una GUI per SVN per rendere le operazioni più veloci e pratiche. Siccome si parla di scrivere percorsi di cartelle e URL, la riga di comando la lasciamo ai più temerari, che rimanderemo alla lettura del Codex.

Se vuoi qualche consiglio potresti usare TortoiseSVN per Windows e RapidSVN per Linux e Mac.

Adesso è giunto il momento di introdurre qualche concetto generale del sistema di subversioning per permetterà di padroneggiare le operazioni di revisione e pubblicazione del codice. Le operazioni principali che farete saranno 3:

1. Importare il repository (questo generalmente si fa la prima volta e in caso ci si voglia lavorare su più postazioni)
2. Aggiungere i file alla lista dei file da committare
3. Fare il commit

Iniziamo con ordine, prendi il client SVN che hai scelto e importa (checkout è il termine che troverai in molti casi) la struttura del repository in una cartella appositamente creata da (io l’ho messa nella cartella /home/progetti/glossary-by-codeat/), usando il link e le credenziali fornite da WordPress.

A questo punto noterai che nella cartella sono state create automaticamente delle sottocartelle, esaminiamole per bene.

/trunk/

Qui metteremo il codice su cui attualmente stiamo lavorando, può tranquillamente essere l’ultima stabile se non hai in progetto nulla di nuovo, la cosa importante è che questa sia la prima cartella riempita di tutti i files e le cartelle usati dal plugin, compreso il nostro carissimo file readme.txt.

/tags/

Questa cartella deve contenere sottocartelle nominate con il numero di versione, puoi iniziare con il creare la 1.0 e copiarci il contenuto di /trunk/. Il modo in cui si dovrebbe procedere è, infatti, quello di lavorare nella cartella trunk e poi a codice ultimato e testato creare una nuova cartella in /tags/ e copiarci direttamente tutto dentro, stando attenti a modificare poi il numero di versione stabile nel readme sia nel trunk che nella cartella corrente.

/branches/

Qui siamo facilitati dalla parola stessa che ci indica la funzione della cartella. Ovviamente se lo stai pubblicando per la prima volta è poco probabile che tu abbia branches disponibili, se comunque senti la necessità di utilizzarli questa è la cartella dove piazzare tutto il codice!

/assets/

Questa cartella è praticamente a tua disposizione per inserirci tutto ciò che potrebbe tornarti utile, io la uso per aggiornare la documentazione per esempio. La funzione fondamentale di questa cartella però è quella di permetterci di caricare il banner e gli screenshot del nostro plugin da mostrare poi nella relativa pagina su wordpress.org.

Gli screenshot devono essere rinominati in questa forma <em>screenshot-1.png con numero progressivo, per essere associati alla relativa descrizione che abbiamo messo nel readme mentre il banner deve essere un png di 772×250 pixel e deve chiamarsi banner-772x250.png.

Riempite le varie cartelle con i giusti files che dovrai procedere ad aggiungere (add in molti client) e successivamente a committare (commit). Controllate bene di aver aggiunto tutti i files, anche quelli nelle sottocartelle del vostro plugin, prima di fare commit. Avere un client SVN è comodo perchè ci segnala i cambiamenti nelle cartelle e ci fa notare eventuali disallineamenti di versioni con il server.

Ricordiamoci  che per “spingere” un aggiornamento per il plugin basta cambiare il parametro stable del readme messo nel /trunk, quindi prima creiamo le cartelle, committiamo tutto nella cartella relativa alla nuova versione e cambiamolo nel suo readme.txt e poi anche in quello del /trunk!

Il sistema di subversioning ci permette altre operazioni comode per spostare, unire e controllare le differenze tra le varie revisioni (i commentini di cui parlavo prima), per questo vi rimando ad una basilarissima ma completa guida sul tema.

Conclusioni

Eccoci giunti alla fine di questo articolo. Quelle che sono state presentate sono state le cose che avrei voluto conoscere prima ancora di scrivere il mio primo plugin e spero che sia stata una piccola guida utile a farti m,uovere i primi passi.

Come spesso accade su questo blog, mi farebbe piacere cosa ne pensi di questo articolo, se hai dubbi, se vuoi condividere qualche suggerimento… Insomma, per qualsiasi comunicazione, la sezione dei commenti è proprio qua sotto!