Guida per gli sviluppatori

L'API Embedded Viewer consente di incorporare i contenuti dei libri da Google Libri direttamente nelle tue pagine web con JavaScript. L'API fornisce inoltre una serie di utilità per manipolare le anteprime dei libri e viene spesso utilizzata insieme alle altre API descritte su questo sito.

La Procedura guidata di anteprima è uno strumento basato sull'API del visualizzatore incorporato che semplifica l'aggiunta di funzionalità di anteprima al tuo sito semplicemente copiando un paio di righe di codice. Questo documento è rivolto agli sviluppatori più esperti che vogliono personalizzare l'aspetto degli utenti sui loro siti.

Pubblico

Questa documentazione è rivolta alle persone che hanno familiarità con la programmazione JavaScript e i concetti di programmazione orientata agli oggetti. Dovresti conoscere anche Google Libri dal punto di vista dell'utente. Sul Web sono disponibili numerosi tutorial JavaScript.

Questa documentazione concettuale non è completa ed esaustiva; è progettata per consentirti di iniziare rapidamente a esplorare e sviluppare applicazioni interessanti con l'API Embedded Viewer. Gli utenti avanzati possono consultare la pagina di riferimento sull'API Embedded Viewer, che fornisce dettagli completi sui metodi e sulle risposte supportati.

Come indicato sopra, i principianti possono iniziare con la Procedura guidata di anteprima, che genera automaticamente il codice necessario per incorporare le anteprime di base sul tuo sito.

Il "Hello World" dell'API Embedded Viewer

Il modo più semplice per iniziare a conoscere meglio l'API Embedded Viewer è un semplice esempio. La seguente pagina web mostra un'anteprima 600 x 500 di Mountain View, di Nicholas Perry, 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 sperimentarlo. 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 lo spettatore.
  3. Scriviamo una funzione JavaScript per creare un oggetto "viewer".
  4. Il libro viene caricato utilizzando il suo identificatore univoco (in questo caso ISBN:0738531367).
  5. Utilizziamo google.books.setOnLoadCallback per chiamare initialize quando l'API si è caricata completamente.

Questi passaggi sono spiegati di seguito.

Caricare l'API Embedded Viewer

Utilizzare il framework API Loader per caricare l'API Embedded Viewer è relativamente semplice. Sono previsti due passaggi:

  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 prende 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>

Caricare una versione localizzata dell'API Embedded Viewer

L'API Embedded Viewer utilizza l'inglese per impostazione predefinita per la visualizzazione di informazioni testuali come le descrizioni comando, i nomi dei controlli e il testo dei link. Se vuoi modificare l'API Embedded Viewer 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 di un libro con l'interfaccia in portoghese brasiliano:

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

Visualizza 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, he, hu, is, id, it, ja, ko, lv, lt, ms, no, pl-r

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

Elementi DOM del visualizzatore

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

Per poter visualizzare un libro su una pagina web, è necessario prenotare un posto. In genere, ciò viene fatto creando un elemento div denominato e ottenendo un riferimento a questo elemento nel Document Object Model (DOM) del browser.

L'esempio precedente definisce un div denominato "viewerCanvas" e imposta la dimensione tramite attributi di stile. Lo spettatore utilizza implicitamente le dimensioni del contenitore per determinarne le dimensioni.

L'oggetto DefaultViewer

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

La classe JavaScript che crea e controlla un singolo visualizzatore della pagina è la classe DefaultViewer. (Puoi creare più di un'istanza di questa classe, ogni oggetto definirà 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, specifichi un nodo DOM nella pagina (di solito un elemento div) come container per il visualizzatore. I nodi HTML sono elementi secondari dell'oggetto JavaScript document 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 Embedded Viewer) è riportata di seguito:

Costruttore Descrizione
DefaultViewer(container, opts?) Crea un nuovo visualizzatore all'interno dell'elemento HTML container specificato, che deve 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 nel costruttore è facoltativo, destinato a implementazioni avanzate che vanno oltre l'ambito di questo documento, e viene omesso dall'esempio "Hello World".

Inizializzare il visualizzatore con un libro specifico

  viewer.load('ISBN:0738531367');

Una volta creato un visualizzatore tramite il costruttore DefaultViewer, 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 di eseguire qualsiasi altra operazione sull'oggetto visualizzatore.

