Guida per gli sviluppatori

L'API Embedded Viewers ti consente di incorporare contenuti di libri da Google Libri direttamente nelle tue pagine web con JavaScript. L'API fornisce inoltre una serie di utilità per la gestione delle anteprime dei libri e spesso viene utilizzata insieme alle altre API descritte in questo sito.

La Procedura guidata di anteprima è uno strumento basato sull'API EmbeddedViewer che semplifica l'aggiunta di funzionalità di anteprima al sito semplicemente copiando un paio di righe di codice. Questo documento è destinato a sviluppatori più esperti che vogliono personalizzare l'aspetto dello spettatore sui propri siti.

Pubblico

Questa documentazione è progettata per coloro che hanno familiarità con la programmazione di JavaScript e i concetti di programmazione con oggetti. Dovresti anche conoscere Google Libri dal punto di vista dell'utente. Sono disponibili molti tutorial su JavaScript sul Web.

Questa documentazione concettuale non è completa ed esauriente ed è progettata per consentirti di iniziare rapidamente a esplorare e sviluppare applicazioni interessanti con l'API Embedded Viewers. Gli utenti avanzati dovrebbero considerare l'articolo sull'API del visualizzatore incorporato, che fornisce informazioni complete sui metodi e le risposte supportati.

Come indicato sopra, è consigliabile che i principianti inizino con la Procedura guidata di anteprima, che genera automaticamente il codice necessario per incorporare anteprime di base sul vostro sito.

"Hello World" dell'API Embedded Viewers

Il modo più semplice per iniziare a conoscere l'API Embedded Viewers è vedere un esempio semplice. La seguente pagina web mostra un'anteprima 600x500 di Mountain View, di Nicholas Perry, codice ISBN 0738531367 (parte della serie "Images of America" di Arcadia Publishing):

<!DOCTYPE html "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
    <title>Google Books Embedded Viewer API Example</title>
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
    <script type="text/javascript">
      google.books.load();

      function initialize() {
        var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));
        viewer.load('ISBN:0738531367');
      }

      google.books.setOnLoadCallback(initialize);
    </script>
  </head>
  <body>
    <div id="viewerCanvas" style="width: 600px; height: 500px"></div>
  </body>
</html>

Puoi guardare questo esempio e scaricarlo per modificarlo e giocarci. Anche in questo semplice esempio, ci sono cinque aspetti da considerare:

  1. Includiamo il caricatore API utilizzando un tag script.
  2. Creiamo un elemento div denominato "viewerCanvas" per trattenere il visualizzatore.
  3. Scriviamo una funzione JavaScript per creare un oggetto "viewer".
  4. Carichiamo il libro utilizzando il suo identificatore univoco (in questo caso ISBN:0738531367).
  5. Utilizziamo google.books.setOnLoadCallback per chiamare initialize quando l'API è stata completamente caricata.

Questi passaggi sono spiegati di seguito.

Caricare l'API Embedded Viewers

Usare il framework di caricatore API per caricare l'API EmbeddedViewer è relativamente semplice. Sono previsti i due passaggi seguenti:

  1. Includi la libreria del caricatore API: 
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
  2. Richiama il metodo google.books.load. Il metodo google.books.load utilizza un parametro facoltativo dell'elenco che specifica una funzione o una lingua di callback, come spiegato di seguito. 
    <script type="text/javascript">
  google.books.load();
</script>

Caricamento di una versione localizzata dell'API Embedded Viewers

Quando vedi informazioni testuali, come descrizioni comando, nomi per i controlli e testo dei link, l'API Embedded Viewers utilizza l'inglese per impostazione predefinita. Se vuoi modificare l'API Embedded Viewers per visualizzare correttamente le informazioni in una determinata lingua, puoi aggiungere un parametro language facoltativo alla chiamata google.books.load.

Ad esempio, per visualizzare un modulo di anteprima del libro con la lingua dell'interfaccia del portoghese brasiliano:

<script type="text/javascript">
  google.books.load({"language": "pt-BR"});
</script>

Visualizza un esempio (book-language.html)

