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:
- Incluimos el cargador de API con una etiqueta
script
. - Creamos un elemento
div
llamado "viewerCanvas" para retener al visualizador. - Escribimos una función de JavaScript para crear un objeto "viewer".
- Cargamos el libro con su identificador único (en este caso,
ISBN:0738531367
). - Usamos
google.books.setOnLoadCallback
para llamar ainitialize
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:
- Incluye la biblioteca del cargador de API:
<script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
- Invoca el método
google.books.load
. El métodogoogle.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:
- Busca errores de ortografía. Recuerda que JavaScript es un lenguaje en el que se distinguen mayúsculas y minúsculas.
- Usar un depurador de JavaScript En Firefox, puedes usar la consola de JavaScript, Venkman Debugger o el complemento de FireEye. En IE, puedes usar el Microsoft Script Debugger. El navegador Google Chrome viene con diversas herramientas de desarrollo integradas, como un inspector de DOM y un depurador de JavaScript.