TNT Locator: istruzioni per l’embedding Versione 2.0.1
Per includere TNT Locator all’interno delle proprie pagine web sarà sufficiente inserire il seguente codice all’interno dei tag <head>:
Per richiamare l’apertura del TNT Locator basterà utilizzare un pulsante o un’icona che richiami la funzione openLocator() mediante l’evento onClick:
oppure utilizzando JQuery:
La funzione openLocator() accetta un oggetto di tipo JSON.
I parametri della funzione sono i seguenti:
- width: si tratta della larghezza espressa in pixel della finestra di TNT Locator. Può essere impostato ad un valore minimo di 780 pixel. Tale limite viene
automaticamente forzato nel caso in cui venga inserito un valore minore. Valore di default: 780.
- height: si tratta dell'altezza espressa in pixel della finestra di TNT Locator. Può essere impostato ad un valore minimo di 600 pixel. Tale limite viene
<html>
<body>
…
<button
onClick="openLocator({width:'1024',height:'768',address:'torino',modView:'101'})"
>Seleziona il punto di consegna</button>
…
</body>
</html>
<html>
<head>
…
<script id="scriptLocator" type="text/javascript"
src="//locator.tntitalia.it/locator/v2/locator.js?id=00000">
</script>
</head>
…
<html>
<head>
<script>
$(document).ready(function(){
$(“#openicon”).click(function() {
openLocator({width:'1024',height:'768',address:'torino',modView:'101'});
});
});
</script>
</head>
<body>
…
<button id=”openicon”>Seleziona il punto di consegna</button>
…
</body>
</html>
automaticamente forzato nel caso in cui venga inserito un valore minore.Valore di default: 600.
- address: si tratta dell’indirizzo di partenza su cui desideriamo effettuare la ricerca all’apertura del TNT Locator. Può essere valorizzato con l’indirizzo predefinito di consegna dell’utente oppure con la posizione rilevata dal suo browser. Se presente, la mappa verrà centrata su tale indirizzo, se assente verrà posizionata sull'Italia intera. Comportamento di default: il locator viene centrato sull'Italia intera.
- view: indica la modalità con cui verrà aperto il TNT Locator. Il parametro può assumere i seguenti valori: “window” o “modal”. Se view è impostata a “window”, il TNT Locator si aprirà in una nuova finestra del browser, se view è impostata a
“modal”, verrà aperto in un JQuery Dialog ospitante il TNT Locator. Valore di default: modal.
- depot: questo parametro filtra i risultati ai soli delivery point serviti dalla filiale specificata (codice filiale di competenza, es “PD1”). Se non specificato, non vengono applicati filtri all’elenco dei delivery point.
- modopen: è una variabile che permette di selezionare quali tipi di delivery point devono essere mostrati all’utente. Il suo valore è composto da tre cifre, ognuna associata ad un tipo di punto (Filiali TNT, LockerBox e TNT Point). Ogni cifra può assumere un valore tra 0 e 1. Il valore 1 abilità la visualizzazione, mentre 0 la disabilità. Il valore è così composto:
o Primo digit: abilità/disabilita la visualizzazione delle Filiali TNT.
o Secondo digit: abilità/disabilita la visualizzazione delle LockerBox.
o Terzo digit: abilità/disabilita la visualizzazione dei TNT Point.
In questa tabella vengono mostrati tutti i valori assegnabili alla variabile openMod:
Codice Comportamento
000 Tutti I punti 001 Solo TNT point 010 Solo Lockerbox 100 Solo filiali 101 Filiali e TNT Point 011 Lockerbox e TNT point 110 Filiali e Lockerbox
111 Tutti
E’ bene tener presente che in futuro potrebbero essere inserite nuove tipologie di delivery point. Valore di default: 111, vengono mostrati tutti i delivery point disponibili.
NB: la funzione openLocator() è disabilitata per i dispositivi mobili. In questo caso è opportuno nascondere l'opzione all'utente.
Quando l’utente avrà selezionato il delivery point in cui far recapitare la propria spedizione nella variabile locatorReturn saranno presenti tutti i dati riguardanti il delivery point selezionato:
- nome: accessibile utilizzando locatorReturn.name. contiene il nome del delivery point
- indirizzo: accessibile utilizzando locatorReturn.address;
- città: accessibile utilizzando locatorReturn.city;
- provincia: accessibile utilizzando locatorReturn.prov;
- cap: accessibile utilizzando locatorReturn.cap;
- codice: accessibile utilizzando locatorReturn.code. È il codice del delivery point;
- delivery option: accessibile utilizzando locatorReturn.deliveryOption.
Definisce il tipo di delivery point selezionato.
o Le filiali codice 1;
o I point codice 3;
o I locker codice 5
-
tntMessage: accessibile utilizzando locatorReturn.tntMessage. È una variabile booleana impostata a true che identifica il messaggio come proveniente dal TNT Locator.Ti ricordiamo che il codice identificativo del delivery point e la deliveryOption devono essere inseriti nella trasmissione dei dati di spedizione vs TNT sulla base del tipo di integrazione di essere. I dettagli necessari sono disponibili sui manuali di integrazione o chiedendo direttamente al consulente CIT di TNT.
Appendice A: Note tecniche
Eventi e listener del TNT Locator
Lo script locator.js importa automaticamente jQuery qualora non fosse presente nel sito web ospitante.
Lo stesso script aggiunge due eventi window.addEventListener("message" …) e window.attachEvent("message" …). Questi eventi sono necessari per intercettare il valore di ritorno passato da TNT Locator. Se il sito dovesse già gestire un evento simile è bene modificare il codice in modo da non attivare eventi indesiderati. Il messaggio ricevuto dal TNT Locator è un JSON che contiene sempre il parametro tntMessage impostato a true. In questo modo è possibile distinguere il messaggio ricevuto dal TNT Locator da altri messaggi gestiti dalla pagina web.
Per intercettare l'evento di scelta dell'utente è possibile implementare una funzione propria che vada ad attivarsi quando viene ricevuto un messaggio.
NB: il TNT locator non ritornerà mai un messaggio di errore, è possibile che ritorni un valore nullo.
Gestione dell’eventuale indisponibilità del servizio
Per verificare che lo snippet di TNT Locator sia caricato correttamente si può procedere nel seguente modo:
Caso 1 implementazione mediante utilizzo dell’evento onClick:
<html>
<body>
…
<button onClick="if(typeof openLocator !=
“undefined”){openLocator({width:'1024',height:'768',address:'torino',point:'101'})
;} >Seleziona il punto di consegna</button>
…
</body>
</html>
…
</body>
</html>
<html>
<head>
<script>
if(window.addEventListener){
window.addEventListener(“message”, myfunction, false) }else{
window.attachEvent(“onmessage”,myfunction) }
function myfunction(event){
var dataJSONLocator = JSON.parse(event.data);
if(dataJSONLocator.tntMessage){
//fai qualcosa }
}
</script>
</head>
<body>
…
<button id=”openicon”>Seleziona il punto di consegna</button>
… </body>
</html>
Caso 2 implementazione mediante utilizzo di JQuery:
Questo controllo disabilità totalmente il TNT locator nel caso in cui il servizio non sia disponibile (al click del pulsante non sarà eseguita nessuna azione). Si consiglia di implementare questo controllo in modo da mostrare contenuti alternativi qualora il TNT Locator non fosse disponibile.
<html>
<head>
<script>
$(document).ready(function(){
$(“#openicon”).click(function()
{ if(typeof openLocator != “undefined”){
openLocator({width:'1024',height:'768',address:'torino',point:'101'});
} });
});
</script>
</head>
<body>
…
<button id=”openicon”>Seleziona il punto di consegna</button>
…
</body>
</html>
