Guia do desenvolvedor

A API Embedded Viewer permite incorporar conteúdo de livros do Google Livros diretamente nas suas páginas da Web com JavaScript. A API também oferece vários utilitários para manipular as visualizações de livros e é frequentemente usada com as outras APIs descritas neste site.

O assistente de visualização é uma ferramenta criada com base na API Embedded Viewer que facilita a adição de recursos de visualização ao seu site apenas copiando algumas linhas de código. Este documento é destinado a desenvolvedores mais avançados que querem personalizar a aparência do leitor nos sites.

Público

Esta documentação foi projetada para pessoas familiarizadas com a programação JavaScript e com conceitos de programação orientada a objetos. Também é preciso saber utilizar o Google Livros como usuário. Há muitos tutoriais de JavaScript disponíveis na Web.

Esta documentação conceitual não está completa e não é completa. Ela foi projetada para permitir que você comece rapidamente a explorar e desenvolver aplicativos interessantes com a API Embedded Viewer. Os usuários avançados podem se interessar pela referência da API Embedded Viewer, que fornece detalhes completos sobre métodos e respostas com suporte.

Como indicado acima, os iniciantes podem começar com o assistente de visualização, que gera automaticamente o código necessário para incorporar visualizações básicas ao seu site.

O "Hello World" da API Embedded Viewer

