Addon:Forms Gramplet/he

כתיבת הגדרות טופסים מותאם אישית

הערה חשוב לוודא שקובץ ההגדרות נשמר בקידוד UTF-8.

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

הגדרות הטופס מאוחסנות בקובצי XML. אלה ממוקמים במחיצה בה שוכן קוד הטופס בנתיב [[Gramps_Template:Version manual_Wiki_Manual_-_User_Directory|מחיצת מתקעי משתמש]]. הקובץ שנקרא form_xx.xml(כאשר xx הוא קוד מדינה), נכלל בהורדה ומכיל מספר הגדרות נפוצות. בנוסף יתבצע גם חיפוש בקבצים נוספים, custom.xml ו-test.xml. שמות אלו שמורים לשימוש בתהליך יצירת קוד באופן אצמעי.

קבצי הגדרה מורכבים מהצהרת XML ובעקבותיה הרכיב forms.

<?xml version="1.0" encoding="UTF-8" ?>
<forms>
   ...
</forms>

הרכיב forms מכיל בתוכו מספר רכיבי form נוספים, כל אחד מייצג הגדרת טופס. תג הפתיחה בטופס מכיל ארבע תכונות:

1. id : קוד ייחודי לזיהוי הגדרת הטופס. קוד הזיהוי הזה ישמש בהמשך לעת יצירת או עדכון בתכונת "טופס" המקור.
2. type: סוג האירוע שנוצר על ידי עורך הטפסים. ערך זה יופיע בעמודת האירועים "Type" ("EventType"). יהיה חכם להימנע מסוגים תקניים ושכיחים , לדוגמה, להוספת מידע על פטירה ניתן לציין סוג "Death.Info" (ולא Death) או כל שם סוג שעולה על הדעת. אחרת לא מן הנמנע שנתונים יאבדו.
3. title : כותרת הטופס שמשמש לתיאור קצר. אפשר להזין לשדה זה כל דבר.
4. date : תאריך (לא חובה) בתסדיר תאריך גרמפס תיקני. תג התאריך שימושי בעיקר באירועים תלויי זמן כמו לדוגמה מפקדי אוכלוסין ואירועים דומים שהתרחשו בתאריך (נקוב) מסוים.

<form id='UK1841' type='Census' title='1841 UK Census' date='6 Jun 1841'>

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

1. role : התפקיד אותו ממלאים אנשים במקטע זה, באירוע. הערך יופיע בעמודת האירועים 'תפקיד' "Role" ("EventRoleType").
2. type : סוג המקטע. מגדיר כיצד המקטע יוצג ואופן בחירת אנשים. ערכים מותרים הם: 'person' לאדם יחיד, 'multi' לאדם אחד או יותר, או 'family' לשני אנשים שנבחרו על ידי בחירת משפחה.
3. title : כותרת שמשמשת בעת הצגת מקטע טופס ולמעשה הדרך היחידה בה ניתן להבדיל חזותית בין מקטעים מרובים. בנישואין לדוגמה נקבל תפקיד "בעל", "אישה" ואולי מספר תפקידים אחרים כמו "עדים", "רב" או "כומר", "שושבינים".

<section role='Primary' type='person' title='Child'>

כל רכיב מקטע בטופס חייב להכיל רכיב column עבור כל אחת מהעמודות בתעודת/רשומת המקור. רכיבי עמודה מתארים ולוכדים מידע עבור כל אדם במקטע.

רכיב עמודה מכיל:

• רכיב _attribute – מכיל מפתח לזיהוי 'מידע עמודה' (שברכיב 'תכונות' בחלון דו־שיח עצמי הפניה לאירועים), במסד־נתוני גרמפס בתכונת "סוג" מידע הפניה לאירוע. במידה ונעשה שימוש ברכיב "שם", אזי שדה 'שם' יאוכלס מראש בשמו של ה'אדם' שנבחר. לתשומת לב! אין לשנות מלל זה לאחר שהוגדר בקובץ forms_xx.xml.
• רכיב _longname (חלופי) – מכיל 'תיאור ארוך' של העמודה ומשמש לרמזים־צצים, בעת מעבר עכבר מעל השדה בטופס.
• רכיב size – מכיל את ערך גודל העמודה בטופס. מבוטא באחוז מרוחב העמוד הכולל, כך שסכום אחוזי העמודות הכולל חייב להסתכם ב 100.

<column>
    <_attribute>At Home</_attribute>
    <_longname>Working at Home</_longname>
    <size>6</size>
</column>

Note The underscore is important and indicates that the text should be translated by translators.

Each form element may optionally contain heading elements. Heading elements describe information that is recorded once for each form.

A heading element contains:

• An _attribute element. This contains the key used to store information in the attributes of the event objects within the Gramps database.

<heading>
    <_attribute>City or Borough</_attribute>
</heading>

Although you can add your definitions to the pre-defined entries in form_xx.xml, it is recommended you create a separate file called custom.xml or test.xml for this purpose.

ניפוי־תקלים

לאחר יצירה או עדכון טופס (custom.xml או test.xml) חשוב לוודא שהטופס עוצב נכון, לשם כך יש להשתמש בעורך מלל שתומך במצב XML ובדיקת תחביר , (כמו NotePad++ או חלופה דומה למערכות הפעלה דמויי יוניקס) ולהתקין תוסף "כלי XML", העורך יתריע אם קוד ה־XML בטופס לא עוצב כראוי.

לאחר שבדיקות טופס ה־XML (test.xml) עברו באופן תקין, אפשר לאתחל את גרמפס כדי לבדוק את ביצועי הטופס. ולחצנים חדש ועריכה לא מופיעים בחלון גרמפלט טפסים, סיכוי סביר שקיימת שגיאת תחביר XML (או שגיאה אחרת). גרמפלט טפסים לא מדווח על מיקום השגיאה בקוד, אך למרבה המזל היא עשויה להופיע בהודעת grampsXX.log (שורש ספריית משתמש גרמפס) שתראה בערך כך:

 
Traceback (most recent call last):
  File "C:\Program Files\GrampsAIO64-5.1.2\gramps\gen\plug\_manager.py", line 252, in load_plugin
    _module = self.import_plugin(pdata)
  ...
  ...
  File "C:\Users\<~username>\AppData\Roaming\gramps\gramps51\plugins\Form\form.py", line 114, in __load_definitions
    dom = xml.dom.minidom.parse(definition_file)
  File "AIO/xml/dom/minidom.py", line 1958, in parse
  File "AIO/xml/dom/expatbuilder.py", line 911, in parse
  File "AIO/xml/dom/expatbuilder.py", line 207, in parseFile xml.parsers.expat.ExpatError: mismatched tag: line 12, column 10

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

  25285: ERROR: grampsapp.py: line 157: Unhandled exception 
  ...
  ...
  File "C:\Users\<~username>\AppData\Roaming\gramps\gramps51\plugins\Form\editform.py", line 995, in __init__
    title1, title2 = title.split('/')
ValueError: not enough values to unpack (expected 2, got 1)

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