Guía para programadores

La API de Embedded Viewer te permite incorporar contenido de libros de Google Libros directamente en tus páginas web con JavaScript. La API también proporciona varias utilidades para manipular las vistas previas de los libros y, a menudo, se usa junto con las otras APIs que se describen en este sitio.

El Asistente de vista previa es una herramienta creada sobre la API de Embedded Viewer que facilita la adición de funciones de vista previa a tu sitio con solo copiar algunas líneas de código. Este documento está dirigido a desarrolladores más avanzados que deseen personalizar el aspecto del visor en sus sitios.

Público

Esta documentación está diseñada para personas que estén familiarizadas con la programación en JavaScript y los conceptos de la programación orientada a objetos. También debes estar familiarizado con Google Libros desde la perspectiva del usuario. Hay muchos instructivos de JavaScript disponibles en la Web.

Esta documentación conceptual no es completa ni exhaustiva. Está diseñada para que puedas comenzar a explorar y desarrollar aplicaciones geniales con la API de Embedded Viewer rápidamente. Es posible que a los usuarios avanzados les interese la Referencia de la API de Embedded Viewer, que proporciona detalles completos sobre los métodos y las respuestas admitidos.

Como se indicó anteriormente, es posible que los principiantes deseen comenzar con el Asistente de vista previa, que genera automáticamente el código necesario para incorporar vistas previas básicas en tu sitio.

El "Hello World" de la API de Embedded Viewer

