Entwicklerhandbuch

Mit der Embedded Viewer API kannst du Buchinhalte von Google Books direkt in JavaScript in deine Webseiten einbetten. Das API bietet außerdem eine Reihe von Hilfsprogrammen zur Bearbeitung von Buchvorschauen und wird häufig zusammen mit den anderen auf dieser Website beschriebenen APIs verwendet.

Der Vorschauassistent ist ein auf der Embedded Viewer API basierendes Tool, mit dem Sie Ihrer Website Vorschaufunktionen hinzufügen können, indem Sie einfach ein paar Zeilen Code kopieren. Dieses Dokument richtet sich an fortgeschrittene Entwickler, die die Darstellung des Betrachters auf ihren Websites anpassen möchten.

Zielgruppe

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

Diese konzeptionelle Dokumentation ist nicht vollständig und umfassend. Sie soll Ihnen einen schnellen Einstieg in die Entwicklung und Entwicklung cooler Anwendungen mit der Embedded Viewer API ermöglichen. Fortgeschrittene Nutzer können die Referenz der Embedded Viewer API mit ausführlichen Informationen zu unterstützten Methoden und Antworten interessieren.

Wie oben erwähnt, sollten Anfänger mit dem Vorschauassistenten beginnen. Dabei wird automatisch der Code generiert, der zum Einbetten grundlegender Vorschauen auf Ihrer Website erforderlich ist.

„Hello World“ der Embedded Viewer API

Am einfachsten lernen Sie die Embedded Viewer API anhand eines einfachen Beispiels kennen. Auf der folgenden Webseite wird eine Vorschau von Mountain View (600 x 500) von Nicholas Perry, ISBN 0738531367 (Teil der Reihe "Images of America" von Arcadia Publishing) angezeigt:

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

Sie können sich dieses Beispiel ansehen und es herunterladen, um es zu bearbeiten und damit zu experimentieren. Auch für dieses einfache Beispiel müssen folgende fünf Schritte ausgeführt werden:

  1. Der API-Loader wird über ein script-Tag eingefügt.
  2. Wir erstellen ein div-Element namens „viewerCanvas“, in dem der Betrachter enthalten ist.
  3. Wir erstellen eine JavaScript-Funktion, um ein „Viewer“-Objekt zu erstellen.
  4. Das Buch wird mit seiner eindeutigen ID (in diesem Fall ISBN:0738531367) geladen.
  5. Wir verwenden google.books.setOnLoadCallback, um initialize aufzurufen, wenn die API vollständig geladen ist.

Diese Schritte werden nachfolgend erläutert.

Embedded Viewer API laden

Die Verwendung des API Loader-Frameworks zum Laden der Embedded Viewer API ist relativ einfach. Dazu sind zwei Schritte erforderlich:

  1. Fügen Sie die API-Loader-Bibliothek hinzu: 
    <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 list-Parameter, der eine Callback-Funktion oder -Sprache angibt, wie unten beschrieben. 
    <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, die 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 dem google.books.load-Aufruf einen optionalen language-Parameter hinzufügen.

So rufen Sie beispielsweise ein Buchvorschaumodul mit der Sprache der brasilianischen Portugiesische Benutzeroberfläche auf:

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

Beispiel ansehen (book-language.html)

Derzeit unterstützte RFC 3066-Sprachcodes sind 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, b, b, b, b, b, b, b

Wenn Sie die Embedded Viewer API in einer anderen Sprache als Englisch verwenden, empfehlen wir dringend, für die Seite den Header content-type auf utf-8 festzulegen oder ein entsprechendes <meta>-Tag in die Seite einzufügen. Dadurch werden Zeichen in allen Browsern richtig gerendert. 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 für das Buch reserviert werden. Dazu wird normalerweise ein benanntes div-Element erstellt und eine Referenz auf dieses Element im DOM (Document Object Model) des Browsers abgerufen.

Im Beispiel oben wird ein div mit dem Namen „viewerCanvas“ definiert und seine Größe mit Stilattributen festgelegt. Der Betrachter verwendet implizit die Größe des Containers, um seine Größe zu bestimmen.

Das DefaultViewer-Objekt

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

Die JavaScript-Klasse, mit der ein einzelner Betrachter auf der Seite erstellt und gesteuert wird, ist die Klasse DefaultViewer. Sie können mehrere Instanzen dieser Klasse erstellen – für jedes Objekt wird ein separater Viewer auf der Seite definiert. Mit dem JavaScript-Operator new wird eine neue Instanz dieser Klasse erstellt.

Wenn Sie eine neue Betrachterinstanz erstellen, geben Sie auf der Seite einen DOM-Knoten (normalerweise ein div-Element) als Container für den Betrachter an. HTML-Knoten sind untergeordnete Objekte des JavaScript-document-Objekts. Ein Verweis auf dieses Element wird über die Methode document.getElementById() abgerufen.

