מדריך - יצירת תוסף לכרום

[מנחם מחשבים 0]

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

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

מה זה בכלל תוסף לכרום?

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

התוספים נכתבים באמצעות טכנולוגיות ה-WEB המוכרות – ג’אווהסקריפט, CSS, HTML, וכו’. הם יכולים להשתמש בכל ה-APIים שהדפדפן מספק לאתרים ואפליקציות ווב, והם גם יכולים לתקשר עם שרתים ואתרים.

התוספים מתקבצים בסופו של הפיתוח לקובץ אחד ויחיד אשר המשתמש יכול להוריד ולהתקין הישר מחנות התוספים של כרום, או ממקומות אחרים (למשל מהאתר שלכם).

קבצים בתוסף לכרום
בגדול, תוסף כרום מכיל את הקבצים הבאים, עליהם אפרט יותר במדריך עצמו:

קובץ מניפסט (manifest)
קובץ HTML אחד או יותר
קובץ ג’אווהסקריפט אחד או יותר
קבצי עזר (תמונות, קבצים נוספים אשר נדרשים לתוסף וכו’)

את כלל הקבצים מרכזים בתוך תיקייה אחת, כשבזמן ההפצה של התוסף מקבצים אותם לקובץ אחד בסיומת crx.

התייחסות לקבצים בתוסף לכרום

באם אנחנו רוצים להתייחס לקובץ מסויים שהוספנו לתוסף באמצעות URL רלטיבי, השימוש יהיה זהה לחלוטין לשימוש שאנחנו רגילים לעשות בפיתוח דפי WEB שונים:

<link rel=”stylesheet” type=”text/css” href=”style.css” />

ומה עושים כשרוצים להתייחס לקובץ באמצעות כתובת מלאה?

כתובת URL אבסולוטית של קובץ בתוסף נראית ככה:

chrome-extension://<extension_ID>/<file_path>

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

לצורך כך גוגל וכרום הקצו לנו מספר “הודעות מוגדרות מראש” (שהן בעצם סוג של משתנים), אשר אחת מהן מתייחסת ל-ID של התוסף – מה שיחסוך לנו את שינוי ה-ID בכל פעם מחדש.

ההודעה המוגדרת מראש המדוברת היא extension_id@@, וניתן להשתמש בה בקבצי ג’אווהסקריפט וCSS – אולם לא בקובץ המניפסט.

ארכיטקטורה של תוסף לכרום
הקונספטים העיקריים (אך לא מחייבים) הנהוגים בפיתוח תוסף לדפדפן הם דף הרקע(Background Page), דף “בלתי נראה” אשר מכיל את הלוגיקה המרכזית של התוסף. בנוסף לדף הרקע, ישנם דפי UI, אשר כשמם כן הם – מכילים את פרזנטציית הUI של התוסף. אחרון חביב הוא סקריפט התוכן(Content Script), אשר משמש ליצירת אינטרקציה עם אתרים, אפליקציות ודפים חיצוניים לתוסף.

דף רקע

דף רקע על פי רוב יקבל את השם background.html ויתייחס לקוד הג’אווהסקריפט המרכזי בהתנהגות התוסף (background.js).

ישנם 2 סוגים שונים של דפי רקע: דפי רקע “עקביים” אשר תמיד נשארים פתוחים, ודפי “אירוע” אשר נפתחים ונסגרים על פי צורך. ההמלצה החמה של גוגל היא להשתמש בדפי אירוע בלבד, אלא אם כן יש צורך ממשי בכך שדף רקע יהיה פתוח וירוץ תמיד.

דפי UI

דפי UI הם דפי HTML רגילים לגמרי אשר מציגים את הUI של התוסף. דוגמאות נפוצות לדפי UI הם דפי הגדרות של תוספים (כמו בחוסמי הפרסומות למיניהם, אשר תמיד מכילים דף אפשרויות והגדרות), פופאפים ותפריטים.

סקריפט תוכן

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

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

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

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

מה אנחנו בונים?

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

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

ככה יראה התוסף שלנו בסוף

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

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

manifest.json – קובץ המניפסט אשר חייב להיות קיים בכל תוסף
popup.html – דף ה-UI שלנו
popup.js – קובץ הג’אווהסקריפט אשר יכיל את הלוגיקה
style.css – כי חייבים להוסיף קצת סטייל
icon.png – הסמליל שיוצג בדפדפן וייצג את התוסף שלנו
אני החלטתי לקרוא לתוסף qExt, קיצור של Quotes Extension, אבל תרגישו חופשי להתפרע בשם.
ניצור תיקייה חדשה בשם שבחרנו, ונתחיל לעבוד.

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

ניצור קובץ בשם manifest.json, ונעתיק את הקוד הבא פנימה:

בואו נעבור על הדברים:

manifest_version, name, ו-version הינם שדות חובה במניפסט. שם התוסף והגרסא ברורים מאליהם, ולגבי גרסאת המניפסט – החל מגרסא 188 של כרום ההנחיה היא להשתמש בגרסא 2.

description איננו שדה חובה, אבל מומלץ להוסיף אותו ולתאר מה התוסף בעצם עושה.

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

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

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

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

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

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

אנחנו נרצה לעבוד עם JSON, ולכן הכתובת לשליפת ציטוט רנדומלי אחד, באנגלית ובפורמט JSON תהיה:

http://api.forismatic.com/api/1.0/?&method=getQuote&format=json&lang=en

ה-API מחזיר לנו אובייקט JSON שנראה כך:

מכאן אנחנו מסיקים שהדברים היחידים שמעניינים אותנו הם quoteText ו-quoteAuthor.

תחילה נכתוב את הפונקציה למשיכת הציטוט, שכן היא “מרכז הכובד” של הקוד שלנו – ואחריה שנסיים איתה הכל יהיה פשוט יותר. ניצור קובץ popup.js:

הפונקציה פשוטה למדי, משתמשת ב-Fetch API על מנת לבצע את הקריאה ל-API של forismatic ומקבלת callback להתמודדות עם המידע שהתקבל מהקריאה. Fetch עדיין מוגדרת כטכנולוגיה ניסיונית, אם כי התמיכה שלה בכרום יחסית רחבה (החל מגרסא 42). היא דומה לXMLHttpRequest, אולם מכילה פיצ’רים גמישים וחזקים יותר.

למי שלא מספיק בקיא – אני ממליץ מאוד לקרוא עוד אודות ה-Fetch API.

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

נמשיך ונשלים את קובץ הלוגיקה שלנו, popup.js:

הוספנו eventListener לטעינת ה-DOM, בו מתרחשים מספר דברים:

קודם כל, הכנסנו את שלושת אלמנטי הUI שלנו לתוך משתנים. לאחר מכן, יצרנו פונקציה חדשה בשם setDataToDOM שמקבלת את הציטוט ומכניסה אותו לתוך האלמנטים הרלוונטיים.

ביצענו קריאה לפונקציה הראשונה שלנו, getQuoteFromAPI, ונתנו לה את setDataToDOM כ-callback. לבסוף, יצרנו עוד eventListener שמאזין ללחיצה על הכפתור שלנו, ומבצע את אותה פעולה – קורא לgetQuoteFromAPI עם setDataToDOM כ-callbackk.

אבל מה שווה הלוגיקה אם לא מתייחסים אליה?
נחזור לקובץ popup.html ונוסיף התייחסות ב-head:

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

ניצור קובץ style.css ונעתיק את הקוד הבא:

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

כמובן שגם פה דרושה התייחסות בקובץ ה-UI שלנו, ולכן נחזור לpopup.html ונוסיף ב-head התייחסות:

ולבסוף, נוסיף אייקון לתוסף. על האייקון להיות קובץ PNG בגודל 19×19. אתם מוזמנים להכין אחד משלכם, או להשתמש באייקון שהכנתי עבורנו:

שמרו את האייקון בתיקייה של התוסף תחת השם icon.png – וזהו, סיימנו את התוסף הראשון שלנו לכרום.

בדיקת התוסף
אז נכון שאני טוען שסיימנו, אבל אמא שלי תמיד אומרת: “אל תאמין לאף אחד עד שאתה לא רואה בעיניים שלך”. סתם, האמת שהיא בכלל לא אומרת את המשפט הזה, אבל הוא נורא התאים לי פה.

הגיע הזמן לראות שהתוסף עובד.

נלך למנהל התוספות בכרום (אפשר גם לגלוש לכתובת: chrome://extensions/), ונוודא שסימנו את תיבת “Developer Mode”:

לאחר מכן נלחץ על הכפתור “Load unpacked extension…” ונבחר בתיקייה שלנו. מיד לאחר מכן נוכל לראות שהתוסף מופיע ברשימת התוספים:

בשלב הזה אנחנו כבר יכולים לראות את האייקון שלנו מבצבץ לו בשורת התוספים – זה הזמן ללחוץ עליו ולראות מה קורה.

לדבג את התוסף

ישנן הרבה מתודות שונות בעזרתן ניתן לדבג תוספים. אבל אם נאמר את האמת, בתוסף שלנו אין יותר מידי מה לדבג. הוא מתנהג כמעט לחלוטין כמו כל דף WEB אחר, ולכן גם הדרך לחקור אותו תהיה זהה – נשתמש בInspect Element.

כן כן, גם על תוספים ניתן לעשות Inspect Element, שם ניתן לחקור את הDOM שלהם, את הבקשות, את קבצי המקור – בקיצור, כל מה שאתם מכירים כבר.

מאוד שימושי, והאמת שגם מאוד טריוויאלי – אבל יש אנשים שיופתעו מהגילוי הזה (עבדכם הנאמן למשל..).

דפדפנים שהם לא כרום
צריך לדבר גם קצת על דפדפנים שאינם כרום. התוסף שכתבנו נבנה במיוחד לכרום, ולמרות שאחוז השימוש נמוך משמעותית – אי אפשר לשכוח מהעובדה שיש עוד דפדפנים חוץ מכרום. כתיבת תוסף לדפדפנים שונים היא דומה בעקרונות שלה, אולם יש שינויים קלים בסמנטיקה ובקוד בדברים מסויימים. למשל בעבור תוספים ל-Edge, חייבים להוסיף שדה author בקובץ manifest.json.

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

ל-MDN יש ספריית תוכן שלמה אודות WebExtensions, מערכת ליצירת תוספים חוצי-דפדפנים. אני ממליץ בחום לכל מי שמתעניין בנושא.

קרדיט לאתר הזה