Guida per gli sviluppatori

L'API Embedded Viewer ti consente di incorporare i contenuti dei libri di Google Libri direttamente nelle tue pagine web con JavaScript. L'API fornisce anche 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 Embedded Viewer 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 la visualizzazione dello spettatore sui propri 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 molti tutorial su JavaScript.

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

Come indicato sopra, i principianti possono iniziare con la Procedura guidata 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 esaminare questo esempio e scaricarlo per modificarlo e provarlo. Anche in questo semplice esempio, ci sono cinque aspetti da tenere presente:

  1. Includi il caricatore di API utilizzando un tag script.
  2. Creiamo un elemento div denominato "viewerCanvas" per contenere 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 al termine del caricamento dell'API.

Questi passaggi sono spiegati di seguito.

Caricare l'API Embedded Viewer

L'utilizzo del framework API Loader per caricare l'API Embedded Viewer è relativamente semplice. che prevede i seguenti due passaggi:

  1. Includi la libreria API Loader: 
    <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 accetta un parametro di elenco facoltativo che specifica una funzione di callback o una lingua, 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 visualizzare informazioni testuali come le descrizioni comando, i nomi dei controlli e il testo dei link. Se vuoi modificare l'API Embedded Viewer in modo da visualizzare correttamente le informazioni in una determinata lingua, puoi aggiungere un parametro facultativo language alla chiamata google.books.load.

Ad esempio, per visualizzare un modulo di anteprima del 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, pt-BR, pt-PT, ro, ru, sr, sk, sl, es, sv, tl, th, tr, uk e vi.

Quando utilizzi 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 di includere un tag <meta> equivalente nella pagina. In questo modo, puoi assicurarti che i caratteri vengano visualizzati correttamente su tutti i browser. Per ulteriori informazioni, consulta la pagina di W3C sull'impostazione del parametro HTTP charset.

Elementi DOM dello spettatore

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

Affinché un libro venga visualizzato in una pagina web, è necessario prenotare un posto. Di solito, questo viene eseguito creando un elemento div denominato e ottenendo un riferimento a questo elemento nel DOM (Document Object Model) 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 regolarsi.

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ù istanze 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 contenitore per il visualizzatore. I nodi HTML sono elementi secondari dell'oggetto document di JavaScript e otteniamo un riferimento a questo elemento tramite il metodo document.getElementById().

Questo codice definisce una variabile (chiamata viewer) e la assegna a un nuovo oggettoDefaultViewer. La funzione DefaultViewer() è nota come constructor e la sua definizione (ridotta per chiarezza dal Documentazione di riferimento dell'API Embedded Viewer) è riportata di seguito:

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

Tieni presente che il secondo parametro del costruttore è facoltativo, destinato a implementazioni avanzate non coperte da questo documento, ed è 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, è necessario inizializarlo 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, ad esempio il codice ISBN per l'edizione in brossura o numeri OCLC alternativi, puoi passare un array di stringhe di identificatori 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 dei libri supportati

Come la funzionalità Link dinamici, l'API Embedded Viewer supporta una serie di valori per identificare un determinato libro. Queste 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 da OCLC quando il record del libro viene aggiunto al sistema di catalogazione WorldCat.
Esempio: OCLC:70850767
LCCN
Il Library of Congress Control Number assegnato al record dalla Biblioteca 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 la pagina di anteprima di un libro su Google Libri.
Esempio: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

Questi identificatori vengono spesso utilizzati con altre API della famiglia di API di Google Libri. Ad esempio, puoi utilizzare i link dinamici per visualizzare un pulsante di anteprima solo se il libro è incorporabile e, quando l'utente fa clic sul pulsante, puoi creare un visualizzatore utilizzando l'URL di anteprima restituito dalla chiamata di link dinamici. Analogamente, puoi creare un'applicazione completa di navigazione e anteprima con l'API Books, che restituisce diversi identificatori di settore adatti nei suoi feed di volumi. Visita la pagina degli esempi per dare un'occhiata ad alcune implementazioni avanzate.

Gestione delle inizializzazioni non riuscite

In alcuni casi, la chiamata a load potrebbe non riuscire. In genere, questo si verifica quando l'API non riesce a trovare un libro associato all'identificatore fornito, quando non è disponibile un'anteprima del libro, quando l'anteprima del libro non può essere incorporata o quando le limitazioni territoriali impediscono all'utente finale di vedere questo determinato libro. 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 finestra di "avviso" JavaScript se il libro può 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 esempio (book-notfound.html)

Utilizzando questo callback, puoi decidere di mostrare un errore simile o di nascondere completamente l'elemento viewerCanvas. Il parametro di callback in caso di 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 un'anteprima è disponibile prima di provare a caricare un visualizzatore. Ad esempio, potresti voler mostrare un pulsante, una pagina o una sezione "Anteprima Google" nella tua UI solo se un'anteprima sarà effettivamente disponibile per l'utente. Puoi farlo utilizzando l'API Books o i link dinamici, che indicano entrambi se un libro sarà disponibile per l'incorporamento utilizzando il visualizzatore.

Gestione delle inizializzazioni riuscite

Può 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 verrà eseguito se e quando il caricamento di un libro è terminato.

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 tua pagina solo se lo spettatore ha completato il rendering.

Visualizzare il visualizzatore durante il caricamento

  google.books.setOnLoadCallback(initialize);

Durante il rendering di una pagina HTML, viene creato il modello a oggetti del documento (DOM) e eventuali immagini e script esterni vengono ricevuti e incorporati nell'oggetto document. Per assicurarci che il nostro visualizzatore venga posizionato nella pagina solo dopo il caricamento completo della pagina, viene utilizzata la funzione google.books.setOnLoadCallback per posticipare l'esecuzione della funzione che crea l'oggetto DefaultViewer. Poiché setOnLoadCallback chiamerà initialize solo quando l'API Embedded Viewer è caricata e pronta per essere utilizzata, questo evita comportamenti imprevedibili e garantisce il controllo di come e quando viene visualizzato il visualizzatore.

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 degli spettatori

Ora che hai un oggetto DefaultViewer, puoi interagire con esso. L'oggetto visualizzatore di base ha un aspetto e un comportamento molto simili a quelli del visualizzatore 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 una serie di metodi che modificano 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 un'anteprima di un libro che "gira" 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 l'esempio (book-animate.html)

Tieni presente che le chiamate programmatiche allo spettatore non andranno a buon fine o non avranno alcun effetto finché lo spettatore non sarà stato completamente inizializzato con un determinato libro. Per assicurarti di chiamare queste funzioni solo quando lo spettatore è 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 a esaminare l'API Embedded Viewer, devi prendere nota dei seguenti problemi per assicurarti che la tua applicazione funzioni correttamente sulle piattaforme previste.

Compatibilità del browser

L'API Embedded Viewer supporta le versioni recenti di Internet Explorer, Firefox e Safari e, in genere, 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 i 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.

Le applicazioni non banali riscontreranno inevitabilmente incoerenze 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 XHTML conforme agli standard nelle pagine che contengono il visualizzatore. Quando i browser vedono il codice XHTMLDOCTYPE nella parte superiore della pagina, la visualizzano in "modalità di conformità agli standard", il che rende il layout e i comportamenti molto più prevedibili tra i browser. Le pagine senza questa definizione potrebbero essere visualizzate in "modalità quirks", il che può portare a 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 nel tuo file HTML di base oppure scaricare il file HTML completo per ogni esempio facendo clic sul link dopo l'esempio.

Risoluzione dei problemi

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