דף זה תורגם על ידי Cloud Translation API.

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

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

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

קהל

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

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

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

הקוד Hello, World של Embedded Viewer API

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

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

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

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

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

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

כוללים את ספריית API Loader:

<script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>

הפעלה של השיטה google.books.load. השיטה google.books.load מקבלת פרמטר רשימה אופציונלי שקובע שפה או פונקציית קריאה חוזרת (callback), כפי שמוסבר בהמשך.
```
<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)

קודי השפות שנתמכים (הם 30666). הם כוללים את תדירות התמיכה ( [מי היא 30666). אחד מהקודים שנתמכים (: אי הוא: אי אפשר: (ha), [ : רע! ואת [ : ואת: ואת: ואת: רע ואת ואת:

כשמשתמשים ב-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'));

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

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

הקוד הזה מגדיר משתנה (שנקרא viewer) ומקצה את המשתנה הזה לאובייקט DefaultViewer חדש. הפונקציה DefaultViewer() נקראת constructor וההגדרה שלה (שצומצמה לצורך הבהירות מ החומר העזר בנושא Embedded Viewer 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: מספר הספר התקני הבינלאומי (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' רק אם התצוגה המקדימה תהיה זמינה בפועל למשתמש. אפשר לעשות זאת באמצעות 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)

הקריאה החוזרת (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 זמין במדריך העזרה.

הערות לתכנות

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

תאימות לדפדפנים

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

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

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

XHTML ומצב תאימות (quirks mode)

מומלץ להשתמש ב-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 המלא של כל דוגמה בלחיצה על הקישור שמופיע אחרי הדוגמה.

פתרון בעיות

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

מחפשים שגיאות הקלדה. חשוב לזכור ש-JavaScript היא שפה תלוית אותיות רישיות.
משתמשים בכלי לניפוי באגים ב-JavaScript. ב-Firefox, אפשר להשתמש במסוף JavaScript, ב- Venkman Debugger או ב-תוסף Firebug. ב-IE, אפשר להשתמש ב- Microsoft Script Debugger. דפדפן Google Chrome מגיע עם כמה כלי פיתוח מובנים, כולל בודק DOM ומנקה באגים של JavaScript.