Author: Renato Formato

PRESENTAZIONE
Il plugin Annotations consente di visualizzare delle annotazioni (testo, immagini, video etc) su immagini generiche. Le annotazioni sono associate ad un punto specifico dell'immagine ed indicate mediante l'uso di icone personalizzabili (“marker”). Il testo relativo all'annotazione potrà essere visualizzato sia al passaggio del mouse sul marker che cliccando sullo stesso.
PRIMI PASSI
Come per tutti i plugin, si procederà allo scaricamento dell'archivio zip (link), alla sua decompressione ed al successivo upload nella cartella plugins del proprio sito SPIP.
Dopo aver attivato il plugin dalla redazione di SPIP, sarà necessario preparare i modelli sui quali si vuole usufruire delle funzionalità di annotazione, come vedremo in seguito. 
MODALITA' DI GESTIONE DEI DATI DELLE ANNOTAZIONI
Il plugin consente di leggere le annotazioni inserite a partire da un qualsiasi supporto di memorizzazione, ad esempio una tabella del proprio database, ma non solo. Infatti, il plugin propone una interfaccia software generica di lettura di tali dati, sfruttando il formato di interscambio dati client-server JSON (http://json.org/).
Il plugin propone 2 implementazioni:
1)	Lettura e scrittura dei dati in una tabella aggiuntiva (“spip_annotations”) - modalità predefinita
2)	Lettura e scrittura dei dati mediante l'uso dei forum di SPIP
I file di interscambio JSON, essendo dei normali file di testo, possono essere creati anche mediante la scrittura di particolari modelli di SPIP, utilizzando cicli e segnaposti.
Dal punto di vista del redattore, le immagini annotate possono essere inserite nel corpo di un articolo, mediante il tag <anno_docXX>, dove XX è il numero dell'immagine caricata in un articolo, oppure come documenti allegati. In quest'ultimo caso sarà necessario predisporre i propri modelli affinché SPIP possa rilevare la presenza di immagini annotate ed attivare le funzionalità del plugin.
PREPARAZIONE DEI MODELLI
Tutti i modelli che contengono immagini annotate dovranno necessariamente presentare il segnaposto #INSERT_HEAD all'interno del tag <head>, per indicare a SPIP di caricare tutti gli script necessari al corretto funzionamento delle annotazioni (la libreria javascript jQuery ed altri plugin di jQuery)
Utilizzo di immagini annotate allegate
Qualora si utilizzino immagini annotate allegate, e non inserite nel corpo di un articolo, sarà necessario aggiungere ai relativi tag <IMG>, l'attributo id=”annotated_mapXX”, dove XX è l'id dell'immagine allegata.
Gestione delle annotazioni mediante la tabella aggiuntiva “spip_annotations”
Il plugin fornisce una finestra di gestione delle annotazioni, visualizzabile direttamente dalla parte pubblica del sito e solo da utenti loggati. Per ogni immagine annotata “allegata” (non presente nel corpo dell'articolo) è necessario aggiungere il seguente codice per mostrare il link alla finestra di gestione:
[(#SESSION{statut}|=={0minirezo}|?{' ',''})
	<div class="spip_doc_descriptif">
		<a class="annotate_link" id="map_#ID_DOCUMENT" href="#" title="<:annotations:manage_points_title:>"><:annotations:manage_points:></a>
	</div>
]

Da notare che il filtro =={0minirezo} attiva la gestione delle annotazioni per i soli amministratori.
Modificando il valore del filtro è possibile personalizzare il tipo di utente abilitato a gestire le annotazioni
Infine, bisognerà aggiungere immediatamente prima della chiusura del tag <body> il seguente codice, che rappresenta la finestra di gestione vera e propria:
<INCLUDE{fond=inc-annotationswindow}>

Ricapitolando:
-Inserire il segnaposto #INSERT_HEAD
-Per le immagini annotate allegate inserire l'id “annotated_mapXX” ad ogni immagine
-Se si adotta la modalità di gestione con la tabella “spip_annotations”, inserire il link alla finestra di gestione e il codice di gestione della finestra prima della chiusura del body

Nel plugin è fornito un modello di articolo (article.html) già modificato come esempio.
Gestione delle annotazioni mediante forum
La gestione mediante forum, consente di utilizzare i forum di SPIP per la lettura e scrittura delle annotazioni.
A tale scopo è possibile utilizzare il segnaposto 
#FORMULAIRE_ANNOTATIONS{#SELF}
che presenta un modulo personalizzato per l'immissione dell'annotazione.
E' evidente che, a seconda dell'effetto voluto, il webmaster potrebbe non voler mostrare affatto i messaggi del forum, ma semplicemente le annotazione in essi contenuti, eliminando, quindi, tutti i cicli sui forum dai propri modelli.
Una ulteriore modifica consiste nel modificare il file config_annotations.js.html, in cui si trovano delle righe commentate per attivare la modalità forum. Basterà invertire i commenti sulle seguenti righe.
loadCoordsAnnotations: "#URL_PAGE{show_image_annotations}",
//loadCoordsAnnotations: "#URL_PAGE{show_image_annotations_forum}",
.........
loadAnnotationText: "#URL_PAGE{get_annotation_text}",
//loadAnnotationText: "#URL_PAGE{get_annotation_text_forum}",
Visualizzazione delle annotazioni con tooltip o con finestre di overlay
E' possibile modificare la modalità di visualizzazione delle annotazioni invertendo i commenti tra le seguenti righe, poste alla fine del file cfg_annotations.js.html
jQuery.carto.loadMarkersWithTooltip();
//jQuery.carto.loadMarkersWithOverlay();
DOCUMENTAZIONE DEL PLUGIN JQUERY annotations
Impostare un marker personalizzato:
var marker = {mapMarker: {
	//il tag <img> da utilizzare come marker
	src: "<img src='..' width='32' height='32' />",
	//opzionale, se il marker non è rettangolare è possibile specificare una mappa html con 	//coordinate di tipo 'poly'
	map: "<map><area coords='11,29,10,25,8,21,6,16,4,12,1,9,7,8,7,0,15,0,15,8,22,9,18,12,17,15,15,19,13,23,11,31' shape='poly' alt=''' href='javascript:void(0)'/></map>",
	//opzionale, indicano le coordinate del marker che andranno a coincidere con il punto in 	//cui il marker viene aggiunto (nell'esempio un marker aggiunto alle coordinate x,y 	//dell'immagine, avrà il suo angolo in basso a destra coincidente con tale punto) 
	hotSpot: [32,32]		
	},
};
jQuery.extend(jQuery.carto,marker);
Impostare le url di lettura dei dati e delle immagini di servizio:
jQuery.extend(jQuery.carto,{
	cfg: {
		//url per caricare le coordinate delle annotazioni per una data immagine
		loadCoordsAnnotations: "#URL_PAGE{show_image_annotations}",
		//url per caricare il testo di una data annotazione
		loadAnnotationText: "#URL_PAGE{get_annotation_text}",
		//immagine vuota
		emptyImage: "#CHEMIN{images/rien.gif}",
		//immagine di caricamento
		loaderImage: "#CHEMIN{images/loader.gif}",
		}
	});
Formato del file JSON processato da loadCoordsAnnotations:
{"documents":{ //i dati delle immagini
	//una proprietà con nome uguale all'id dell'immagine per ogni immagine
	"1":{
	     "width": 200, //dimensioni dell'immagine NON RIDIMENSIONATA in px
	     "height": 200		
	},
	"2":{
	     "width": 200,
	     "height": 200
	},
	.....
},
"ids":[ //tutte le annotazioni
	{
	    "id_annotation":1, //id annotazione
	    "id_document":1, //id documento
	    "title": “titolo”, //titolo annotazione
	    "x":12, //coordinata x dell'annotazione sull'immagine NON RIDIMENSIONATA
	    "y":14 //coordinata y dell'annotazione sull'immagine non ridimensionata
	},
	{
	    "id_annotation":2,
	    "id_document":1,
	    "title": “titolo”,
	    "x":32,
	    "y":48
	},
	......
]}

Formato del file da loadAnnotationText:
HTML standard
Nelle implementazioni proposte sul click di un link con classejqmClose si provoca la chiusura del tooltip o della finestra di overlay.

API

jQuery.carto.loadMarkers(root,callback,params)
Caricamento delle annotazioni per le immagini annotate presenti all'interno di un tag della pagina.
Argomenti:
–	root (selettore jQuery, elemento o oggetto jQuery)
–	Elemento base a partire dal quale cercare le immagini annotate (tag <img> con id del tipo annotated_mapXX dove XX è l'id dell'immagine)
–	callback (funzione con firma function(data,images))
–	funzione richiamata a caricamento completato, responsabile della visualizzazione dei markers e del collegamento dei relativi eventi.
–	Argomenti:
–	“data” è l'oggetto restituito dal file JSON  loadCoordsAnnotations
–	images è un hash di oggetti jQuery contententi le immagini annotate trovate all'interno di root, 
–	in cui il nome è l'id dell'immagine {“1”:oggetto jQuery immagine 1,”2”:oggetto jQuery immagine 2}
–	params (hash {nome:valore}) (opzionale)
–	parametri aggiuntivi passati nella richiesta del file loadCoordsAnnotations

jQuery.carto.loadMarkersWithTooltip(root,params)
Funzione helper per il caricamento delle annotazioni per le immagini annotate presenti all'interno di un tag della pagina  e visualizzazione con tooltip.
Argomenti:
–	root (selettore jQuery, elemento o oggetto jQuery)
–	Elemento base a partire dal quale cercare le immagini annotate (tag <img> con id del tipo annotated_mapXX dove XX è l'id dell'immagine)
–	params (hash {nome:valore}) (opzionale)
–	parametri aggiuntivi passati nella richiesta del file loadCoordsAnnotations
–	
jQuery.carto.loadMarkersWithOverlay(root,params)
Funzione helper per il caricamento delle annotazioni per le immagini annotate presenti all'interno di un tag della pagina e visualizzazione con finestra di overlay.
Argomenti:
–	root (selettore jQuery, elemento o oggetto jQuery)
–	Elemento base a partire dal quale cercare le immagini annotate (tag <img> con id del tipo annotated_mapXX dove XX è l'id dell'immagine)
–	params (hash {nome:valore}) (opzionale)
–	parametri aggiuntivi passati nella richiesta del file loadCoordsAnnotations

jQuery.carto.loadCoordAnnotations(ids,callback,params) 
Funzione per il caricamento delle annotazioni per le immagini annotate con id specificato.
Argomenti
–	ids: (matrice di interi)
–	gli id delle immagini per cui caricare le annotazioni
–	callback (funzione con firma function(data))
–	funzione richiamata a caricamento completato a cui viene passato come argomento l'oggetto
–	l'oggetto restituito dal file JSON  indicato da jQuery.carto.cfg.loadCoordAnnotations
–	params (hash {nome:valore}) (opzionale)
–	parametri aggiuntivi passati nella richiesta del file indicato da jQuery.carto.cfg.loadCoordAnnotations
–	Gli id delle immagini vengono passati in altrettanti parametri con nome id_document[]

jQuery.carto.displayMarkers(points,images,id_prefix,callback) 
oppure
jQuery.carto.displayMarkers(points,images,callback) 
Funzione per visualizzare le annotazioni sulle relative immagini.
Argomenti
–	points (oggetto restituito dal file JSON indicato da jQuery.carto.cfg.loadCoordAnnotations)
–	images (hash)
–	è un hash di oggetti jQuery contententi le immagini annotate trovate all'interno di root, 
–	in cui il nome è l'id dell'immagine {“1”:oggetto jQuery immagine 1,”2”:oggetto jQuery immagine 2}

–	id_prefix (stringa default:”map_marker”):
      prefisso dell'id da impostare per i marker e per tutti gli altri elementi creati da questa funzione.
      Utile per mostrare più volte in una pagina gli stessi markers     
–	callback (funzione con firma function(point,attr)):
–	elabora gli attributi da aggiungere al marker per un dato punto e li restituisce modificati
–	Argomenti
–	point (oggetto item della matrice points.ids ) 
–	attr (hash nome valore di attributi)
     Esempio: 
	function(point,attr) {
		attr.title = point.title+"; click here to show the data";
		return attr;	
	}	 	

jQuery.carto.addMarker(selector,coord,attr)
Aggiunge un marker all'immagine.
Argomenti:
–	selector (selettore jQuery, elemento o oggetto jQuery) 
–	rappresenta l'immagine su cui aggiungere il marker
–	coord (oggetto {xy:[x,y]})
–	coordinate dell'immagine in cui aggiungere il punto
–	attr (hash {nome:valore})
–	attributi da inserire del tag del marker