Geliştirici Kılavuzu

Yerleştirilmiş Görüntüleyici API'si, Google Kitaplar'daki kitap içeriğini JavaScript ile doğrudan web sayfalarınıza yerleştirmenize olanak tanır. API ayrıca kitap önizlemelerini değiştirmeniz için çeşitli yardımcı programlar sağlar ve genellikle bu sitede açıklanan diğer API'larla birlikte kullanılır.

Önizleme Sihirbazı, Sadece birkaç satır kod kopyalayarak sitenize önizleme özellikleri eklemeyi kolaylaştıran, Yerleşik Görüntüleyici API'sının üzerine inşa edilmiş bir araçtır. Bu doküman, görüntüleyenin sitelerinde nasıl göründüğünü özelleştirmek isteyen daha gelişmiş geliştiriciler için hazırlanmıştır.

Kitle

Bu doküman, JavaScript programlama ve nesne odaklı programlama kavramlarına aşina olan kullanıcılar için tasarlanmıştır. Ayrıca kullanıcının bakış açısından Google Kitaplar'a da aşina olmanız gerekir. Web'de JavaScript öğreticilerini bulabilirsiniz.

Bu kavramsal belgeler eksiksiz değildir ve kapsamlı değildir. Bu özellik, Yerleşik Görüntüleyici API'siyle popüler uygulamaları hızlıca keşfetmeye ve geliştirmeye başlamanız için tasarlanmıştır. İleri düzey kullanıcılar, desteklenen yöntemler ve yanıtlar hakkında kapsamlı ayrıntılar sağlayan Yerleşik Görüntüleyici API Referansı'na ilgi duyabilirler.

Yukarıda belirtildiği gibi, yeni başlayanlar sitenize temel önizlemeleri yerleştirmek için gerekli kodu otomatik olarak oluşturan Önizleme Sihirbazı ile başlamak isteyebilir.

Yerleşik Görüntüleyici API'sının "Merhaba, Dünya"

Yerleştirilmiş Görüntüleyici API'si hakkında bilgi edinmeye başlamanın en kolay yolu basit bir örnek görmektir. Aşağıdaki web sayfası, Nicholas Perry, ISBN 0738531367 (Arcadia Publishing'in "Images of America" serisinin bir parçası olan) Mountain View'ın 600x500 boyutlu önizlemesini gösterir:

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

Bu örneğe göz atıp örneği düzenleyip bununla ilgili oynayabilirsiniz. Bu basit örnekte bile dikkat edilmesi gereken beş nokta vardır:

  1. API etiketi, script etiketi kullanılarak eklenir.
  2. İzleyiciyi tutmak için "viewerCanvas" adlı bir div öğesi oluştururuz.
  3. "İzleyici" nesnesi oluşturmak için bir JavaScript işlevi yazıyoruz.
  4. Kitabı, benzersiz tanımlayıcısını (bu örnekte ISBN:0738531367) kullanarak yüklüyoruz.
  5. API tam olarak yüklendiğinde initialize işlevini çağırmak için google.books.setOnLoadCallback kullanılır.

Bu adımlar aşağıda açıklanmıştır.

Yerleşik Görüntüleyici API'sını Yükleme

Yerleşik Görüntüleyici API'sını yüklemek için API Yükleyici çerçevesini kullanmak nispeten basittir. Bu işlem aşağıdaki iki adımı içerir:

  1. API Yükleyici kitaplığını ekleyin: 
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
  2. google.books.load yöntemini çağırın. google.books.load yöntemi, aşağıda açıklandığı gibi bir geri çağırma işlevi veya dili belirten isteğe bağlı bir liste parametresi alır. 
    <script type="text/javascript">
  google.books.load();
</script>

Yerleşik Görüntüleyici API'sinin yerelleştirilmiş sürümünü yükleme

Yerleştirilmiş Görüntüleyici API'si; ipuçları, kontrol adları ve bağlantı metni gibi metin bilgileri gösterirken varsayılan olarak İngilizceyi kullanır. Belirli bir dildeki bilgileri düzgün şekilde görüntülemek için Yerleşik Görüntüleyici API'sını değiştirmek isterseniz google.books.load çağrınıza isteğe bağlı bir language parametresi ekleyebilirsiniz.

Örneğin, Brezilya Portekizcesi arayüz diliyle bir kitap önizleme modülü görüntülemek için:

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

Örneği görüntüleyin (book-language.html)

Şu anda desteklenen RFC 3066 dil kodları arasında af, ar, hy, bg, ca, zh-CN, zh-TW, hr, cs, da, nl, en, fil, fi, fr, de, el, he, hu, is, id, id, ja, ko, vv, lt, r, pt, tr, tr, tr, tr

