راهنمای توسعه دهنده

Embedded Viewer API به شما امکان می دهد محتوای کتاب را از Google Books مستقیماً در صفحات وب خود با جاوا اسکریپت جاسازی کنید. API همچنین تعدادی ابزار برای دستکاری پیش‌نمایش کتاب‌ها فراهم می‌کند و اغلب همراه با سایر APIهای توضیح داده شده در این سایت استفاده می‌شود.

جادوگر پیش‌نمایش ابزاری است که بر روی Embedded Viewer API ساخته شده است که تنها با کپی کردن چند خط کد، افزودن قابلیت‌های پیش‌نمایش به سایت شما را آسان‌تر می‌کند. این سند برای توسعه دهندگان پیشرفته تری در نظر گرفته شده است که به دنبال سفارشی کردن نحوه نمایش بیننده در سایت های خود هستند.

مخاطب

این مستندات برای افرادی که با برنامه نویسی جاوا اسکریپت و مفاهیم برنامه نویسی شی گرا آشنا هستند طراحی شده است. همچنین باید از دیدگاه کاربر با Google Books آشنا باشید. بسیاری از آموزش های جاوا اسکریپت در وب وجود دارد.

این مستندات مفهومی کامل و جامع نیست. این برنامه به گونه ای طراحی شده است که به شما امکان می دهد به سرعت شروع به کاوش و توسعه برنامه های کاربردی جالب با Embedded Viewer API کنید. کاربران پیشرفته ممکن است به مرجع API نمایشگر جاسازی شده علاقه مند شوند، که جزئیات جامعی در مورد روش ها و پاسخ های پشتیبانی شده ارائه می دهد.

همانطور که در بالا ذکر شد، مبتدیان ممکن است بخواهند با پیش نمایش جادوگر شروع کنند، که به طور خودکار کد لازم برای جاسازی پیش نمایش های اولیه در سایت شما را تولید می کند.

"Hello, World" از Embedded Viewer API

ساده ترین راه برای شروع یادگیری در مورد Embedded Viewer API دیدن یک مثال ساده است. صفحه وب زیر یک پیش‌نمایش 600x500 از Mountain View ، توسط نیکلاس پری، ISBN 0738531367 (بخشی از مجموعه «تصاویر آمریکا» انتشارات Arcadia) را نشان می‌دهد:

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

می توانید به این مثال نگاه کنید و آن را برای ویرایش و بازی با آن دانلود کنید. حتی در این مثال ساده، پنج نکته قابل توجه است:

  1. ما API Loader را با استفاده از یک تگ script اضافه می کنیم.
  2. ما یک عنصر div به نام "viewerCanvas" ایجاد می کنیم تا بیننده را نگه دارد.
  3. ما یک تابع جاوا اسکریپت می نویسیم تا یک شی "نمایشگر" ایجاد کنیم.
  4. ما کتاب را با استفاده از شناسه منحصر به فرد آن بارگذاری می کنیم (در این مورد ISBN:0738531367 ).
  5. ما از google.books.setOnLoadCallback برای فراخوانی initialize زمانی که API به طور کامل بارگیری شد استفاده می کنیم.

این مراحل در زیر توضیح داده شده است.

در حال بارگیری Embedded Viewer API

استفاده از چارچوب API Loader برای بارگذاری Embedded Viewer API نسبتا ساده است. این شامل دو مرحله زیر است:

  1. شامل کتابخانه API Loader: 
    <script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
  2. روش google.books.load را فراخوانی کنید. روش google.books.load یک پارامتر فهرست اختیاری را می گیرد که تابع یا زبان بازگشت به تماس را مشخص می کند، همانطور که در زیر توضیح داده شده است. 
    <script type="text/javascript">
  google.books.load();
</script>

در حال بارگیری یک نسخه بومی سازی شده از Embedded Viewer API