I codici lingua RFC 3066 attualmente supportati includono af, ar, hy, bg, ca, zh-CN, zh-TW, hr, cs, da, nl, en, fil, fi, fr, de, el, hu, pl, is, id, ja, ko, lv, lt, ms, , pl, pl, pl, pl, pl, pl, pl.

Se utilizzi l'API Embedded Viewers in lingue diverse dall'inglese, ti consigliamo vivamente di pubblicare la pagina con un'intestazione content-type impostata su utf-8 o di includere un tag <meta> equivalente nella pagina. In questo modo ti assicuri che i caratteri vengano visualizzati correttamente in tutti i browser. Per ulteriori informazioni, consulta la pagina del W3C sull'impostazione del parametro charset HTTP.

Elementi del DOM del visualizzatore

<div id="viewerCanvas" style="width: 600px; height: 500px"></div>

Per visualizzare un libro in una pagina web, è necessario prenotare un posto. In genere, questo viene eseguito creando un elemento div denominato e ottenendo un riferimento a questo elemento nel DOM del browser.

L'esempio precedente definisce un div denominato "viewerCanvas" e imposta le dimensioni utilizzando gli attributi di stile. Il visualizzatore utilizza implicitamente le dimensioni del contenitore per le dimensioni stesse.

L'oggetto DefaultViewer

var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));

La classe JavaScript che crea e controlla un singolo visualizzatore nella pagina è la classe DefaultViewer. (puoi creare più di un'istanza di questa classe; ogni oggetto definisce un visualizzatore separato nella pagina). Viene creata una nuova istanza di questa classe utilizzando l'operatore JavaScript new.

Quando crei una nuova istanza del visualizzatore, devi specificare un nodo DOM nella pagina (di solito un elemento div) come container per il visualizzatore. I nodi HTML sono figli dell'oggetto document JavaScript e otteniamo un riferimento a questo elemento tramite il metodo document.getElementById().

Questo codice definisce una variabile (denominata viewer) e la assegna a un nuovo oggetto DefaultViewer. La funzione DefaultViewer() è nota come costruttore e la sua definizione (condensata per chiarezza dal Riferimento API visualizzatore incorporato) è riportata di seguito:

Costruttore Descrizione
DefaultViewer(contenitore, opts?) Crea un nuovo visualizzatore all'interno del codice HTML fornito container, che dovrebbe essere un elemento a livello di blocco nella pagina (in genere un DIV). Le opzioni avanzate vengono trasmesse utilizzando il parametro facoltativo opts.

Tieni presente che il secondo parametro del costruttore è facoltativo, previsto per le implementazioni avanzate che non rientrano nell'ambito di questo documento, e viene omesso dall'esempio "Hello, World".

Inizializzare lo spettatore con un libro specifico

  viewer.load('ISBN:0738531367');

Una volta creato un visualizzatore tramite il costruttore DefaultViewer, questo deve essere inizializzato con un determinato libro. Questa inizializzazione viene eseguita utilizzando il metodo load() del visualizzatore. Il metodo load() richiede un valore identifier, che indica all'API quale libro mostrare. Questo metodo deve essere inviato prima che vengano eseguite altre operazioni nell'oggetto visualizzatore.

Se conosci diversi identificatori per un libro (il codice ISBN per l'edizione in brossura o i numeri OCLC alternativi), puoi passare una matrice di stringhe di identificatori come primo parametro alla funzione load(). Il visualizzatore visualizzerà il libro se è presente un'anteprima incorporabile associata a qualsiasi identificatore nella matrice.

Identificatori di libri supportati

Come la funzionalità Link dinamici, l'API Viewer visualizzatore supporta una serie di valori per identificare un libro specifico. Questi metodi includono:

ISBN
L'unico numero commerciale di 10 o 13 cifre International Standard Book Number.
Esempio: ISBN:0738531367
Numero OCLC
Il numero univoco assegnato a un libro dalla OCLC quando il record del libro viene aggiunto al sistema di catalogazione WorldCat.
Esempio: OCLC:70850767
LCCN
Il numero di controllo della Biblioteca del Congresso assegnato al Registro dalla Raccolta del Congresso.
Esempio: LCCN:2006921508
ID volume di Google Libri
La stringa univoca assegnata da Google Libri al volume, che viene visualizzata nell'URL del libro su Google Libri.
Esempio: Py8u3Obs4f4C
URL di anteprima di Google Libri
Un URL che apre una pagina di anteprima del libro su Google Libri.
Esempio: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

Questi identificatori sono spesso utilizzati con altre API nella famiglia delle API di Google Libri. Ad esempio, puoi utilizzare Link dinamici per visualizzare un pulsante di anteprima soltanto se il libro è incorporabile, quindi, quando l'utente fa clic sul pulsante, crea un'istanza del visualizzatore utilizzando l'URL di anteprima restituito dalla chiamata ai link dinamici. Analogamente, puoi creare una ricca applicazione di navigazione e anteprima con l'API Libri, che restituisce diversi identificatori di settore adatti nei relativi feed Volume. Visita la pagina degli esempi per dare un'occhiata ad alcune implementazioni avanzate.

Gestire le inizializzazioni non riuscite

In alcuni casi, la chiamata al numero load potrebbe non riuscire. In genere ciò accade quando l'API non riesce a trovare un libro associato all'identificatore fornito, quando non è disponibile l'anteprima del libro, quando l'anteprima del libro non può essere incorporata o quando le limitazioni territoriali impediscono all'utente finale di visualizzare il libro specifico. Se vuoi ricevere un avviso di questo errore, il tuo codice può gestire correttamente questa condizione. Per questo motivo, la funzione load consente di passare un secondo parametro facoltativo, notFoundCallback, che indica la funzione da chiamare se non è stato possibile caricare il libro. Ad esempio, il seguente codice genererà una casella "avviso" JavaScript se il libro potrebbe essere incorporato:

function alertNotFound() {
  alert("could not embed the book!");
}

function initialize() {
  var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));
  viewer.load('ISBN:1234', alertNotFound);
}

