Geliştirici Kılavuzu

Yerleşik 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. Ayrıca, kitap önizlemelerinde değişiklik yapmak için çeşitli yardımcı programlar da sağlayan API, genellikle bu sitede açıklanan diğer API'lerle birlikte kullanılır.

Önizleme Sihirbazı, Embedded Viewer API'sinin üzerinde yerleşik olarak bulunan ve sadece birkaç satır kod kopyalayarak sitenize önizleme özellikleri eklemenizi kolaylaştıran bir araçtır. Bu doküman, görüntüleyicinin sitelerindeki görünümünü özelleştirmek isteyen daha ileri düzey geliştiricilere yöneliktir.

Kitle

Bu belge, JavaScript programlama ve nesne odaklı programlama kavramlarını bilen kişiler için tasarlanmıştır. Ayrıca, Google Kitaplar'ı bir kullanıcının bakış açısından da öğrenmelisiniz. Web'de pek çok JavaScript eğiticisi vardır.

Kavramsal belgeleme, eksiksiz ve kapsamlı değildir. Embedded Viewer API ile etkileyici uygulamaları hızlıca keşfedip geliştirmeye başlamanızı sağlamak için tasarlanmıştır. İleri düzey kullanıcılar, desteklenen yöntemler ve yanıtlar hakkında kapsamlı bilgi içeren Yerleşik Görüntüleyici API Referansı'na göz atabilir.

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

Yerleşik Görüntüleyici API'sinde "Hello, World"

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

<!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 bakabilir ve düzenlemek ve üzerinde çalışmak için indirebilirsiniz. Bu basit örnekte bile dikkate alınması gereken beş nokta var:

  1. API Yükleyici'yi bir script etiketi kullanarak dahil ederiz.
  2. Görüntüleyiciyi tutmak için "viewerCanvas" adlı bir div öğesi oluştururuz.
  3. Bir "görüntüleyici" nesnesi oluşturmak için bir JavaScript işlevi yazarız.
  4. Kitabı, benzersiz tanımlayıcısını (bu örnekte ISBN:0738531367) kullanarak yükleriz.
  5. API tam olarak yüklendiğinde initialize işlevini çağırmak için google.books.setOnLoadCallback kodunu kullanırız.

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

Yerleşik Görüntüleyici API'sini yükleme

Yerleşik Görüntüleyici API'sini 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ı dahil edin: 
    <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 dil 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ş bir sürümünü yükleme

Yerleşik Görüntüleyici API'si ipuçları, kontrol adları ve bağlantı metni gibi metin bilgilerini görüntülerken varsayılan olarak İngilizce kullanır. Yerleşik Görüntüleyici API'sini belirli bir dildeki bilgileri düzgün şekilde görüntüleyecek şekilde değiştirmek isterseniz google.books.load çağrınıza isteğe bağlı bir language parametresi ekleyebilirsiniz.

Örneğin, bir kitap önizleme modülünü Brezilya Portekizcesi arayüz diliyle 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ı şunlardır: 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, plv, lt, ms, no, plv, lt, ms, no, plv.

Yerleşik Görüntüleyici API'sini İngilizce dışındaki dillerde kullanırken, sayfanızı content-type başlığı utf-8 olarak ayarlanmış bir şekilde veya sayfanıza eşdeğer bir <meta> etiketi ekleyerek sunmanızı önemle tavsiye ederiz. Bunu yapmak, karakterlerin tüm tarayıcılarda doğru şekilde oluşturulmasını sağlar. Daha fazla bilgi için W3C'nin HTTP karakter kümesi parametresini ayarlama 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 kitap için yer rezerve edilmesi gerekir. Genellikle bu işlem, adlandırılmış bir div öğesi oluşturularak ve tarayıcının belge nesne modelinde (DOM) bu öğeye referans elde edilerek yapılır.

Yukarıdaki örnekte "viewerCanvas" adlı bir div tanımlanır ve boyutu, stil özelliklerini kullanarak ayarlanır. Görüntüleyen, dolaylı olarak kapsayıcının boyutunu kendini boyutlandırmak için kullanır.

DefaultViewer nesnesi

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

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

Yeni bir görüntüleyici örneği oluşturduğunuzda, görüntüleyici için kapsayıcı olarak sayfada bir DOM düğümü (genellikle div öğesi) belirtirsiniz. HTML düğümleri, JavaScript document nesnesinin alt öğeleridir ve bu öğeye document.getElementById() yöntemi aracılığıyla başvuru alırız.

Bu kod viewer adında bir değişken tanımlar ve söz konusu değişkeni yeni bir DefaultViewer nesnesine atar. DefaultViewer() işlevi oluşturucu olarak bilinir ve tanımı (daha açık olması için Yerleşik Görüntüleyici API Referansı'ndan alınmış şekilde daraltılmıştır) aşağıda gösterilmiştir:

Marka Açıklama
DefaultViewer(container, opts?) Belirtilen HTML container içinde yeni bir görüntüleyici oluşturur. Bu görüntüleyici, sayfada engelleme düzeyinde bir öğe olmalıdır (genellikle DIV). Gelişmiş seçenekler, isteğe bağlı opts parametresi kullanılarak geçirilir.

Yapıcıdaki ikinci parametrenin isteğe bağlı olduğunu (bu dokümanın kapsamı dışındaki gelişmiş uygulamalar için amaçlanmıştır) ve "Hello, World" örneğinden çıkarıldığını unutmayın.

İzleyiciyi belirli bir kitapla başlatma

  viewer.load('ISBN:0738531367');

DefaultViewer oluşturucu aracılığıyla bir görüntüleyici oluşturduktan sonra, görüntüleyicinin belirli bir kitapla başlatılması gerekir. Bu başlatma işlemi, görüntüleyen kişinin load() yöntemi kullanılarak gerçekleştirilir. load() yöntemi, API'ye hangi kitabın gösterileceğini belirten identifier değeri gerektirir. Bu yöntem, görüntüleyici nesnesi üzerinde başka işlemler yapılmadan önce gönderilmelidir.

Bir kitabın birden çok tanımlayıcısı (ciltsiz basımın ISBN'si veya alternatif OCLC numaraları) biliyorsanız load() işlevine ilk parametre olarak bir tanımlayıcı dizeleri dizisi aktarabilirsiniz. Dizideki tanımlayıcıların herhangi biriyle ilişkili, yerleştirilebilir bir önizleme varsa görüntüleyen, 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 bir dizi değeri destekler. Bunlardan bazıları:

ISBN
10 veya 13 haneli benzersiz ticari Uluslararası Standart Kitap Numarası.
Örnek: ISBN:0738531367
OCLC numarası
Bir kitabın kaydı WorldCat katalog sistemine eklendiğinde OCLC tarafından 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 cilde atadığı benzersiz dize. Bu dize, Google Kitaplar'daki kitabın URL'sinde görünür.
Örnek: Py8u3Obs4f4C
Google Kitaplar önizleme URL'si
Google Kitaplar'da kitap önizleme sayfasını açan bir 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 kitap yerleştirilebilir durumdaysa bir önizleme düğmesi oluşturmak için Dinamik Bağlantılar'ı kullanabilir ve ardından, kullanıcı düğmeyi tıkladığında Dinamik Bağlantılar çağrısı tarafından döndürülen önizleme URL'sini kullanarak bir görüntüleyici örneği oluşturabilirsiniz. Benzer şekilde, Books API ile zengin bir göz atma ve önizleme uygulaması oluşturabilirsiniz. Bu API, 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, kitap önizlemesi olmadığında, kitap önizlemesi yerleştirilemediğinde veya bölgesel kısıtlamalar son kullanıcının bu kitabı görmesini engellediğinde meydana gelir. Kodunuzun bu durumla sorunsuz bir şekilde başa çıkabilmesi için böyle bir hata konusunda uyarı almak isteyebilirsiniz. Bu nedenle, load işlevi, isteğe bağlı ikinci bir parametre (notFoundCallback) aktarmanıza olanak tanır. Bu parametre, kitap yüklenemediğinde hangi işlevin çağrılması gerektiğini gösterir. Örneğin, kitap yerleştirilebilirse 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 gizlemeyi seçebilirsiniz. Hata geri çağırma parametresi isteğe bağlıdır ve "Hello World" örneğine dahil değildir.

Not: Önizlemeler tüm kitaplar ve tüm kullanıcılar için sunulmayabileceğinden, bir görüntüleyici yüklemeye çalışmadan önce önizlemenin kullanılabilir olup olmadığını bilmek yararlı olabilir. Örneğin, yalnızca bir önizleme kullanıcı için gerçekten kullanılabilir olacaksa kullanıcı arayüzünüzde bir "Google Önizleme" düğmesi, sayfa veya bölüm göstermek isteyebilirsiniz. Bunu Books API veya Dinamik Bağlantılar'ı kullanarak yapabilirsiniz. Her ikisi de, kitabın görüntüleyici kullanılarak yerleştirilmeye uygun olup olmadığını bildirir.

Başarılı başlatma işlemlerini gerçekleştirme

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 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ızdaki belirli öğelerin yalnızca görüntüleyen kişi tamamen oluşturulmuşsa gösterilmesini istiyorsanız yararlı olabilir.

İzleyiciyi yükleme sırasında gösterme

  google.books.setOnLoadCallback(initialize);

Bir HTML sayfası oluşturulurken belge nesne modeli (DOM) oluşturulur ve harici resimler ile komut dosyaları alınıp document nesnesine dahil edilir. Görüntüleyicimizin 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 amacıyla kullanılır. setOnLoadCallback, initialize öğesini yalnızca Yerleşik Görüntüleyici API'si yüklendiğinde ve kullanıma hazır olduğunda çağıracağından, öngörülemeyen davranışlardan kaçınarak görüntüleyicinin nasıl ve ne zaman çizildiğinin kontrol edilmesini sağlar.

Not: Tarayıcılar arası uyumluluğu en üst düzeye çıkarmak için izleyici yüklemesini, <body> etiketinizde bir onLoad etkinliği kullanmak yerine google.books.setOnLoadCallback işlevini kullanarak planlamanız önemle tavsiye edilir.

İzleyici etkileşimleri

Artık DefaultViewer nesneniz olduğuna göre onunla etkileşimde bulunabilirsiniz. Temel görüntüleyici nesnesi, Google Kitaplar web sitesinde etkileşimde bulunduğunuz izleyiciye çok benzer bir görünür ve davranır ve pek çok yerleşik davranışı vardır.

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

Aşağıdaki örnekte her 3 saniyede bir otomatik olarak sonraki sayfaya "dönen" bir kitap önizlemesi görüntülenmektedir. Sonraki sayfa, görüntüleyenin görünen kısmındaysa görüntüleyen kişi sayfayı sorunsuzca kaydırır; böyle değilse izleyici doğrudan sonraki sayfanın üst kısmına 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)

İzleyiciye yapılan programatik çağrıların, görüntüleyen kişi belirli bir kitapla tamamen başlatılana kadar başarısız olacağını veya herhangi bir etkisinin olmayacağını unutmayın. Bu tür işlevleri yalnızca görüntüleyici hazır olduğunda çağırdığınızdan emin olmak amacıyla viewer.load için successCallback parametresini yukarıda açıklandığı şekilde kullanın.

DefaultViewer nesnesi tarafından desteklenen tüm işlevler hakkında bilgi için Başvuru Kılavuzu'na bakın.

Programlama notları

Embedded Viewer API'yi incelemeye başlamadan önce uygulamanızın hedeflediği platformlarda sorunsuz çalıştığından emin olmak için aşağıdaki hususları göz önünde bulundurun.

Tarayıcı uyumluluğu

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

Farklı uygulamalar, bazen uyumsuz tarayıcılara sahip kullanıcılar için farklı davranışlar gerektirir. Yerleşik Görüntüleyici API'si, uyumlu olmayan bir tarayıcı algıladığında hiç otomatik olarak çalışmaz. Bu belgedeki örneklerin çoğu, Tarayıcı uyumluluğunu kontrol etmez veya daha eski tarayıcılar için bir hata mesajı görüntülemez. Gerçek uygulamalar eski veya uyumsuz tarayıcılarla daha uyumlu bir şekilde çalışabilir, ancak örneklerin daha kolay okunabilmesi için bu tür kontroller atlanır.

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

XHTML ve Quirks modu

Görüntüleyiciyi içeren sayfalarda standartlarla uyumlu XHTML kullanmanızı öneririz. Tarayıcılar, sayfanın üst kısmında XHTML DOCTYPE kodunu gördüğünde sayfayı "standartlar uyumluluğu modunda" oluşturur. Bu da düzen ve davranışların tarayıcılar genelinde çok daha tahmin edilebilir olmasını sağlar. Bu tanıma sahip olmayan sayfalar "Quirks modunda" oluşturulabilir ve bu da tutarsız bir düzene neden olabilir.

<!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 Görüntüleyici API örnekleriyle ilgili bir not

Bu belgelerdeki örneklerin çoğunun tam HTML dosyasını değil, yalnızca alakalı JavaScript kodunu gösterdiğini unutmayın. JavaScript kodunu kendi iskelet HTML dosyanıza takabilir veya örnekten sonra gelen bağlantıyı tıklayarak her örnek için tam HTML dosyasını indirebilirsiniz.

Sorun giderme

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