Embedded Viewer API هنگام نمایش اطلاعات متنی مانند نکات ابزار، نام کنترل ها و متن پیوند به طور پیش فرض از زبان انگلیسی استفاده می کند. اگر می‌خواهید Embedded Viewer API را تغییر دهید تا اطلاعات به زبان خاصی نمایش داده شود، می‌توانید یک پارامتر language اختیاری را به تماس google.books.load خود اضافه کنید.

به عنوان مثال، برای نمایش یک ماژول پیش نمایش کتاب با زبان رابط پرتغالی برزیل:

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

مشاهده نمونه (book-language.html)

کدهای زبان RFC 3066 پشتیبانی شده در حال حاضر شامل 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, pl, pt-BR, pt-PT, ro, ru, sr, sk, sl, es, sv, tl, th, tr, uk, و vi.

هنگام استفاده از Embedded Viewer API در زبان‌هایی غیر از انگلیسی، اکیداً توصیه می‌کنیم صفحه خود را با یک سرصفحه content-type تنظیم شده روی utf-8 یا یک تگ <meta> معادل در صفحه خود قرار دهید. انجام این کار کمک می کند تا اطمینان حاصل شود که کاراکترها به درستی در همه مرورگرها ارائه می شوند. برای اطلاعات بیشتر، به صفحه W3C در مورد تنظیم پارامتر مجموعه حروف HTTP مراجعه کنید.

مشاهده عناصر DOM 

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

برای اینکه یک کتاب در یک صفحه وب نمایش داده شود، باید جایی برای آن رزرو کنید. معمولاً این کار با ایجاد یک عنصر div با نام و به دست آوردن ارجاع به این عنصر در مدل شی سند مرورگر (DOM) انجام می شود.

مثال بالا یک div با نام "viewerCanvas" را تعریف می کند و اندازه آن را با استفاده از ویژگی های سبک تنظیم می کند. بیننده به طور ضمنی از اندازه ظرف برای اندازه گیری خود استفاده می کند.

شی DefaultViewer 

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

کلاس جاوا اسکریپت که یک بیننده را در صفحه ایجاد و کنترل می کند، کلاس DefaultViewer است. (شما می توانید بیش از یک نمونه از این کلاس ایجاد کنید - هر شی یک نمایشگر جداگانه در صفحه تعریف می کند.) یک نمونه جدید از این کلاس با استفاده از عملگر new جاوا اسکریپت ایجاد می شود.

هنگامی که یک نمونه بیننده جدید ایجاد می کنید، یک گره DOM را در صفحه (معمولا یک عنصر div ) به عنوان یک ظرف برای بیننده مشخص می کنید. گره های HTML فرزندان شی document جاوا اسکریپت هستند و ما از طریق متد document.getElementById() به این عنصر ارجاع می دهیم.

این کد یک متغیر ( viewer نام) را تعریف می کند و آن متغیر را به یک شی DefaultViewer جدید اختصاص می دهد. تابع DefaultViewer() به عنوان سازنده شناخته می شود و تعریف آن (برای وضوح از مرجع API مشاهده کننده جاسازی شده فشرده شده است) در زیر نشان داده شده است:

سازنده توضیحات
DefaultViewer ( کانتینر ، گزینه ها؟ ) یک بیننده جدید در داخل container HTML داده شده ایجاد می کند که باید یک عنصر در سطح بلوک در صفحه باشد (معمولاً یک DIV ). گزینه های پیشرفته با استفاده از پارامتر opts اختیاری ارسال می شوند.

توجه داشته باشید که پارامتر دوم در سازنده اختیاری است - که برای پیاده سازی های پیشرفته خارج از محدوده این سند در نظر گرفته شده است - و از مثال "Hello, World" حذف شده است.

آغاز کردن بیننده با یک کتاب خاص 

  viewer.load('ISBN:0738531367');

هنگامی که یک نمایشگر از طریق سازنده DefaultViewer ایجاد کردیم، باید با یک کتاب خاص مقداردهی اولیه شود. این مقداردهی اولیه با استفاده از متد load() viewer's انجام می شود. متد load() به یک مقدار identifier نیاز دارد که به API می گوید چه کتابی را نشان دهد. این روش باید قبل از انجام هر گونه عملیات دیگری بر روی شی viewer ارسال شود.

