עריכת הדף "חב"דטקסט:מערכת בדיקת פרמטרים"

'''מערכת בדיקת פרמטרים''' מאפשרת להוסיף ל[[חב"דפדיה:תבנית|תבנית]] תיאור של הפרמטרים שהיא מצפה לקבל, ובדרך זו לאתר שימוש שגוי בתבנית (מספר לא נכון של פרמטרים, השמטה של פרמטר שחובה לדווחו ועוד).
== יחידה ==
ב[[יחידה:ParamValidator]] ([[יחידה:ParamValidator/תיעוד|תיעוד]]) שתי פונקציות: הפונקציה העיקרית מקבלת frame שהועבר מתבנית. הפונקציה מוצאת את שם התבנית, ובעזרת יחידת [[יחידה:ReadTd]] קוראת את ה- templatedata (מכאן והלאה - TD) של התבנית. אם הקריאה נכשלת, הפונקציה מחזירה שגיאה ויוצאת. 

הפונקציה עוברת על הפרמטרים שהועברו לתבנית (בעזרת {{קוד|frame.getParent()}}), ובודקת אותם מול המידע ב-TD, וכן ההפך, ומייצרת שגיאות שונות:
* פרמטר עם שם שגוי (כלומר לא מוצהר ב-TD)
* כנ"ל כשלפרמטר אין ערך
* פרמטר מספרי (כלומר "מבוסס סדר": כלומר אין סימן = בין שני מקלות) שלא מוצהר ב-TD
* כנ"ל בלי ערך
* פרמטר "מיושן" (deprecated) 
* כנ"ל בלי ערך
* פרמטר חובה (required) חסר (בין אם מועבר בלי ערך או לא מועבר כלל)
* פרמטר מסוג לא תואם (למשל פרמטר שמוגדר numeric ומקבל ערך לא ריק שאינו מספר חוקי)
היחידה מחזירה טבלת [[לואה (שפת תכנות)|לואה]] שיכולה להיות ריקה, כאשר אין שגיאות, או להכיל שדות עבור כל אחת מסוגי השגיאות שתוארו, כשבכל שדה רשימת הפרמטרים בהם נמצאה שגיאה.

הפונקציה השנייה מקבלת frame של תבנית, ופרמטר יחיד בשם options. הפרמטר הזה הוא מחרוזת שאמורה להכיל אובייקט [[JSON]] חוקי, שמתאר את הקונפיגורציה שמגדירה את הבדיקות. הפרטים מתוארים בפסקה הבאה. הפונקציה קוראת לפונציית הבדיקה, ואז "מלחימה" את רשימת השגיאות שנמצאו לקונפיגורציה, ויוצרת מחרוזת יחידה. אם לא נמצאו שגיאות, מחרוזת ריקה. אם נמצאו, האופציות מגדירות בדיוק את המחרוזת. המחרוזת הזו היא הפלט של הפונקציה.

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

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

== האופציות בשימוש המערכת בחב"דפדיה ==
בחב"דפדיה הפרמטרים ליחידה, נמצאים ביחידה נוספת: [[יחידה:PV-options]]. הפרמטרים הללו נחלקים לשלוש קבוצות, לפי מרחב השם של הדף בו מוצבת התבנית הנבדקת: ברוב מרחבי השם, רשימת הפרמטרים ריקה, ותבנית שנמצאת במרחב שם כזה לא תיבדק כלל. מרחבי השם בהם כן מתבצעת בדיקה מתחלקים לשני סוגים, וההבדל ביניהם הוא בקטגוריה שתתווסף להודעה: בחלק ממרחבי השם הקטגוריה היא [[:קטגוריה:שגיאות פרמטריות מחוץ למרחב הערכים]], ובחלק, ייתווספו שלוש קטגוריות שונות: [[:קטגוריה:שגיאות פרמטריות]], [[:קטגוריה:שגיאות פרמטריות בתבנית XXXX]] (לפי התבנית), ו[[:קטגוריה:שגיאות פרמטריות <תיאור השגיאה>>]]. דוגמה לקטגוריה האחרונה היא [[:קטגוריה:שגיאות פרמטריות שימוש בפרמטר מיושן]]. נכון למאי 2018, מרחבי השם מהסוג הראשון ("מחוץ למרחב הערכים") הם  2, 4, 12, 108, 118, 446, 828, 2300, 2302, 2600: משתמש, חב"דפדיה, עזרה, ספר, טיוטה, הוראה, יחידה, גאדג'ט, הגדרת גאדג'ט, ונושא.

מרחבי השם מהסוג השני ("כמו מרחב הערכים") הם 0, 6, 10, 14, 100: מרחב הערכים, קובץ, תבנית, קטגוריה, ופורטל.

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

פרט לקטגוריה, במרחבים הנבדקים, היחידה מייצרת הודעה על השגיאה. ההודעה הזו "מוסתרת" ממשתמשים שלא הפעילו גאדג'ט "{{מדיה ויקי:Gadget-validate-template-params}}" (בסעיף "ניטור"). עורכים שהפעילו את הגאדג'ט יראו קופסה (או כמה קופסאות) עם הודעה על השגיאה, בפינה שמאלית עליונה של הדף. ההודעה מכילה הסבר על השגיאה שכולל את שם התבנית וסוג השגיאה, ורשימת הפרמטרים הרלוונטיים. כמו כן ההודעה מכילה כפתורים ל"הסתרה" (הסתרת ההודעה), ו"סימון". לחיצה על "סימון" בדרך כלל תגרום להקפת התבנית בה מופיעה השגיאה במסגרת אדומה, והקפצת הקופסה עם ההודעה למקום בדף בו מופיעה התבנית. זה שימושי בעיקר כאשר יש הודעה על שגיאה בתבנית שמופיעה יותר מפעם אחת בדף, והעורך רוצה לראות איזה מופע של התבנית מכיל את השגיאה.

כמה נקודות שיש לשים אליהם לב:
* אם התבנית עם השגיאה מוכלת באלמנט מוסתר (כלומר כזה: {{טבלה מוסתרת|כותרת=דוגמה לאלמנט מוסתר|תוכן=ואנוכי הוהו היהי, מי כאן יודע מה הוא שמי?|עיצוב=max-width:18em;}}), הודעת השגיאה עלולה לא להופיע. כאשר מגיעים לדף עם קטגוריית שגיאה אך בלי הודעה, כדאי לנסות לחפש בדף אלמנטים מוסתרים ולפתוח את כולם
* תבניות ויחידות אחרות יכולות גם הן להוסיף את אחת מקטגוריות השגיאה (אולי יותר מאחת), ובפרט, תבניות שמשתמשות ב[[יחידה:תבנית מידע]]. במקרים אלו, תופיע קטגוריה אבל לא תופיע הודעה, ובדרך כלל התבנית עצמה לא תוצג בדף (אם כי כמובן היא כן תופיע בדף במצב עריכה).

== תצוגה וגאדג'טים ==
כל נושא התצוגה נשלט בעזרת מחלקת ה-CSS שהוזכרה בסעיף הקודם: "paramvalidator-wrapper". מחלקה זו מוגדרת ב-[[מדיה ויקי:common.css]], עם מצב תצוגה מוסתר. בשני מרחבי שם ספציפיים, "מרחב משתמש" ו"מרחב טיוטה", יש הגדרה אחרת למחלקה הזו, ושם היא מוגדרת במצב תצוגה גלוי ו"צף", כלומר ההודעה מוצגת במקום קבוע בדף, בלי להיות מושפעת מהמיקום של האלמנט שמכיל אותה, או למצב הגלילה. 

ב[[מדיה ויקי:Common.js]] יש קטע קוד שדואג, כאשר אלמנט מהמחלקה הזו נמצא בדף במצב תצוגה גלוי, להוסיף לו כפתורים להסתרת ההודעה, ולסימון התבנית בה נמצאו שגיאות. אם דף מסוים מכיל מספר תבניות שנמצאות תחת מערכת הבדיקות שיש בהן שגיאות, ההודעות ה"צפות" מוצגות זו על גבי זו, ויש לסגור כל הודעה כדי לקרוא את ההודעה שמתחתה. כדי להקל, במקרה שדף מכיל מספר הודעות, נוסף כפתור "סגור הכל" שסוגר את כולן.

כדי לראות את הודעות השגיאה במרחבים אחרים (כלומר לא משתמש או טיוטה), יש להתקין (ב"[[מיוחד:העדפות#mw-prefsection-gadgets|העדפות > גאדג'טים]]") את הגאדג'ט "הראה הודעות שגיאה ממערכת בדיקת הפרמטרים", שמשנה את מצב התצוגה של ההודעה מ"מוסתר" ל"צף" בכל מרחבי השם.

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

=== אלמנטים מוסתרים ===
מדובר באלמנטים שמשתמשים בתשתית ה"הסתרה" בחב"דפדיה. אלמנטים אלו נראים בדרך כלל כך:
{{טבלה מוסתרת | כותרת = כותרת האלמנט המוסתר | תוכן = תוכן האלמנט המוסתר - עשוי להכיל תבנית שנמצאת במערכת הבדיקות}}
כאשר אלמנט מוסתר מכיל תבנית עם שגיאת פרמטרים, קוד JS כללי, שמופעל במערכת מדיה ויקי ללא קשר למערכת הבדיקות, מסיר מהדף במצב "מוסתר" את התוכן המוסתר, ולכן הודעת השגיאה נעלמת גם אם היא אמורה להיות גלויה. במצב זה, ההודעה תופיע בחזרה ברגע שהאלמנט המוסתר מוצג. אם מצאתם דף שנמצא באחת מקטגוריות שגיאות הפרמטרים אבל לא מופיעה בו הודעה, חפשו אלמנטים מוסתרים ונסו לפתוח אותם - יתכן שהתבנית עם השגיאות נמצאת באלמנט כזה.

[[קטגוריה:ניהול פרמטרים]]