Entwicklerhandbuch

Mit der Embedded Viewer API können Sie Buchinhalte aus Google Books mit JavaScript direkt in Ihre Webseiten einbetten. Die API bietet auch eine Reihe von Dienstprogrammen zum Bearbeiten von Buchvorschauen und wird häufig zusammen mit den anderen auf dieser Website beschriebenen APIs verwendet.

Der Vorschau-Assistent ist ein Tool, das auf der Embedded Viewer API basiert. Mit ihm kannst du deiner Website ganz einfach Vorschaufunktionen hinzufügen, indem du nur ein paar Codezeilen kopierst. Dieses Dokument richtet sich an fortgeschrittene Entwickler, die die Darstellung des Videoplayers auf ihren Websites anpassen möchten.

Zielgruppe

Diese Dokumentation richtet sich an Personen, die mit der JavaScript und objektorientierten Programmierungskonzepten vertraut sind. Außerdem sollten Sie mit Google Books aus Sicht des Nutzers vertraut sein. Im Web sind viele JavaScript-Anleitungen verfügbar.

Diese konzeptbezogene Dokumentation ist nicht vollständig und erschöpfend. Sie soll Ihnen einen schnellen Einstieg in die Verwendung und Entwicklung von Anwendungen mit der Embedded Viewer API ermöglichen. Fortgeschrittene Nutzer können sich für die Referenz zur eingebetteten Viewer API interessieren, die umfassende Informationen zu unterstützten Methoden und Antworten enthält.

Wie oben erwähnt, sollten Anfänger mit dem Vorschau-Assistenten beginnen. Er generiert automatisch den Code, der zum Einbetten einfacher Vorschauen auf Ihrer Website erforderlich ist.

Das „Hallo Welt“ der Embedded Viewer API

Mit einem einfachen Beispiel gelingt der Einstieg in die Embedded Viewer API am leichtesten. Die folgende Webseite enthält eine Vorschau von 600 × 500 Pixeln des Buches Mountain View von Nicholas Perry, ISBN 0738531367 (Teil der Reihe „Images of America“ von 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>

Sehen Sie sich dieses Beispiel an und laden Sie es herunter, um es zu bearbeiten und auszuprobieren. Auch für dieses einfache Beispiel müssen folgende fünf Schritte ausgeführt werden:

  1. Wir fügen den API-Lademechanismus mit einem script-Tag ein.
  2. Wir erstellen ein div-Element namens „viewerCanvas“, das den Betrachter aufnimmt.
  3. Wir schreiben eine JavaScript-Funktion, um ein „viewer“-Objekt zu erstellen.
  4. Wir laden das Buch anhand seiner eindeutigen ID (in diesem Fall ISBN:0738531367).
  5. Wir verwenden google.books.setOnLoadCallback, um initialize aufzurufen, wenn die API vollständig geladen ist.

Diese Schritte sind nachfolgend beschrieben.

Embedded Viewer API laden

Das Laden der Embedded Viewer API mit dem API Loader-Framework ist relativ einfach. Dazu sind die folgenden zwei Schritte erforderlich:

  1. Fügen Sie die API Loader-Bibliothek ein: 
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
  2. Rufen Sie die Methode google.books.load auf. Die Methode google.books.load verwendet einen optionalen Listenparameter, der eine Callback-Funktion oder Sprache angibt, wie unten erläutert. 
    <script type="text/javascript">
  google.books.load();
</script>

Lokalisierte Version der Embedded Viewer API laden

Die Embedded Viewer API verwendet standardmäßig Englisch, wenn Textinformationen wie Kurzinfos, Namen von Steuerelementen und Linktext angezeigt werden. Wenn Sie die Embedded Viewer API so ändern möchten, dass Informationen in einer bestimmten Sprache korrekt angezeigt werden, können Sie Ihrem google.books.load-Aufruf einen optionalen language-Parameter hinzufügen.

So können Sie beispielsweise ein Modul für die Buchvorschau mit der Benutzeroberflächensprache brasilianisches Portugiesisch anzeigen lassen:

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

Beispiel ansehen (book-language.html)

Derzeit werden die folgenden RFC 3066-Sprachcodes unterstützt: 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 und vi.

Wenn du die Embedded Viewer API in anderen Sprachen als Englisch verwendest, empfehlen wir dringend, für die Bereitstellung deiner Seite einen content-type-Header zu verwenden, der auf utf-8 gesetzt ist, oder ein entsprechendes <meta>-Tag in die Seite einzufügen. So wird sichergestellt, dass Zeichen in allen Browsern korrekt dargestellt werden. Weitere Informationen finden Sie auf der W3C-Seite zum Festlegen des HTTP-Zeichensatzparameters.

DOM-Elemente des Betrachters

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

Damit ein Buch auf einer Webseite angezeigt wird, muss ein Platz dafür reserviert werden. Dazu wird normalerweise ein benanntes div-Element erstellt, auf das im DOM (Document Object Model) des Browsers verwiesen wird.

Im Beispiel oben wird ein div namens „viewerCanvas“ definiert und seine Größe mithilfe von Stilattributen festgelegt. Der Viewer verwendet implizit die Größe des Containers, um seine eigene Größe festzulegen.

StandardViewer-Objekt

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

Die JavaScript-Klasse, mit der ein einzelner Viewer auf der Seite erstellt und gesteuert wird, ist die Klasse DefaultViewer. Sie können mehrere Instanzen dieser Klasse erstellen. Jedes Objekt definiert einen separaten Viewer auf der Seite. Mit dem JavaScript-Operator new wird eine neue Instanz dieser Klasse erstellt.

Wenn Sie eine neue Viewer-Instanz erstellen, geben Sie einen DOM-Knoten auf der Seite (in der Regel ein div-Element) als Container für den Viewer an. HTML-Knoten sind untergeordnete Elemente des JavaScript-document-Objekts. Ein Verweis auf dieses Element wird über die Methode document.getElementById() hergestellt.

Dieser Code definiert eine Variable (namens viewer) und weist sie einem neuen DefaultViewer-Objekt zu. Die Funktion DefaultViewer() wird als constructor bezeichnet. Die Definition der Funktion (zur Verdeutlichung zusammengefasst aus der Referenz zur Embedded Viewer API) ist unten zu sehen:

Konstruktor Beschreibung
DefaultViewer(container, opts?) Erstellt einen neuen Viewer innerhalb des angegebenen HTML-container-Objekts, das ein Element auf Blockebene auf der Seite sein sollte (in der Regel DIV). Erweiterte Optionen werden mit dem optionalen opts-Parameter übergeben.

Der zweite Parameter im Konstruktor ist optional und für erweiterte Implementierungen gedacht, die nicht in den Geltungsbereich dieses Dokuments fallen. Er wird im Beispiel „Hallo Welt“ weggelassen.

Betrachter mit einem bestimmten Buch initialisieren

  viewer.load('ISBN:0738531367');

Nachdem wir mit dem DefaultViewer-Konstruktor einen Viewer erstellt haben, muss er mit einem bestimmten Buch initialisiert werden. Diese Initialisierung erfolgt mithilfe der load()-Methode des Betrachters. Für die Methode load() ist ein identifier-Wert erforderlich, der der API mitteilt, welches Buch angezeigt werden soll. Diese Methode muss gesendet werden, bevor andere Vorgänge auf dem Viewer-Objekt ausgeführt werden.

Wenn Sie mehrere Kennungen für ein Buch kennen, z. B. die ISBN für die Taschenbuchausgabe oder alternative OCLC-Nummern, können Sie der Funktion load() als ersten Parameter ein Array von Kennungsstrings übergeben. Das Buch wird vom Betrachter gerendert, wenn mit einer beliebigen der IDs im Array eine einbettbare Vorschau verknüpft ist.

Unterstützte Buch-IDs

Ähnlich wie die Funktion Dynamic Links unterstützt die Embedded Viewer API eine Reihe von Werten, um ein bestimmtes Buch zu identifizieren. Dazu gehören:

ISBN
Die eindeutige 10- oder 13-stellige kommerzielle Internationale Standardbuchnummer.
Beispiel: ISBN:0738531367
OCLC-Nummer
Die eindeutige Nummer, die einem Buch von der OCLC zugewiesen wird, wenn der Eintrag des Buchs dem Katalogsystem WorldCat hinzugefügt wird.
Beispiel: OCLC:70850767
LCCN
Die Library of Congress Control Number, die dem Datensatz von der Library of Congress zugewiesen wurde.
Beispiel: LCCN:2006921508
Google Books-Band-ID
Der eindeutige String, den Google Books dem Band zugeordnet hat und in der URL des Buchs auf Google Books erscheint.
Beispiel: Py8u3Obs4f4C
Google Books-Vorschau-URL
Eine URL, über die eine Buchvorschauseite bei Google Books geöffnet wird.
Beispiel: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

Diese IDs werden häufig mit anderen APIs in der Google Books API-Familie verwendet. Sie können beispielsweise Dynamic Links verwenden, um nur dann eine Vorschauschaltfläche zu rendern, wenn das Buch eingebettet werden kann. Wenn der Nutzer dann auf die Schaltfläche klickt, wird ein Viewer mit der Vorschau-URL erstellt, die vom Dynamic Links-Aufruf zurückgegeben wird. Ebenso können Sie mit der Books API eine umfassende Anwendung zum Stöbern und Ansehen von Vorschauen erstellen, die in ihren Volumes-Feeds mehrere geeignete Branchen-IDs zurückgibt. Auf der Beispielseite finden Sie einige erweiterte Implementierungen.

Fehlgeschlagene Initialisierungen verarbeiten

In einigen Fällen schlägt der load-Aufruf fehl. Das ist in der Regel der Fall, wenn die API kein Buch mit der angegebenen Kennung finden konnte, wenn keine Buchvorschau verfügbar ist, wenn die Buchvorschau nicht eingebettet werden kann oder wenn der Endnutzer aufgrund von Gebietsbeschränkungen dieses Buch nicht sehen kann. Sie können sich über einen solchen Fehler informieren lassen, damit Ihr Code diese Situation ordnungsgemäß verarbeiten kann. Aus diesem Grund können Sie der Funktion load einen optionalen zweiten Parameter, notFoundCallback, übergeben. Dieser gibt an, welche Funktion aufgerufen werden soll, wenn das Buch nicht geladen werden konnte. Mit dem folgenden Code wird beispielsweise ein JavaScript-Infofeld generiert, wenn das Buch eingebettet werden konnte:

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

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

Beispiel ansehen (book-notfound.html)

Mit diesem Callback können Sie einen ähnlichen Fehler anzeigen oder das viewerCanvas-Element vollständig ausblenden. Der Parameter für den Fehler-Callback ist optional und nicht im Beispiel „Hallo Welt“ enthalten.

Hinweis: Da Vorschauen möglicherweise nicht für alle Bücher und Nutzer verfügbar sind, kann es hilfreich sein, vor dem Laden eines Viewers zu prüfen, ob eine Vorschau verfügbar ist. So können Sie beispielsweise eine Schaltfläche, Seite oder einen Bereich „Google-Vorschau“ in Ihrer Benutzeroberfläche nur anzeigen, wenn für den Nutzer tatsächlich eine Vorschau verfügbar ist. Dazu kannst du die Books API oder Dynamic Links verwenden. Beide geben an, ob ein Buch über den Viewer eingebettet werden kann.

Erfolgreiche Initialisierungen verarbeiten

Es kann auch hilfreich sein zu wissen, ob und wann ein Buch erfolgreich geladen wurde. Aus diesem Grund unterstützt die Funktion load einen optionalen dritten Parameter, successCallback, der ausgeführt wird, wenn das Laden eines Buchs abgeschlossen ist.

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

Beispiel ansehen (book-success.html)

Dieser Rückruf kann beispielsweise nützlich sein, wenn bestimmte Elemente auf deiner Seite nur angezeigt werden sollen, wenn der Viewer vollständig gerendert wurde.

Anzeigen des Viewers beim Laden

  google.books.setOnLoadCallback(initialize);

Während eine HTML-Seite gerendert wird, wird das Document Object Model (DOM) erstellt und alle externen Bilder und Scripts werden empfangen und in das document-Objekt eingefügt. Damit der Videoplayer erst auf der Seite platziert wird, wenn die Seite vollständig geladen ist, wird mit der Funktion google.books.setOnLoadCallback die Ausführung der Funktion verschoben, die das DefaultViewer-Objekt erstellt. Da setOnLoadCallback initialize nur aufruft, wenn die Embedded Viewer API geladen und einsatzbereit ist, wird unvorhersehbares Verhalten vermieden und es kann gesteuert werden, wie und wann der Viewer dargestellt wird.

Hinweis:Um die browserübergreifende Kompatibilität zu maximieren, wird dringend empfohlen, das Laden des Betrachters mit der Funktion google.books.setOnLoadCallback zu planen, anstatt ein onLoad-Ereignis im <body>-Tag zu verwenden.

Interaktionen der Zuschauer

Nachdem Sie ein DefaultViewer-Objekt erstellt haben, können Sie damit interagieren. Das grundlegende Viewer-Objekt ähnelt in Aussehen und Verhalten dem Viewer, mit dem Sie auf der Google Books-Website interagieren, und bietet viele integrierte Funktionen.

Du kannst aber auch programmatisch mit dem Betrachter interagieren. Das DefaultViewer-Objekt unterstützt eine Reihe von Methoden, mit denen der Vorschaustatus direkt geändert werden kann. Die Methoden zoomIn(), nextPage() und highlight() wirken sich beispielsweise programmatisch auf den Betrachter aus und nicht durch Nutzerinteraktionen.

Im folgenden Beispiel sehen Sie eine Buchvorschau, bei der alle drei Sekunden automatisch zur nächsten Seite gewechselt wird. Wenn sich die nächste Seite im sichtbaren Bereich des Viewers befindet, wird der Viewer reibungslos zur Seite gezoomt. Andernfalls springt der Viewer direkt zum Anfang der nächsten Seite.

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

Beispiel ansehen (book-animate.html)

Programmatische Aufrufe an den Viewer schlagen fehl oder haben keine Auswirkungen, bis der Viewer mit einem bestimmten Buch vollständig initialisiert wurde. Damit diese Funktionen nur aufgerufen werden, wenn der Viewer bereit ist, verwenden Sie den successCallback-Parameter für viewer.load wie oben beschrieben.

Informationen zu allen vom DefaultViewer-Objekt unterstützten Funktionen finden Sie im Referenzhandbuch.

Programmhinweise

Bevor du dich mit der Embedded Viewer API beschäftigst, solltest du dir die folgenden Punkte ansehen, damit deine Anwendung auf allen vorgesehenen Plattformen reibungslos funktioniert.

Browserkompatibilität

Die Embedded Viewer API unterstützt aktuelle Versionen von Internet Explorer, Firefox und Safari sowie in der Regel auch andere Gecko- und WebKit-basierte Browser wie Camino und Google Chrome.

Verschiedene Anwendungen erfordern manchmal unterschiedliches Verhalten bei Nutzern mit inkompatiblen Browsern. Die Embedded Viewer API führt keine automatischen Aktionen aus, wenn ein inkompatibler Browser erkannt wird. Die meisten Beispiele in diesem Dokument prüfen nicht die Browserkompatibilität und zeigen auch keine Fehlermeldung für ältere Browser an. In echten Anwendungen wird bei alten oder inkompatiblen Browsern möglicherweise etwas Freundlicheres getan, aber solche Prüfungen werden weggelassen, um die Beispiele besser lesbar zu machen.

Bei komplexeren Anwendungen kommt es unweigerlich zu Inkonsistenzen zwischen Browsern und Plattformen. Websites wie quirksmode.org sind ebenfalls eine gute Quelle für Problemumgehungen.

XHTML und Quirks-Modus

Wir empfehlen, auf Seiten, die den Viewer enthalten, standardkonforme XHTML zu verwenden. Wenn Browser den XHTML-DOCTYPE oben auf der Seite sehen, rendern sie die Seite im „Standards Compliance Mode“. Dadurch werden Layout und Verhalten in verschiedenen Browsern besser vorhersehbar. Seiten ohne diese Definition werden möglicherweise im Quirks-Modus gerendert, was zu einem uneinheitlichen Layout führen kann.

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

Hinweis zu den Beispielen für die Embedded Viewer API

In den meisten Beispielen in dieser Dokumentation wird nur der relevante JavaScript-Code angezeigt, nicht die vollständige HTML-Datei. Sie können den JavaScript-Code in Ihre eigene Skelett-HTML-Datei einfügen oder die vollständige HTML-Datei für jedes Beispiel herunterladen, indem Sie auf den Link nach dem Beispiel klicken.

Fehlerbehebung

Wenn Ihr Code nicht zu funktionieren scheint, finden Sie hier einige Ansätze, die Ihnen bei der Lösung Ihrer Probleme helfen könnten: