Przewodnik dla programistów

Interfejs Embedded Viewer API umożliwia umieszczanie treści książki z Książek Google bezpośrednio na stronach internetowych za pomocą JavaScriptu. Interfejs API udostępnia też wiele narzędzi do manipulowania podglądami książek i jest często używany razem z innymi interfejsami API opisanymi na tej stronie.

Kreator podglądu to narzędzie oparte na interfejsie Embedded Viewer API, które ułatwia dodawanie do witryny funkcji podglądu. Wystarczy skopiować kilka linii kodu. Ten dokument jest przeznaczony dla zaawansowanych programistów, którzy chcą dostosować sposób wyświetlania odtwarzacza w swoich witrynach.

Odbiorcy

Ta dokumentacja jest przeznaczona dla osób, które znają programowanie w JavaScript i pojęcia związane z programowaniem obiektowym. Musisz też znać Książki Google z perspektywy użytkownika. W internecie dostępnych jest wiele samouczków na temat JavaScriptu.

Ta dokumentacja koncepcyjna nie jest kompletna ani wyczerpująca. Została zaprojektowana, by umożliwić szybkie rozpoczęcie odkrywania i tworzenia ciekawych aplikacji za pomocą interfejsu Embedded Wyświetlający API. Zaawansowani użytkownicy mogą zapoznać się z dokumentacją Embedded Viewer API, która zawiera obszerne informacje o obsługiwanych metodach i odpowiedziach.

Jak już wspomnieliśmy, początkujący użytkownicy mogą zacząć od Kreatora podglądu, który automatycznie generuje kod potrzebny do umieszczenia podstawowych podglądów w witrynie.

„Hello, World” interfejsu Embedded Wyświetlający API

Najłatwiejszym sposobem na zapoznanie się z interfejsem Embedded Viewer API jest obejrzenie prostego przykładu. Ta strona zawiera podgląd filmu Mountain View w formacie 600 x 500 autorstwa Nicholasa Perry'ego, numer ISBN 0738531367 (część serii „Images of America” firmy 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>

Możesz zapoznać się z tym przykładem i pobrać go, aby go edytować i przetestować. Nawet w tym prostym przykładzie należy zwrócić uwagę na 5 rzeczy:

  1. Ładowarka interfejsu API jest dołączana za pomocą tagu script.
  2. Tworzymy element div o nazwie „viewerCanvas”, aby przechowywać odtwarzacz.
  3. Napiszemy funkcję JavaScript, która utworzy obiekt „viewer”.
  4. Ładujemy książkę za pomocą jej unikalnego identyfikatora (w tym przypadku ISBN:0738531367).
  5. Gdy interfejs API zostanie w pełni załadowany, używamy wywołania google.books.setOnLoadCallback do wywołania initialize.

Poniżej omawiamy te etapy.

Wczytywanie interfejsu Embedded Viewer API

Ładowanie interfejsu Embedded Viewer API za pomocą platformy API Loader jest stosunkowo proste. Polega ona na wykonaniu tych 2 czynności:

  1. Uwzględnij bibliotekę API Loader: 
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
  2. Wywołaj metodę google.books.load. Metoda google.books.load wykorzystuje opcjonalny parametr listy, który określa funkcję lub język wywołania zwrotnego, jak wyjaśniono poniżej. 
    <script type="text/javascript">
  google.books.load();
</script>

Wczytywanie zlokalizowanej wersji interfejsu Embedded Viewer API

Domyślnie interfejs Embedded Viewer API wyświetla informacje tekstowe, takie jak teksty narzędziowe, nazwy elementów sterujących i tekst linków, w języku angielskim. Jeśli chcesz zmienić interfejs Embedded Viewer API, aby wyświetlał informacje w określonym języku, możesz dodać opcjonalny parametr language do wywołania google.books.load.

Aby na przykład wyświetlić moduł podglądu książki w języku portugalskim (Brazylia):

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

Przykład (book-language.html)

Obecnie obsługiwane kody języków RFC 3066 to 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 i vi.