Yerleşik Görüntüleyici API'sını İngilizce dışında bir dilde kullanırken sayfanızı content-type başlığı utf-8 olarak veya sayfanıza eşdeğer bir <meta> etiketi eklemenizi öneririz. Bu sayede karakterlerin tüm tarayıcılarda doğru şekilde oluşturulması sağlanır. Daha fazla bilgi için HTTP karakter kümesi parametresini ayarlama ile ilgili W3C sayfasına bakın.

İzleyici DOM öğeleri

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

Bir kitabın web sayfasında gösterilebilmesi için yer ayırtılması gerekir. Genellikle bu işlem, adlandırılmış bir div öğesi oluşturularak ve tarayıcının belge nesne modelinde (DOM) bu öğeye bir referans yapılarak yapılır.

Yukarıdaki örnekte, "viewerCanvas" adlı bir div tanımlanmaktadır ve stil özellikleri kullanılarak boyutu ayarlanmaktadır. İzleyici, dolaylı olarak boyutunu belirlemek için kapsayıcının boyutunu kullanır.

DefaultViewer nesnesi

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

Sayfada tek bir görüntüleyen oluşturan ve kontrol eden JavaScript sınıfı DefaultViewer sınıfıdır. (Bu sınıfın birden fazla örneği oluşturabilirsiniz. Her nesne, sayfada ayrı bir görüntüleyen tanımlar.) JavaScript new operatörü kullanılarak bu sınıfın yeni bir örneği oluşturulur.

Yeni bir görüntüleyen örneği oluşturduğunuzda, izleyici için kapsayıcı olarak sayfada bir DOM düğümü (genellikle div öğesi) belirtirsiniz. HTML düğümleri, JavaScript document nesnesinin alt öğeleridir. Bu yönteme document.getElementById() yöntemi aracılığıyla referans verilir.

