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 capacidades 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 la forma en que el usuario aparece en sus sitios.

Público

Esta documentación está diseñada para las personas 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 como usuario. Hay muchos instructivos de JavaScript disponibles en la Web.

Esta documentación conceptual no es exhaustiva y está diseñada para que puedas comenzar rápidamente a explorar y desarrollar aplicaciones interesantes con la API de visualizador incorporado. Es posible que a los usuarios avanzados les interese la Referencia de la API de visualizador incorporada, que proporciona detalles completos sobre los métodos y las respuestas compatibles.

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

“Hello, World” de la API de visualizador incorporada

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 ver este ejemplo y descargarlo para editarlo y probarlo. Incluso en este ejemplo simple, debes tener en cuenta cinco puntos:

  1. Incluimos el cargador de API con una etiqueta script.
  2. Creamos un elemento div llamado "viewerCanvas" para retener al visualizador.
  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 carga 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. Este proceso consta de dos pasos:

  1. Incluye la biblioteca del cargador de API: 
    <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 o un idioma de devolución de llamada, 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 la información sobre herramientas, los nombres de los controles y el texto del vínculo. 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 en el idioma de la interfaz del portugués de Brasil:

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

Ver ejemplo (book-language.html)

Entre los códigos de idioma RFC 3066 que se admiten actualmente, se 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, 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-pt, s-BR, k-BR, lts y ptr.

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. De esta manera, te aseguras de que los caracteres se rendericen correctamente en todos los navegadores. Para obtener más información, consulta la página de W3C sobre cómo configurar el parámetro HTTP charset.

Elementos del DOM de visualización

<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, para ello se crea un elemento div con nombre y se obtiene una referencia a este elemento en el modelo de objetos del documento (DOM) del navegador.

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

El objeto DefaultViewer

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

La clase de JavaScript que crea y controla un solo lector en la página es la clase DefaultViewer. (Puedes crear más de una instancia de esta clase; cada objeto definirá un visualizador separado 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 en la Referencia de la API de visualizador incorporada) se muestra a continuación:

Constructor Descripción
DefaultViewer(container, opts?) Crea un visor nuevo dentro del container de HTML especificado, que debe ser un elemento de nivel de 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 en el constructor es opcional, destinado a implementaciones avanzadas más allá del alcance de este documento, y se omite del ejemplo “Hello, World”.

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

  viewer.load('ISBN:0738531367');

Una vez que creamos un visualizador a través del constructor DefaultViewer, se debe inicializar con un libro en particular. Esta inicialización se lleva a cabo mediante el uso del método load() del visualizador. 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 visualizador.

Si conoces varios identificadores para un libro (el ISBN de la edición de bolsillo o los números OCLC alternativos), puedes pasar un array de cadenas de identificadores como primer parámetro a la función load(). El lector renderizará el libro si hay una vista previa incorporable asociada con cualquiera 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. Examinémoslos.

ISBN
El número internacional normal de libro comercial único de 10 o 13 dígitos.
Ejemplo: ISBN:0738531367
Número de OCLC
Es el número único que asigna el OCLC a un libro cuando este se agrega al sistema de catalogación de WorldCat.
Ejemplo: OCLC:70850767
LCCN
El número de control de la Biblioteca del Congreso asignado al registro por la Biblioteca del Congreso.
Ejemplo: LCCN:2006921508
ID de volumen de Google Libros
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 procesar un botón de vista previa solo si el libro es incorporable y, luego, cuando el usuario haga clic en el botón, crear una instancia de un usuario con la URL de vista previa que muestra la llamada de Dynamic Links. De manera similar, puedes compilar una aplicación enriquecida de exploración y vista previa con la API de Libros, que muestra varios identificadores de industria adecuados en sus feeds de Volumes. Visita la página de ejemplos para ver algunas implementaciones avanzadas.

Cómo controlar las inicializaciones con errores

En algunos casos, la llamada a load puede fallar. 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. Es posible que desees recibir una alerta de este tipo de falla, de modo que tu código pueda manejar esta condición correctamente. 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)

Al usar esta devolución de llamada, puedes optar por mostrar un error similar o puedes optar por 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 de "Hello World".

Nota: Dado que es posible que las vistas previas no estén disponibles para todos los libros y para todos los usuarios, puede ser útil saber si están disponibles antes de intentar cargar un lector para ellas. 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 Dynamic Links, que informan si un libro estará disponible para incorporarlo mediante el lector.

Cómo administrar inicializaciones exitosas

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á cuando un libro haya terminado de cargarse.

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 quieres mostrar ciertos elementos en tu página si el usuario se renderizó por completo.

Cómo mostrar el visualizador en 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 al objeto document las imágenes y secuencias de comandos externas. Para garantizar que el visualizador solo se coloque en la página después de que esta se haya cargado por completo, se usa la función google.books.setOnLoadCallback para diferir 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, se evita un comportamiento impredecible y se garantiza el control de cómo y cuándo se dibuja el visualizador.

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

Interacciones con 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 modifican el estado de la vista previa de forma directa. Por ejemplo, los métodos zoomIn(), nextPage() y highlight() operan en el visualizador de manera programática, en lugar de hacerlo a través de la interacción del usuario.

En el siguiente ejemplo, se muestra la vista previa de un libro que "pasa" a la página siguiente automáticamente cada 3 segundos. Si la página siguiente está en la parte visible del visualizador, este se desplaza lateralmente por la página de manera fluida; de lo contrario, salta directamente a la parte superior de la página siguiente.

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 usuario fallarán o no tendrán efecto hasta que el lector se inicialice por completo con un libro en particular. Para asegurarte de que solo llames a esas funciones cuando el visualizador esté listo, usa el parámetro successCallback para viewer.load, como se describió más arriba.

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 profundizar en 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 con navegadores

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.

Las distintas aplicaciones a veces requieren distintos comportamientos para los usuarios que tienen navegadores incompatibles. La API de Embed Viewer no se comporta automáticamente 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 fácil con navegadores antiguos o incompatibles, pero esas comprobaciones se omiten para que los ejemplos sean más legibles.

Inevitablemente, las aplicaciones más importantes encontrarán inconsistencias entre los navegadores y las plataformas. Sitios como quirksmode.org también son recursos útiles 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 procesan en el "modo de cumplimiento estándar", 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 un "modo no estándar", 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 base o puedes descargar el archivo HTML completo de cada ejemplo si haces clic en el vínculo que aparece después del ejemplo.

Solución de problemas

Si parece que tu código no funciona, a continuación, se incluyen algunos enfoques que pueden ayudarte a resolver los problemas: