Quick Views/he

תפריט הקשר מצג מהיר בעורך אדם

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

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

מבוא

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

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

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

היכן לאחסן מצגים מהירים שיצרתי

מצגים מהירים מורכבים בדרך כלל משני קבצים בתת מחיצה יעודית עבורם, שממוקמים במחיצת התוספים של המשתמש. הנתיב למחיצה זו במערכות הפעלה דמויי לינוקס הוא /home/[user_name]/.gramps. במחיצה זו תמצא מחיצת משנה בשם plugins. על מנת שתוסף המצג המהיר המותאם אישית יופיע בגרמפס, יש לשמור את הקבצים במחיצה זו. אל המחיצה ניתן להגיע ממסוף באופן הבא (כאשר XX מציין את הגרסה המותקנת במחשב):

cd ~/.gramps/grampsxx/plugins

• לקריאה נוספת במערכות ההפעלה השונותנספח ד' במדריך הויקי – מחיצת משתמש

דוגמה

קוד

תפריט הקשר מצג מהיר בסוג־אב במצג אדם

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

פלט דוח מהיר יראה כך:

פלט תוצאת מצג מהיר לדוגמה

siblings2.gpr.py

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

#------------------------------------------------------------------------
# File: siblings.gpr.py
#------------------------------------------------------------------------

register(QUICKREPORT, 
    id    = 'siblings2',
    name  = _("Siblings2 - Example Quick View"),
    description =  _("Display a person's siblings."),
    version = '0.1',
    gramps_target_version = '5.2',
    status = STABLE,
    fname = 'siblings2.py',
    authors = ["שם היוצר כאן"],
    authors_email = ["כתובת @ דו"ל היוצר כאן"],
    category = CATEGORY_QR_PERSON,
    runfunc = 'run'
  )

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

siblings2.py

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

#------------------------------------------------------------------------
# File: siblings2.py
#------------------------------------------------------------------------

from gramps.gen.simple import SimpleAccess, SimpleDoc
from gramps.gui.plug.quick import QuickTable
from gramps.gen.const import GRAMPS_LOCALE as glocale
_ = glocale.translation.gettext

def run(database, document, person):
    """
    Loops through the families that the person is a child in, and display
    the information about the other children.
    """

    # setup the simple access functions
    sdb = SimpleAccess(database)
    sdoc = SimpleDoc(document)

    # display the title
    sdoc.title(_("Siblings of %s") % sdb.name(person))
    sdoc.paragraph("")

    # grab our current id, so we can filter the active person out
    # of the data

    gid = sdb.gid(person)


    stab = QuickTable(sdb)
    sdoc.header1(_("Siblings"))
    stab.columns(_("Person"), 
                 _("Gender"), 
                 _("Date"))

    # loop through each family in which the person is a child
    for family in sdb.child_in(person):

        # loop through each child in the family
        for child in sdb.children(family):

            # only display if this child is not the active person
            if sdb.gid(child) != gid:
                stab.row(child,
                        sdb.gender(child),
                        sdb.birth_date(child))
                document.has_data = True
    stab.write(sdoc)

ניתוח הקוד: רישום הדוח

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

1. קובץ הרישום siblings2.gpr.py . גרמפס יחפש בקובץ הרישום את הפונקציה register שמופיעה בתחתית הקובץ.

להלן פירוט והסבר על שאר שורות קוד קובץ הרישום:

• name = שם ייחודי: שם שבו יזהה גרמפס את המתקע (במקרה זה זהו דוח המצג המהיר), אין להשתמש ברווחים או בסמלים מוזרים. בדוגמה שלעיל נוספה לשם הסיפרה '2' כדי למנוע התנגשויות עם מצג צאצאים מהיר.
• סוג־אב = קבוע מיוחד שמציין היכן יוצג הדוח. ניתן להשתמש בCATEGORY_QR_PERSON כדי לצפות בדוח בעורך מצג אדם, או CATEGORY_QR_FAMILY כדי לצפות בדוח בעורך מצג משפחה. (CATEGORY_QR_DATE מיועד לדוחות שניתן להטמיע בתוך דוחות אחרים מכיוון שאין סוג־אב "תאריך").
• run_func = the function you create in this plugin and that Gramps will execute when the user selects your quick report in the menu
• translated_name = the name of the report as it will appear in the menu
• status = is your report Stable, Unstable, Experimental and Beta
• description = a description of what your plugin does. This appears in a tooltip over the menu
• author_name = your name
• author_email= your email, so people can congratulate you with your work, or ask for bug fixes...

And beginning with Gramps 5.2 version, there are additional registration properties:

• help_url = a webpage that will be opened when using the Help
• audience = filtering options: ‘All’, ‘Developer’ and ‘Expert’.
• maintainers = name of person currently maintaining the addon, if different from the author_name
• maintainers_email = email of person currently maintaining the addon, if different from the author_email
• requires_mod, requires_gi, requires_exe = if the addon has prerequisites.

Analysis: the run function

Now lets analyse the siblings.py file.

If the user clicks in the quick view report menu on your report, the run function is executed with the following three parameters:

run(database, document, person)

So, your report receives from Gramps the currently opened database name on which to work, the document on which to write, and the person of the object the user is on. For a person quick view report, this is a person, for family, a family.

In this example, the function called is

def run(database, document, person):

Analysis: accessing the data

Now that your plugin runs, you need to open the database, start the document, access data, and write it out. We do this using the Simple Database API.

So, the following code:

# setup the simple access functions
sdb = SimpleAccess(database)
sdoc = SimpleDoc(document)

prepares everything. Then we write a title on the document, an empty line under it, and a header, with the title, paragraph and header function:

# display the title
sdoc.title(_("Siblings of %s") % sdb.name(person))
sdoc.paragraph("")

Note that we use an underscore (_) to indicate every string that requires translation, which comes from the line:

from gramps.gen.ggettext import gettext as _

Everything is set up, now we write out the lines with all the siblings, leaving out the active person himself, as he is in the title field!

# grab our current id, so we can filter the active person out
# of the data

gid = sdb.gid(person)

# loop through each family in which the person is a child
for family in sdb.child_in(person):

    # loop through each child in the family
    for child in sdb.children(family):

        # only display if this child is not the active person
        if sdb.gid(child) != gid:
            stab.row(child,
                     sdb.gender(child),
                     sdb.birth_date(child))
            document.has_data = True
stab.write(sdoc)

Here, the easy access classes from the Simple Access API have been used to quickly achieve what we want.

דוגמה שניה

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

הערות

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

לקריאה נוספת: מצגים מהירים

לקריאה נוספת

• מצגים מהירים