Jeśli używasz interfejsu Embedded Viewer API w językach innych niż angielski, zdecydowanie zalecamy wyświetlanie strony z nagłówkiem content-type ustawionym na utf-8 lub dodanie na stronie tagu <meta>. Dzięki temu znaki będą renderowane prawidłowo we wszystkich przeglądarkach. Więcej informacji znajdziesz na stronie W3C poświęconej konfigurowaniu parametru kodowania znaków HTTP.

Elementy DOM widza

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

Aby książka wyświetlała się na stronie internetowej, należy zarezerwować dla niej miejsce. Zwykle odbywa się to przez utworzenie elementu o nazwie div i uzyskanie odwołania do tego elementu w modelu obiektów dokumentu (DOM) przeglądarki.

W przykładzie powyżej zdefiniowano element div o nazwie „viewerCanvas” i ustawiono jego rozmiar za pomocą atrybutów stylu. Wyświetlający domyślnie ustala rozmiar kontenera na podstawie jego rozmiaru.

Obiekt DefaultViewer

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

Klasa JavaScript, która tworzy i kontroluje pojedynczego widza na stronie, to klasa DefaultViewer. (możesz utworzyć więcej niż 1 instancję tej klasy – każdy obiekt będzie definiować na stronie osobny odtwarzacz). Nowa instancja tej klasy jest tworzona przy użyciu operatora JavaScript new.

Podczas tworzenia nowej instancji odtwarzacza określasz węzeł DOM na stronie (zazwyczaj element div) jako kontener dla odtwarzacza. Węzły HTML są elementami podrzędnymi obiektu JavaScript document, a odniesienie do tego elementu uzyskujemy za pomocą metody document.getElementById().

Ten kod definiuje zmienną (o nazwie viewer) i przypisuje ją do nowego obiektu DefaultViewer. Funkcja DefaultViewer() jest nazywana constructor, a jej definicja (skrócona w celu uniknięcia wątpliwości w dokumentacji interfejsu Embedded Wyświetlający API) została przedstawiona poniżej:

Zespół Opis
DefaultViewer(container, opts?) Tworzy nowy widok w danym elemencie HTML container, który powinien być elementem na poziomie bloku na stronie (zazwyczaj jest to element DIV). Opcje zaawansowane są przekazywane za pomocą opcjonalnego parametru opts.

Pamiętaj, że drugi parametr w konstruktorze jest opcjonalny – przeznaczony dla zaawansowanych implementacji wykraczających poza zakres tego dokumentu – i jest pomijany w przykładzie „Hello, World”.

Inicjowanie odtwarzacza z konkretną książką

  viewer.load('ISBN:0738531367');

Po utworzeniu przeglądarki za pomocą konstruktora DefaultViewer należy ją zainicjować z konkretną książką. Ta inicjalizacja jest wykonywana za pomocą metody load() odbiorcy. Metoda load() wymaga wartości identifier, która informuje interfejs API, jaka książka ma się wyświetlić. Ta metoda musi zostać wysłana przed wykonaniem jakichkolwiek innych operacji na obiekcie wyświetlającego.

Jeśli znasz kilka identyfikatorów książki (numer ISBN wydania w miękkiej oprawie lub inne numery OCLC), możesz przekazać tablicę ciągów znaków identyfikatorów jako pierwszy parametr funkcji load(). Odtwarzanie książki rozpocznie się, jeśli w tablicy jest widoczny wbudowany podgląd powiązany z dowolnym z identyfikatorów.

Obsługiwane identyfikatory książek

Podobnie jak funkcja Dynamic Links interfejs Embedded Viewer API obsługuje wiele wartości służących do identyfikacji konkretnej książki. Obejmują one:

ISBN
Unikalny 10- lub 13-cyfrowy numer międzynarodowego znormalizowanego numeru książki.
Przykład: ISBN:0738531367
Numer OCLC
Unikalny numer przypisany do książki przez OCLC, gdy jej rekord jest dodawany do systemu katalogowania WorldCat.
Przykład: OCLC:70850767
LCCN
Numer kontrolny Library of Congress przypisany do rekordu przez Bibliotekę Kongresu.
Przykład: LCCN:2006921508
Identyfikator woluminu w Książkach Google
Niepowtarzalny ciąg znaków przypisany przez Książki Google do woluminu, który pojawia się w adresie URL książki w Książkach Google.
Przykład: Py8u3Obs4f4C
Adres URL podglądu w Książkach Google
Adres URL, który otwiera stronę podglądu książki w Książkach Google.
Przykład: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