La manera más fácil de comenzar a aprender sobre la API de Embedded Viewer es con un ejemplo simple. En la siguiente página web, se muestra una vista previa de 600 x 500 de Mountain View, de Nicholas Perry, ISBN 0738531367 (parte de la serie "Images of America" de 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>

Puedes consultar este ejemplo y descargarlo para editarlo y probarlo. Incluso en este ejemplo simple, hay cinco aspectos que debes tener en cuenta:

  1. Incluimos el cargador de API con una etiqueta script.
  2. Se crea un elemento div llamado "viewerCanvas" para que contenga el visor.
  3. Escribimos una función de JavaScript para crear un objeto "viewer".
  4. Cargamos el libro con su identificador único (en este caso, ISBN:0738531367).
  5. Usamos google.books.setOnLoadCallback para llamar a initialize cuando la API se cargó por completo.

Estos pasos se explican a continuación:

Cómo cargar la API de Embedded Viewer

Usar el framework del cargador de la API para cargar la API del visualizador incorporado es relativamente simple. Implica los siguientes dos pasos:

  1. Incluye la biblioteca de API Loader: 
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
  2. Invoca el método google.books.load. El método google.books.load toma un parámetro de lista opcional que especifica una función de devolución de llamada o un idioma, como se explica a continuación. 
    <script type="text/javascript">
  google.books.load();
</script>

Cómo cargar una versión localizada de la API de Embedded Viewer

La API de Embedded Viewer usa el inglés de forma predeterminada cuando muestra información textual, como las indicaciones sobre herramientas, los nombres de los controles y el texto de los vínculos. Si quieres cambiar la API de Embedded Viewer para que muestre correctamente la información en un idioma en particular, puedes agregar un parámetro language opcional a tu llamada a google.books.load.

Por ejemplo, para mostrar un módulo de vista previa de un libro con el idioma de la interfaz en portugués de Brasil, haz lo siguiente:

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

Ver ejemplo (book-language.html)

Actualmente, los códigos de idioma RFC 3066 compatibles incluyen 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 y vi.

Cuando uses la API de Embedded Viewer en idiomas distintos del inglés, te recomendamos que publiques tu página con un encabezado content-type establecido en utf-8 o que incluyas una etiqueta <meta> equivalente en tu página. Esto ayuda a garantizar que los caracteres se rendericen correctamente en todos los navegadores. Para obtener más información, consulta la página del W3C sobre cómo configurar el parámetro de codificación de caracteres HTTP.

Elementos DOM del usuario

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

Para que un libro aparezca en una página web, se debe reservar un lugar para él. Por lo general, esto se hace creando un elemento div con nombre y obteniendo una referencia a este elemento en el modelo de objetos del documento (DOM) del navegador.

En el ejemplo anterior, se define un div llamado "viewerCanvas" y se establece su tamaño con atributos de estilo. El visor usa implícitamente el tamaño del contenedor para ajustarse.

El objeto DefaultViewer

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

La clase de JavaScript que crea y controla un solo visor en la página es la clase DefaultViewer. (Puedes crear más de una instancia de esta clase; cada objeto definirá un visor independiente en la página). Se crea una instancia nueva de esta clase con el operador new de JavaScript.

Cuando creas una instancia nueva de visualizador, especificas un nodo DOM en la página (por lo general, un elemento div) como contenedor para el visualizador. Los nodos HTML son elementos secundarios del objeto document de JavaScript. Se obtiene una referencia a este elemento a través del método document.getElementById().

Este código define una variable (llamada viewer) y la asigna a un objeto DefaultViewer nuevo. La función DefaultViewer() se conoce como constructor y su definición (condensada para mayor claridad de la Referencias de la API de Embedded Viewer) se muestra a continuación:

Constructor Descripción
DefaultViewer(container, opts?) Crea un visor nuevo dentro del container HTML determinado, que debe ser un elemento a nivel del bloque en la página (por lo general, un DIV). Las opciones avanzadas se pasan con el parámetro opcional opts.

Ten en cuenta que el segundo parámetro del constructor es opcional (está destinado a implementaciones avanzadas más allá del alcance de este documento) y se omite del ejemplo de "Hello World".

Cómo inicializar el visor con un libro específico

  viewer.load('ISBN:0738531367');

Una vez que hayamos creado un visor a través del constructor DefaultViewer, se debe inicializar con un libro en particular. Esta inicialización se logra con el uso del método load() del visor. El método load() requiere un valor identifier, que le indica a la API qué libro mostrar. Este método debe enviarse antes de que se realicen otras operaciones en el objeto de visor.

Si conoces varios identificadores de un libro (el ISBN de la edición en rústica o números alternativos de OCLC), puedes pasar un array de cadenas de identificadores como primer parámetro a la función load(). El visor renderizará el libro si hay una vista previa incorporable asociada con cualquier de los identificadores del array.

Identificadores de libros admitidos

Al igual que la función Dynamic Links, la API de Embedded Viewer admite varios valores para identificar un libro en particular. Por ejemplo:

ISBN
El código normalizado internacional para libros comercial único de 10 o 13 dígitos.
Ejemplo: ISBN:0738531367
Número de OCLC
Es el número único que el OCLC asigna a un libro cuando se agrega su registro al sistema de catalogación WorldCat.
Ejemplo: OCLC:70850767
LCCN
Es el número de control de la Biblioteca del Congreso que la Biblioteca del Congreso asignó al registro.
Ejemplo: LCCN:2006921508
ID de volumen de Google Libros
Es la cadena única que Google Libros asignó al volumen, que aparece en la URL del libro en Google Libros.
Ejemplo: Py8u3Obs4f4C
URL de vista previa de Google Libros
Una URL que abre la página de vista previa de un libro en Google Libros.
Ejemplo: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

Estos identificadores se suelen usar con otras APIs de la familia de APIs de Google Books. Por ejemplo, puedes usar Dynamic Links para renderizar un botón de vista previa solo si el libro se puede incorporar y, luego, cuando el usuario haga clic en el botón, crear una instancia de un visor con la URL de vista previa que devuelve la llamada a Dynamic Links. De manera similar, puedes compilar una aplicación enriquecida de navegación y vista previa con la API de Books, que muestra varios identificadores de la industria adecuados en sus feeds de volúmenes. Visita la página de ejemplos para ver algunas implementaciones avanzadas.

Cómo controlar las inicializaciones fallidas

En algunos casos, es posible que la llamada a load falle. Por lo general, esto ocurre cuando la API no puede encontrar un libro asociado con el identificador proporcionado, cuando no hay una vista previa del libro disponible, cuando la vista previa del libro no se puede incorporar o cuando restricciones territoriales impiden que el usuario final vea este libro en particular. Te recomendamos que recibas una alerta sobre este tipo de fallas para que tu código pueda manejar esta condición de forma fluida. Por este motivo, la función load te permite pasar un segundo parámetro opcional, notFoundCallback, que indica qué función se debe llamar si el libro no se pudo cargar. Por ejemplo, el siguiente código generará un cuadro de "alerta" de JavaScript si el libro se puede insertar:

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

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

Ver ejemplo (book-notfound.html)

Con esta devolución de llamada, puedes decidir mostrar un error similar o ocultar el elemento viewerCanvas por completo. El parámetro de devolución de llamada de error es opcional y no se incluye en el ejemplo "Hello World".

Nota: Dado que es posible que las vistas previas no estén disponibles para todos los libros y usuarios, puede ser útil saber si hay una vista previa disponible antes de intentar cargar un visor para ella. Por ejemplo, es posible que desees mostrar un botón, una página o una sección de "Vista previa de Google" en tu IU solo si la vista previa estará realmente disponible para el usuario. Puedes hacerlo con la API de Books o los Dynamic Links, que informan si un libro estará disponible para incorporarlo con el visor.

Cómo controlar las inicializaciones correctas

También puede ser útil saber si un libro se cargó correctamente y cuándo. Por este motivo, la función load admite un tercer parámetro opcional, successCallback, que se ejecutará si y cuando se termine de cargar 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);
}