اگر چندین شناسه برای یک کتاب می‌شناسید - ISBN برای نسخه شومیز، یا اعداد OCLC جایگزین - می‌توانید آرایه‌ای از رشته‌های شناسه را به‌عنوان اولین پارامتر به تابع load() بفرستید. اگر پیش‌نمایش قابل جاسازی مرتبط با هر یک از شناسه‌های آرایه وجود داشته باشد، بیننده کتاب را ارائه می‌کند.

شناسه های کتاب پشتیبانی شده

همانند ویژگی Dynamic Links ، Embedded Viewer API از تعدادی مقادیر برای شناسایی یک کتاب خاص پشتیبانی می کند. این موارد عبارتند از:

شابک
شماره کتاب استاندارد بین المللی تجاری 10 یا 13 رقمی منحصر به فرد.
مثال: ISBN:0738531367
شماره OCLC
شماره منحصر به فردی که توسط OCLC به یک کتاب اختصاص داده می شود، زمانی که رکورد کتاب به سیستم فهرست نویسی WorldCat اضافه می شود.
مثال: OCLC:70850767
LCCN
شماره کنترل کتابخانه کنگره که توسط کتابخانه کنگره به رکورد اختصاص داده شده است.
مثال: LCCN:2006921508
شناسه جلد Google Books
رشته منحصر به فردی که Google Books به حجم اختصاص داده است، که در URL کتاب در Google Books ظاهر می شود.
مثال: Py8u3Obs4f4C
نشانی وب پیش‌نمایش کتاب‌های Google
نشانی اینترنتی که صفحه پیش‌نمایش کتاب را در Google Books باز می‌کند.
مثال: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

این شناسه‌ها اغلب با سایر APIهای خانواده Google Books API استفاده می‌شوند. برای مثال، تنها در صورتی می‌توانید از پیوندهای پویا برای ارائه یک دکمه پیش‌نمایش استفاده کنید که کتاب قابل جاسازی باشد—و سپس، زمانی که کاربر روی دکمه کلیک می‌کند، یک بیننده را با استفاده از URL پیش‌نمایش بازگردانده شده توسط تماس پیوندهای پویا ، نمونه‌سازی کنید. به طور مشابه، می‌توانید یک برنامه مرور و پیش‌نمایش غنی با Books API بسازید که چندین شناسه صنعتی مناسب را در فیدهای Volumes خود برمی‌گرداند. برای مشاهده برخی از پیاده سازی های پیشرفته، از صفحه نمونه ها دیدن کنید.

مدیریت اولیه سازی های ناموفق

در برخی موارد، تماس load ممکن است با شکست مواجه شود. معمولاً زمانی که API نمی تواند کتاب مرتبط با شناسه ارائه شده را پیدا کند، زمانی که هیچ پیش نمایشی از کتاب در دسترس نیست، زمانی که پیش نمایش کتاب نمی تواند جاسازی شود، یا زمانی که محدودیت های منطقه ای کاربر نهایی را از دیدن این کتاب خاص جلوگیری می کند، رخ می دهد. ممکن است بخواهید در مورد چنین شکستی هشدار داده شود، بنابراین کد شما می تواند این شرایط را به خوبی مدیریت کند. به همین دلیل، تابع load به شما امکان می دهد یک پارامتر دوم اختیاری، notFoundCallback را ارسال کنید، که نشان می دهد اگر کتاب بارگیری نمی شود، چه تابعی باید فراخوانی شود. برای مثال، اگر کتاب قابل جاسازی باشد، کد زیر یک جعبه هشدار جاوا اسکریپت ایجاد می کند:

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

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

مشاهده نمونه (book-notfound.html)

با استفاده از این تماس، ممکن است تصمیم بگیرید که خطای مشابهی را نشان دهید، یا ممکن است انتخاب کنید که عنصر viewerCanvas را به طور کامل پنهان کنید. پارامتر پاسخ به تماس شکست اختیاری است و در مثال "Hello World" گنجانده نشده است.

توجه : از آنجایی که پیش‌نمایش‌ها ممکن است برای همه کتاب‌ها و برای همه کاربران در دسترس نباشد، ممکن است قبل از اینکه بخواهید یک بیننده برای آن بارگیری کنید، بدانید که آیا پیش‌نمایش در دسترس است یا خیر. برای مثال، ممکن است بخواهید دکمه، صفحه یا بخش «پیش‌نمایش Google» را در رابط کاربری خود نشان دهید تنها در صورتی که یک پیش‌نمایش واقعاً در دسترس کاربر باشد. می‌توانید این کار را با استفاده از Books API یا Dynamic Links انجام دهید، که هر دو گزارش می‌دهند که آیا کتابی برای جاسازی با استفاده از بیننده در دسترس خواهد بود یا خیر.

مدیریت اولیه سازی های موفق

همچنین ممکن است دانستن اینکه آیا کتاب با موفقیت بارگیری شده است یا خیر مفید باشد. به همین دلیل، تابع load از پارامتر سوم اختیاری، successCallback پشتیبانی می‌کند، که در صورت پایان بارگیری کتاب اجرا می‌شود.

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

مشاهده نمونه (book-success.html)

برای مثال، اگر بخواهید فقط در صورتی که بیننده به طور کامل رندر کرده باشد، عناصر خاصی را در صفحه خود نشان دهید، این پاسخ تماس ممکن است مفید باشد.

نمایش بیننده در حالت بارگذاری 

  google.books.setOnLoadCallback(initialize);

در حالی که یک صفحه HTML ارائه می شود، مدل شی سند (DOM) ساخته می شود و هر تصویر و اسکریپت خارجی دریافت می شود و در شی document گنجانده می شود. برای اطمینان از اینکه بیننده ما فقط پس از بارگیری کامل صفحه در صفحه قرار می گیرد، از تابع google.books.setOnLoadCallback برای به تعویق انداختن اجرای تابعی استفاده می شود که شی DefaultViewer را می سازد. از آنجایی که setOnLoadCallback فقط زمانی که Embedded Viewer API بارگیری شده و آماده استفاده باشد، initialize فراخوانی می کند، این امر از رفتار غیرقابل پیش بینی جلوگیری می کند و کنترل نحوه و زمان ترسیم بیننده را تضمین می کند.

توجه: برای به حداکثر رساندن سازگاری بین مرورگرها، اکیداً توصیه می‌شود که بارگیری بیننده را با استفاده از تابع google.books.setOnLoadCallback به جای استفاده از یک رویداد onLoad در تگ <body> خود برنامه‌ریزی کنید.

تعامل بیننده

اکنون که یک شی DefaultViewer دارید، می توانید با آن تعامل داشته باشید. شیء اصلی بیننده بسیار شبیه بیننده‌ای است که با آن در وب‌سایت Google Books تعامل دارید و رفتارهای داخلی زیادی دارد.

اما شما همچنین می توانید به صورت برنامه ای با بیننده تعامل داشته باشید. شی DefaultViewer از تعدادی روش پشتیبانی می کند که مستقیماً وضعیت پیش نمایش را تغییر می دهد. برای مثال، متدهای zoomIn() ، nextPage() و highlight() بر روی بیننده به صورت برنامه نویسی عمل می کنند، نه از طریق تعامل با کاربر.

مثال زیر یک پیش‌نمایش کتاب را نشان می‌دهد که هر 3 ثانیه به‌طور خودکار به صفحه بعدی تبدیل می‌شود. اگر صفحه بعدی در قسمت قابل مشاهده بیننده باشد، بیننده به آرامی به صفحه حرکت می کند. اگر نه، بیننده مستقیماً به بالای صفحه بعدی می‌پرد. 

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

مشاهده نمونه (book-animate.html)

توجه داشته باشید که تا زمانی که بیننده به طور کامل با یک کتاب خاص مقداردهی اولیه نشود، تماس‌های برنامه‌ای با بیننده ناموفق خواهند بود یا تأثیری ندارند. برای اطمینان از فراخوانی چنین توابعی فقط زمانی که بیننده آماده است، از پارامتر successCallback برای viewer.load همانطور که در بالا توضیح داده شد استفاده کنید.

برای اطلاعات در مورد تمام توابع پشتیبانی شده توسط شی DefaultViewer ، به راهنمای مرجع مراجعه کنید.

یادداشت های برنامه نویسی

قبل از شروع به جستجو در Embedded Viewer API، باید به نگرانی‌های زیر توجه داشته باشید تا مطمئن شوید که برنامه شما در پلتفرم‌های مورد نظر خود به خوبی کار می‌کند.

سازگاری با مرورگر

Embedded Viewer API از نسخه‌های اخیر اینترنت اکسپلورر، فایرفاکس و سافاری و معمولاً سایر مرورگرهای مبتنی بر Gecko و WebKit مانند Camino و Google Chrome نیز پشتیبانی می‌کند.

گاهی اوقات برنامه های مختلف برای کاربران با مرورگرهای ناسازگار رفتارهای متفاوتی را می طلبند. Embedded Viewer API هنگامی که یک مرورگر ناسازگار را شناسایی می کند، هیچ رفتار خودکاری ندارد. بیشتر نمونه‌های موجود در این سند سازگاری مرورگر را بررسی نمی‌کنند و برای مرورگرهای قدیمی‌تر پیام خطا نشان نمی‌دهند. برنامه‌های کاربردی واقعی ممکن است با مرورگرهای قدیمی یا ناسازگار کار دوستانه‌تری انجام دهند، اما چنین بررسی‌هایی برای خوانایی‌تر کردن مثال‌ها حذف می‌شوند.

برنامه های غیر پیش پا افتاده به ناچار با ناهماهنگی هایی بین مرورگرها و پلتفرم ها مواجه می شوند. سایت‌هایی مانند quirksmode.org نیز منابع خوبی برای یافتن راه‌حل‌ها هستند.

حالت XHTML و quirks

توصیه می کنیم از XHTML سازگار با استانداردها در صفحاتی که دارای نمایشگر هستند استفاده کنید. وقتی مرورگرها XHTML DOCTYPE در بالای صفحه می‌بینند، صفحه را در «حالت انطباق با استانداردها» نمایش می‌دهند، که طرح‌بندی و رفتارها را در مرورگرها قابل پیش‌بینی‌تر می‌کند. صفحات بدون آن تعریف ممکن است در " حالت عجیب و غریب " ارائه شوند، که می تواند منجر به چیدمان ناسازگار شود. 

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

یادداشتی در مورد نمونه‌های Embedded Viewer API

توجه داشته باشید که بیشتر نمونه‌های موجود در این مستندات فقط کد جاوا اسکریپت مربوطه را نشان می‌دهند، نه فایل کامل HTML. می‌توانید کد جاوا اسکریپت را به فایل HTML اسکلت خود متصل کنید، یا می‌توانید فایل کامل HTML را برای هر نمونه با کلیک کردن روی پیوند بعد از مثال دانلود کنید.

عیب یابی

اگر به نظر می رسد کد شما کار نمی کند، در اینجا چند روش وجود دارد که ممکن است به شما در حل مشکلات کمک کند:

  • به دنبال اشتباهات تایپی باشید به یاد داشته باشید که جاوا اسکریپت یک زبان حساس به حروف بزرگ و کوچک است.
  • از یک دیباگر جاوا اسکریپت استفاده کنید. در فایرفاکس، می‌توانید از کنسول جاوا اسکریپت، Venkman Debugger یا افزونه Firebug استفاده کنید. در اینترنت اکسپلورر، می توانید از Microsoft Script Debugger استفاده کنید. مرورگر گوگل کروم دارای تعدادی ابزار توسعه است که مستقیماً در آن تعبیه شده است، از جمله بازرس DOM و دیباگر جاوا اسکریپت.