Panduan Developer

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

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

Penonton

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 lengkap; dokumentasi ini dirancang untuk memungkinkan Anda secara cepat memulai dan mengembangkan aplikasi keren dengan Embedded Viewer API. Pengguna tingkat lanjut mungkin tertarik dengan Referensi Penampil Viewer API, yang memberikan detail lengkap tentang metode dan respons yang didukung.

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

"Halo, Dunia" dari Embedded Viewer API

Cara termudah untuk mulai mempelajari Embedded Viewer API adalah dengan melihat contoh sederhana. Halaman web berikut menampilkan pratinjau 600x500 dari Mountain View, oleh Nicholas Perry, ISBN 0738531367 (bagian dari seri "Images of America" dari 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 bermain-main dengannya. Bahkan dalam contoh sederhana ini, ada lima hal yang perlu diperhatikan:

  1. Kami menyertakan API Loader menggunakan tag script.
  2. Kita membuat elemen div bernama "viewerKanvas" untuk menyimpan penampil.
  3. Kita menulis fungsi JavaScript untuk membuat objek "viewer".
  4. Kami memuat buku menggunakan ID uniknya (dalam hal ini ISBN:0738531367).
  5. Kita menggunakan google.books.setOnLoadCallback untuk memanggil initialize ketika 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 mengambil parameter daftar opsional yang menentukan fungsi atau bahasa callback, seperti yang dijelaskan di bawah. 
    <script type="text/javascript">
  google.books.load();
</script>

Memuat versi lokal Embedded Viewer API

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 dalam bahasa tertentu dengan benar, 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 saat ini didukung 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, dd, bl, ms, no, bls, ru, ms, tidak, mis, ras, no, bls, md, sr, pp, str, ms, tru, sk, no, dd, ms, tidak, ru, thr, SMS, mis.

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 akan membantu memastikan bahwa karakter dirender dengan benar di semua browser. Untuk informasi selengkapnya, lihat halaman W3C tentang menyetel parameter charset HTTP.

Elemen DOM pengakses lihat-saja

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

Agar buku ditampilkan pada halaman web, seseorang harus memesan tempatnya. Umumnya, ini dilakukan dengan membuat elemen div bernama dan mendapatkan referensi ke elemen ini dalam document object model (DOM) browser.

Contoh di atas menentukan div bernama "viewerKanvas" dan menetapkan ukurannya menggunakan atribut gaya. Penampil 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 pelihat pada halaman tersebut adalah class DefaultViewer. (Anda bisa membuat lebih dari satu instance class ini - setiap objek akan menentukan penampil terpisah pada 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 pelihat. Node HTML adalah turunan dari objek document JavaScript, dan kita mendapatkan referensi ke elemen ini melalui metode document.getElementById().

Kode ini menentukan variabel (bernama viewer) dan menetapkan variabel tersebut ke objek DefaultViewer baru. Fungsi DefaultViewer() dikenal sebagai konstruktor dan definisinya (diringkas agar lebih jelas dari Referensi Embedded Viewer API) ditampilkan di bawah ini:

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

Perlu diketahui bahwa parameter kedua di konstruktor bersifat opsional—ditujukan untuk penerapan lanjutan di luar cakupan dokumen ini—dan dihilangkan dari contoh "Halo, Dunia".

Menginisialisasi audiens dengan buku tertentu

  viewer.load('ISBN:0738531367');

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

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

ID buku yang didukung

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

ISBN
Nomor Buku Standar Internasional 10 atau 13 digit yang unik.
Contoh: ISBN:0738531367
Nomor OCLC
Nomor unik yang ditetapkan untuk buku oleh OCLC saat catatan buku ditambahkan ke sistem katalog WorldCat.
Contoh: OCLC:70850767
LCCN
Nomor Kontrol Perpustakaan Kongres yang ditetapkan ke catatan oleh Perpustakaan Kongres.
Contoh: LCCN:2006921508
ID volume Google Buku
String unik yang telah ditetapkan Google Buku untuk volume, yang muncul di URL untuk 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 Keluarga API Google Buku. 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 jelajah dan pratinjau yang kaya dengan Books API, yang menampilkan beberapa ID industri yang sesuai dalam feed Volume. Buka halaman contoh untuk melihat beberapa penerapan lanjutan.

Menangani inisialisasi yang gagal

Dalam beberapa kasus, panggilan load mungkin gagal. Biasanya ini terjadi ketika 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 pembatasan wilayah mencegah pengguna akhir melihat buku tertentu ini. Anda mungkin ingin mendapatkan pemberitahuan 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 apa yang harus dipanggil jika buku tidak dapat dimuat. Misalnya, kode berikut akan menghasilkan kotak "peringatan" 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 callback ini, Anda dapat memutuskan untuk menampilkan error yang serupa, atau 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 semua pengguna, mungkin Anda perlu mengetahui apakah pratinjau tersedia sebelum mencoba memuat audiens untuk pratinjau tersebut. Misalnya, Anda mungkin ingin menampilkan tombol, halaman, atau bagian "Pratinjau Google", di UI hanya jika pratinjau akan benar-benar tersedia bagi 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

Sebaiknya ketahui juga apakah buku berhasil dimuat dan kapan waktunya. Karena alasan ini, fungsi load mendukung parameter ketiga opsional, successCallback, yang akan dijalankan jika dan setelah 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 jika, misalnya, Anda hanya ingin menampilkan elemen tertentu di halaman Anda jika penampil telah dirender sepenuhnya.

Menampilkan penampil saat dimuat

  google.books.setOnLoadCallback(initialize);

Saat halaman HTML dirender, model objek dokumen (DOM) di-build, dan gambar serta skrip eksternal apa pun diterima dan dimasukkan ke dalam objek document. Untuk memastikan penampil hanya ditempatkan di halaman setelah halaman 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 terduga dan memastikan kontrol terkait cara dan waktu pengguna menggambar.

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

Interaksi penonton

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

Namun, Anda juga dapat berinteraksi dengan penonton 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 "berbalik" secara otomatis ke halaman berikutnya setiap 3 detik. Jika halaman berikutnya berada di bagian yang terlihat dari penampil, penampil akan bergeser ke halaman dengan lancar; jika tidak, penonton akan langsung melompat 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 kepada pelihat akan gagal atau tidak berpengaruh sampai penampil diinisialisasi sepenuhnya dengan buku tertentu. Untuk memastikan Anda hanya memanggil fungsi tersebut saat penampil siap, gunakan parameter successCallback untuk viewer.load seperti dijelaskan di atas.

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

Catatan pemrograman

Sebelum mulai mempelajari Embedded Viewer API, Anda harus memperhatikan masalah berikut untuk memastikan aplikasi 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 bagi pengguna dengan browser yang tidak kompatibel. Embedded Viewer API tidak memiliki perilaku otomatis saat mendeteksi browser yang tidak kompatibel. Sebagian besar contoh dalam dokumen ini tidak memeriksa kompatibilitas Browser, atau pun menampilkan pesan error untuk browser lama. Aplikasi sebenarnya dapat melakukan hal yang lebih cocok untuk browser lama atau yang tidak kompatibel, tetapi pemeriksaan tersebut dihilangkan untuk membuat contoh lebih mudah dibaca.

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

Mode XML dan quirks

Sebaiknya gunakan XHTML yang sesuai standar pada halaman yang berisi penampil. Saat browser melihat XHTML DOCTYPE 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 "mode quirks", yang dapat menyebabkan tata letak 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 mendownload file HTML lengkap untuk setiap contoh dengan mengklik link setelah contoh tersebut.

Pemecahan masalah

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