Ver ejemplo (book-success.html)

Esta devolución de llamada puede ser útil si, por ejemplo, solo deseas mostrar ciertos elementos en tu página si el visor se renderizó por completo.

Cómo mostrar el visor durante la carga

  google.books.setOnLoadCallback(initialize);

Mientras se renderiza una página HTML, se compila el modelo de objetos del documento (DOM) y se reciben y se incorporan las imágenes y secuencias de comandos externas en el objeto document. Para asegurarnos de que nuestro visor solo se coloque en la página después de que esta se cargue por completo, la función google.books.setOnLoadCallback se usa para aplazar la ejecución de la función que construye el objeto DefaultViewer. Dado que setOnLoadCallback solo llamará a initialize cuando la API de Embedded Viewer esté cargada y lista para usarse, esto evita un comportamiento impredecible y garantiza el control de cómo y cuándo se dibuja el visor.

Nota: Para maximizar la compatibilidad entre navegadores, te recomendamos que programes la carga del visor con la función google.books.setOnLoadCallback, en lugar de usar un evento onLoad en tu etiqueta <body>.

Interacciones de los usuarios

Ahora que tienes un objeto DefaultViewer, puedes interactuar con él. El objeto de visualizador básico tiene un aspecto y un comportamiento muy similares al usuario con el que interactúas en el sitio web de Google Libros, y tiene un comportamiento integrado.

Sin embargo, también puedes interactuar con el usuario de forma programática. El objeto DefaultViewer admite varios métodos que alteran el estado de vista previa directamente. Por ejemplo, los métodos zoomIn(), nextPage() y highlight() operan en el visor de forma programática, en lugar de hacerlo a través de la interacción del usuario.

En el siguiente ejemplo, se muestra una vista previa de un libro que pasa automáticamente a la página siguiente cada 3 segundos. Si la siguiente página está en la parte visible del visor, este se desplaza suavemente hasta la página. De lo contrario, el visor salta directamente a la parte superior de la siguiente página.

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);

Ver ejemplo (book-animate.html)

Ten en cuenta que las llamadas programáticas al visor fallarán o no tendrán efecto hasta que el visor se inicialice por completo con un libro en particular. Para asegurarte de llamar a esas funciones solo cuando el usuario esté listo, usa el parámetro successCallback para viewer.load como se describió anteriormente.

Para obtener información sobre todas las funciones compatibles con el objeto DefaultViewer, consulta la Guía de referencia.

Notas de programación

Antes de comenzar a analizar la API de Embedded Viewer, debes tener en cuenta las siguientes inquietudes para asegurarte de que tu aplicación funcione sin problemas en las plataformas previstas.

Compatibilidad del navegador

La API de Embedded Viewer también es compatible con versiones recientes de Internet Explorer, Firefox y Safari, y, por lo general, otros navegadores basados en Gecko y WebKit, como Camino y Google Chrome.

A veces, las diferentes aplicaciones requieren comportamientos diferentes para los usuarios con navegadores incompatibles. La API de Embedded Viewer no tiene ningún comportamiento automático cuando detecta un navegador incompatible. La mayoría de los ejemplos de este documento no verifican la compatibilidad del navegador ni muestran un mensaje de error para navegadores más antiguos. Las aplicaciones reales pueden hacer algo más amigable con navegadores incompatibles o antiguos, pero se omiten esas verificaciones para que los ejemplos sean más legibles.

Las aplicaciones no triviales encontrarán incoherencias inevitables entre los navegadores y las plataformas. Sitios como quirksmode.org también son buen recurso para encontrar soluciones alternativas.

XHTML y modo no estándar

Te recomendamos que utilices XHTML que cumpla con los estándares en las páginas que contengan al usuario. Cuando los navegadores ven el DOCTYPE de XHTML en la parte superior de la página, la renderizan en el "modo de cumplimiento de estándares", lo que hace que el diseño y los comportamientos sean mucho más predecibles en todos los navegadores. Las páginas sin esa definición pueden renderizarse en el "modo de peculiaridades", lo que puede generar un diseño incoherente.

<!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 sobre los ejemplos de la API de Embedded Viewer

Ten en cuenta que la mayoría de los ejemplos de esta documentación solo muestran el código JavaScript relevante, no el archivo HTML completo. Puedes conectar el código JavaScript a tu propio archivo HTML de esqueleto o hacer clic en el vínculo que aparece después de cada ejemplo para descargar el archivo HTML completo de cada ejemplo.

Solución de problemas

Si tu código no parece funcionar, estos son algunos enfoques que podrían ayudarte a resolver tus problemas: