Panduan Developer

Embedded Viewer API memungkinkan Anda menyematkan konten buku dari Google Buku langsung di halaman web dengan JavaScript. API ini juga menyediakan sejumlah utilitas untuk memanipulasi pratinjau buku, dan sering digunakan bersama dengan API lain yang dijelaskan di situs ini.

Pratinjau Wizard adalah alat yang dibuat di atas Embedded Viewer API yang memudahkan penambahan kemampuan pratinjau ke situs Anda hanya dengan menyalin beberapa baris kode. Dokumen ini ditujukan untuk developer tingkat lanjut yang ingin menyesuaikan tampilan penampil di situs mereka.

Audiens

Dokumentasi ini didesain untuk orang yang memahami pemrograman JavaScript dan konsep pemrograman berorientasi objek. Anda juga harus memahami Google Buku dari sudut pandang pengguna. Ada banyak tutorial JavaScript yang tersedia di Web.

Dokumentasi konseptual ini tidak lengkap dan menyeluruh; dokumentasi ini dirancang agar Anda dapat dengan cepat mulai menjelajahi dan mengembangkan aplikasi keren dengan Embedded Viewer API. Pengguna tingkat lanjut mungkin tertarik dengan Referensi Embedded Viewer API, yang memberikan detail komprehensif tentang metode dan respons yang didukung.

Seperti yang ditunjukkan di atas, pemula dapat memulai dengan Wizard Pratinjau, yang otomatis membuat kode yang diperlukan untuk menyematkan pratinjau dasar di situs Anda.

"Hello, World" dari Embedded Viewer API

Cara termudah untuk mulai mempelajari Embedded Viewer API adalah melihat contoh sederhana. Halaman web berikut menampilkan pratinjau 600x500 dari Mountain View, oleh Nicholas Perry, ISBN 0738531367 (bagian dari seri "Images of America" 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>

Anda dapat melihat contoh ini dan mendownloadnya untuk mengedit dan memainkannya. Bahkan dalam contoh sederhana ini, ada lima hal yang perlu diperhatikan:

  1. Kami menyertakan Loader API menggunakan tag script.
  2. Kita membuat elemen div bernama "viewerCanvas" untuk menyimpan penampil.
  3. Kita menulis fungsi JavaScript untuk membuat objek "pelihat".
  4. Kita memuat buku menggunakan ID uniknya (dalam hal ini ISBN:0738531367).
  5. Kita menggunakan google.books.setOnLoadCallback untuk memanggil initialize saat API telah dimuat sepenuhnya.

Langkah-langkah ini dijelaskan di bawah.

Memuat Embedded Viewer API

Menggunakan framework API Loader untuk memuat Embedded Viewer API relatif sederhana. Hal ini melibatkan dua langkah berikut:

  1. Sertakan library API Loader: 
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
  2. Panggil metode google.books.load. Metode google.books.load menggunakan parameter daftar opsional yang menentukan fungsi atau bahasa callback, seperti yang dijelaskan di bawah. 
    <script type="text/javascript">
  google.books.load();
</script>

Memuat Embedded Viewer API versi yang dilokalkan

Embedded Viewer API menggunakan bahasa Inggris secara default saat menampilkan informasi tekstual seperti tooltip, nama untuk kontrol, dan teks link. Jika ingin mengubah Embedded Viewer API untuk menampilkan informasi dengan benar dalam bahasa tertentu, Anda dapat menambahkan parameter language opsional ke panggilan google.books.load.

Misalnya, untuk menampilkan modul pratinjau buku dengan bahasa antarmuka Portugis Brasil:

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

Lihat contoh (book-language.html)

Kode bahasa RFC 3066 yang didukung saat ini mencakup 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, dan vi.

Saat menggunakan Embedded Viewer API dalam bahasa selain bahasa Inggris, sebaiknya tayangkan halaman Anda dengan header content-type yang ditetapkan ke utf-8, atau sertakan tag <meta> yang setara di halaman Anda. Tindakan ini membantu memastikan bahwa karakter dirender dengan benar di semua browser. Untuk informasi selengkapnya, lihat halaman W3C tentang menetapkan parameter set karakter HTTP.

Elemen DOM pelihat

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

Agar buku ditampilkan di halaman web, Anda harus menentukan tempat untuk menampilkannya. Biasanya, hal ini dilakukan dengan membuat elemen div bernama dan mendapatkan referensi ke elemen ini dalam model objek dokumen (DOM) browser.

Contoh di atas menentukan div bernama "viewerCanvas" dan menetapkan ukurannya menggunakan atribut gaya. Pelihat secara implisit menggunakan ukuran penampung untuk menyesuaikan ukurannya sendiri.

Objek DefaultViewer

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

Class JavaScript yang membuat dan mengontrol satu penampil di halaman adalah class DefaultViewer. (Anda dapat membuat lebih dari satu instance class ini - setiap objek akan menentukan penampil terpisah di halaman.) Instance baru dari class ini dibuat menggunakan operator new JavaScript.

Saat membuat instance penampil baru, Anda menentukan node DOM di halaman (biasanya elemen div) sebagai penampung untuk penampil. Node HTML adalah turunan dari objek document JavaScript, dan referensi ke elemen ini diperoleh melalui metode document.getElementById().

Kode ini menentukan variabel (bernama viewer) dan menetapkan variabel tersebut ke objek DefaultViewer baru. Fungsi DefaultViewer() dikenal sebagai constructor dan definisinya (dipadatkan untuk kejelasan dari Referensi API Pelihat Tersemat) ditampilkan di bawah ini:

Konstruktor Deskripsi
DefaultViewer(container, opts?) Membuat penampil baru di dalam container HTML yang diberikan, yang harus berupa elemen tingkat blok di halaman (biasanya DIV). Opsi lanjutan diteruskan menggunakan parameter opts opsional.

Perhatikan bahwa parameter kedua dalam konstruktor bersifat opsional—ditujukan untuk implementasi lanjutan di luar cakupan dokumen ini—dan parameter ini dihilangkan dari contoh "Hello, World".

Melakukan inisialisasi penampil dengan buku tertentu

  viewer.load('ISBN:0738531367');

Setelah membuat penampil melalui konstruktor DefaultViewer, penampil perlu diinisialisasi dengan buku tertentu. Inisialisasi ini dilakukan dengan menggunakan metode load() penampil. Metode load() memerlukan nilai identifier, yang memberi tahu API buku yang akan ditampilkan. Metode ini harus dikirim sebelum operasi lainnya dilakukan pada objek penampil.

Jika Anda mengetahui beberapa ID untuk buku—ISBN untuk edisi paperback, atau nomor OCLC alternatif—Anda dapat meneruskan array string ID sebagai parameter pertama ke fungsi load(). Pembaca akan merender buku jika ada pratinjau yang dapat disematkan yang terkait dengan apa pun ID dalam array.

ID buku yang didukung

Seperti fitur Dynamic Links, Embedded Viewer API mendukung sejumlah nilai untuk mengidentifikasi buku tertentu. Ini mencakup:

ISBN
International Standard Book Number komersial 10 atau 13 digit yang unik.
Contoh: ISBN:0738531367
Nomor OCLC
Nomor unik yang ditetapkan ke buku oleh OCLC saat data buku ditambahkan ke sistem pengindeksan WorldCat.
Contoh: OCLC:70850767
LCCN
Nomor Kontrol Perpustakaan Kongres yang ditetapkan ke data oleh Perpustakaan Kongres.
Contoh: LCCN:2006921508
ID volume Google Buku
String unik yang ditetapkan Google Buku ke volume, yang muncul di URL buku di Google Buku.
Contoh: Py8u3Obs4f4C
URL pratinjau Google Buku
URL yang membuka halaman pratinjau buku di Google Buku.
Contoh: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

ID ini sering digunakan dengan API lain dalam Google Books API Family. Misalnya, Anda dapat menggunakan Dynamic Links untuk merender tombol pratinjau hanya jika buku dapat disematkan—lalu, saat pengguna mengklik tombol, buat instance penampil menggunakan URL pratinjau yang ditampilkan oleh panggilan Dynamic Links. Demikian pula, Anda dapat membuat aplikasi penjelajahan dan pratinjau yang kaya dengan Books API, yang menampilkan beberapa ID industri yang sesuai di feed Volume-nya. Kunjungi halaman contoh untuk melihat beberapa implementasi lanjutan.

Menangani inisialisasi yang gagal

Dalam beberapa kasus, panggilan load mungkin gagal. Biasanya hal ini terjadi saat API tidak dapat menemukan buku yang terkait dengan ID yang diberikan, saat tidak ada pratinjau buku yang tersedia, saat pratinjau buku tidak dapat disematkan, atau saat batasan teritorial mencegah pengguna akhir melihat buku tertentu ini. Anda mungkin ingin diberi tahu tentang kegagalan tersebut, sehingga kode Anda dapat menangani kondisi ini dengan baik. Karena alasan ini, fungsi load memungkinkan Anda meneruskan parameter kedua opsional, notFoundCallback, yang menunjukkan fungsi yang harus dipanggil jika buku tidak dapat dimuat. Misalnya, kode berikut akan menghasilkan kotak "notifikasi" JavaScript jika buku dapat disematkan:

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

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

Lihat contoh (book-notfound.html)

Dengan menggunakan callback ini, Anda dapat memutuskan untuk menampilkan error serupa, atau Anda dapat memilih untuk menyembunyikan elemen viewerCanvas sepenuhnya. Parameter callback kegagalan bersifat opsional, dan tidak disertakan dalam contoh "Hello World".

Catatan: Karena pratinjau mungkin tidak tersedia untuk semua buku dan untuk semua pengguna, sebaiknya ketahui apakah pratinjau tersedia sebelum Anda mencoba memuat penampil untuknya. Misalnya, Anda dapat menampilkan tombol, halaman, atau bagian "Pratinjau Google" di UI hanya jika pratinjau benar-benar akan tersedia untuk pengguna. Anda dapat melakukannya menggunakan Books API atau Dynamic Links, yang keduanya melaporkan apakah buku akan tersedia untuk disematkan menggunakan penampil.

Menangani inisialisasi yang berhasil

Mungkin juga berguna untuk mengetahui apakah buku berhasil dimuat dan kapan. Oleh karena itu, fungsi load mendukung parameter ketiga opsional, successCallback, yang akan dieksekusi jika dan saat buku selesai dimuat.

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

Lihat contoh (book-Success.html)

Callback ini mungkin berguna, misalnya, jika Anda hanya ingin menampilkan elemen tertentu pada halaman jika penampil telah dirender sepenuhnya.

Menampilkan penampil saat pemuatan

  google.books.setOnLoadCallback(initialize);

Saat halaman HTML dirender, model objek dokumen (DOM) akan dibuat, dan gambar serta skrip eksternal apa pun diterima dan digabungkan ke dalam objek document. Untuk memastikan bahwa penampil hanya ditempatkan di halaman setelah halaman tersebut dimuat sepenuhnya, fungsi google.books.setOnLoadCallback digunakan untuk menunda eksekusi fungsi yang membuat objek DefaultViewer. Karena setOnLoadCallback hanya akan memanggil initialize saat Embedded Viewer API dimuat dan siap digunakan, hal ini akan menghindari perilaku yang tidak dapat diprediksi dan memastikan kontrol atas cara dan waktu penampil digambar.

Catatan: Untuk memaksimalkan kompatibilitas lintas browser, sebaiknya jadwalkan pemuatan penampil menggunakan fungsi google.books.setOnLoadCallback, bukan menggunakan peristiwa onLoad pada tag <body>.

Interaksi penonton

Setelah memiliki objek DefaultViewer, Anda dapat berinteraksi dengannya. Objek penampil dasar terlihat dan berperilaku sangat mirip dengan penampil yang berinteraksi dengan Anda di situs Google Buku dan memiliki banyak perilaku bawaan.

Namun, Anda juga dapat berinteraksi dengan penampil secara terprogram. Objek DefaultViewer mendukung sejumlah metode yang mengubah status pratinjau secara langsung. Misalnya, metode zoomIn(), nextPage(), dan highlight() beroperasi pada penampil secara terprogram, bukan melalui interaksi pengguna.

Contoh berikut menampilkan pratinjau buku yang otomatis "beralih" ke halaman berikutnya setiap 3 detik. Jika halaman berikutnya berada di bagian penampil yang terlihat, penampil akan bergeser dengan lancar ke halaman tersebut; jika tidak, penampil akan langsung berpindah ke bagian atas halaman berikutnya.

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

Lihat contoh (book-animate.html)

Perhatikan bahwa panggilan terprogram ke penampil akan gagal atau tidak berpengaruh hingga pemirsa sepenuhnya diinisialisasi dengan buku tertentu. Untuk memastikan Anda hanya memanggil fungsi tersebut saat penampil siap, gunakan parameter successCallback ke viewer.load seperti yang dijelaskan di atas.

Untuk mendapatkan informasi tentang semua fungsi yang didukung oleh objek DefaultViewer, lihat Panduan Referensi.

Catatan pemrograman

Sebelum mulai mempelajari Embedded Viewer API, Anda harus memperhatikan perhatian berikut untuk memastikan aplikasi Anda berfungsi dengan lancar di seluruh platform yang diinginkan.

Kompatibilitas browser

Embedded Viewer API mendukung versi terbaru Internet Explorer, Firefox, dan Safari—dan biasanya browser berbasis Gecko dan WebKit lainnya seperti Camino dan Google Chrome.

Aplikasi yang berbeda terkadang memerlukan perilaku yang berbeda pula bagi pengguna dengan browser yang tidak kompatibel. Embedded Viewer API tidak memiliki perilaku otomatis apa pun saat mendeteksi browser yang tidak kompatibel. Sebagian besar contoh dalam dokumen ini tidak memeriksa kompatibilitas Browser, dan juga tidak menampilkan pesan error untuk browser lama. Aplikasi sebenarnya mungkin melakukan sesuatu yang lebih mudah digunakan dengan browser lama atau yang tidak kompatibel, tetapi pemeriksaan tersebut dihilangkan untuk membuat contoh lebih mudah dibaca.

Aplikasi non-trivial pasti akan mengalami inkonsistensi antara browser dan platform. Situs seperti quirksmode.org juga merupakan referensi yang bagus untuk menemukan solusi.

XHTML dan quirks mode

Sebaiknya gunakan XHTML yang sesuai standar di halaman yang berisi penampil. Saat melihat DOCTYPE XHTML di bagian atas halaman, browser akan merender halaman dalam "mode kepatuhan standar", yang membuat tata letak dan perilaku jauh lebih dapat diprediksi di seluruh browser. Halaman tanpa definisi tersebut dapat dirender dalam "quirks mode", yang dapat menyebabkan tata letak yang tidak konsisten.

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

Catatan tentang contoh Embedded Viewer API

Perlu diketahui bahwa sebagian besar contoh dalam dokumentasi ini hanya menampilkan kode JavaScript yang relevan, bukan file HTML lengkap. Anda dapat memasukkan kode JavaScript ke dalam file HTML kerangka Anda sendiri, atau Anda dapat mendownload file HTML lengkap untuk setiap contoh dengan mengklik link setelah contoh.

Pemecahan masalah

Jika kode Anda tampaknya tidak berfungsi, berikut beberapa pendekatan yang dapat membantu Anda menyelesaikan masalah: