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.

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 pengembang 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 lengkap. Dokumentasi konseptual ini dirancang agar Anda dapat dengan cepat mulai menjelajahi dan mengembangkan aplikasi keren menggunakan Embedded Viewer API. Pengguna lanjutan mungkin tertarik pada Referensi Embedded Viewer API, yang memberikan detail lengkap 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 berukuran 600x500 Mountain View, oleh Nicholas Perry, ISBN 0738531367 (bagian dari seri "Images of America" di 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 menggunakannya. 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 "viewer".
  4. Kami memuat buku menggunakan ID unik buku tersebut (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 Loader API untuk memuat Embedded Viewer API relatif sederhana. Hal ini melibatkan dua langkah berikut:

  1. Sertakan library Loader API: 
    <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 callback atau bahasa, seperti yang dijelaskan di bawah. 
    <script type="text/javascript">
  google.books.load();
</script>

Memuat versi Embedded Viewer API 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 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, pt, ms, no, lv, lt, pt, no.

Saat menggunakan Embedded Viewer API dalam bahasa selain bahasa Inggris, sebaiknya tayangkan halaman dengan header content-type yang disetel 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 menetapkan parameter charset HTTP.

Elemen DOM pelihat

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

Agar buku ditampilkan di halaman web, buku harus memesan tempatnya. Umumnya, hal 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 "viewerCanvas" 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 penampil di halaman adalah class DefaultViewer. (Anda bisa 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 konstruktor dan definisinya (diringkas agar lebih jelas dari Referensi Embedded Viewer API) ditampilkan di bawah ini:

Konstruktor Deskripsi
DefaultViewer(container, opts?) Membuat penampil baru di dalam container HTML tertentu, yang seharusnya 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 penonton 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() pelihat. Metode load() memerlukan nilai identifier, yang memberi tahu API buku apa yang akan ditampilkan. Metode ini harus dikirim sebelum operasi lainnya dilakukan pada objek penampil.

Jika Anda mengetahui beberapa ID untuk sebuah buku, yaitu ISBN untuk edisi edisi cetak, 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. Contoh tersebut meliputi:

ISBN
Nomor Buku Standar Internasional berisi 10 atau 13 digit yang unik.
Contoh: ISBN:0738531367
Nomor OCLC
Nomor unik yang ditetapkan ke buku oleh OCLC ketika 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 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 di Kelompok Google Books API. Misalnya, Anda dapat menggunakan Dynamic Links untuk merender tombol pratinjau hanya jika buku dapat disematkan—lalu, saat pengguna mengklik tombol tersebut, buat instance penampil menggunakan URL pratinjau yang ditampilkan oleh panggilan Dynamic Links. Demikian pula, Anda dapat membuat aplikasi pratinjau dan penjelajahan yang lengkap dengan Books API, yang menampilkan beberapa ID industri yang sesuai di feed Volume-nya. Buka halaman contoh untuk melihat beberapa penerapan lanjutan.

Menangani inisialisasi yang gagal

Dalam beberapa kasus, panggilan load mungkin gagal. Umumnya hal ini terjadi jika 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 jika batasan wilayah 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 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 menggunakan callback ini, Anda dapat memutuskan untuk menampilkan error yang serupa, atau 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 penampilnya. Misalnya, Anda mungkin ingin menampilkan tombol, halaman, atau bagian "Pratinjau Google" di UI hanya jika pratinjau benar-benar akan 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

Mungkin juga berguna untuk mengetahui apakah buku berhasil dimuat dan kapan. Karena alasan ini, 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 sedang dimuat

  google.books.setOnLoadCallback(initialize);

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

Catatan: Untuk memaksimalkan kompatibilitas lintas browser, sebaiknya Anda menjadwalkan pemuatan pelihat 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 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 secara otomatis "berputar" ke halaman berikutnya setiap 3 detik. Jika halaman berikutnya berada di bagian yang terlihat pada penampil, penampil akan menggeser dengan mulus ke halaman; jika tidak, pelihat 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 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 untuk 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 dikehendaki.

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 hal yang lebih ramah dengan browser lama atau yang tidak kompatibel, tetapi pemeriksaan tersebut dihilangkan agar contoh lebih mudah dibaca.

Aplikasi yang tidak umum pasti akan mengalami inkonsistensi antara browser dan platform. Situs seperti quirksmode.org juga merupakan sumber daya yang bagus untuk menemukan solusi.

XHTML dan quirks mode

Sebaiknya gunakan Xcode yang sesuai standar pada halaman yang berisi penampil. Saat 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 "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 mencolokkan kode JavaScript ke file HTML kerangka Anda sendiri, atau mengunduh file HTML lengkap untuk setiap contoh dengan mengklik link setelah contoh.

Pemecahan masalah

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