מסמך ההגדרות של הגאדג'ט
לחלק מהגאדג'טים קיים חלון הגדרות, מסמך אשר מכיל בתוכו תיבות טקסט, תיבות סימון וכדומה. באמצעות מסמך זה אנו יכולים לשנות הגדרות בגאדג'ט. את מסמך זה אנו יוצרים בתיקיה הראשית של הגאדג'ט ובדומה למסמך ה-Scrollie.html, מסמך זה הוא כמו כל מסמך אינטרנט רגיל. ניצור את המסמך settings.html:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Gadget Settings</title>
</head>
<body>
</body>
</html>
אילו הגדרות אנו רוצים שיופיעו לנו במסמך זה? אם ניזכר במטרת הגאדג'ט, נראה כי רצינו שתהיה לנו תיבת טקסט שבה המשתמש יוכל להכניס את המשפט שהוא רוצה שיופיע כטקסט נגלל. לכן נעדכן את מסמך ה-settings.html שלנו:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Gadget Settings</title>
<link rel="stylesheet" href="resources/css/settings.css" />
<script type="text/javascript" src="resources/js/settings.js"></script>
</head>
<body onload="settingsLoad();">
<div id="settings_wrapper">
<table>
<tr><td>Scrolling Text:</td><td><input id="scrollText" type="text" size="25" value="" /></td></tr>
</table>
</div>
</body>
</html>
כפי שניתן לראות עטפנו את הגאדג'ט שלנו ב-div אשר נשתמש בו מאוחר יותר כדי ליצור מרווחים עם שולי המסמך (padding). הוספנו תיאור של תיבת הטקסט וכמובן את תיבת הטקסט עצמה. כמו כן, הוספנו טבלה שבה יצרנו שני עמודות: עמודה אחת מתארת את תיבת הטקסט ועמודה שנייה מכילה את תיבת הטקסט עצמה. כך נהוג לעשות כאשר יוצרים טפסים שקולטים מידע מן המשתמש. לתיבת הקלט ניתן את ה-id: scrollText כדי שנוכל יותר מאוחר להתייחס אליה באמצעות JavaScript. אם נסתכל בחלקו העליון של המסמך, נראה שהוספנו שתי שורות בתגית ה-head. השורה הראשונה מייבאת מסמך עיצוב חיצוני (settings.css) ומסמך JavaScript (settings.js). נשתמש במסמכים אלו כדי לעצב את מסמך ההגדרות ולשמור או לעלות את ההגדרות שהמשתמש הכניס במסמך זה. בתגית ה-body הוספנו מתודה בשם settingsLoad אשר תגיב לאירוע ה-onLoad של המסמך, או במילים אחרות, מתודה זו תופעל כאשר מסך ההגדרות יעלה.
מסמך ה-JavaScript של הגדרות הגאדג'ט
resources/js/settings.js יכיל בתוכו את תכנות ה-JavaScript של מסמך ה-settings.html. בכדי שנוכל להבין קצת יותר לעומק איך אנו מגדירים גאדג'טים עלינו לראות דוגמה. גאדג'ט המכיל חלון הגדרות יכיל בתוכו אייקון בצורת מפתח ברגים. כאשר נלחץ על אייקון זה חלון ההגדרות של הגאדג'ט יעלה:
החלק התחתון של החלון מכיל את כפתור האישור וכפתור הביטול (OK ו-Cancel). כפתורים אלה נוספים באופן אוטומטי לחלון ההגדרות ואנו לא צריכים להגדיר אותם. החלק העליון של החלון הוא בעצם מסמך ה-settings.html של הגאדג'ט. לכל חלון הגדרות יש אירוע בשם onSettingsClosing. אירוע זה מתרחש ברגע שאנו סוגרים את חלון ההגדרות (על ידי לחיצה על כפתור האישור או ביטול). כל גאדג'ט המכיל בתוכו מסך הגדרות שומר את ההגדרות שלו על קובץ באמצעות מחלקת ה-System.Gadget.Settings. מחלקה זו מכילה פונקציות לשמירה וקריאת הגדרות המשתמש. קוד ה-JavaScript של מסמך זה הוא:
//Gadget window events
System.Gadget.onSettingsClosing = settingsClosing;
//Window is being closed
function settingsClosing(event) {
if (event.closeAction == event.Action.commit) //User pressed "Ok!"
{
//Saving user's settings
var scrollText = document.getElementById("scrollText").value;
setScrollTextSetting(scrollText);
}
}
//Window loaded
function settingsLoad() {
document.getElementById("scrollText").value = getScrollTextSetting();
}
באמצעות השורה = settingsClosing System.Gadget.onSettingsClosing אמרנו לגאדג'ט לקפוץ למתודת ה-settingsClosing כאשר חלון הגאדג'ט נסגר. בכדי לקרוא קצת יותר על מחלקת ה-Gadget לחצו כאן. מחלקת ה-settingClosing מכילה פרמטר בשם event ובאמצעותו נוכל לקבוע אם כפתור האישור או הביטול נלחץ. התנאי שאנו רואים במחלקה זו בודק אם כפתור האישור נלחץ. אם כן, עלינו לשמור את הגדרות המשתמש. מתודת ה-settingsLoad נקראת ברגע שחלון הגאדג'ט עולה (כפי שהגדרנו במסמך ה-settings.html בתגית ה-body). אם שמתם לב, מסמך זה משתמש בשני פונקציות שאנו לא מכירים: setScrollingTextSetting ו-getScrollingTextSetting אותם נכיר וניצור בהמשך. כל שעלינו לדעת בשלב זה שפונקציות אלה מאפשרות לנו לשמור או לעלות את הטקסט שהמשתמש הכניס.
איזה מסמכים יצטרכו לקרוא את ההגדרות הללו? האם רק מסמך ה-settings.html יצטרך לקרוא את הגדרות הגאדג'ט? התשובה לכך היא לא. מסמך ה-Scrollie.html גם כן יצטרך לקרוא את ההגדרות בכדי שיוכל להציג את הטקסט שהמשתמש הכניס במסך ההגדרות כטקסט נגלל. לכן, עלינו ליצור מסמך settings_manager.js אשר יכיל פונקציות אשר יפשטו לנו את תהליך קריאת וכתיבת ההגדרות וניתן יהיה לייבא אותו בקלות ולשתף אותו עם שאר המסמכים שיצטרכו לשמור או לטעון הגדרות.
מסמך ההגדרות המשותף
resources/js/settings_manager.js יכיל פונקציות אשר יפשטו לנו את תהליך כתיבת וקריאת הגדרות המשתמש. מסמך ה-settings.html ומסמך ה-Scrollie.html ייבאו את מסמך זה בכדי שיוכלו לקרוא את הגדרות המשתמש בקלות, ללא צורך בכתיבה חוזרת של הפונקציות בכל מסמך נפרד.
הגאדג'ט שלנו מכיל שני הגדרות:
- scrollText – הגדרה זו היא מחרוזת המכילה את הטקסט שינוע.
- settingsLoaded – הגדרה זו מאפשרת לנו לדעת אם הגאדג'ט כבר עלה לפני, או שזוהי הפעם הראשונה שהגאדג'ט עלה (ז"א, הגאדג'ט נוסף לשולחן העבודה ולא הוגדר אף פעם).
בכדי לשמור ולקרוא את הגדרות המשתמש נשתמש במחלקת ה-Settings. מחלקת ה-Settings מכילה בתוכה שתי פונקציות: System.Gadget.Settings.write ו-System.Gadget.Settings.read. נשתמש בפונקציות אלו בכדי לשמור ולקרוא את הגדרות הגאדג'ט. מסמך ה-settings_manager.js יכיל את הקוד הבא:
//Sets the default settings for the gadget
function setDefaults() {
System.Gadget.Settings.write("scrollText", "Change this text in the settings menu");
System.Gadget.Settings.write("settingsLoaded", true);
}
//Checks if it's first time our gadget loads
function firstLoaded() {
return (System.Gadget.Settings.read("settingsLoaded") != true);
}
/* Settings set and get methods */
function getScrollTextSetting() {
return System.Gadget.Settings.read("scrollText");
}
function setScrollTextSetting(newSetting) {
System.Gadget.Settings.write("scrollText", newSetting);
}
פירוט על הפונקציות המופיעות במסמך:
- setDefaults – משנה את הגדרות הגאדג'ט להגדרות ברירת המחדל (ההגדרות הראשוניות). ברגע שהגאדג'ט שלנו עלה בפעם הראשונה, אנו קוראים למתודה זו.
- firstLoaded – פונקציה זו מחזירה לנו משתנה בוליאני (אמת או שקר). אם הפונקצייה מחזירה לנו אמת, זוהי הפעם הראשונה שהגאדג'ט שלנו עלה. אם היא מחזירה שקר, הגאדג'ט שלנו כבר רץ לפני ויש לו הגדרות שמורות.
- getScrollTextSetting – פונקציה זו מחזירה לנו את הגדרת ה-scrollText (הטקסט הנע) השמורה. היא משתמש בפונקצייה read שבמחלקת ה-Settings בכדי לקרוא את המידע השמור בקובץ
- setScrollTextSetting – פונקציה זו שומרת לנו את הטקסט שנכניס אלייה כפרמטר בהגדרת ה-scrollText. היא משתמשת בפונקצייה write שבמחלקת ה-Settings בכדי לשמור את המידע לקובץ.
כעת נוכל להשתמש בפונקציות הנ"ל בכדי לנהל את הגדרות הגאדג'ט בקלות רבה יותר. נוסיף לתגית ה-head של המסמכים settings.html ו-Scrollie.html את השורה הבאה:
<script type="text/javascript" src="resources/js/settings_manager.js"></script>
עלינו לדאוג לשים את שורה זו במסמך ה-settings.html לפני שאר השורות שמייבאות מסמכים. זאת כדי ששאר המסמכים יוכלו לקרוא לפונקציות אלו.
