ה-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>
אפשר לעיין בדוגמה הזו ולהוריד אותה כדי לערוך אותה ולשחק איתה. בדוגמה פשוטה זו נציין חמישה דברים שכדאי לשים לב אליהם:
- אנחנו כוללים את ה-API Loader באמצעות תג
script
. - אנחנו יוצרים רכיב
div
בשם "viewerCanvas" כדי להשאיר את הצופה. - אנחנו כותבים פונקציית JavaScript כדי ליצור אובייקט "צופה".
- אנחנו טוענים את הספר באמצעות המזהה הייחודי שלו (במקרה הזה
ISBN:0738531367
). - אנחנו משתמשים ב-
google.books.setOnLoadCallback
כדי להתקשר אלinitialize
כשה-API נטען באופן מלא.
שלבים אלה מוסברים להלן.
טעינה של ה-API הצופה המוטמע
קל מאוד להשתמש בממשק ה-API Loader API כדי לטעון את ה-API הצופה המוטמע. כדי לעשות זאת יש לבצע את שני השלבים הבאים:
- מוסיפים את ספריית Loader API:
<script type="text/javascript" src="https://www.google.com/books/jsapi.js"></script>
- הפעלת השיטה
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>
נכון לכרגע, קודי השפה של 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); }
באמצעות הקריאה החוזרת הזו תהיה לך אפשרות להחליט להציג שגיאה דומה, או להסתיר לגמרי את הרכיב 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); }
התקשרות חזרה זו יכולה להיות שימושית אם, למשל, תרצו להציג אלמנטים מסוימים בדף רק אם הצופה ביצע עיבוד מלא.
הצגת הצופה בטעינה
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 המלא לכל דוגמה.
פתרון בעיות
אם נראה שהקוד שלכם לא פועל, הנה כמה גישות שיעזרו לכם לפתור את הבעיות:
- מחפשים שגיאות הקלדה. חשוב לזכור ש-JavaScript היא שפה תלוית אותיות רישיות.
- אפשר להשתמש בכלי לניפוי באגים של JavaScript. ב-Firefox, אפשר להשתמש במסוף JavaScript, בכלי לניפוי באגים ב-Venkman או בתוסף Firebug. ב-IE, אפשר להשתמש בכלי לניפוי באגים של Microsoft Script. דפדפן Google Chrome כולל מספר כלי פיתוח מובנים, כולל בודק DOM וניפוי באגים.