Guide du développeur

L'API Embedded Viewer vous permet d'intégrer le contenu de livres Google Livres directement dans vos pages Web avec JavaScript. L'API fournit également un certain nombre d'utilitaires pour manipuler les aperçus de livres et est souvent utilisée avec les autres API décrites sur ce site.

L'assistant d'aperçu est un outil basé sur l'API Embedded Viewer qui vous permet d'ajouter facilement des fonctionnalités d'aperçu à votre site en copiant simplement quelques lignes de code. Ce document s'adresse aux développeurs expérimentés qui souhaitent personnaliser l'affichage du lecteur sur leurs sites.

Audience

Cette documentation s'adresse aux personnes familiarisées avec la programmation JavaScript et les concepts de programmation orientée objet. Il est également recommandé de connaître Google Livres du point de vue de l'utilisateur. De nombreux tutoriels JavaScript sont disponibles sur le Web.

Cette documentation conceptuelle n'est pas complète ni exhaustive. Elle est conçue pour vous permettre de découvrir et de développer rapidement des applications intéressantes avec l'API Embedded Viewer. Les utilisateurs avancés peuvent être intéressés par la documentation de référence de l'API Embedded Viewer, qui fournit des informations complètes sur les méthodes et réponses compatibles.

Comme indiqué ci-dessus, les débutants peuvent commencer par l'assistant d'aperçu, qui génère automatiquement le code nécessaire pour intégrer des aperçus de base sur votre site.

L'exemple "Hello, World" de l'API Embedded Viewer

Le moyen le plus simple de commencer à vous familiariser avec l'API Embedded Viewer consiste à consulter un exemple simple. La page Web suivante affiche un aperçu 600x500 de Mountain View, par Nicholas Perry, ISBN 0738531367 (qui fait partie de la série "Images of America " d'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>

Vous pouvez consulter cet exemple et le télécharger pour le modifier et l'utiliser. Même dans cet exemple simple, cinq points sont à noter:

  1. Nous incluons le chargeur d'API à l'aide d'une balise script.
  2. Nous créons un élément div nommé "viewerCanvas" pour contenir le visualiseur.
  3. Nous écrivons une fonction JavaScript pour créer un objet "viewer".
  4. Nous chargeons le livre à l'aide de son identifiant unique (ISBN:0738531367 dans ce cas).
  5. Nous utilisons google.books.setOnLoadCallback pour appeler initialize une fois le chargement complet de l'API.

Ces étapes sont expliquées ci-dessous.

Charger l'API Embedded Viewer

Il est relativement simple d'utiliser le framework API Loader pour charger l'API Embedded Viewer. Il comprend les deux étapes suivantes:

  1. Incluez la bibliothèque du chargeur d'API: 
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
  2. Appelez la méthode google.books.load. La méthode google.books.load utilise un paramètre de liste facultatif spécifiant une fonction de rappel ou une langue, comme expliqué ci-dessous. 
    <script type="text/javascript">
  google.books.load();
</script>

Charger une version localisée de l'API Embedded Viewer

L'API Embedded Viewer utilise l'anglais par défaut pour afficher des informations textuelles telles que les info-bulles, les noms des commandes et le texte des liens. Si vous souhaitez modifier l'API Embedded Viewer pour qu'elle affiche correctement les informations dans une langue spécifique, vous pouvez ajouter un paramètre language facultatif à votre appel google.books.load.

Par exemple, pour afficher un module d'aperçu de livre avec l'interface en portugais brésilien:

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

Voir un exemple (book-language.html)

Les codes de langue RFC 3066 actuellement acceptés incluent 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 et vi.

Si vous utilisez l'API Embedded Viewer dans des langues autres que l'anglais, nous vous recommandons vivement de diffuser votre page avec un en-tête content-type défini sur utf-8, ou avec une balise <meta> équivalente sur la page. Cela permet de garantir que les caractères s'affichent correctement dans tous les navigateurs. Pour en savoir plus, consultez la page du W3C sur le paramètre de jeu de caractères HTTP.

Éléments DOM du lecteur

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

Pour qu'un livre s'affiche sur une page Web, vous devez lui réserver un espace. En règle générale, cela consiste à créer un élément div nommé et à obtenir une référence à cet élément dans le Document Object Model (DOM) du navigateur.

L'exemple ci-dessus définit un div nommé "viewerCanvas" et définit sa taille à l'aide d'attributs de style. Le lecteur utilise implicitement la taille du conteneur pour se dimensionner lui-même.

Objet DefaultViewer

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

La classe JavaScript qui crée et contrôle un seul lecteur sur la page est la classe DefaultViewer. (Vous pouvez créer plusieurs instances de cette classe. Chaque objet définira alors un lecteur distinct sur la page.) Une instance de cette classe est créée à l'aide de l'opérateur JavaScript new.

Lorsque vous créez une instance de lecteur, vous spécifiez un nœud DOM sur la page (généralement un élément div) en tant que conteneur pour le lecteur. Les nœuds HTML sont des enfants de l'objet JavaScript document. Nous obtenons une référence à cet élément via la méthode document.getElementById().

Ce code définit une variable (nommée viewer) et l'attribue à un nouvel objet DefaultViewer. La fonction DefaultViewer() est appelée constructor et sa définition (condensée pour plus de clarté à partir de la Documentation de référence de l'API Embedded Viewer) est présentée ci-dessous:

Constructeur Description
DefaultViewer(container, opts?) Crée un lecteur dans l'container HTML donné, qui doit être un élément de niveau bloc sur la page (généralement un DIV). Les options avancées sont transmises à l'aide du paramètre opts facultatif.

Notez que le deuxième paramètre du constructeur est facultatif (il est destiné aux implémentations avancées qui ne relèvent pas du champ d'application de ce document) et qu'il est omis de l'exemple "Hello, World".

Initialiser la visionneuse avec un livre spécifique

  viewer.load('ISBN:0738531367');

Une fois que nous avons créé un lecteur via le constructeur DefaultViewer, il doit être initialisé avec un livre particulier. Cette initialisation est effectuée à l'aide de la méthode load() du lecteur. La méthode load() nécessite une valeur identifier, qui indique à l'API le livre à afficher. Cette méthode doit être envoyée avant toute autre opération effectuée sur l'objet viewer.

Si vous connaissez plusieurs identifiants pour un livre (l'ISBN de l'édition en livre broché ou d'autres numéros OCLC), vous pouvez transmettre un tableau de chaînes d'identifiants en tant que premier paramètre à la fonction load(). Le lecteur affichera le livre s'il existe un aperçu intégré associé à n'importe quel identifiant de la matrice.

Identifiants de livre acceptés

Tout comme la fonctionnalité Liens dynamiques, l'API Embedded Viewer est compatible avec un certain nombre de valeurs permettant d'identifier un livre particulier. Exemples :

ISBN
Numéro ISBN commercial à 10 ou 13 chiffres.
Exemple: ISBN:0738531367
Numéro OCLC
Numéro unique attribué à un livre par l'OCLC lorsque son enregistrement est ajouté au système de catalogage WorldCat.
Exemple: OCLC:70850767
LCCN
Numéro de contrôle de la Bibliothèque du Congrès attribué à l'enregistrement par la Bibliothèque du Congrès.
Exemple: LCCN:2006921508
ID de volume Google Livres
Chaîne unique attribuée par Google Livres au volume, qui apparaît dans l'URL du livre sur Google Livres.
Exemple: Py8u3Obs4f4C
URL d'aperçu Google Livres
URL qui ouvre une page d'aperçu d'un livre sur Google Livres.
Exemple: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

Ces identifiants sont souvent utilisés avec d'autres API de la famille d'API Google Livres. Par exemple, vous pouvez utiliser les liens dynamiques pour afficher un bouton d'aperçu uniquement si le livre peut être intégré. Ensuite, lorsque l'utilisateur clique sur le bouton, vous pouvez instancier un lecteur à l'aide de l'URL d'aperçu renvoyée par l'appel des liens dynamiques. De même, vous pouvez créer une application de navigation et d'aperçu enrichie avec l'API Books, qui renvoie plusieurs identifiants du secteur adaptés dans ses flux de volumes. Consultez la page des exemples pour découvrir quelques implémentations avancées.

Gérer les initialisations infructueuses

Dans certains cas, l'appel load peut échouer. Cela se produit généralement lorsque l'API n'a pas trouvé de livre associé à l'identifiant fourni, lorsqu'aucun aperçu du livre n'est disponible, lorsqu'il ne peut pas être intégré ou lorsque des restrictions territoriales empêchent l'utilisateur final de voir ce livre en particulier. Vous voudrez peut-être être averti d'un tel échec, afin que votre code puisse gérer cette condition correctement. Pour cette raison, la fonction load vous permet de transmettre un deuxième paramètre facultatif, notFoundCallback, qui indique la fonction à appeler si le livre n'a pas pu être chargé. Par exemple, le code suivant génère une boîte d'alerte JavaScript si le livre peut être intégré:

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

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

Voir un exemple (book-notfound.html)

À l'aide de ce rappel, vous pouvez choisir d'afficher une erreur similaire ou de masquer complètement l'élément viewerCanvas. Le paramètre de rappel d'échec est facultatif et n'est pas inclus dans l'exemple "Bonjour à tous".

Remarque: Étant donné que les aperçus ne sont pas disponibles pour tous les livres ni pour tous les utilisateurs, il peut être utile de savoir si un aperçu est disponible avant d'essayer de charger une visionneuse. Par exemple, vous pouvez n'afficher un bouton, une page ou une section "Aperçu Google" dans votre UI que si un aperçu est réellement disponible pour l'utilisateur. Pour ce faire, vous pouvez utiliser l'API Livres ou les liens dynamiques, qui indiquent si un livre peut être intégré à l'aide de la visionneuse.

Gérer les initialisations réussies

Il peut également être utile de savoir si et quand un livre a été correctement chargé. Pour cette raison, la fonction load accepte un troisième paramètre facultatif, successCallback, qui s'exécutera lorsque le chargement d'un livre sera terminé.

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

Voir un exemple (book-success.html)

Ce rappel peut être utile si, par exemple, vous ne souhaitez afficher certains éléments sur votre page que si l'utilisateur a entièrement affiché son écran.

Afficher la visionneuse au chargement

  google.books.setOnLoadCallback(initialize);

Lors de l'affichage d'une page HTML, le Document Object Model (DOM) est créé, et toutes les images et scripts externes sont reçues et intégrées à l'objet document. Pour que l'internaute ne soit placé sur la page qu'une fois celle-ci entièrement chargée, la fonction google.books.setOnLoadCallback diffère l'exécution de la fonction qui construit l'objet DefaultViewer. Étant donné que setOnLoadCallback n'appelle initialize que lorsque l'API Embedded Viewer est chargée et prête à être utilisée, cela évite tout comportement imprévisible et permet de contrôler comment et quand le lecteur est dessiné.

Remarque:Pour maximiser la compatibilité entre les navigateurs, nous vous recommandons vivement de planifier le chargement du lecteur à l'aide de la fonction google.books.setOnLoadCallback plutôt qu'à l'aide d'un événement onLoad sur votre balise <body>.

Interactions des spectateurs

Maintenant que vous disposez d'un objet DefaultViewer, vous pouvez interagir avec lui. L'objet Viewer de base ressemble beaucoup au lecteur avec lequel vous interagissez sur le site Web de Google Livres et comporte de nombreux comportements intégrés.

Mais vous pouvez aussi interagir avec l'utilisateur par programmation. L'objet DefaultViewer accepte un certain nombre de méthodes qui modifient directement l'état de l'aperçu. Par exemple, les méthodes zoomIn(), nextPage() et highlight() fonctionnent de manière programmatique sur le lecteur, plutôt que par interaction utilisateur.

L'exemple suivant affiche un aperçu de livre qui "tourne" automatiquement à la page suivante toutes les trois secondes. Si la page suivante se trouve dans la partie visible du visionneuse, il fait un panoramique fluide vers la page. Sinon, il passe directement en haut de la page suivante.

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

Voir un exemple (book-animate.html)

Notez que les appels programmatiques au lecteur échoueront ou n'auront aucun effet tant que le lecteur n'est pas complètement initialisé avec un livre particulier. Pour vous assurer que vous n'appelez ces fonctions que lorsque le lecteur est prêt, utilisez le paramètre successCallback pour viewer.load, comme décrit ci-dessus.

Pour en savoir plus sur toutes les fonctions compatibles avec l'objet DefaultViewer, consultez le guide de référence.

Remarques concernant la programmation

Avant de vous plonger dans l'API Embedded Viewer, vous devez prendre note des points suivants pour vous assurer que votre application fonctionne correctement sur les plates-formes prévues.

Compatibilité du navigateur

L'API Embedded Viewer est compatible avec les versions récentes d'Internet Explorer, de Firefox et de Safari, ainsi qu'avec d'autres navigateurs basés sur Gecko et WebKit, tels que Camino et Google Chrome.

Différentes applications nécessitent parfois des comportements différents pour les utilisateurs disposant de navigateurs incompatibles. L'API Embedded Viewer n'a aucun comportement automatique lorsqu'elle détecte un navigateur incompatible. La plupart des exemples de ce document ne vérifient pas la compatibilité du navigateur ni n'affichent de message d'erreur pour les navigateurs plus anciens. Les applications réelles peuvent adopter une approche plus conviviale avec des navigateurs anciens ou incompatibles, mais ces vérifications sont omises pour rendre les exemples plus lisibles.

Les applications complexes rencontreront inévitablement des incohérences entre les navigateurs et les plates-formes. Des sites tels que quirksmode.org sont également de bonnes ressources pour trouver des solutions de contournement.

XHTML et mode quirks

Nous vous recommandons d'utiliser du code XHTML conforme aux normes sur les pages contenant le lecteur. Lorsque les navigateurs voient le DOCTYPE XHTML en haut de la page, ils affichent la page en mode "conformité aux normes", ce qui rend la mise en page et les comportements beaucoup plus prévisibles entre les navigateurs. Les pages sans cette définition peuvent s'afficher en mode quirks, ce qui peut entraîner une mise en page incohérente.

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

Remarque concernant les exemples d'API Embedded Viewer

Notez que la plupart des exemples de cette documentation n'affichent que le code JavaScript pertinent, et non le fichier HTML complet. Vous pouvez insérer le code JavaScript dans votre propre fichier HTML squelette ou télécharger le fichier HTML complet de chaque exemple en cliquant sur le lien qui suit l'exemple.

Dépannage

Si votre code ne semble pas fonctionner, voici quelques approches qui pourraient vous aider à résoudre vos problèmes: