Guide du développeur

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

L'assistant de prévisualisation est un outil intégré à l'API Embedded Viewer, qui vous permet d'ajouter plus 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 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 les réponses compatibles.

Comme indiqué ci-dessus, les débutants peuvent commencer avec l'Assistant de prévisualisation, qui génère automatiquement le code nécessaire pour intégrer des aperçus de base à votre site.

"Hello, World" de l'API Embedded Viewer

Pour vous familiariser avec l'API Embedded Viewer, le moyen le plus simple est de consulter un exemple simple. La page Web suivante affiche un aperçu 600 x 500 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, il y a cinq choses à noter:

  1. Nous incluons le chargeur d'API à l'aide d'un tag script.
  2. Nous créons un élément div nommé "viewerCanvas" pour tenir le spectateur.
  3. Nous écrivons une fonction JavaScript pour créer un objet "viewer".
  4. Nous chargeons le livre à l'aide de son identifiant unique (dans ce cas, ISBN:0738531367).
  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

L'utilisation du framework du chargeur d'API pour charger l'API de la visionneuse intégrée est relativement simple. Elle comporte 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 l'affichage d'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 afficher correctement les informations dans une langue particulière, vous pouvez ajouter un paramètre language facultatif à votre appel google.books.load.

Par exemple, pour afficher un module d'aperçu de livre dans la langue d'interface en portugais (Brésil) :

<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 sont les suivants : 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, ro pl, PT, pt

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 plus d'informations, consultez la page du W3C sur la définition du paramètre de jeu de caractères HTTP.

Éléments DOM de la visionneuse

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

Pour qu'un livre puisse s'afficher sur une page Web, vous devez lui réserver un emplacement. 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.

L'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 constructeur et sa définition (condensée pour plus de clarté dans la documentation de référence de l'API Embedded Viewer) est illustrée ci-dessous:

Constructeur Description
DefaultViewer(container, opts?) Crée une visionneuse dans le container HTML donné, qui devrait être un élément au niveau du 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 (destiné à des implémentations avancées qui dépassent le cadre de ce document) et est omis dans l'exemple "Hello, World".

Initialiser la visionneuse avec un livre spécifique

  viewer.load('ISBN:0738531367');

Une fois que nous avons créé une visionneuse via le constructeur DefaultViewer, elle doit être initialisée 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 sur l'objet visualiseur.

Si vous connaissez plusieurs identifiants pour un livre (l'ISBN de l'édition de poche 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 rendra le livre s'il existe un aperçu intégrable associé à l'un des identifiants du tableau.

Identifiants de livres 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. humainement responsable :

ISBN
Le numéro international normalisé du livre à 10 ou 13 chiffres.
Exemple: ISBN:0738531367
Numéro OCLC
Numéro unique attribué à un livre par l'OCLC lorsque l'enregistrement du livre est ajouté au système de catalogage WorldCat.
Exemple: OCLC:70850767
Numéro de contrôle de la Bibliothèque du Congrès
Le 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 au volume par Google Livres. Elle 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 de 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 des API Google Livres. Par exemple, vous pouvez utiliser des liens dynamiques pour afficher un bouton d'aperçu uniquement si le livre est intégrable. Ensuite, lorsque l'utilisateur clique sur le bouton, instanciez une visionneuse à l'aide de l'URL d'aperçu renvoyée par l'appel Dynamic Links. De même, vous pouvez créer une application de navigation et d'aperçu enrichie à l'aide de l'API Livres, qui renvoie plusieurs identifiants sectoriels appropriés dans ses flux de volumes. Consultez la page Exemples pour découvrir quelques implémentations avancées.

Gérer les échecs d'initialisation

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 n'est disponible, lorsque l'aperçu du livre ne peut pas être intégré ou lorsque des restrictions territoriales empêchent l'utilisateur final de consulter le livre en question. Vous voudrez peut-être être averti d'un tel échec, afin que votre code puisse gérer cette condition comme il se doit. 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 zone 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)

Avec ce rappel, vous pouvez décider 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 "Hello World".

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 choisir d'afficher un bouton, une page ou une section "Aperçu Google" dans votre interface utilisateur uniquement si un aperçu est effectivement 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 s'est chargé correctement. 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 lors du chargement

  google.books.setOnLoadCallback(initialize);

Pendant le rendu d'une page HTML, le modèle d'objet de document (DOM) est créé, et toutes les images et tous les scripts externes sont reçus et intégrés dans 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 permet d'éviter tout comportement imprévisible et de contrôler quand et comment la visionneuse est dessinée.

Remarque:Pour optimiser la compatibilité entre les navigateurs, nous vous recommandons vivement de planifier le chargement de la page à l'aide de la fonction google.books.setOnLoadCallback, plutôt que d'utiliser 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 de consultation de base ressemble à celui avec lequel vous interagissez sur le site Web Google Livres et se comporte de manière très semblable. Il est doté de nombreux comportements intégrés.

Mais vous pouvez aussi interagir avec l'utilisateur de manière programmatique. 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 sur le lecteur de manière programmatique, plutôt que via une interaction de l'utilisateur.

L'exemple suivant affiche un aperçu de livre qui "passe" automatiquement à la page suivante toutes les trois secondes. Si la page suivante se trouve dans la partie visible de l'utilisateur, celui-ci se déplace de manière 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 à l'utilisateur échoueront ou n'auront aucun effet tant que l'utilisateur n'aura pas entièrement été 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 sur 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, et généralement d'autres navigateurs basés sur Gecko et WebKit, tels que Camino et Google Chrome.

Des applications différentes exigent parfois un comportement différent pour les utilisateurs dont les navigateurs sont incompatibles. L'API Embedded Viewer n'a pas de comportement automatique lorsqu'elle détecte un navigateur incompatible. La plupart des exemples de ce document ne vérifient pas la compatibilité des navigateurs et n'affichent pas de message d'erreur pour les anciens navigateurs. Les applications réelles peuvent offrir des fonctionnalités plus adaptées aux 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.

Mode XHTML et quirks

Nous vous recommandons d'utiliser le format XHTML conforme aux normes sur les pages sur lesquelles la visionneuse est installée. Lorsque les navigateurs voient le code XHTML DOCTYPE en haut de la page, ils affichent la page en "mode de conformité avec les normes", ce qui rend la mise en page et les comportements beaucoup plus prévisibles d'un navigateur à l'autre. 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 sur les exemples de l'API Embedded Viewer

Notez que la plupart des exemples de cette documentation ne montrent que le code JavaScript pertinent, et non le fichier HTML complet. Vous pouvez brancher le code JavaScript dans votre propre fichier HTML squelette ou télécharger le fichier HTML complet pour chaque exemple en cliquant sur le lien à côté de l'exemple.

Dépannage

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