Te identyfikatory są często używane z innymi interfejsami API z rodziny interfejsu Google Books API. Możesz na przykład użyć linków dynamicznych, aby renderować przycisk podglądu tylko wtedy, gdy książkę można osadzić, a gdy użytkownik kliknie przycisk, utworzyć instancję odtwarzacza za pomocą adresu URL podglądu zwróconego przez wywołanie linku dynamicznego. W podobny sposób można utworzyć zaawansowaną aplikację do przeglądania i wyświetlania podglądu za pomocą interfejsu Books API, który zwraca kilka odpowiednich identyfikatorów branży w plikach danych woluminów. Zaawansowane implementacje znajdziesz na stronie przykładów.

Obsługa nieudanych inicjalizacji

W niektórych przypadkach wywołanie load może się nie udać. Zwykle dzieje się tak, gdy interfejs API nie może znaleźć książki powiązanej z podanym identyfikatorem, nie jest dostępny podgląd książki, gdy nie można umieścić podglądu książki lub gdy ograniczenia regionalne uniemożliwiają użytkownikowi wyświetlenie danej książki. Możesz chcieć otrzymywać alerty o takim błędzie, aby Twój kod mógł odpowiednio zareagować na tę sytuację. Z tego powodu funkcja load umożliwia przekazanie opcjonalnego drugiego parametru notFoundCallback, który wskazuje, jaką funkcję należy wywołać, jeśli nie uda się załadować książki. Na przykład poniższy kod wygeneruje pole „alert” JavaScript, jeśli książkę będzie można umieścić:

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

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

Przykład (book-notfound.html)

Za pomocą tej funkcji możesz wyświetlić podobny błąd lub całkowicie ukryć element viewerCanvas. Parametr funkcji wywołania zwrotnego w przypadku błędu jest opcjonalny i nie jest uwzględniony w przykładowym kodzie „Hello World”.

Uwaga: podglądy mogą nie być dostępne w przypadku niektórych książek i użytkowników, dlatego warto sprawdzić, czy podgląd jest dostępny, zanim spróbujesz go otworzyć. Możesz na przykład wyświetlać przycisk, stronę lub sekcję „Podgląd Google” w interfejsie tylko wtedy, gdy użytkownik będzie mógł zobaczyć podgląd. Możesz to zrobić za pomocą Books API lub Dynamic Links. Oba te interfejsy API podają, czy książka będzie dostępna do osadzenia w czytniku.

Przetwarzanie pomyślnie zainicjowanych procesów

Przydatne mogą być też informacje o tym, czy i kiedy książka została wczytana. Z tego powodu funkcja load obsługuje opcjonalny trzeci parametr successCallback, który zostanie wykonany, gdy wczytanie książki się zakończy.

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

Przykład (book-success.html)

Ta funkcja może być przydatna, jeśli na przykład chcesz wyświetlać określone elementy strony tylko wtedy, gdy widzowie mają w pełni renderowany obraz.

Wyświetlanie przeglądarki po załadowaniu

  google.books.setOnLoadCallback(initialize);

Podczas renderowania strony HTML tworzony jest model obiektu dokumentu (DOM), a wszystkie zewnętrzne obrazy i skrypty są odbierane i włączane do obiektu document. Aby mieć pewność, że nasz widok zostanie umieszczony na stronie dopiero po jej pełnym załadowaniu, używamy funkcji google.books.setOnLoadCallback, która opóźnia wykonanie funkcji tworzącej obiekt DefaultViewer. Funkcja setOnLoadCallback wywołuje funkcję initialize tylko wtedy, gdy interfejs Embedded Viewer API jest załadowany i gotowy do użycia. Dzięki temu unikniesz nieprzewidywalnego zachowania i zyskasz kontrolę nad tym, jak i kiedy przeglądarka jest rysowana.

Uwaga: aby zapewnić maksymalną zgodność z różnymi przeglądarkami, zdecydowanie zalecamy zaplanowanie wczytania odtwarzacza za pomocą funkcji google.books.setOnLoadCallback zamiast korzystania ze zdarzenia onLoad w tagu <body>.

Interakcje widzów

Teraz, gdy masz obiekt DefaultViewer, możesz z nim wchodzić w interakcje. Podstawowy obiekt przeglądarki wygląda i działa podobnie do przeglądarki, z którą użytkownicy wchodzą w interakcje na stronie Książek Google. Zawiera on wiele wbudowanych zachowań.

Możesz też wchodzić w interakcje z widzem za pomocą kodu. Obiekt DefaultViewer obsługuje kilka metod, które bezpośrednio zmieniają stan podglądu. Na przykład metody zoomIn(), nextPage() i highlight() działają na odtwarzaczu programowo, a nie przez interakcję z użytkownikiem.

Przykład poniżej przedstawia podgląd książki, który co 3 sekundy automatycznie „przewraca” na następną stronę. Jeśli następna strona jest widoczna w przeglądarce, przewijanie odbywa się płynnie. W przeciwnym razie przewijanie odbywa się bezpośrednio do góry następnej strony.

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

Przykład (book-animate.html)

Pamiętaj, że wywołania programowe dotyczące wyświetlacza nie będą działać lub nie będą miały żadnego efektu, dopóki wyświetlacz nie zostanie w pełni zainicjowany za pomocą danej książki. Aby mieć pewność, że takie funkcje są wywoływane tylko wtedy, gdy widz jest gotowy, ustaw parametr successCallback na viewer.load, jak omówiono powyżej.

Informacje o wszystkich funkcjach obsługiwanych przez obiekt DefaultViewer znajdziesz w przewodniku.

Uwagi dotyczące programowania

Zanim zaczniesz korzystać z interfejsu Embedded Viewer API, zapoznaj się z tymi informacjami, aby mieć pewność, że aplikacja będzie płynnie działać na wszystkich platformach, na których ma być dostępna.

Zgodność z przeglądarką

Interfejs Embedded Viewer API obsługuje najnowsze wersje przeglądarek Internet Explorer, Firefox i Safari, a także zwykle inne przeglądarki oparte na Gecko i WebKit, takie jak Camino i Google Chrome.

W przypadku niektórych aplikacji użytkownicy korzystający z nieobsługiwanych przeglądarek muszą czasem postępować w inny sposób. Interfejs Embedded Wyświetlający API nie działa automatycznie po wykryciu niezgodnej przeglądarki. Większość przykładów w tym dokumencie nie sprawdza zgodności z przeglądarką ani nie wyświetla komunikatu o błędzie w przypadku starszych przeglądarek. Prawdziwe aplikacje mogą działać w bardziej przyjazny sposób w starszych lub niezgodnych przeglądarkach, ale pomijamy takie kontrole, aby przykłady były czytelniejsze.

W przypadku bardziej skomplikowanych aplikacji nieuniknione są niespójności między przeglądarkami i platformami. Warto też zajrzeć na strony takie jak quirksmode.org, aby znaleźć obejście problemu.

Tryb XHTML i tryb osobliwości

Na stronach zawierających przeglądarkę zalecamy używanie zgodnego ze standardami języka XHTML. Gdy przeglądarki widzą kod XHTML DOCTYPE u góry strony, renderują stronę w „standardowym trybie zgodności”, co sprawia, że układ i działanie są znacznie bardziej przewidywalne w różnych przeglądarkach. Strony bez takiej definicji mogą być renderowane w „trybie osobliwości”, co może prowadzić do niespójnego układu.

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

Uwaga na temat przykładów interfejsu Embedded Wyświetlający API

Pamiętaj, że większość przykładów w tej dokumentacji zawiera tylko odpowiedni kod JavaScriptu, a nie cały plik HTML. Możesz umieścić kod JavaScript we własnym szkieletowym pliku HTML lub pobrać pełny plik HTML z każdego przykładu, klikając link za przykładem.

Rozwiązywanie problemów

Jeśli kod nie działa, wypróbuj te rozwiązania: