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:
- Kami menyertakan Loader API menggunakan tag
script
. - Kita membuat elemen
div
bernama "viewerCanvas" untuk menyimpan penampil. - Kita menulis fungsi JavaScript untuk membuat objek "viewer".
- Kami memuat buku menggunakan ID unik buku tersebut (dalam hal ini
ISBN:0738531367
). - Kita menggunakan
google.books.setOnLoadCallback
untuk memanggilinitialize
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:
- Sertakan library Loader API:
<script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
- Panggil metode
google.books.load
. Metodegoogle.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:
- Cari kesalahan ketik. Ingatlah, JavaScript adalah bahasa yang membedakan huruf besar dan kecil.
- Menggunakan debugger JavaScript. Di Firefox, Anda dapat menggunakan konsol JavaScript, Venkman Debugger, atau add-on Firebug. Di IE, Anda dapat menggunakan Microsoft Script Debugger. Browser Google Chrome dilengkapi dengan sejumlah alat pengembangan bawaan, termasuk pemeriksa DOM dan debugger JavaScript.