Dieser Code definiert eine Variable namens viewer und weist sie einem neuen DefaultViewer-Objekt zu. Die Funktion DefaultViewer() ist ein Konstruktor. Die Definition (zusammengefasst in der Referenzdokumentation für die Embedded Viewer API) lautet:

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

Beachten Sie, dass der zweite Parameter im Konstruktor optional ist und für erweiterte Implementierungen über den Umfang dieses Dokuments hinaus gedacht ist. Er wird im Beispiel „Hello World“ ausgelassen.

Betrachter mit einem bestimmten Buch initialisieren

  viewer.load('ISBN:0738531367');

Nachdem wir einen Viewer über den DefaultViewer-Konstruktor erstellt haben, muss er mit einem bestimmten Buch initialisiert werden. Diese Initialisierung erfolgt mithilfe der Methode load() des Betrachters. Die Methode load() erfordert einen identifier-Wert, der der API mitteilt, welches Buch angezeigt werden soll. Diese Methode muss gesendet werden, bevor andere Vorgänge für das Viewer-Objekt ausgeführt werden.

Wenn Sie mehrere IDs für ein Buch kennen – die ISBN für die Taschenbuchausgabe oder alternative OCLC-Nummern –, können Sie ein Array von ID-Strings als ersten Parameter an die Funktion load() übergeben. Der Betrachter rendert das Buch, wenn mit beliebigen Kennungen im Array eine einbettbare Vorschau verknüpft ist.

Unterstützte Buch-IDs

Wie die Funktion Dynamische Links unterstützt die Embedded Viewer API eine Reihe von Werten zur Identifizierung eines bestimmten Buches. Verfügbare Ausrichtungsmethoden:

ISBN
Die eindeutige 10- oder 13-stellige kommerzielle internationale Standardbuchnummer.
Beispiel: ISBN:0738531367
OCLC-Nummer
Die eindeutige Nummer, die einem Buch vom OCLC zugewiesen wird, wenn der Datensatz des Buchs dem Katalogisierungssystem WorldCat hinzugefügt wird.
Beispiel: OCLC:70850767
LCCN (LCN)
Die Library of Congress Control Number, die dem Datensatz von der Library of Congress zugewiesen ist.
Beispiel: LCCN:2006921508
ID des Google Books-Volumes
Der eindeutige String, den Google Books dem Band zugewiesen hat. Er wird in der URL des Buchs in Google Books angezeigt.
Beispiel: Py8u3Obs4f4C
Vorschau-URL für Google Books
Eine URL, über die eine Buchvorschauseite bei Google Books geöffnet werden kann.
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 mit dynamischen Links nur dann eine Vorschauschaltfläche rendern, wenn das Buch eingebettet werden kann. Wenn der Nutzer dann auf die Schaltfläche klickt, instanziieren Sie einen Betrachter mithilfe der Vorschau-URL, die vom Aufruf der dynamischen Links zurückgegeben wird. Ähnlich können Sie eine umfangreiche Anwendung zum Durchsuchen und Vorschauen mit der Books API erstellen, die mehrere geeignete Branchenkennungen in ihren Volumes-Feeds zurückgibt. Auf der Seite mit Beispielen finden Sie erweiterte Implementierungen.

Umgang mit fehlgeschlagenen Initialisierungen

In einigen Fällen schlägt der load-Aufruf fehl. Das passiert in der Regel, wenn die API ein Buch, das mit der angegebenen ID verknüpft ist, nicht finden konnte, wenn keine Vorschau des Buchs verfügbar ist, wenn die Buchvorschau nicht eingebettet werden kann oder wenn gebietsspezifische Einschränkungen verhindern, dass der Endnutzer dieses Buch sieht. Möglicherweise möchten Sie über einen solchen Fehler informiert werden, damit Ihr Code diese Bedingung problemlos verarbeiten kann. Aus diesem Grund können Sie mit der Funktion load einen optionalen zweiten Parameter, notFoundCallback, angeben, der angibt, welche Funktion aufgerufen werden soll, wenn das Buch nicht geladen werden konnte. Der folgende Code generiert beispielsweise ein JavaScript-Benachrichtigungsfeld, wenn das Buch eingebettet werden könnte:

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)

Mithilfe dieses Callbacks können Sie einen ähnlichen Fehler anzeigen oder das viewerCanvas-Element komplett ausblenden. Der Callback-Parameter für Fehler ist optional und nicht im Beispiel „Hello World“ enthalten.

Hinweis: Da Vorschauen möglicherweise nicht für alle Bücher und für alle Nutzer verfügbar sind, kann es hilfreich sein, zu wissen, ob eine Vorschau verfügbar ist, bevor Sie versuchen, eine Vorschau dafür zu laden. Sie möchten beispielsweise nur dann eine Schaltfläche, eine Seite oder einen Abschnitt der Google-Vorschau in Ihrer UI anzeigen, wenn dem Nutzer eine Vorschau zur Verfügung steht. Dazu können Sie die Books API oder die dynamischen Links nutzen, mit denen angegeben wird, ob ein Buch über den Viewer eingebettet werden kann.

Umgang mit erfolgreichen Initialisierungen

Es kann auch hilfreich sein zu wissen, ob und wann ein Buch erfolgreich geladen wurde. Aus diesem Grund unterstützt die Funktion load den optionalen Parameter successCallback, der ausgeführt wird, wenn das Buch vollständig geladen wurde.

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 Callback kann nützlich sein, wenn du bestimmte Elemente auf deiner Seite nur anzeigen möchtest, wenn der Betrachter vollständig gerendert hat.

Betrachter beim Laden anzeigen

  google.books.setOnLoadCallback(initialize);

Während eine HTML-Seite gerendert wird, wird das DOM (Document Object Model) umgesetzt und alle externen Bilder und Skripts werden empfangen und in das document-Objekt aufgenommen. Damit der Viewer nur auf der Seite platziert wird, nachdem die Seite vollständig geladen wurde, wird die Funktion google.books.setOnLoadCallback verwendet, um die Ausführung der Funktion, die das DefaultViewer-Objekt erstellt, zu verschieben. setOnLoadCallback ruft nur dann initialize auf, wenn die Embedded Viewer API geladen und einsatzbereit ist. Dadurch wird unvorhersehbares Verhalten vermieden und die Kontrolle darüber, wie und wann der Viewer gezeichnet wird, wird gewährleistet.

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

Nutzerinteraktionen

Da Sie jetzt ein DefaultViewer-Objekt haben, können Sie damit interagieren. Das einfache Betrachterobjekt ähnelt in seiner Darstellung und dem Verhalten des Betrachters, mit dem Sie auf der Google Books-Website interagieren, und bietet zahlreiche integrierte Verhaltensweisen.

Du kannst aber auch programmatisch mit dem Zuschauer interagieren. Das DefaultViewer-Objekt unterstützt eine Reihe von Methoden, mit denen der Vorschaustatus direkt geändert werden kann. Beispielsweise werden die Methoden zoomIn(), nextPage() und highlight() programmatisch und nicht durch Nutzerinteraktion im Viewer ausgeführt.

Im folgenden Beispiel wird eine Buchvorschau angezeigt, die automatisch alle drei Sekunden zur nächsten Seite wechselt. Wenn sich die nächste Seite im sichtbaren Bereich der Anzeige befindet, schwenkt der Nutzer gleichmäßig über die Seite. Andernfalls springt er direkt zur 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 (buch-animieren.html)

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

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

Programmierhinweise

Bevor Sie sich mit der Embedded Viewer API befassen, sollten Sie die folgenden Punkte beachten, damit Ihre Anwendung auf den vorgesehenen Plattformen reibungslos funktioniert.

Browserkompatibilität

Die Embedded Viewer API unterstützt aktuelle Versionen von Internet Explorer, Firefox und Safari sowie normalerweise 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 verhält sich nicht automatisch, wenn sie einen inkompatiblen Browser erkennt. Die meisten Beispiele in diesem Dokument prüfen nicht auf Browserkompatibilität und zeigen auch keine Fehlermeldung für ältere Browser an. Echte Anwendungen sind mit alten oder inkompatiblen Browsern vielleicht etwas nutzerfreundlicher. Diese Überprüfungen werden jedoch ausgelassen, um die Beispiele besser lesbar zu machen.

Nicht triviale Anwendungen werden zwangsläufig Inkonsistenzen zwischen Browsern und Plattformen feststellen. Websites wie quirksmode.org sind ebenfalls gute Ressourcen für die Problemumgehung.

XHTML- und Quirks-Modus

Wir empfehlen, auf Seiten, die den Viewer enthalten, standardkonformes XHTML zu verwenden. Wenn Browser den XHTML-Code DOCTYPE oben auf der Seite sehen, rendern sie die Seite im „Standards Compliance Mode“, was das Layout und Verhalten in allen Browsern vorhersagbarer macht. Seiten ohne diese Definition werden möglicherweise im Quirks-Modus gerendert, was zu einem inkonsistenten 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

Beachten Sie, dass die meisten Beispiele in dieser Dokumentation nur relevanten JavaScript-Code und nicht die vollständige HTML-Datei enthalten. Sie können den JavaScript-Code in Ihre eigene HTML-Dateidatei 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 funktioniert, können Sie die folgenden Lösungsansätze ausprobieren: