Guia do desenvolvedor

Com a API Embedded Viewer, você pode incorporar conteúdo de livros do Google Livros diretamente nas suas páginas da Web com JavaScript. A API também fornece vários utilitários para manipular visualizações de livros e é frequentemente usada em conjunto com 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 copiando apenas algumas linhas de código. Este documento é destinado a desenvolvedores mais avançados que procuram personalizar a forma como o visualizador aparece em seus sites.

Público

Esta documentação destina-se a 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. Existem 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 estar interessados na Referência da API Embedded Viewer, que fornece detalhes abrangentes sobre métodos e respostas compatíveis.

Conforme 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 no 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>

Você pode conferir este exemplo e fazer o download para editá-lo e testá-lo. 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 armazenar o visualizador.
  3. Escrevemos uma função JavaScript para criar um objeto "viewer".
  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 estiver 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 de APIs Loader: 
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
  2. Invoque 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 para exibir informações textuais, como dicas, os nomes dos controles e texto do 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 exibir o módulo de visualização de um livro no idioma da interface em português do Brasil:

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

Veja um exemplo (book-language.html)

No momento, os códigos de idioma RFC 3066 com suporte são: 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-BR, lt, ms, no, plropt, lv-pt,

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 configurar o parâmetro do conjunto de caracteres HTTP.

Elementos DOM do visualizador

<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 chamado div e conseguindo uma referência a ele no DOM (modelo de objeto do documento) do navegador.

O exemplo acima define uma div chamada "viewerCanvas" e define o tamanho dela usando atributos de estilo. O leitor, implicitamente, usa o tamanho do contêiner para dimensionar a si mesmo.

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 definirá um visualizador separado na página. Uma nova instância dessa classe é criada usando o operador JavaScript new.

Ao criar uma nova instância de 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 document JavaScript, e obtemos uma referência a esse elemento usando o 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 construtor e a definição dela (resumida para maior clareza na 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 (normalmente um DIV). As opções avançadas são transmitidas usando o parâmetro opts opcional.

Observe que 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".

Inicialização do visualizador com um livro específico

  viewer.load('ISBN:0738531367');

Depois de criar um visualizador usando o construtor DefaultViewer, ele precisa ser inicializado com um livro específico. Essa inicialização é realizada com o uso do método load() do visualizador. O método load() requer 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 visualizador vai renderizar o livro se houver uma visualização incorporável associada a qualquer um dos identificadores na matriz.

Identificadores de livros compatíveis

Assim como o recurso Dynamic Links, a API Embedded Viewer aceita vários valores para identificar um livro específico. São elas:

ISBN
O número padrão internacional de livro comercial exclusivo 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 dele é adicionado ao sistema de catalogação do 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
Código do volume do Google Livros
A string exclusiva que o Google Livros atribuiu ao volume, que aparece no URL do livro.
Exemplo: Py8u3Obs4f4C
URL de visualização do Google Livros
Um URL que abre a página de visualização do livro no Google Livros.
Exemplo: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

Esses identificadores costumam ser usados com outras APIs na família da API 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, você pode criar um aplicativo avançado de navegação e visualização com a API Books, que retorna vários identificadores do setor adequados nos feeds de volumes. Acesse a página de exemplos para conhecer algumas implementações avançadas.

Como lidar com inicializações com falha

Em alguns casos, a chamada load pode falhar. Normalmente, isso ocorre quando a API não consegue encontrar um livro associado ao identificador fornecido, quando não há visualização do livro disponível, quando a visualização do livro não pode ser incorporada ou quando restrições territoriais impedem o usuário final de ver esse livro específico. É recomendável ser alertado dessa falha para que o código possa lidar com essa condição corretamente. Por esse motivo, a função load permite que você transmita 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 gera uma caixa de "alerta" JavaScript caso o livro possa 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);
}

Veja um exemplo (book-notfound.html)

Ao usar esse callback, você pode mostrar um erro semelhante ou ocultar o elemento viewerCanvas completamente. O parâmetro de callback com 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 querer mostrar um botão, uma página ou uma seção "Visualização do Google" na sua interface somente se uma visualização realmente estiver disponível para o usuário. É possível fazer isso usando a API Books ou o Dynamic Links, que informam se um livro vai estar disponível para incorporação usando o visualizador.

Como gerenciar inicializações bem-sucedidas

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

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ê só quiser mostrar determinados elementos na página se o visualizador tiver sido totalmente renderizado.

Como mostrar o espectador no carregamento

  google.books.setOnLoadCallback(initialize);

Durante a renderização de uma página HTML, o 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ó chamará initialize quando a API Embedded Viewer estiver carregada e pronta para ser usada, 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 do visualizador básico se parece e se comporta de maneira muito parecida com o visualizador com quem você interage no site do Google Livros, além de ter muitos comportamentos integrados.

Mas você também pode interagir com o espectador de forma programática. O objeto DefaultViewer oferece suporte a vários métodos que mudam o estado da visualização diretamente. Por exemplo, os métodos zoomIn(), nextPage() e highlight() operam no visualizador de forma programática, e não por meio da interação do usuário.

O exemplo a seguir mostra uma visualização de livro que "volta" 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);

Veja um exemplo (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 compatíveis com o objeto DefaultViewer, consulte o Guia de referência.

Notas de programação

Antes de começar a se aprofundar na API Embedded Viewer, considere as questões a seguir para garantir que seu aplicativo funcione sem problemas nas plataformas pretendidas.

Compatibilidade do navegador

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 quando detecta um navegador incompatível. A maioria dos exemplos neste documento não verifica a compatibilidade do navegador nem exibe 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.

Os aplicativos não triviais encontrarão, inevitavelmente, inconsistências 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. Páginas sem essa definição podem ser renderizadas no modo quirks, 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 códigos JavaScript relevantes, não o arquivo HTML completo. Você pode conectar o código JavaScript ao seu próprio esqueleto de arquivo HTML 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 parece não estar funcionando, aqui estão algumas abordagens que podem ajudar a resolver seus problemas: