מדריך למפתחים

ה-API בעל הרשאת צפייה בהטמעה מאפשר להטמיע תוכן של ספרים מ-Google Books ישירות בדפי האינטרנט באמצעות JavaScript. ממשק ה-API גם מספק מספר כלים לשינוי תצוגה מקדימה של ספרים. בדרך כלל משתמשים בו יחד עם ממשקי API אחרים המתוארים באתר זה.

אשף התצוגה המקדימה הוא כלי שנבנה בנוסף לממשק ה-API של בעל הרשאת הצפייה המוטמעת, כדי להקל עליכם להוסיף יכולות של תצוגה מקדימה לאתר. כדי לעשות זאת, תוכלו פשוט להעתיק כמה שורות קוד. המסמך הזה מיועד למפתחים מתקדמים יותר שמעוניינים להתאים אישית את האופן שבו הצופה מציג את האתר שלו.

קהל

התיעוד הזה מיועד לאנשים שמכירים את התכנות של JavaScript ושל תכנות שמתמקד באובייקטים. צריך להכיר גם את Google Books מנקודת המבט של המשתמש. יש מדריכים רבים בנושא JavaScript הזמינים באינטרנט.

התיעוד הקונספטואלי הזה אינו מלא ומקיף. הוא נועד לאפשר לך להתחיל במהירות לחקור ולפתח אפליקציות מגניבות עם Implementer Viewer API. כדאי לעיין במשתמשים מוטמעים ב-API כדי לקבל מידע מקיף על השיטות והתגובות הנתמכות.

כפי שצוין קודם, מומלץ למתחילים להתחיל עם אשף התצוגה המקדימה, שיוצר באופן אוטומטי את הקוד הדרוש כדי להטמיע תצוגות מקדימות בסיסיות באתר שלכם.

"Hello, World" של הטמעת הצופים המוטמעים

הדרך הפשוטה ביותר להתחיל ללמוד על ה-API הצופה המוטמע היא לראות דוגמה פשוטה. דף האינטרנט הבא מציג תצוגה מקדימה של 600x500 של Mountain View, מאת ניקולס פרי, ISBN 0738531367 (חלק מסדרת "תמונות של אמריקה" של 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>

אפשר לעיין בדוגמה הזו ולהוריד אותה כדי לערוך אותה ולשחק איתה. בדוגמה פשוטה זו נציין חמישה דברים שכדאי לשים לב אליהם:

  1. אנחנו כוללים את ה-API Loader באמצעות תג script.
  2. אנחנו יוצרים רכיב div בשם "viewerCanvas" כדי להשאיר את הצופה.
  3. אנחנו כותבים פונקציית JavaScript כדי ליצור אובייקט "צופה".
  4. אנחנו טוענים את הספר באמצעות המזהה הייחודי שלו (במקרה הזה ISBN:0738531367).
  5. אנחנו משתמשים ב-google.books.setOnLoadCallback כדי להתקשר אל initialize כשה-API נטען באופן מלא.

שלבים אלה מוסברים להלן.

טעינה של ה-API הצופה המוטמע

קל מאוד להשתמש בממשק ה-API Loader API כדי לטעון את ה-API הצופה המוטמע. כדי לעשות זאת יש לבצע את שני השלבים הבאים:

  1. מוסיפים את ספריית Loader API: 
    <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>

טעינה של גרסה מותאמת של ה-Implementer API המוטמע

ב-מוטמע ממשק צפייה נעשה שימוש באנגלית כברירת מחדל בעת הצגת מידע טקסטואלי, כמו הסברים, שמות של בקרות וטקסט של קישורים. אם אתם רוצים לשנות את ה-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, t, t, t, t, t, t, t, t, t, t, t, t, t, t, , 1 וגם 2, 1

כשמשתמשים בממשק ה-API של בעל הרשאת הצפייה מוטמע בשפות שאינן אנגלית, מומלץ מאוד להציג את הדף עם כותרת content-type שמוגדרת ל-utf-8, או לכלול תג <meta> מקביל בדף. כך תוכלו להבטיח שתווים יוצגו כהלכה בכל הדפדפנים. למידע נוסף, עיינו בדף של ה-W3C בנושא הגדרת הפרמטר charset של HTTP.

רכיבי DOM של צופה

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

כדי שהספר יוצג בדף אינטרנט, נדרש בו מקום מראש. ברוב המקרים אפשר לעשות זאת על ידי יצירת רכיב בשם div וקבלת הפניה לרכיב הזה במודל האובייקט של המסמך (DOM).

בדוגמה שלמעלה מוגדר div בשם "viewerCanvas" ומגדיר את גודלו באמצעות מאפייני סגנון. הצופה משתמש באופן לא מפורש בגודל של הגורם המכיל כדי להתאים את גודלו.

אובייקט ברירת המחדל של צפייה

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

כיתת JavaScript שיוצרת צופה יחיד בדף ושולטת בה, היא הכיתה DefaultViewer. (אפשר ליצור יותר ממופע אחד של הכיתה הזו – כל אובייקט יגדיר צופה נפרד בדף.) מופע חדש של הכיתה הזו נוצר באמצעות האופרטור JavaScript new.

כשיוצרים מופע חדש של צופה, צריך לציין צומת DOM בדף (בדרך כלל זהו רכיב div) כמאגר לצופה. צמתי HTML הם צאצאים של אובייקט JavaScript document, ואנחנו מקבלים הפניה לרכיב הזה באמצעות שיטת document.getElementById().

הקוד הזה מגדיר משתנה (בשם viewer) ומקצה את המשתנה לאובייקט DefaultViewer חדש. הפונקציה DefaultViewer() נקראת constructor (בנאי) ולכן ההגדרה שלה (שנבדקת באופן ברור מתוך ה-מוטמע של Viewer API) מוצגת בהמשך:

יצרן תיאור
DefaultViewer(container, Opts?) יצירת צופה חדש בתוך קוד ה-HTML container הנתון, שאמור להיות רכיב ברמת החסימה בדף (בדרך כלל DIV). אפשרויות מתקדמות מועברות באמצעות הפרמטר האופציונלי opts.

חשוב לשים לב שהפרמטר השני בבנאי הוא אופציונלי - הוא מיועד להטמעות מתקדמות מעבר להיקף המסמך הזה - והוא מושמט מהדוגמה "שלום, עולם".

אתחול הצופה עם ספר ספציפי

  viewer.load('ISBN:0738531367');

לאחר שיצרנו מכשיר צפייה דרך בנאי DefaultViewer, הוא צריך להתחיל בספר מסוים. ההפעלה הזו מתבצעת באמצעות שיטת load() של הצופה. השיטה load() מחייבת ערך identifier שמגדיר ל-API איזה ספר להציג. צריך לשלוח את השיטה הזו לפני שמתבצעות פעולות אחרות באובייקט הצופה.

אם ידוע לכם על כמה מזהים של ספר – ה-ISBN של מהדורת הכריכה הרכה או מספרי OCLC חלופיים – אפשר להעביר מערך של מחרוזות זיהוי כפרמטר הראשון לפונקציה load(). הצופה יעבד את הספר אם יש תצוגה מקדימה מוטמעת המשויכת לאחד מהמזהים במערך.

מזהי ספרים נתמכים

בדומה לתכונה קישורים דינמיים, ממשק ה-API של הצופה המוטמע תומך במספר ערכים כדי לזהות ספר מסוים. רשימת המדינות כוללת את:

מספר ISBN
הספר המסחרי הייחודי בן 10 או 13 הספרות של International Standard Book Number .
לדוגמה: ISBN:0738531367
מספר OCLC
המספר הייחודי שהוקצה על ידי ה-OCLC כאשר רשומת הספר מתווספת למערכת הקטלוג של WorldCat.
לדוגמה: OCLC:70850767
LCCN
ספריית ספריית הקונגרס שהוקצתה להקלטה על ידי ספריית הקונגרס.
לדוגמה: LCCN:2006921508
מזהה הכרך של Google Books
המחרוזת הייחודית ש-Google Books הקצה לכרך, שמופיע בכתובת ה-URL של הספר ב-Google Books.
לדוגמה: Py8u3Obs4f4C
כתובת URL לתצוגה מקדימה של Google Books
כתובת URL שפותחת דף תצוגה מקדימה של ספר ב-Google Books.
לדוגמה: https://books.google.com/books?id=Py8u3Obs4f4C&printsec=frontcover

המזהים האלה נמצאים בשימוש נפוץ עם ממשקי API אחרים במשפחת Google Books API. לדוגמה, אתם יכולים להשתמש בקישורים דינמיים כדי לעבד לחצן תצוגה מקדימה רק אם הספר מוטמע, ואז כשהמשתמש לוחץ על הלחצן, ליצור לצופה צפייה באמצעות כתובת ה-URL לתצוגה המקדימה שקריאה לפעולה של קישורים דינמיים. באופן דומה, ניתן ליצור אפליקציה עשירה לגלישה ולתצוגה מקדימה באמצעות Books API, שמחזיר כמה מזהי תחום מתאימים בפידים של הנפח. נכנסים לדף הדוגמאות כדי לראות כמה הטמעות מתקדמות.

טיפול באתחולים שנכשלו

במקרים מסוימים, השיחה של load עשויה להיכשל. לרוב זה קורה כשה-API לא מצליח למצוא ספר המשויך למזהה שסופק, כשאין תצוגה מקדימה זמינה של הספר, כשלא ניתן להטמיע את התצוגה המקדימה של הספר או כשמגבלות טריטוריאליות מונעות ממשתמש הקצה לראות את הספר הספציפי הזה. מומלץ לקבל התראה על כשל כזה, כדי שהקוד שלך יוכל לטפל במצב הזה בחינניות. מסיבה זו, הפונקציה load מאפשרת לך להעביר פרמטר שני אופציונלי, notFoundCallback, שמציין לאיזו פונקציה יש לקרוא אם לא ניתן לטעון את הספר. לדוגמה, הקוד הבא ייצור תיבת "alert" של JavaScript אם אפשר להטמיע את הספר:

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. פרמטר ה-callback הנכשל הוא אופציונלי, ואינו כלול בדוגמה של "Hello World" (שלום עולם).

הערה: יכול להיות שהתצוגה המקדימה לא תהיה זמינה לכל הספרים ולכל המשתמשים, כך שמומלץ לדעת אם התצוגה המקדימה זמינה לפני שמנסים לטעון אותה. לדוגמה, ייתכן שתרצו להציג לחצן, דף או קטע "תצוגה מקדימה של Google" בממשק המשתמש רק אם התצוגה המקדימה תהיה זמינה למשתמש. תוכלו לעשות זאת באמצעות Books API או קישורים דינמיים, ששניהם ידווח אם הספר יהיה זמין להטמעה באמצעות הצופה.

טיפול באתחול מוצלח

כדאי גם לדעת אם ספר נטען בהצלחה ומתי. מסיבה זו, הפונקציה 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 יתקשר ל-initialize רק כשממשק ה-API של הצופה המוטמע נטען ומוכן לשימוש, כך ניתן להימנע מהתנהגות לא צפויה ומבטיחה שליטה על אופן וזמן הצפייה של המשתמש.

הערה: כדי לשמור על תאימות למספר דפדפנים, מומלץ מאוד לתזמן את העומס של הצופים באמצעות הפונקציה 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, אפשר לעיין במדריך העזר.

נתוני תכנות

לפני שמתחילים להתעמק ב-הטמעה מוטמעת של ממשק API, חשוב לשים לב לחששות הבאים כדי לוודא שהאפליקציה פועלת בצורה תקינה בפלטפורמות הרצויות.

תאימות דפדפן

ה-API בעל הרשאת צפייה מוטמעת תומך בגרסאות עדכניות של Internet Explorer , Firefox ו-Safari, ובדרך כלל גם בדפדפנים אחרים המבוססים על Gecko ו-WebKit כמו Camino ו-Google Chrome.

אפליקציות שונות מחייבות לפעמים התנהגות שונה אצל משתמשים עם דפדפנים לא תואמים. ה-API של הצופה המוטמע לא מתנהג באופן אוטומטי כשהוא מזהה דפדפן לא תואם. רוב הדוגמאות במסמך הזה לא בודקות את התאימות של הדפדפן וגם לא מציגות הודעת שגיאה בדפדפנים ישנים. יכול להיות שאפליקציות אמיתיות הופכות את הפעולה לידידותית יותר לדפדפנים ישנים או לא תואמים, אבל השמטנו את הבדיקות האלה כדי להקל על הקריאה של הדוגמאות.

אין ספק שאפליקציות לא טריוויאליות נתקלו בחוסר עקביות בין הדפדפנים לפלטפורמות. גם אתרים כמו quirksmode.org הם משאבים טובים לחיפוש פתרונות זמניים.

מצב XHTML ורגילות

מומלץ להשתמש ב-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">

הערה בדוגמאות של ה-API הצופה המוטמע

חשוב לשים לב: ברוב הדוגמאות בתיעוד הזה מוצג רק קוד JavaScript רלוונטי, ולא קובץ ה-HTML המלא. תוכלו לטעון את קוד JavaScript לקובץ HTML בסיסי משלכם, או ללחוץ על הקישור שמופיע אחרי הדוגמה כדי להוריד את קובץ ה-HTML המלא לכל דוגמה.

פתרון בעיות

אם נראה שהקוד שלכם לא פועל, הנה כמה גישות שיעזרו לכם לפתור את הבעיות: