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

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

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

קהל

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

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

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

"שלום, עולם" של ממשק ה-API של 'צפייה מוטמעת'

הדרך הקלה ביותר להתחיל ללמוד על Embedded Viewer API היא לעיין בדוגמה פשוטה. בדף האינטרנט הבא מוצגת תצוגה מקדימה בגודל 600x500 של Mountain View, מאת ניקולס פרי, ISBN 0738531367 (חלק מהסדרה "Images of America" של 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. אנחנו כוללים את Loader API באמצעות התג script.
  2. אנחנו יוצרים רכיב div בשם 'viewerCanvas' כדי להחזיק את הצופה.
  3. אנחנו כותבים פונקציית JavaScript כדי ליצור אובייקט "viewer".
  4. אנחנו טוענים את הספר באמצעות המזהה הייחודי שלו (במקרה הזה ISBN:0738531367).
  5. אנחנו משתמשים ב-google.books.setOnLoadCallback כדי לשלוח קריאה ל-initialize כשה-API נטען במלואו.

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

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

השימוש ב-API Loader framework כדי לטעון את 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>

טעינת גרסה מותאמת לשוק המקומי של ממשק ה-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, zh-TW, hr, cs, da, nl, en, fil, fi, fr, de, el, he, hu, is, id, it, ja, ko, lv, lt, ms, no

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

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

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

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

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

האובייקט DefaultViewer

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

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

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

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

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

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

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

  viewer.load('ISBN:0738531367');

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

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

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

בדומה לתכונה קישורים דינמיים, גם Embedded Viewer API תומך במספר ערכים לזיהוי ספר מסוים. האפשרויות הן:

מספר ISBN
מספר ספר סטנדרטי בינלאומי ייחודי בן 10 או 13 ספרות.
לדוגמה: 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, שמציין לאיזו פונקציה צריך לקרוא אם לא ניתן היה לטעון את הספר. לדוגמה, הקוד הבא ייצור תיבת "התראות" של 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)

באמצעות הקריאה החוזרת (callback) הזו, אפשר להחליט להציג שגיאה דומה או להסתיר לגמרי את הרכיב viewerCanvas. פרמטר הקריאה החוזרת של הכשל הוא אופציונלי, ולא נכלל בדוגמה "Hello World".

הערה: יכול להיות שתצוגות מקדימות לא יהיו זמינות לכל הספרים ולכל המשתמשים, ולכן כדאי לדעת אם יש תצוגה מקדימה זמינה לפני שתנסו לטעון תצוגה מקדימה שלה. לדוגמה, יכול להיות שתרצו להציג לחצן, דף או קטע של Google Preview בממשק המשתמש רק אם התצוגה המקדימה זמינה בפועל למשתמש. אפשר לעשות זאת באמצעות 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-הצלחה.html)

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

הצגת הצופה בזמן הטעינה

  google.books.setOnLoadCallback(initialize);

בזמן עיבוד של דף HTML, מודל אובייקט המסמך (DOM) מובנה, וכל תמונה וסקריפט חיצוניים מתקבלים ומשתלבים באובייקט document. כדי לוודא שהצופה ממוקם בדף רק אחרי שהדף נטען במלואו, נעשה שימוש בפונקציה google.books.setOnLoadCallback כדי לדחות את הביצוע של הפונקציה שיוצרת את האובייקט DefaultViewer. setOnLoadCallback יקרא ל-initialize רק כאשר Embedded Viewer 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 של Embedded Viewer, כדאי שתשימו לב לחששות הבאים כדי לוודא שהאפליקציה שלכם פועלת בצורה חלקה בפלטפורמות שלה.

תאימות דפדפן

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

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

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

מצב XHTML ו-quirks

מומלץ להשתמש ב-XHTML תואם לתקנים בדפים שמכילים את הצופה. כשדפדפנים רואים את המילה XHTML DOCTYPE בחלק העליון של הדף, הם מעבדים את הדף ב'מצב תאימות לתקנים', ולכן הפריסה וההתנהגות הרבה יותר חזויות בדפדפנים שונים. דפים בלי ההגדרה הזו עשויים להיות מוצגים במצב תאימות (quirks), מה שעלול להוביל לחוסר עקביות בפריסה.

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

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

פתרון בעיות

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