A maneira mais fácil de começar a aprender sobre a API Embedded Viewer é com um exemplo simples. A página da Web a seguir exibe uma visualização de 600 x 500 de Mountain View, de Nicholas Perry, ISBN 0738531367 (parte da série "Images of America" da 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>

Confira este exemplo e faça o download para editar e brincar com ele. Mesmo neste exemplo simples, há cinco itens a observar:

  1. Incluímos o API Loader usando uma tag script.
  2. Criamos um elemento div chamado "viewerCanvas" para conter o visualizador.
  3. Escrevemos uma função JavaScript para criar um objeto "visualizador".
  4. Nós carregamos o livro usando seu identificador exclusivo (neste caso, ISBN:0738531367).
  5. Usamos google.books.setOnLoadCallback para chamar initialize quando a API é totalmente carregada.

Essas etapas são explicadas a seguir:

Como carregar a API Embedded Viewer

Usar o framework do API Loader para carregar a API Embedded Viewer é relativamente simples. Isso envolve as duas etapas a seguir:

  1. Inclua a biblioteca API Loader: 
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
  2. Invocar o método google.books.load. O método google.books.load usa um parâmetro de lista opcional que especifica uma função de callback ou uma linguagem, conforme explicado abaixo. 
    <script type="text/javascript">
  google.books.load();
</script>

Como carregar uma versão localizada da API Embedded Viewer

A API Embedded Viewer usa o inglês por padrão ao mostrar informações textuais, como tooltips, nomes de controles e texto de link. Se você quiser mudar a API Embedded Viewer para mostrar corretamente as informações em um idioma específico, adicione um parâmetro language opcional à chamada google.books.load.

Por exemplo, para mostrar um módulo de visualização de livro com a interface em português do Brasil:

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

Exemplo (book-language.html)

Os códigos de idioma RFC 3066 com suporte no momento incluem 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.

Ao usar a API Embedded Viewer em outros idiomas além do inglês, recomendamos veicular sua página com um cabeçalho content-type definido como utf-8 ou incluir uma tag <meta> equivalente na sua página. Isso ajuda a garantir que os caracteres sejam renderizados corretamente em todos os navegadores. Para mais informações, consulte a página do W3C sobre como definir o parâmetro de charset HTTP.

Elementos DOM do espectador

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

Para que um livro apareça em uma página da Web, é preciso reservar um lugar para ele. Normalmente, isso é feito criando um elemento div nomeado e obtendo uma referência a esse elemento no modelo de objetos do documento (DOM) do navegador.

O exemplo acima define uma div chamada "viewerCanvas" e define o tamanho usando atributos de estilo. O visualizador usa implicitamente o tamanho do contêiner para se dimensionar.

O objeto DefaultViewer

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

A classe JavaScript que cria e controla um único visualizador na página é a classe DefaultViewer. É possível criar mais de uma instância dessa classe. Cada objeto define um visualizador separado na página. Uma nova instância dessa classe é criada usando o operador new do JavaScript.

Ao criar uma nova instância do visualizador, você especifica um nó DOM na página (geralmente um elemento div) como um contêiner para o visualizador. Os nós HTML são filhos do objeto JavaScript document, e obtemos uma referência a esse elemento pelo método document.getElementById().

Esse código define uma variável (denominada viewer) e atribui essa variável a um novo objeto DefaultViewer. A função DefaultViewer() é conhecida como um constructor, e a definição dela (condensada para maior clareza da referência da API Embedded Viewer) é mostrada abaixo:

Construtor Descrição
DefaultViewer(container, opts?) Cria um novo visualizador dentro do HTML container fornecido, que precisa ser um elemento de nível de bloco na página (geralmente um DIV). As opções avançadas são transmitidas usando o parâmetro opts opcional.

O segundo parâmetro no construtor é opcional, destinado a implementações avançadas além do escopo deste documento, e é omitido do exemplo "Hello, World".

Como inicializar o leitor com um livro específico

  viewer.load('ISBN:0738531367');

Depois de criar um leitor pelo construtor DefaultViewer, ele precisa ser inicializado com um livro específico. Essa inicialização é feita usando o método load() do visualizador. O método load() exige um valor identifier, que informa à API qual livro mostrar. Esse método precisa ser enviado antes que qualquer outra operação seja realizada no objeto do visualizador.

Se você souber de vários identificadores para um livro (o ISBN da edição de brochura ou números OCLC alternativos), será possível transmitir uma matriz de strings de identificador como o primeiro parâmetro para a função load(). O leitor vai renderizar o livro se houver uma prévia incorporável associada a qualquer dos identificadores no array.

Identificadores de livros compatíveis

Assim como o recurso Links dinâmicos, a API Embedded Viewer oferece suporte a vários valores para identificar um livro específico. São eles:

ISBN
O International Standard Book Number comercial de 10 ou 13 dígitos.
Exemplo: ISBN:0738531367
Número OCLC
O número exclusivo atribuído a um livro pela OCLC quando o registro do livro é adicionado ao sistema de catalogação WorldCat.
Exemplo: OCLC:70850767
LCCN
O número de controle da Biblioteca do Congresso atribuído ao registro pela Biblioteca do Congresso.
Exemplo: LCCN:2006921508
ID do volume do Google Livros
A string exclusiva que o Google Livros atribuiu ao volume, que aparece no URL do livro no Google Livros.
Exemplo: Py8u3Obs4f4C
URL de visualização do Google Livros
Um URL que abre a página de visualização de um livro no Google Livros.
Exemplo: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

Esses identificadores são usados com frequência com outras APIs da família Google Books. Por exemplo, é possível usar o Dynamic Links para renderizar um botão de visualização somente se o livro for incorporável. Em seguida, quando o usuário clicar no botão, criar uma instância de um visualizador usando o URL de visualização retornado pela chamada do Dynamic Links. Da mesma forma, é possível criar um aplicativo de navegação e visualização avançado com a API Books, que retorna vários identificadores do setor adequados nos feeds de volumes. Acesse a página de exemplos para conferir algumas implementações avançadas.

Como lidar com inicializações com falha

Em alguns casos, a chamada load pode falhar. Isso geralmente ocorre quando a API não consegue encontrar um livro associado ao identificador fornecido, quando não há uma visualização do livro disponível, quando a visualização do livro não pode ser incorporada ou quando restrições territoriais impedem que o usuário final veja esse livro específico. Talvez você queira receber um alerta sobre essa falha para que seu código possa processar essa condição de maneira adequada. Por esse motivo, a função load permite transmitir um segundo parâmetro opcional, notFoundCallback, que indica qual função precisa ser chamada se o livro não puder ser carregado. Por exemplo, o código a seguir vai gerar uma caixa de "alerta" do JavaScript se o livro puder ser incorporado:

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

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

Exemplo de visualização (book-notfound.html)

Usando esse callback, você pode mostrar um erro semelhante ou ocultar o elemento viewerCanvas completamente. O parâmetro de callback de falha é opcional e não está incluído no exemplo "Hello World".

Observação: como as visualizações podem não estar disponíveis para todos os livros e usuários, pode ser útil saber se a visualização está disponível antes de tentar carregar o visualizador. Por exemplo, você pode mostrar um botão, uma página ou uma seção "Prévia do Google" na interface somente se uma prévia estiver realmente disponível para o usuário. Para isso, use a API Books ou os links dinâmicos, que informam se um livro vai estar disponível para incorporação usando o visualizador.

Processamento de inicializações bem-sucedidas

Também pode ser útil saber se e quando um livro foi carregado. Por esse motivo, a função load aceita um terceiro parâmetro opcional, successCallback, que será executado quando o carregamento de um livro for concluído.

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

Veja um exemplo (book-success.html)

Esse callback pode ser útil se, por exemplo, você quiser mostrar apenas alguns elementos na página se o visualizador tiver renderizado totalmente.

Como mostrar o espectador no carregamento

  google.books.setOnLoadCallback(initialize);

Enquanto uma página HTML é renderizada, o modelo de objeto do documento (DOM) é criado, e todas as imagens e scripts externos são recebidos e incorporados ao objeto document. Para garantir que nosso visualizador seja colocado na página somente após o carregamento completo dela, a função google.books.setOnLoadCallback é usada para adiar a execução da função que cria o objeto DefaultViewer. Como setOnLoadCallback só vai chamar initialize quando a API Embedded Viewer estiver carregada e pronta para uso, isso evita comportamentos imprevisíveis e garante o controle de como e quando o visualizador é renderizado.

Observação:para maximizar a compatibilidade entre navegadores, é altamente recomendável programar o carregamento do visualizador usando a função google.books.setOnLoadCallback, em vez de um evento onLoad na tag <body>.

Interações do espectador

Agora que você tem um objeto DefaultViewer, é possível interagir com ele. O objeto de leitor básico tem uma aparência e um comportamento muito semelhantes ao leitor com que você interage no site do Google Livros e vem com muitos comportamentos integrados.

No entanto, também é possível interagir com o leitor de forma programática. O objeto DefaultViewer oferece suporte a vários métodos que alteram o estado de visualização diretamente. Por exemplo, os métodos zoomIn(), nextPage() e highlight() operam no visualizador de forma programática, em vez de pela interação do usuário.

O exemplo a seguir mostra uma visualização de livro que "passa" automaticamente para a próxima página a cada três segundos. Se a próxima página estiver na parte visível do visualizador, ele se movimentará até a página com facilidade. Caso contrário, ele vai pular diretamente para o topo da página seguinte.

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

Exemplo de visualização (book-animate.html)

As chamadas programáticas para o visualizador falharão ou não terão efeito até que o visualizador seja totalmente inicializado com um livro específico. Para garantir que essas funções sejam chamadas apenas quando o visualizador estiver pronto, use o parâmetro successCallback para viewer.load, conforme descrito acima.

Para informações sobre todas as funções aceitas pelo objeto DefaultViewer, consulte o Guia de referência.

Notas de programação

Antes de começar a usar a API Embedded Viewer, observe as preocupações a seguir para garantir que o aplicativo funcione sem problemas nas plataformas pretendidas.

Compatibilidade com navegadores

A API Embedded Viewer é compatível com versões recentes do Internet Explorer, Firefox e Safari. Geralmente, ela também é compatível com outros navegadores baseados em Gecko e WebKit, como o Camino e o Google Chrome.

Às vezes, aplicativos diferentes exigem comportamentos distintos de usuários com navegadores incompatíveis. A API Embedded Viewer não tem nenhum comportamento automático ao detectar um navegador incompatível. A maioria dos exemplos neste documento não verifica a compatibilidade do navegador nem mostra uma mensagem de erro para navegadores mais antigos. Aplicativos reais podem fazer algo mais amigável com navegadores antigos ou incompatíveis, mas essas verificações são omitidas para tornar os exemplos mais legíveis.

Aplicativos não triviais vão encontrar inconsistências inevitáveis entre navegadores e plataformas. Sites como quirksmode.org também são bons recursos para encontrar soluções alternativas.

XHTML e modo quirks

Recomendamos que você use Xcode compatível com padrões nas páginas que contenham o visualizador. Quando os navegadores veem o DOCTYPE X na parte superior da página, eles renderizam a página em "modo de conformidade com os padrões", o que torna o layout e os comportamentos muito mais previsíveis em todos os navegadores. As páginas sem essa definição podem ser renderizadas no modo de peculiaridades, o que pode levar a um layout inconsistente.

<!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">

Uma observação sobre os exemplos da API Embedded Viewer

A maioria dos exemplos nesta documentação mostra apenas o código JavaScript relevante, não o arquivo HTML completo. Você pode conectar o código JavaScript ao seu próprio arquivo HTML de esqueleto ou fazer o download do arquivo HTML completo para cada exemplo clicando no link após o exemplo.

Solução de problemas

Se o código não estiver funcionando, confira algumas abordagens que podem ajudar a resolver os problemas: