Creare un plugin per WordPress (WP) è un’operazione abbastanza semplice, a patto che si seguano i pochi accorgimenti e regole base stabilite da WP (per maggiori info https://wordpress.org/plugins/about/).
Attraverso questo tutorial realizzeremo un plugin base per la creazione e la gestione di uno slider utilizzabile in WP (http://wordpress.org/plugins/slider-you-n/).
Consigliamo di iniziare lo sviluppo su una installazione aggiornata all’ultima versione di WP e pulita (senza plugin aggiuntivi, costante WP_DEBUG settata a TRUE).
Con una connessione FTP entriamo nella cartella /wp-content/plugins e creiamo la cartella che conterrà il nostro codice, in questo caso: “slider-you-n”. Il secondo passaggio prevede l’inserimento al suo interno dei file utili al nostro obiettivo: un file .php che chiameremo Yslider.php e che dovrà contenere delle informazioni simili a quelle inserite nel file style.css quando si crea un tema custom.
Ecco cosa bisogna inserire:
[php] /*** @package SliderYou-n
* @version 1.2
* @author <e-mail autore>*/
/*
Plugin Name: Slider You-n v 1.2
Plugin URI:
Description: A simple and full customizable WordPress plugin for slideshow creation, responsive or none
Author: <e-mail autore>
Version: 1.2
Author URI: http://www.you-n.com
*/
[/php]
I commenti php qui sopra contengono delle informazioni base che serviranno al core di WP per riconoscere il nostro plugin.
Ora possiamo creare un file readme.txt che conterrà le informazioni necessarie a “riempire” la pagina del plugin sul sito wordpress.org, ad esempio: http://www.wordpress.org/plugins/slider-you-n/.
Per maggiori informazioni sui campi vi invitiamo a visitare la pagina https://wordpress.org/plugins/about/readme.txt; per validare il vostro file readme.txt potete andare su https://wordpress.org/plugins/about/validator/.
Completati questi due passi sarà possibile passare alla stesura del codice php.
- 1. Aprire il file .php creato in precedenza (Yslider.php).
Attenzione: non è obbligatorio seguire questa metodologia di sviluppo orientato agli oggetti. Tuttavia, qualora si scegliesse di farlo, è molto importante ricordarsi di aggiungere un prefisso o un suffisso standard per le definizioni di costanti, classi e metodi, in modo da non influire su eventuali altri plugin.
- 2. Inseriamo delle costanti che serviranno per il corretto funzionamento.
defined(‘YSLIDER_SETTINGS’) or define(‘YSLIDER_SETTINGS’, ‘Yslider_settings’);
defined(‘YSLIDER_FOTO_SRCS’) or define(‘YSLIDER_FOTO_SRCS’, ‘Yslider_foto_srcs’);
if (!defined(‘YSLIDER_UPLOAD_PATH’)) {
$uploads_info = wp_upload_dir();
$YsliderUpload = $uploads_info[‘basedir’];
if (!is_dir($YsliderUpload . ‘/YouSlider’)) {
if (wp_mkdir_p($YsliderUpload . ‘/YouSlider’)) {
define(‘YSLIDER_UPLOAD_PATH’, $YsliderUpload . ‘/YouSlider’);
wp_mkdir_p($YsliderUpload . ‘/YouSlider/thumbs/’);
} else {
die(‘La cartella non è stata creata!!!!’);
}
}
}[/php]
Importante: l’ultima definizione si occupa di verificare che la cartella di upload delle foto esista. Solitamente si crea per la prima volta quando viene istanziato il plugin.
Può capitare che, a seconda della configurazione del server, l’installazione fallisca per via dei permessi di scrittura sulla cartella uploads di WP.
Definite le costanti di cui abbiamo bisogno, si può ora creare la classe del plugin:
[php]/*** Classe del plugin
*/
class Yslider {
function __construct() {
// Create the settings array by merging the user’s settings and the defaults
$usersettings = (array) get_option(YSLIDER_SETTINGS);
$defaultArray = $this->Ys_getBaseSetting();
//check whether stored settings are compatible with current plugin version.
//if not: overwrite stored settings
$validSettings = $this->validateSettingsInDatabase($usersettings);
if (!$validSettings) {
$this->YsliderSettings = $defaultArray;
update_option(YSLIDER_SETTINGS, $defaultArray);
} else {
$this->YsliderSettings = wp_parse_args($usersettings, $usersettings);
}
$userFoto = (array) get_option(YSLIDER_FOTO_SRCS);
$dafaultArrayFoto = $this->checkFotoInDB($userFoto);
if (!$dafaultArrayFoto) {
$this->foto = $userFoto;
} else {
$campi=array(
‘id’=>0,
‘path’=>”,
‘title’=>”,
‘alt’=>”,
‘nome’=>”
);
$this->foto = wp_parse_args($userFoto, $campi); //
update_option(YSLIDER_FOTO_SRCS, $campi);
}
if (is_admin()) {
include_once ‘core/YsliderBE.php’;
new Ys_BEPage($this->YsliderSettings, $this->foto);
} else {
//qui parte front!!
include_once ‘core/YsliderFront.php’;
new YS_FrontPage($this->YsliderSettings, $this->foto);
}
}
/**
* Get default settings of plugin
* @return Array
*/
function Ys_getBaseSetting() {
return array(
‘version’ => ‘1.2’,
‘active’ => true,
‘width’ => ‘625’,
‘height’ => ‘480’,
‘speed’ => ‘4000’,
‘fx’=>’fade’,
‘color’=>’#fff’,
‘paginatore’=>true,
‘colorPaginatore’=>’#fff’,
‘responsive’=>FALSE
);
}
function validateSettingsInDatabase($settings) {
if ($settings) {
if (!array_key_exists(‘version’, $settings)) {
return false;
}
}
return true;
}
/**
* check if the option plugin is write in wp_options table
* @param array $userFoto
* @return boolean
*/
function checkFotoInDB($userFoto) {
if ($userFoto) {
if (!array_key_exists(‘id’, $userFoto)) {
return false;
}
}
return true;
}
}
new Yslider();
[/php]
Queste poche righe di codice si occupano di istanziare la classe “base” del plugin.
Il costruttore ora deve controllare se sono presenti delle scritture nella tabella wp_options (
[php]$usersettings = (array) get_option(YSLIDER_SETTINGS);[/php]) relativamente alle configurazioni base e alle configurazioni custom del plugin.
Se sono presenti, devono essere assegnate alla proprietà “YsliderSettings” (
[php]$this->YsliderSettings = wp_parse_args($usersettings, $usersettings);[/php]) altrimenti a “YsliderSettings” verranno assegnate le configurazioni base:
[php]$this->YsliderSettings = $defaultArray;update_option(YSLIDER_SETTINGS, $defaultArray);[/php]
Un procedimento analogo viene effettuato sulle foto: il nome della proprietà è “foto”.
Come si nota dal codice del costruttore della classe Yslider, a seconda della pagina visualizzata verrà istanziata la appropriata classe per gestire lo slider:
[php]if (is_admin()) { //stiamo visualizzando l’amministrazione del sitoinclude_once ‘core/YsliderBE.php’;
new Ys_BEPage($this->YsliderSettings, $this->foto);
} else {//stiamo visualizzando il front
include_once ‘core/YsliderFront.php’;
new YS_FrontPage($this->YsliderSettings, $this->foto);
}[/php]
Come si nota dagli include, il codice che compone questo plugin è stato suddiviso in più file: in particolare, la cartella “core” contiene le classi per visualizzare lo slider nelle pagine del front (YsliderFront) dove è incluso oppure crea le voci di menu e la pagina per la gestione all’interno del back end (YsliderBE.php).
Il file YsliderBE.php
Questo file contiene la dichiarazione della classe che gestisce il backend e le classi per gestire l’upload di foto (credits: http://github.com/valums/file-uploader). Potete notare che per gestire il resize delle immagini è stata utilizzata la libreria Timthumb (http://timthumb.googlecode.com/svn/trunk/timthumb.php); inoltre, è opportuno prestare attenzione alla configurazione per evitare vulnerabilità di sicurezza.
Il costruttore della classe Ys_BEPage prende come argomenti $settings e $foto (in pratica le proprietà “YsliderSettings” e “foto” della classe Yslider passati in fase di istanza di Ys_BEPage.)
Continuiamo con il codice del costruttore: aggiungiamo hook al core di WP per gestire alcuni casi ed azioni particolari. Di seguito un estratto del codice del metodo magico __construct($settings, $foto):
[php]add_action(‘admin_menu’, array($this, ‘addYmenu’), 11);add_action(‘admin_post_YsliderUpdateSettings’, array(&$this, ‘YsliderUpdateSettings’));
add_action(‘admin_post_YsliderUpdateFoto’, array(&$this, ‘YsliderUpdateFoto’));[/php]
La prima chiamata a add_action() comanda al core di WP di creare le voci di menu attraverso il metodo addYmenu della classe Ys_BEPage, mentre le successive chiamate si occupano di gestire l’evento di aggiornamento configurazioni e upload di foto che vedremo più avanti.
Di seguito il codice di addYmenu:
[php] /*** aggiunge la voce di menù
* @param null
*
* @return null
*
*/
function addYmenu() {
if (function_exists(‘add_menu_page’)) {
$messaggio = ”;
add_menu_page(‘Slider You-n’, ‘Slider You-n’, ‘administrator’, ‘yslider’, array(&$this, ‘renderAdminPage’), YS_PLUGIN_URI . ‘/images/you-slider-menu-thumb.png’, 26);
if (isset($_GET[‘YsliderUpdateSettings’]) || isset($_GET[‘YsliderUpdateFoto’])) {
$messaggio = ‘Modifiche Apportate con successo!’;
}
$this->showMyMessage($messaggio);
}
}[/php]
Questo metodo, oltre a creare la voce di menu (con una iconcina personalizzata), si occupa di legare al click sulla voce di menu il metodo renderAdminPage(), e di visualizzare un messaggio quando si aggiornano le impostazioni del plugin.
Nota: a tal riguardo è possibile inserire un hook per gestire anche questo caso, ma non è argomento di questa guida.
Da notare il passaggio per riferimento dell’oggetto $this
Il metodo renderAdminPage()
[php]/** chiama il php che genera la pagina Home del plugin
* @subpackage home.php
*
*
* @param null
*
* @return null
*/
function renderAdminPage() {
include PLUGIN_URL . ‘/includes/sliderBEConf.php’;
include PLUGIN_URL . ‘/includes/sliderBEFoto.php’;
}
[/php]
Come anticipato sopra, il codice di questo plugin è stato spezzettato in sottodirectory.
La cartella “includes” contiene due script php che renderizzano l’html della pagina del plugin (configurazione e upload / gestione foto)
Anche trattandosi di una sola pagina, il codice è stato diviso solamente per comodità.
Il salvataggio viene gestito dai metodi anticipati sopra: “YsliderUpdateSettings” per le configurazioni e “YsliderUpdateFoto” quando si salva l’ordine delle foto.
Le altre azioni, come ad esempio la gestione dell’ordine o l’aggiornamento dei tag alt e title delle immagini che compongono lo slider, sono gestite tramite chiamate AJAX.
Completata la scrittura dei metodi che si occupano della configurazione dello slider, si può ora procedere alla stesura del codice che gestisce la parte visibile agli utenti finali.
Il file YsliderFront.php
Questo file è simile al “fratello” che si occupa di gestire la parte di configurazione del plugin.
Il costruttore deve prendere come parametri le due proprietà esaminate all’inizio di questo tutorial: $settings e $foto. In questo momento, quando nella configurazione è settato lo stato active a TRUE, l’unica azione eseguita è l’inclusione degli scipt Javascript e dei fogli di stile base.
[php]if ($this->YsliderSettings[‘active’] === TRUE) { //includo tutti gli script, inizializzo lo slideradd_action(‘wp_enqueue_scripts’, array(&$this, ‘YS_SetScriptFront’));
add_shortcode(‘YS-slider’, array(&$this, ‘YS_render_slider’));
}[/php]
Il metodo “YS_SetScriptFront” come si intuisce dal nome e dal codice carica e lega al core di WP gli script e i CSS necessari al corretto funzionamento del nostro slider.
[php] /*** Funzione per appendere gli script all’header del front
*
* @param null
* @return void
*/
function YS_SetScriptFront() {
global $post;
$isYS_page = get_post_meta($post->ID, ‘YSslide’, true);
if ($isYS_page == ‘on’) {
$width = ”;
if ($this->YsliderSettings[‘width’] == ‘100%’) {
$width = ‘100’;
}
?>
<script type=”text/javascript”>
<?php if ($this->YsliderSettings[‘width’] != ‘100%’) { ?>
var widthResize= <?php echo $this->YsliderSettings[‘width’]; ?>;
<?php } ?>
var heightResize= <?php echo $this->YsliderSettings[‘height’]; ?>;
var speed= ‘<?php echo $this->YsliderSettings[‘speed’]; ?>’;
var fx ='<?php echo $this->YsliderSettings[‘fx’]; ?>’;
var paginatore=false;
<?php if ($this->YsliderSettings[‘paginatore’] == TRUE) { ?>
paginatore=true;
var colorePaginatore= ‘<?php echo $this->YsliderSettings[‘colorPaginatore’] ?>’;
<?php } ?>
var Zindex = <?php echo sizeof($this->foto); ?>;
var responsive=false;
<?php if ($this->YsliderSettings[‘responsive’] == TRUE) { ?>
responsive=true;
<?php } ?>
</script>
<?php
wp_enqueue_script(‘jquery’);
wp_register_script(‘cycle’, YS_PLUGIN_URI . ‘/js/cycle.js’, array(), ‘1.0’, TRUE);
wp_register_script(‘cycleFront’, YS_PLUGIN_URI . ‘/js/gestSliderFront.js’, array(), ‘1.0’, TRUE);
wp_register_script(‘resize’, YS_PLUGIN_URI . ‘/js/jResize.js’, array(), ‘1.0’, TRUE);
wp_register_script(‘gestResize’, YS_PLUGIN_URI . ‘/js/gestResize.js’, array(), ‘1.0’, TRUE);
wp_register_style(‘YS_default’, YS_PLUGIN_URI . ‘/css/YS_default-configuration.css’, array(), ‘screen’);
wp_enqueue_script(‘cycle’);
wp_enqueue_script(‘cycleFront’);
wp_enqueue_style(‘YS_default’);
}
}
[/php]
Tra quelli sopra descritti, l’unico script degno di nota è gestSliderFront.js che prende le variabili JS settate in precedenza e, in caso di slider responsive con immagini ed altezze diverse, si occupa di riposizionare il paginatore (se visibile) e i comandi, sempre in posizione centrale.
Terminata la stesura del codice, non rimane altro che testarlo! 🙂
Dopo i test (si consiglia vivamente di testare il plugin su un sito WP che utilizzi altri plugin attivi, in modo da scoprire eventuali incompatibilità), dopo aver revisionato, pulito e ottimizzato il codice, possiamo pubblicare il nostro nuovo plugin nei repository di WP.
Per caricare il vostro codice, vi basterà andare sulla pagina http://www.wordpress.org/plugins/add/ fare la registrazione e completare il profilo.
Attenzione: è necessario possedere uno spazio web in remoto dove caricare un file .zip che conterrà il vostro progetto.
Una volta che il codice sarà stato esaminato dai revisori di WP, riceverete gli accessi e le istruzioni rigorosamente in Inglese, per caricare via SVN il vostro codice, che finalmente sarà rilasciato alla comunità.
Nel prossimo tutorial analizzeremo nel dettaglio il codice di un secondo plugin sviluppato dall’Agenzia di comunicazione e marketing non convenzionale You-n specifico per Google Maps!
Stay tuned!