Se conosci più identificatori per un libro (il codice ISBN dell'edizione in brossura o numeri OCLC alternativi), puoi passare un array di stringhe di identificazione come primo parametro alla funzione load(). Lo spettatore visualizzerà il libro se è presente un'anteprima incorporabile associata a uno qualsiasi di identificatori nell'array.

Identificatori di libri supportati

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

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

Questi identificatori vengono spesso usati con altre API della famiglia di API Google Libri. Ad esempio, puoi usare Dynamic Links per visualizzare un pulsante di anteprima solo se il libro è incorporabile e poi, quando l'utente fa clic sul pulsante, creare un'istanza di un utente utilizzando l'URL di anteprima restituito dalla chiamata Dynamic Links. Allo stesso modo, puoi creare un'applicazione di navigazione e anteprima completa con l'API Books, che restituisce diversi identificatori di settore adatti nei suoi feed Volume. Visita la pagina degli esempi per dare un'occhiata ad alcune implementazioni avanzate.

Gestione delle inizializzazioni non riuscite

In alcuni casi, la chiamata load potrebbe non riuscire. In genere ciò si verifica quando l'API non riesce a trovare un libro associato all'identificatore fornito, se non è disponibile un'anteprima del libro, se non è possibile incorporare l'anteprima del libro o quando restrizioni territoriali impediscono all'utente finale di visualizzare il libro specifico. Potresti voler ricevere un avviso in caso di errore, in modo che il tuo codice possa gestire questa condizione senza problemi. Per questo motivo, la funzione load ti 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 di "avviso" JavaScript se è possibile incorporare il libro:

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 esempio (book-notfound.html)

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

Nota: poiché le anteprime potrebbero non essere disponibili per tutti i libri e per tutti gli utenti, potrebbe essere utile sapere se è disponibile un'anteprima prima di provare a caricare un visualizzatore. Ad esempio, potresti voler mostrare un pulsante, una pagina o una sezione "Anteprima Google" nell'interfaccia utente solo se l'utente ha effettivamente a disposizione un'anteprima. Puoi farlo utilizzando l'API Books o i link dinamici, che indicano se un libro è disponibile per l'incorporamento tramite il visualizzatore.

Gestione delle 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 al termine del 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 esempio (book-success.html)

Questo callback può essere utile se, ad esempio, vuoi mostrare determinati elementi nella pagina solo se lo spettatore ha completato il rendering.

Visualizzazione del visualizzatore durante il caricamento

  google.books.setOnLoadCallback(initialize);

Durante il rendering di una pagina HTML, viene generato il Document Object Model (DOM) e tutte le immagini e gli script esterni vengono ricevuti e incorporati nell'oggetto document. Per garantire che il visualizzatore venga posizionato sulla pagina solo dopo il caricamento completo della pagina, viene utilizzata la funzione google.books.setOnLoadCallback per rinviare l'esecuzione della funzione che costruisce l'oggetto DefaultViewer. Poiché setOnLoadCallback chiamerà initialize solo quando l'API Embedded Viewer è stata caricata e pronta per essere utilizzata, ciò evita comportamenti imprevedibili e garantisce il controllo su come e quando il visualizzatore viene disegnato.

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

Interazioni con gli spettatori

Ora che hai un oggetto DefaultViewer, puoi interagire. L'oggetto visualizzatore di base ha l'aspetto e il comportamento molto simile allo spettatore con cui interagisci sul sito web di Google Libri ed è dotato di molti comportamenti integrati.

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

L'esempio seguente mostra l'anteprima di un libro che "passa" automaticamente alla pagina successiva ogni 3 secondi. Se la pagina successiva si trova nella parte visibile del visualizzatore, quest'ultimo si sposta facilmente nella pagina; in caso contrario, 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 esempio (book-animate.html)

Tieni presente che le chiamate programmatiche al visualizzatore non riusciranno o non avranno effetto finché il visualizzatore non viene completamente inizializzato con un determinato libro. Per assicurarti di chiamare queste funzioni solo quando il visualizzatore è pronto, utilizza il parametro successCallback per viewer.load come descritto sopra.

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

Note di programmazione

Prima di iniziare ad analizzare l'API Embedded Viewer, prendi nota dei seguenti problemi per assicurarti che l'applicazione funzioni senza problemi sulle piattaforme previste.

Compatibilità del browser

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

A volte applicazioni diverse richiedono comportamenti diversi per gli utenti con browser incompatibili. L'API Embedded Viewer 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 né visualizza un messaggio di errore per browser meno recenti. Le applicazioni reali potrebbero eseguire operazioni più semplici con browser vecchi o incompatibili, ma questi controlli vengono omessi per rendere gli esempi più leggibili.

Per le applicazioni più banali si verificano inevitabilmente incongruenze tra browser e piattaforme. Anche siti come quirksmode.org sono ottime risorse per trovare soluzioni alternative.

XHTML e modalità non standard

Ti consigliamo di utilizzare il linguaggio HTML conforme agli standard nelle pagine che contengono il visualizzatore. Quando i browser rilevano l'XDOCTYPE nella parte superiore della pagina, eseguono il rendering della pagina in "modalità di conformità agli standard", il che rende il layout e i comportamenti molto più prevedibili nei vari browser. Le pagine senza questa definizione potrebbero essere visualizzate in "modalità non standard", il che può comportare 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">

Nota sugli esempi di API Embedded Viewer

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 nello scheletro del tuo file HTML oppure scaricare il file HTML completo per ogni esempio facendo clic sul link dopo l'esempio.

Risoluzione dei problemi

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