Visualizza un esempio (book-notfound.html)

Con questo callback puoi decidere di mostrare un errore simile oppure nascondere completamente l'elemento viewerCanvas. Il parametro di callback di errore è facoltativo e non è incluso nell'esempio di "Hello World".

Nota: poiché le anteprime potrebbero non essere disponibili per tutti i libri e per tutti gli utenti, potrebbe essere utile sapere se un'anteprima è disponibile prima che provi anche a caricare uno spettatore. Ad esempio, potresti voler mostrare un pulsante, una pagina o una sezione "Anteprima Google" nella tua UI solo se l'anteprima è effettivamente disponibile per l'utente. Puoi farlo utilizzando l'API Libri o i Link dinamici, entrambi per segnalare se un libro sarà disponibile per l'incorporamento con il visualizzatore.

Gestire le inizializzazioni riuscite

Potrebbe essere utile anche sapere se e quando un libro è stato caricato correttamente. Per questo motivo, la funzione load supporta un terzo parametro facoltativo, successCallback, che viene eseguito se e quando viene completato il caricamento di un libro.

function alertInitialized() {
  alert("book successfully loaded and initialized!");
}

function initialize() {
  var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));
  viewer.load('ISBN:0738531367', null, alertInitialized);
}

Visualizza un esempio (book-success.html)

Questo callback può essere utile, ad esempio, se vuoi mostrare determinati elementi sulla tua pagina solo se lo spettatore ha eseguito il rendering completo.

Visualizzare lo spettatore al caricamento

  google.books.setOnLoadCallback(initialize);

Durante il rendering di una pagina HTML, viene creato il modello a oggetti documento (DOM), mentre eventuali immagini e script esterni vengono ricevuti e incorporati nell'oggetto document. Per garantire che il nostro visualizzatore venga posizionato sulla pagina solo dopo che questa è stata completamente caricata, la funzione google.books.setOnLoadCallback viene utilizzata per rimandare l'esecuzione della funzione che crea l'oggetto DefaultViewer. Dal momento che setOnLoadCallback chiamerà initialize soltanto quando l'API EmbeddedViewer è caricata e pronta per essere utilizzata, questo evita comportamenti imprevisti e garantisce il controllo di come e quando viene tracciato lo spettatore.

Nota: per massimizzare la compatibilità tra browser, ti consigliamo vivamente di pianificare il caricamento degli utenti con la funzione google.books.setOnLoadCallback, anziché utilizzare un evento onLoad nel tag <body>.

Interazioni degli spettatori

Ora che hai un oggetto DefaultViewer, puoi interagire con esso. L'oggetto visualizzatore di base si comporta e si comporta in modo molto simile allo spettatore con cui interagisci sul sito web di Google Libri e include molti comportamenti integrati.

Tuttavia, puoi anche interagire con lo spettatore in modo programmatico. L'oggetto DefaultViewer supporta vari metodi che alterano direttamente lo stato dell'anteprima. Ad esempio, i metodi zoomIn(), nextPage() e highlight() operano sul visualizzatore in modo programmatico, anziché tramite l'interazione di un utente.

L'esempio riportato di seguito mostra un'anteprima del libro che "passa" automaticamente alla pagina successiva ogni tre secondi. Se la pagina successiva si trova nella parte visibile del visualizzatore, la persona esegue una panoramica fluida sulla pagina; in caso contrario, il visualizzatore passa direttamente alla parte superiore della pagina successiva.

function nextStep(viewer) {
  window.setTimeout(function() {
    viewer.nextPage();
    nextStep(viewer);
  }, 3000);
}

function initialize() {
  var viewer = new google.books.DefaultViewer(document.getElementById('viewerCanvas'));
  viewer.load('ISBN:0738531367');
  nextStep(viewer);
}

google.books.setOnLoadCallback(initialize);

Visualizza un esempio (book-animate.html)

Tieni presente che le chiamate programmatiche al visualizzatore non riusciranno o non avranno alcun effetto finché l'utente non inizia l'inizializzazione con un determinato libro. Per assicurarti di chiamare tali funzioni solo quando lo spettatore è pronto, utilizza il parametro successCallback per viewer.load, come descritto in precedenza.

Per informazioni su tutte le funzioni supportate dall'oggetto DefaultViewer, consulta la Guida di riferimento.

Note sulla programmazione

Prima di iniziare ad approfondire l'API EmbeddedViewer, tieni presente i seguenti aspetti per assicurarti che l'applicazione funzioni senza problemi nelle piattaforme previste.

Compatibilità del browser

L'API EmbeddedViewer supporta le versioni recenti di Internet Explorer, Firefox e Safari, e solitamente anche altri browser basati su Gecko e WebKit, come Camino e Google Chrome.

Applicazioni diverse a volte richiedono comportamenti diversi per gli utenti con browser incompatibili. L'API Embedded Visualizzatore non ha alcun comportamento automatico quando rileva un browser non compatibile. La maggior parte degli esempi in questo documento non verifica la compatibilità del browser e non mostra un messaggio di errore per i browser meno recenti. Le applicazioni reali possono fare qualcosa di più intuitivo con i browser vecchi o incompatibili, ma tali controlli vengono omessi per rendere più leggibili gli esempi.

Le applicazioni non banali troveranno inevitabilmente incongruenze tra i browser e le piattaforme. Anche siti come quirksmode.org sono ottime risorse per trovare soluzioni alternative.

Modalità HTML e non standard

Ti consigliamo di utilizzare XHTML conforme alle norme sulle pagine che contengono il visualizzatore. Quando i browser vedono il codice XHTML DOCTYPE nella parte superiore della pagina, la visualizzano in "modalità di conformità agli standard", il che rende layout e comportamenti molto più prevedibili nei vari browser. Le pagine senza questa definizione potrebbero essere visualizzate in "modalità non standard", che può causare un layout incoerente.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

Una nota sugli esempi di API Embedded Viewers

Tieni presente che la maggior parte degli esempi in questa documentazione mostra solo il codice JavaScript pertinente, non il file HTML completo. Puoi inserire il codice JavaScript nel tuo file HTML scheletro oppure scaricare il file HTML completo di ciascun esempio facendo clic sul link dopo l'esempio.

Risolvere i problemi

Se il tuo codice non sembra funzionare, ecco alcuni approcci che potrebbero aiutarti a risolvere i tuoi problemi: