Guía para programadores

La API de Embed 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 libros y se suele usar junto con las otras API que se describen en este sitio.

El Asistente de vista previa es una herramienta diseñada sobre la API de Embed Viewer que te permite agregar funciones de vista previa a tu sitio más fácilmente con solo copiar un par de líneas de código. Este documento está dirigido a programadores más avanzados que deseen personalizar la forma en que aparece el visor en sus sitios.

Público

Esta documentación está diseñada para personas familiarizadas con la programación en JavaScript y conceptos de programación orientados al objeto. También debes estar familiarizado con Google Libros desde el punto de vista del usuario. Hay muchos instructivos de JavaScript disponibles en la Web.

Esta documentación conceptual no es exhaustiva ni está exhaustiva; está diseñada para que puedas comenzar rápidamente a explorar y desarrollar aplicaciones interesantes con la API incorporada. Los usuarios avanzados pueden estar interesados en la Referencia de la API del visor incorporado, que proporciona detalles completos sobre los métodos y las respuestas admitidos.

Tal 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 a su sitio.

“Hola, mundo” de la API de Embed Viewer

La forma más sencilla de comenzar a conocer la API de Embedded Viewer es ver 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 mirar este ejemplo y descargarlo para editarlo y jugar con él. Incluso en este ejemplo simple, hay cinco aspectos que debes tener en cuenta:

  1. Se incluye el cargador de la API mediante una etiqueta script.
  2. Creamos un elemento div llamado "viewerCanvas" para conservar el visor.
  3. Se escribe una función de JavaScript para crear un objeto “viewer”.
  4. El libro se carga 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 del visor incorporado

Usar el marco de trabajo del cargador de la API para cargar la API del visor incorporado es relativamente simple. Esto implica los dos pasos siguientes:

  1. Incluye la biblioteca del cargador de la 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 Embed Viewer usa inglés de forma predeterminada cuando muestra información textual, como información sobre herramientas, nombres de controles y texto de vínculos. Si deseas cambiar la API de Embedded Viewer para mostrar información en un idioma específico, puedes agregar un parámetro language opcional a tu llamada a google.books.load.

Por ejemplo, para mostrar un módulo de vista previa del libro en el idioma 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, f, f, f, f, f, f, f permiso

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

Elementos DOM del visor

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

Para que un libro se muestre en una página web, se debe reservar un lugar para este. Por lo general, esto se hace mediante la creación de un elemento div con nombre y la obtención de 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 establece su tamaño con atributos de estilo. El visor usa de forma implícita el tamaño del contenedor para modificar 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 independiente en la página). Se crea una instancia nueva de esta clase con el operador new de JavaScript.

Cuando creas una instancia de visualizador nueva, 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, y 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. A la función DefaultViewer() se la conoce como constructor, y su definición (que se resume en función de la Referencia de la API de Visualizadores incorporados) se muestra a continuación:

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

Cómo inicializar el lector 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 logra mediante el uso del método load() del usuario. El método load() requiere un valor identifier, que le indica a la API qué libro debe mostrar. Este método debe enviarse antes de que se realicen otras operaciones en el objeto de visualización.

Si conoces varios identificadores para un libro (el ISBN de la edición de bolsillo o los números de OCLC alternativos), puedes pasar un array de strings de identificador como el primer parámetro a la función load(). El visor procesará el libro si hay una vista previa integrable asociada con cualquiera de los identificadores en el arreglo.

Identificadores de libros compatibles

Al igual que la función Dynamic Links, la API de Embed Viewer admite una serie de valores para identificar un libro en particular. Incluye las siguientes herramientas:

ISBN
El número internacional estándar de libro de 10 o 13 dígitos comercial.
Ejemplo: ISBN:0738531367
Número de OCLC
Es el número único que OCLC le asigna a un libro cuando se agrega el registro al sistema de catálogo WorldCat.
Ejemplo: OCLC:70850767
LCCN
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 string única que Google Libros asignó al volumen, que aparece en la URL de ese 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 API en la familia de API de Google Libros. Por ejemplo, puedes usar Dynamic Links para procesar un botón de vista previa solo si el libro se puede incorporar. Luego, cuando el usuario haga clic en el botón, crea una instancia de visor con la URL de vista previa que muestra la llamada de Dynamic Links. Del mismo modo, puedes compilar una aplicación enriquecida de exploración y vista previa con la API de Libros, que muestra varios identificadores adecuados de la industria en sus feeds de volúmenes. Visita la página de ejemplos para echar un vistazo a algunas implementaciones avanzadas.

Cómo administrar inicializaciones con errores

En algunos casos, la llamada a load puede fallar. Esto generalmente ocurre cuando la API no pudo 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 insertar o cuando las restricciones territoriales impiden que el usuario final vea este libro en particular. Es posible que desees recibir una alerta de dicho error, para que tu código pueda controlar esta condición correctamente. Por este motivo, la función load te permite pasar un segundo parámetro opcional, notFoundCallback, que indica a qué función se debe llamar en caso de que no se pueda cargar el libro. Por ejemplo, el siguiente código generará un cuadro de "alerta" de JavaScript en caso de que el libro pueda insertarse:

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 con errores es opcional y no se incluye en el ejemplo "Hello World".

Nota: Como es posible que las vistas previas no estén disponibles para todos los libros y para todos los usuarios, te puede resultar útil saber si una vista previa está disponible antes de intentar cargar un visor. Por ejemplo, puedes mostrar un botón, una página o una sección de "Vista previa de Google" en tu IU solo si el usuario tendrá una vista previa disponible. Puedes hacerlo con la API de Libros o los Dynamic Links, que informan si un libro está disponible para insertar en él.

Administra inicializaciones exitosas

También puede ser útil saber si un libro se cargó correctamente y en qué momento. Por esta razón, la función load admite un tercer parámetro opcional, successCallback, que se ejecutará cuando un libro termine 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, por ejemplo, si solo quieres mostrar ciertos elementos en tu página si el visor se procesó completamente.

Cómo mostrar el visualizador al cargar

  google.books.setOnLoadCallback(initialize);

Mientras se procesa una página HTML, se compila el modelo de objetos de documento (DOM), y las imágenes y secuencias de comandos externas se reciben y se incorporan en el objeto document. A fin de garantizar que nuestro visor solo se coloque en la página una vez que 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. Como setOnLoadCallback solo llamará a initialize cuando la API de Embed 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 en varios navegadores, se recomienda que programes la carga de usuarios con 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 visor básico tiene un aspecto y un comportamiento muy similares al del usuario con el que interactúas en el sitio web de Google Libros y viene con mucho comportamiento integrado.

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

En el siguiente ejemplo, se muestra una vista previa del libro que "pasa automáticamente" a la página siguiente cada 3 segundos. Si la página siguiente está en la parte visible del visor, el usuario se desplazará lateralmente hasta la página; de lo contrario, el usuario 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 espectador fallarán o no tendrán efecto hasta que el espectador se inicialice por completo con un libro en particular. Para asegurarte de que solo llames a esas funciones cuando el visor esté listo, usa el parámetro successCallback en 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 profundizar en la API de Embed Viewer, ten en cuenta las siguientes inquietudes para asegurarte de que tu aplicación funcione sin problemas en las plataformas previstas.

Compatibilidad con navegadores

La API del visor incorporado admite 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 aplicaciones requieren distintos comportamientos para los usuarios con navegadores incompatibles. La API de Embed Viewer no tiene ningún comportamiento automático cuando detecta un navegador incompatible. En la mayoría de los ejemplos de este documento, no se verifica la compatibilidad del navegador ni se muestra un mensaje de error en navegadores anteriores. Las aplicaciones reales pueden hacer algo más amigable con los navegadores anteriores o incompatibles, pero esas comprobaciones se omiten para que los ejemplos sean más legibles.

Las aplicaciones no triviales encontrarán inevitablemente inconsistencias entre los navegadores y las plataformas. Los sitios como quirksmode.org también son buenos recursos para encontrar soluciones alternativas.

Modo X no estándar y peculiar

Le recomendamos que utilice XHTML que cumpla con los estándares en las páginas que contienen el visor. Cuando los navegadores ven el código DOCTYPE XHTML en la parte superior de la página, la página se procesa en "modo de cumplimiento de los estándares", lo que hace que el diseño y los comportamientos sean mucho más predecibles en los navegadores. Es posible que las páginas sin esa definición se procesen en "modo de interpretación", 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 muestran solo código JavaScript relevante, no el archivo HTML completo. Puedes conectar el código JavaScript a tu propio esqueleto HTML o puedes descargar el archivo HTML completo para cada ejemplo haciendo clic en el vínculo después del ejemplo.

Solución de problemas

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