Guide du développeur

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

L'assistant de prévisualisation est un outil intégré à l'API Embedded Viewer qui permet d'ajouter facilement des fonctionnalités d'aperçu à votre site en copiant simplement quelques lignes de code. Ce document est destiné aux développeurs plus expérimentés qui souhaitent personnaliser l'affichage de l'utilisateur sur leur site.

Audience

Cette documentation s'adresse aux personnes familiarisées avec la programmation JavaScript et les concepts de programmation orientée objet. Vous devez également 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 d'explorer et de développer rapidement des applications sympas avec l'API Embedded Viewer. Les utilisateurs avancés peuvent s'intéresser à la documentation de référence de l'API Visionneuse intégrée, qui fournit des informations complètes sur les méthodes et réponses acceptées.

Comme indiqué ci-dessus, les débutants peuvent commencer par utiliser 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

Le moyen le plus simple de vous familiariser avec l'API Embedded Viewer 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 (faisant 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 vous entraîner à l'utiliser. Même dans cet exemple simple, voici cinq points à noter:

  1. Nous ajoutons le chargeur d'API à l'aide d'un tag script.
  2. Nous créons un élément div nommé "viewerCanvas" pour contenir le lecteur.
  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 lorsque l'API est entièrement chargée.

Ces étapes sont expliquées ci-dessous.

Charger l'API de la visionneuse intégrée

L'utilisation du framework Loader de l'API pour charger l'API Embedded Viewer est relativement simple. Pour ce faire, procédez comme suit:

  1. Incluez la bibliothèque API Loader : 
    <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 qui spécifie une fonction ou une langue de rappel, comme expliqué ci-dessous. 
    <script type="text/javascript">
  google.books.load();
</script>

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

L'API de la visionneuse intégrée utilise l'anglais par défaut lors de l'affichage d'informations textuelles comme des info-bulles, les noms des commandes et le texte des liens. Si vous souhaitez modifier l'API Visionneuse intégrée afin d'afficher correctement les informations dans une langue donnée, vous pouvez ajouter un paramètre language facultatif à votre appel google.books.load.

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

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

Voir un exemple (book-language.html)

:

Lorsque vous utilisez l'API de la visionneuse intégrée 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 en incluant une balise <meta> équivalente dans votre page. Cela permet de garantir l'affichage correct des caractères dans tous les navigateurs. Pour en savoir plus, consultez la page du W3C sur la configuration du paramètre charset HTTP.

Éléments DOM de la visionneuse

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

Pour qu'un livre s'affiche sur une page Web, vous devez lui réserver une place. Pour ce faire, il suffit généralement de créer un élément div nommé et d'obtenir une référence à cet élément dans le modèle d'objet de document (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.

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éfinissant une visionneuse distincte 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) comme 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. Sa définition (résumée à partir de la documentation de référence sur l'API Visionneuse intégrée) est présentée ci-dessous:

Constructeur Description
DefaultViewer(conteneur, opt.) Crée un lecteur dans l'élément HTML HTML container, qui doit ê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 facultatif opts.

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

Initialiser l'utilisateur 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 de la visionneuse.

Si vous connaissez plusieurs identifiants pour un livre (l'ISBN de l'édition brochée ou d'autres numéros OCLC), vous pouvez transmettre un tableau de chaînes d'identifiants en tant que premier paramètre de la fonction load(). L'utilisateur affichera le livre si un aperçu intégrable est associé à n'importe lequel des identifiants du tableau.

Identifiants de livres compatibles

Comme la fonctionnalité Liens dynamiques, l'API Embedded Viewer accepte un certain nombre de valeurs pour identifier un livre particulier. En voici quelques-uns :

ISBN
Le numéro de livre standard international à 10 ou 13 chiffres unique.
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
LCCN
Le numéro de contrôle de la Bibliothèque du Congrès attribué au dossier 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
Une URL qui ouvre une page d'aperçu 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 Google Livres. Par exemple, vous pouvez utiliser des 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, instanciez un lecteur à l'aide de l'URL d'aperçu renvoyée par l'appel Dynamic Links. De la même manière, vous pouvez créer une application enrichie de navigation et d'aperçu avec l'API Livres, qui renvoie plusieurs identifiants sectoriels appropriés dans ses flux Volumes. Accédez à la page d'exemples pour découvrir quelques implémentations avancées.

Gérer les initialisations ayant échoué

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, lorsque l'aperçu du livre ne peut pas être intégré ou lorsque des restrictions territoriales empêchent l'utilisateur final de voir ce livre. Vous pouvez être alerté de ce type de défaillance afin que votre code puisse gérer cette condition de manière optimale. Pour cette raison, la fonction load vous permet de transmettre un second 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)

En utilisant 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: Les aperçus ne sont pas disponibles pour tous les livres ni pour tous les utilisateurs. Par conséquent, il peut être utile de savoir si un aperçu est disponible avant d'essayer de charger une visionneuse. Par exemple, vous pouvez afficher un bouton, une page ou une section "Google Preview" dans votre interface utilisateur uniquement si un aperçu est réellement disponible pour l'utilisateur. Vous pouvez le faire à l'aide de l'API Livres ou de Liens dynamiques, qui indiquent si un livre peut être intégré ou non à l'aide de la visionneuse.

Gérer les initialisations réussies

Il peut également être utile de savoir si et quand un livre a bien été chargé. Pour cette raison, la fonction load accepte un troisième paramètre facultatif, successCallback, qui sera exécuté si et quand un livre a fini de se charger.

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é le contenu.

Afficher la visionneuse au chargement

  google.books.setOnLoadCallback(initialize);

Pendant le rendu d'une page HTML, le modèle d'objet de document (DOM) est créé, et les images et scripts externes sont reçus et intégrés à l'objet document. Pour vous assurer que notre lecteur n'est placé sur la page qu'après son chargement complet, la fonction google.books.setOnLoadCallback permet de différer l'exécution de la fonction qui construit l'objet DefaultViewer. Étant donné que setOnLoadCallback n'appelle initialize que lorsque l'API Visionneuse intégrée est chargée et prête à être utilisée. Cela évite les comportements imprévisibles et permet de contrôler quand et comment l'utilisateur est attiré.

Remarque:Pour optimiser la compatibilité entre les navigateurs, nous vous recommandons vivement de planifier le chargement de la visionneuse à 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 visualisation de base ressemble beaucoup au lecteur avec lequel vous interagissez sur le site Web Google Livres. Il intègre de nombreux comportements.

Vous pouvez également interagir avec le spectateur par programmation. L'objet DefaultViewer est compatible avec un certain nombre de méthodes qui modifient directement l'état de l'aperçu. Par exemple, les méthodes zoomIn(), nextPage() et highlight() opèrent sur l'utilisateur par programmation, plutôt que via une interaction utilisateur.

L'exemple suivant affiche un aperçu de livre qui "se tourne" automatiquement vers la page suivante toutes les trois secondes. Si la page suivante se trouve dans la partie visible de la visionneuse, celle-ci effectue un panoramique fluide. Sinon, il revient directement au 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 l'exemple (book-animate.html)

Notez que les appels programmatiques envoyés à la visionneuse échouent ou n'ont aucun effet tant que l'utilisateur n'est pas complètement initialisé avec un livre donné. 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.

Notes de programmation

Avant de vous lancer dans l'API de la visionneuse intégrée, tenez compte des points suivants pour vous assurer que votre application fonctionne correctement sur les plates-formes prévues.

Compatibilité des navigateurs

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

Le comportement des applications peut varier selon l'utilisateur. L'API Embedded Viewer ne se comporte pas automatiquement 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 navigateurs plus anciens. Les applications réelles peuvent agir de manière plus conviviale avec les navigateurs anciens ou incompatibles, mais ces vérifications sont omises pour rendre les exemples plus lisibles.

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

XHTML et mode quirks

Nous vous recommandons d'utiliser le format 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 de conformité standard", 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 sur les exemples de l'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 pour chaque exemple en cliquant sur le lien situé après l'exemple.

Dépannage

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