Bu kod, viewer adlı bir değişken tanımlar ve bu değişkeni yeni bir DefaultViewer nesnesine atar. DefaultViewer() işlevi, oluşturucu olarak bilinir ve tanımı (Yerleşik Görüntüleyici API Referansı'ndan netlik kazanacak şekilde kısaltılır) aşağıda gösterilmiştir:

Marka Açıklama
DefaultViewer(container, etkinleştirir mi?) Belirtilen HTML'nin container içinde yeni bir görüntüleyen oluşturur. Bu görüntüleyici, sayfada engelleme düzeyinde bir öğe olmalıdır (genellikle DIV). İsteğe bağlı opts parametresi kullanılarak gelişmiş seçenekler iletilir.

Oluşturucudaki ikinci parametrenin isteğe bağlı olduğunu (bu belgenin kapsamı dışında gelişmiş uygulamalar için amaçlandığını) ve "Hello, World" örneğinden çıkarıldığını unutmayın.

İzleyiciyi belirli bir kitapla başlatma

  viewer.load('ISBN:0738531367');

DefaultViewer oluşturucu ile bir izleyici oluşturduktan sonra izleyicinin belirli bir kitapla ilk kullanıma hazırlanması gerekir. Bu başlatma, izleyicinin load() yönteminin kullanılmasıyla gerçekleştirilir. load() yöntemi, API'ye hangi kitabın gösterileceğini belirten identifier değerini gerektirir. Bu yöntem, izleyici nesnesi üzerinde başka herhangi bir işlem gerçekleştirilmeden önce gönderilmelidir.

Bir kitabın birden fazla tanımlayıcısını (ince kapak basımının ISBN'si veya alternatif OCLC numaraları) biliyorsanız load() işlevine ilk parametre olarak bir dizi tanımlayıcı dizesi iletebilirsiniz. Dizideki herhangi bir tanımlayıcı ile ilişkili yerleştirilebilir bir önizleme varsa görüntüleyici kitabı oluşturur.

Desteklenen kitap tanımlayıcıları

Dinamik Bağlantılar özelliği gibi, Yerleşik Görüntüleyici API'si de belirli bir kitabı tanımlamak için çeşitli değerleri destekler. Bunlardan bazıları:

ISBN
10 veya 13 haneli benzersiz ticari Uluslararası Standart Kitap Numarası.
Örnek: ISBN:0738531367
OCLC numarası
Kitabın kaydı WorldCat katalog sistemine eklendiğinde OCLC tarafından bir kitaba atanan benzersiz numara.
Örnek: OCLC:70850767
LCCN
Kongre Kütüphanesi tarafından kayda atanan Kongre Kütüphanesi Kontrol Numarası.
Örnek: LCCN:2006921508
Google Kitaplar cilt kimliği
Google Kitaplar'ın cildine atadığı benzersiz dize. Bu değer, Google Kitaplar'da kitabın URL'sinde görünür.
Örnek: Py8u3Obs4f4C
Google Kitaplar önizleme URL'si
Google Kitaplar'da bir kitap önizleme sayfası açan URL.
Örnek: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

Bu tanımlayıcılar genellikle Google Books API Ailesi'ndeki diğer API'lerle kullanılır. Örneğin, yalnızca kitabın yerleştirilebilir olduğu durumlarda önizleme düğmesi oluşturmak için Dinamik Bağlantılar'ı kullanabilirsiniz. Ardından kullanıcı bu düğmeyi tıkladığında Dinamik Bağlantılar çağrısı tarafından döndürülen önizleme URL'sini kullanarak izleyici örneğini oluşturursunuz. Benzer şekilde, Books API ile zengin bir göz atma ve önizleme uygulaması oluşturabilirsiniz. Bu uygulama, Ciltler feed'lerinde çeşitli uygun sektör tanımlayıcılarını döndürür. Bazı gelişmiş uygulamalara göz atmak için örnekler sayfasını ziyaret edin.

Başarısız başlatma işlemlerini işleme

Bazı durumlarda load çağrısı başarısız olabilir. Bu durum genellikle API, sağlanan tanımlayıcıyla ilişkili bir kitap bulamadığında, kitabın kullanılabilir bir önizlemesi yoksa, kitap önizlemesinin yerleştirilemediği durumlarda veya bölgesel kısıtlamalar son kullanıcının bu kitabı görmesini engellerse meydana gelir. Bu tür bir hatayla ilgili uyarı almak isteyebilirsiniz. Böylece kodunuz bu koşulu sorunsuz bir şekilde işleyebilir. Bu nedenle load işlevi, isteğe bağlı ikinci bir parametre iletmenizi sağlar. Bu parametre, notFoundCallback yüklenemediğinde hangi işlevin çağrılacağını gösterir. Örneğin, kitap yerleştirilebiliyorsa aşağıdaki kod bir JavaScript "uyarı" kutusu oluşturur:

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

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

Örneği görüntüleyin (book-notfound.html)

Bu geri çağırmayı kullanarak benzer bir hata göstermeye karar verebilir veya viewerCanvas öğesini tamamen gizleyebilirsiniz. Hatalı geri çağırma parametresi isteğe bağlıdır ve "Hello World" örneğine dahil değildir.

Not: Önizleme tüm kitaplarda ve tüm kullanıcılar için sunulmayabilir. Bu nedenle, siz bir önizleme yüklemeyi denemeden önce önizlemenin kullanılabilir olup olmadığını bilmeniz yararlı olabilir. Örneğin, kullanıcı arayüzünde "Google Önizleme" düğmesini, sayfasını veya bölümünü, yalnızca önizlemenin kullanıcıya sunulacağı durumlarda göstermek isteyebilirsiniz. Bunu Books API veya Dinamik Bağlantılar'ı kullanarak yapabilirsiniz. Bunların ikisi de bir kitabın görüntüleyici kullanılarak yerleştirilmeye uygun olup olmadığını bildirir.

Başarılı ilk kullanıma hazırlama işlemlerini işleme

Bir kitabın başarıyla yüklenip yüklenmediğini ve ne zaman yüklendiğini bilmek de yararlı olabilir. Bu nedenle load işlevi, bir kitabın yüklenmesi tamamlandığında ve yürütülmesi durumunda yürütülecek isteğe bağlı üçüncü bir parametreyi (successCallback) destekler.

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

Örneği görüntüleyin (book-success.html)

Bu geri çağırma, örneğin sayfanızda yalnızca izleyici tamamen oluşturulmuşsa belirli öğeleri göstermek istiyorsanız faydalı olabilir.

İzleyiciyi yüklemede gösterme

  google.books.setOnLoadCallback(initialize);

Bir HTML sayfası oluşturulurken belge nesne modeli (DOM) oluşturulur. Harici resimler ve komut dosyaları alınıp document nesnesine dahil edilir. İzleyicimizin sayfaya yalnızca sayfa tamamen yüklendikten sonra yerleştirilmesini sağlamak için google.books.setOnLoadCallback işlevi, DefaultViewer nesnesini oluşturan işlevin yürütülmesini ertelemek için kullanılır. setOnLoadCallback, initialize öğesini yalnızca Yerleşik Görüntüleyici API'si yüklenip kullanıma hazır olduğunda çağıracağı için, öngörülemeyen davranışlar önlenir ve görüntüleyen kişinin nasıl ve ne zaman çekileceğini kontrol eder.

Not: Tarayıcılar arası uyumluluğu en üst düzeye çıkarmak için, <body> etiketinizde onLoad etkinliği kullanmak yerine google.books.setOnLoadCallback işlevini kullanarak görüntüleyen yükünü planlamanızı önemle tavsiye ederiz.

İzleyici etkileşimleri

Artık bir DefaultViewer nesnesine sahip olduğunuza göre bu nesneyle etkileşim kurabilirsiniz. Temel izleyici nesnesi, Google Kitaplar web sitesinde etkileşimde bulunduğunuz görüntüye çok benzer ve davranır. Ayrıca birçok yerleşik davranış sunar.

Bununla birlikte, izleyiciyle programatik olarak da etkileşim kurabilirsiniz. DefaultViewer nesnesi, önizleme durumunu doğrudan değiştiren çeşitli yöntemleri destekler. Örneğin zoomIn(), nextPage() ve highlight() yöntemleri, kullanıcı etkileşimi yerine izleyici üzerinde programatik olarak çalışır.

Aşağıdaki örnekte her 3 saniyede bir otomatik olarak sonraki sayfaya "dönen" bir kitap önizlemesi gösterilmektedir. Sonraki sayfa, görüntüleyen kullanıcının görebileceği bölümde yer alıyorsa, görüntüleyen sorunsuz bir şekilde sayfaya kaydırır; aksi takdirde görüntüleyen doğrudan sonraki sayfanın en üstüne atlar.

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

Örneği görüntüleyin (book-animate.html)

İzleyici belirli bir kitapla tamamen başlatılana kadar izleyiciye yapılan programatik aramaların başarısız olacağını veya herhangi bir etkisi olmayacağını unutmayın. Bu tür işlevleri yalnızca görüntüleyen hazır olduğunda çağırdığınızdan emin olmak için yukarıda açıklandığı gibi viewer.load parametresini successCallback parametresini kullanın.

DefaultViewer nesnesinin desteklediği tüm işlevler hakkında bilgi edinmek için Referans Kılavuzu'na bakın.

Programlama notları

Yerleşik Görüntüleyici API'sını incelemeye başlamadan önce uygulamanızın hedeflediği platformlarda sorunsuz çalıştığından emin olmak için aşağıdaki kaygıları dikkate almanız gerekir.

Tarayıcı uyumluluğu

Yerleşik Görüntüleyici API'si Internet Explorer, Firefox ve Safari'nin son sürümlerini ve genellikle Camino ve Google Chrome gibi diğer Gecko ve WebKit tabanlı tarayıcıları destekler.

Bazen farklı uygulamalar, tarayıcıları uyumsuz olan kullanıcılar için farklı davranışlar gerektirir. Yerleşik Görüntüleyici API'si, uyumsuz bir tarayıcı algıladığında otomatik davranışa sahip olmaz. Bu dokümandaki örneklerin çoğu, Tarayıcı uyumluluğunu kontrol etmez ve eski tarayıcılar için bir hata mesajı göstermez. Gerçek uygulamalar, eski veya uyumsuz tarayıcılarla daha uyumlu işlemler yapabilir ancak örneklerin daha okunaklı olması için bu tür kontroller atlanır.

Zor olmayan uygulamalar, tarayıcılar ve platformlar arasında kaçınılmaz olarak tutarsızlıklarla karşılaşacaktır. quirksmode.org gibi siteler de geçici çözüm bulmak için iyi kaynaklardır.

XHTML ve Quirks modu

Görüntüleyenin yer aldığı sayfalarda standartlara uygun XHTML'yi kullanmanızı öneririz. Tarayıcılar, sayfanın üst kısmında XHTML DOCTYPE bölümünü gördüğünde sayfayı "standartlara uygunluk modunda" oluşturur. Bu da, düzeni ve davranışları tarayıcılar genelinde çok daha tahmin edilebilir hale getirir. Bu tanımı taşımayan sayfalar, "tutarsız modda" oluşturulabilir. Bu da düzenin tutarsız olmasına yol açabilir.

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

Yerleşik İzleyici API'si örnekleriyle ilgili not

Bu belgedeki örneklerin çoğunun yalnızca alakalı JavaScript kodunu gösterdiğini, tam HTML dosyasını göstermediğini unutmayın. JavaScript kodunu kendi iskelet HTML dosyanıza bağlayabilir veya örnekten sonraki bağlantıyı tıklayarak her örnek için HTML dosyasının tamamını indirebilirsiniz.

Sorun giderme

Kodunuz çalışmıyor gibi görünüyorsa sorunlarınızı çözmenize yardımcı olabilecek bazı yaklaşımları aşağıda bulabilirsiniz: