Geliştirici Kılavuzu

Yerleşik Görüntüleyici API'si, Google Kitaplar'daki kitap içeriklerini JavaScript ile doğrudan web sayfalarınıza yerleştirmenize olanak tanır. API, kitap önizlemelerini değiştirmek için çeşitli yardımcı programlar da sağlar ve 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 dokümanlar, JavaScript programlama ve nesne yönelimli programlama kavramlarına aşina olan kişiler için tasarlanmıştır. Ayrıca, Google Kitaplar'ı bir kullanıcının bakış açısından da öğrenmelisiniz. Web'de birçok JavaScript eğitimi mevcuttur.

Bu kavramsal dokümanlar tam ve kapsamlı değildir. Yerleşik Görüntüleyen API'yi hızlıca keşfetmenize ve harika uygulamalar geliştirmenize olanak tanımak için tasarlanmıştır. Gelişmiş kullanıcılar, desteklenen yöntemler ve yanıtlar hakkında kapsamlı ayrıntılar sunan Embedded Viewer API Referansı'nı inceleyebilir.

Yukarıda belirtildiği gibi, yeni başlayanlar sitelerine temel önizlemeleri yerleştirmek için gereken kodu otomatik olarak oluşturan Önizleme Sihirbazı'nı kullanmaya başlayabilir.

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

Yerleşik Görüntüleyen API hakkında bilgi edinmeye başlamanın en kolay yolu basit bir örnek görmektir. Aşağıdaki web sayfasında, Nicholas Perry tarafından yazılan ve ISBN 0738531367 numaralı Mountain View kitabının 600x500 önizlemesi gösterilmektedir (Arcadia Publishing'in "Images of America" serisinin bir parçasıdır):

<!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ği inceleyebilir ve indirerek düzenleyebilir ve deneyebilirsiniz. Bu basit örnekte bile dikkat edilmesi gereken beş nokta vardır:

  1. API Yükleyici'yi script etiketi kullanarak ekleriz.
  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

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

  1. API Loader 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 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

Embedded Viewer API, ipuçları, kontrollerin adları ve bağlantı metni gibi metinsel bilgileri görüntülerken varsayılan olarak İngilizceyi kullanır. Embedded Viewer API'yi, bilgileri belirli bir dilde düzgün şekilde gösterecek şekilde değiştirmek istiyorsanız google.books.load çağrınıza isteğe bağlı bir language parametresi ekleyebilirsiniz.

Örneğin, Brezilya Portekizcesi arayüz dilinde 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ı ş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üleyen API'yi İngilizce dışındaki dillerde kullanırken sayfanızı utf-8 olarak ayarlanmış bir content-type üstbilgiyle yayınlamanızı veya sayfanıza eşdeğer bir <meta> etiketi eklemenizi önemle tavsiye ederiz. Bu, 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österilmesi için kitap için yer ayırmanız gerekir. Bu genellikle, adlandırılmış bir div öğesi oluşturulup tarayıcıdaki belge nesne modelinde (DOM) bu öğeye referans alınarak yapılır.

Yukarıdaki örnekte, "viewerCanvas" adlı bir div tanımlanmakta ve stil özelliklerini kullanarak boyutu ayarlanmaktadır. Görüntüleyen, boyutunu belirlemek için kapsayıcının boyutunu dolaylı olarak 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ğini 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, görüntüleyen için kapsayıcı olarak sayfada bir DOM düğümü (genellikle bir div öğesi) belirtirsiniz. HTML düğümleri, JavaScript document nesnesinin alt öğeleridir ve document.getElementById() yöntemi aracılığıyla bu öğeye referans alırız.

Bu kod, bir değişken (viewer adlı) tanımlar ve bu değişkeni yeni bir DefaultViewer nesnesine atar. DefaultViewer() işlevi constructor olarak bilinir ve bu işlevin 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, sayfadaki bir blok düzeyinde öğe (genellikle bir DIV) olmalıdır. Gelişmiş seçenekler, isteğe bağlı opts parametresi kullanılarak iletilir.

Yapıcıdaki ikinci parametrenin isteğe bağlı olduğunu (bu dokümanın kapsamı dışındaki gelişmiş uygulamalar için tasarlanmış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, izleyicinin load() yöntemi kullanılarak gerçekleştirilir. load() yöntemi, API'ye hangi kitabın gösterileceğini belirten bir identifier değeri gerektirir. Bu yöntem, görüntüleyen nesnesi üzerinde başka işlemler yapılmadan önce gönderilmelidir.

Bir kitabın birden fazla tanımlayıcısı varsa (ör. ciltsiz baskının ISBN'si veya alternatif OCLC numaraları) load() işlevine ilk parametre olarak bir tanımlayıcı dizesi dizisi iletebilirsiniz. Dizideki herhangi bir tanımlayıcıyla 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ı
Kitabın kaydı WorldCat kataloglama 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 cilte 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 bir kitap önizleme sayfasını açan URL.
Örnek: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

Bu tanımlayıcılar genellikle Google Books API ailesindeki diğer API'lerle birlikte 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üleyen ö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 ele alma

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ığı, kitabın önizlemesi olmadığı, kitap önizlemesi yerleştirilemediği veya bölgesel kısıtlamalar nedeniyle son kullanıcının söz konusu kitabı görmesini engellediğinde ortaya çıkar. Kodunuzun bu durumu sorunsuz bir şekilde ele alabilmesi için bu tür bir hata oluştuğunda uyarı almak isteyebilirsiniz. Bu nedenle load işlevi, kitap yüklenemediğinde hangi işlevin çağrılması gerektiğini belirten isteğe bağlı ikinci bir parametre (notFoundCallback) iletmenize olanak tanır. Örneğin, aşağıdaki kod, kitap yerleştirilebiliyorsa 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ğırma işlevini kullanarak benzer bir hata göstermeye karar verebilir veya viewerCanvas öğesini tamamen gizlemeyi seçebilirsiniz. Başarısızlık geri çağırma parametresi isteğe bağlıdır ve "Merhaba Dünya" örneğine dahil edilmemiştir.

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, kullanıcının önizlemeyi gerçekten kullanabileceği durumlarda kullanıcı arayüzünüzde "Google Önizlemesi" düğmesi, sayfası 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 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 çalıştırılacak isteğe bağlı üçüncü bir parametre olan successCallback parametresini 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 öğeleri yalnızca görüntüleyen tarafından tamamen oluşturulmuşsa göstermek 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 DefaultViewer nesnesini oluşturan işlevin yürütülmesi google.books.setOnLoadCallback işlevi tarafından erteleniyor. 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

Bir DefaultViewer nesnesi oluşturduğunuza göre bu nesneyle etkileşim kurabilirsiniz. Temel görüntüleyici nesnesi, Google Kitaplar web sitesinde etkileşimde bulunduğunuz izleyiciye çok benzer görünür ve davranır ve pek çok yerleşik davranışı vardır.

Ancak 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 izleyici üzerinde kullanıcı etkileşimi yerine programatik olarak çalışır.

Aşağıdaki örnekte, her 3 saniyede bir otomatik olarak bir sonraki sayfaya "geçen" bir kitap önizlemesi gösterilmektedir. Bir sonraki sayfa, görüntüleyenin görünür kısmındaysa görüntüleyen sayfaya sorunsuz bir şekilde kaydırılır. Aksi takdirde görüntüleyen doğrudan bir 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, izleyici belirli bir kitapla tamamen başlatılana kadar başarısız olacağını veya hiçbir etkisi olmayacağını unutmayın. Bu tür işlevleri yalnızca izleyici hazır olduğunda çağırdığınızdan emin olmak için successCallback parametresini viewer.load için yukarıda açıklandığı gibi 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 amaçlanan platformlarda sorunsuz şekilde çalıştığından emin olmak için aşağıdaki hususları göz önünde bulundurmanız gerekir.

Tarayıcı uyumluluğu

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

Farklı uygulamalar, uyumlu olmayan tarayıcılara sahip kullanıcılar için bazen 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 okunaklı olması için bu tür kontroller atlanır.

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

XHTML ve quirks modu

Görüntüleyiciyi içeren sayfalarda standartlara uygun XHTML kullanmanızı öneririz. Tarayıcılar sayfanın üst kısmında XHTML DOCTYPE etiketini gördüklerinde sayfayı "standartlara uygunluk modunda" oluşturur. Bu da sayfanın düzenini ve davranışlarını tarayıcılar arasında çok daha tahmin edilebilir hale getirir. Bu tanıma sahip olmayan sayfalar "Quirks modu"nda 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 örnekleri hakkında not

Bu dokümandaki örneklerin çoğunda, HTML dosyasının tamamı değil, yalnızca alakalı JavaScript kodu gösterildiğini unutmayın. JavaScript kodunu kendi iskelet HTML dosyanıza ekleyebilir veya her bir örneğin tam HTML dosyasını indirmek için örnekten sonraki bağlantıyı tıklayabilirsiniz.

Sorun giderme

Kodunuz çalışmıyorsa aşağıdaki yaklaşımlar, sorunlarınızı çözmenize yardımcı olabilir: