View source for Quick Views/he

<div dir="rtl" lang="he" class="mw-content-rtl">
{{languages/he|Quick Views}}
[[File:QuickViewReport-EditPerson-context-menu-popup-default-60.png|thumb|left|450px|תפריט הקשר מצג מהיר בעורך אדם]]

מצגים מהירים (בעבר נקראו ''דוחות מהירים'' אך עדין מופיעים ב"עדכוני תוספים זמינים" כ''דוח מהיר'') הם דוחות אליהם ניתן להגיע מתפריטי ההקשר של:  אנשים, משפחות וכדומה'. קיימת קבוצה של [[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_8/he#מצגים_מהירים|מצגים מהירים מובנים]] אותה ניתן להרחיב באמצעות תוספים מסוג QuickView.

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

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

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

נלווה לכלי זה, נבנתה גם [[Simple Access API/he|גישה פשוטה למסד נתונים (API)]] וממשק מסמכים פשוט, כדי להסיר מורכבויות עד כמה שניתן.

==אחסון מצגים מהירים שנוצרו באופן אישי==
מצגים מהירים מורכבים בדרך כלל משני קבצים בתת מחיצה יעודית עבורם, שממוקמים במחיצת התוספים של ה''[[Gramps_{{man version}}_Wiki_Manual_-_User_Directory/he|משתמש]]''. הנתיב למחיצה זו במערכות הפעלה דמויי לינוקס הוא '''/home/[user_name]/.gramps'''. במחיצה זו תמצא מחיצת משנה בשם '''plugins'''. על מנת שתוסף המצג המהיר המותאם אישית יופיע בגרמפס, יש לשמור את הקבצים במחיצה זו.
אל המחיצה ניתן להגיע ממסוף באופן הבא 
(כאשר XX מציין את הגרסה המותקנת במחשב):<br>
<div dir="ltr">
 cd ~/.gramps/grampsxx/plugins
</div>
* לקריאה נוספת [[Gramps_{{man version}}_Wiki_Manual_-_User_Directory/he| במערכות ההפעלה השונותנספח ד' במדריך הויקי – מחיצת משתמש]]

==דוגמה==
===קוד===
[[File:QuickViewReport-people-context-menu-popup-50.png|thumb|left|450px|תפריט הקשר מצג מהיר בסוג־אב במצג אדם]]

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

פלט דוח מהיר יראה כך:
[[File:QuickViewReport-Siblings-example-60.png|thumb|left|450px|פלט תוצאת מצג מהיר לדוגמה]]
{{-}}
<span id="siblings.gpr.py"></span>
==== siblings2.gpr.py ====
תחילה נדרש לייצור קובץ רישום בגרמפס  (<code>*.gpr.py</code>), הרישום לגרמפס נדרש כדי שגרמפס יזהה את הדוח. הרישום מתבצע על ידי יצירת קובץ פיתון בשם <code>Siblings.gpr.py</code> ולהוסיף לתוכו את התוכן הבא:
<div dir="ltr">
<pre>
#------------------------------------------------------------------------
# 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'
  )
</pre>
</div>
<span id="siblings.py"></span>
את הקובץ יש לשמור במחיצה כפי שתואר במקטע שלעיל שמתאר [[#היכן לאחסן מצגים מהירים שיצרתי|היכן לשמור את הקבצים]].

==== siblings2.py ====
לאחר רישום המצג המהיר בגרפס, אפשר לייצור את הקובץ שמכיל את הקוד שנכתב בשפת פיתון. לשם כך יש לייצר קובץ פיתון  נוסף בשם <code>siblings.py</code> ולהוסיף לתוכו את התוכן הבא ולשמור את הקובץ באותה מחיצה בה נשמר קובץ הרישום בגרמפס:
<div dir="ltr">
<pre>
#------------------------------------------------------------------------
# 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)
</pre>
</div>
===ניתוח הקוד: רישום הדוח===

כעת ננתח את קטעי הקוד השונים שנכללו בשני הקבצים שנשמרו קודם לכן.<br>
1. קובץ הרישום [[Quick_Views/he#siblings2.gpr.py|siblings2.gpr.py]] .  גרמפס יחפש בקובץ הרישום את הפונקציה '''register''' שמופיעה בתחתית הקובץ.  
להלן פירוט והסבר על שאר שורות קוד קובץ הרישום:
* {{man label|name}} = שם ייחודי: שם שבו יזהה גרמפס את המתקע (במקרה זה זהו דוח המצג המהיר), אין להשתמש ברווחים או בסמלים מוזרים. בדוגמה שלעיל נוספה לשם הסיפרה '2'  כדי למנוע התנגשויות עם [[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_8/he#צאצאים|מצג צאצאים מהיר]].
* [https://github.com/gramps-project/gramps/blob/892fc270592095192947097d22a72834d5c70447/gramps/gen/plug/_pluginreg.py#L159-L171 {{man label|סוג־אב}}] = קבוע מיוחד שמציין היכן יוצג הדוח. ניתן להשתמש ב־'''CATEGORY_QR_PERSON''' כדי לצפות בדוח בעורך מצג אדם, או '''CATEGORY_QR_FAMILY''' כדי לצפות בדוח בעורך מצג משפחה. (CATEGORY_QR_DATE מיועד לדוחות שניתן להטמיע בתוך דוחות אחרים מכיוון שלא קיים סוג־אב "תאריך").
* {{man label|run_func}} = היא הפונקציה אותה מייצרים בתוסף זה ואותה יבצע גרמפס כאשר משתמש יבחר את הדוח המהיר הזה מתפריט ההקשר.
* [https://github.com/gramps-project/gramps/blob/892fc270592095192947097d22a72834d5c70447/gramps/gen/plug/_pluginreg.py#L58-L69 {{man label|מצב}}] =מצב הדוח שנוצר ''', '''לא יציב''', ''יציב''', '''ניסוי''' או '''בטא'''
* {{man label|translated_name}} = שם הדוח כפי שיופיע בתפריט
* {{man label|description}} = תיאור קצר על התוסף ומטרתו. יופיע כרמז צץ  מעל התפריט
* {{man label|author_name}} = שם יוצר המתקע
* {{man label|author_email}}= דוא"ל יוצר המתקע, כדי שמשתמשים יוכלו לשלוח את ברכתם, או לבקש תיקוני תקלים והצעות לשינויים...

החל בגירסת גרמפס 5.2 נוספו מספר מאפייני [https://github.com/gramps-project/gramps/pull/1451 רישום] חדשים: 
* {{man label|help_url}} = עמוד המרשתת שייפתח בעת השימוש בעזרה
* [https://github.com/gramps-project/gramps/blob/892fc270592095192947097d22a72834d5c70447/gramps/gen/plug/_pluginreg.py#L71-L76 {{man label|audience}}] = 'קהל יעד, אפשרויות סינון: 'כולם', 'מפתחים' ו'מומחים.
* {{man label|maintainers}} = שם האדם שמתחזק כעת את התוסף, במידה ששונה מ־author_name
* {{man label|maintainers_email}} = דוא"ל של האדם שמתחזק כעת את התוסף, במידה ששונה מכתובת author_email
* [https://github.com/gramps-project/gramps/blob/892fc270592095192947097d22a72834d5c70447/gramps/gen/plug/_pluginreg.py#L297-L299 {{man label|requires_mod}}], [https://github.com/gramps-project/gramps/blob/892fc270592095192947097d22a72834d5c70447/gramps/gen/plug/_pluginreg.py#L300-L303 {{man label|requires_gi}}], [https://github.com/gramps-project/gramps/blob/892fc270592095192947097d22a72834d5c70447/gramps/gen/plug/_pluginreg.py#L304-L306 {{man label|requires_exe}}]  = האם קיימות דרישות קדם לתוסף.

===ניתוח הקוד: פונקציית הריצה===

2. קובץ הריצה [[Quick_Views/he#siblings.py|siblings.py]].

כאשר משתמש מקיש על דוח מצג מהיר בתפריט ההקשר, פונקציית הריצה תתבצע עם שלושת המשתנים הבאים:
<div dir="ltr">
<code>run(database, document, person)</code>
</div>
כלומר, הדוח מקבל מגרמפס את המשתנים: שם מסד הנתונים שפתוח כעת ונמצע בעבודה, את המסמך עליו יש לכתוב, ואת ה'אדם' של שמקושר לעצם שבמוקד המשתמש (עליו מונח מצביע העכבר). לדוח מצג מהיר 'אדם', זהו אדם, ובהתאמה לדוח מצג מהיר 'משפחה',  זוהי משפחה.

בדוגמה זו, הפונקציה שתקרא היא:
<div dir="ltr">
<code>def run(database, document, person):</code>
</div>

===ניתוח קטע קוד: גישה לנתונים===
לאחר השלמת פונקציית הקיצה של המצג המהיר, ניתן לטפל בפתיחת מסד הנתונים, הפעלת המסמך, גישה לנתונים וכתיבתם על המסמך. פעולות אלו מתבצעות באמצעות [[Simple Access API/he|מנשק  API גישה פשוטה למסד הנתונים]].

קטע הקוד הבא מכין את כל שנדרש לפעולת הנמנשק:
<div dir="ltr">
<pre>
# setup the simple access functions
sdb = SimpleAccess(database)
sdoc = SimpleDoc(document)
</pre>
</div>
כעת ניתן לטפל בכותרת שתופיע על המסמך: שורת כותרת , שורה ריקה מתחת לשורת הכותרת וכותרת עליונה, באמצעות פונקציית הכותרת, הפסקה וראש העמוד:
<div dir="ltr">
<pre>
# display the title
sdoc.title(_("Siblings of %s") % sdb.name(person))
sdoc.paragraph("")
</pre>
</div>
לתשומת לב! קו תחתון (<code>_</code>) מציין מחרוזת שמצריכות תרגום, מחרוזות אלו ניתנות לשליפה לתוך קובץ &lrm;.pot וזה מגיע מהשורה:
<div dir="ltr">
<pre>
from gramps.gen.ggettext import gettext as _
</pre>
</div>
לאחר שכל ההדגרות הסתיימו, ניתן לגשת לקטע הקוד שיכתוב את השורות עם כל האחאים, את האדם הפעיל עצמו לא כוללים, שכן הוא מופיע בשדה הכותרת!
<div dir="ltr">
<pre>

# 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)
</pre>
</div>
כאן נעשה שימוש במחלקות הגישה הקלה מ־[[Simple Access API/he|מנשק  API גישה פשוטה למסד הנתונים]] כדי להשיג במהירות את המטרה ללא הצורך לכתוב שורות קוד רבות נוספות.

==דוגמה שניה==

דוגמה שנייה ניתן למצוא בקוד גרמפס עצמו. לקריאה נוספת [https://github.com/gramps-project/gramps/blob/master/gramps/plugins/quickview/all_events.py all_events.py]. בדוח זה מודפסים כל האירועים לאדם וכל האירועים למשפחה. לפיכך נרשמים שני דוחות מהירים, אחד לאדם ואחד למשפחה.

==הערות==

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

לקריאה נוספת: [https://github.com/gramps-project/gramps/tree/master/gramps/plugins/quickview מצג מהיר]

=לקריאה נוספת=
* [[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_8/he#מצגים_מהירים|מצגים מהירים]]

[[Category:He:פתוח]]
[[Category:He:תיעוד]]
[[Category:He:תוספים]]
[[Category:He:דוחות]]
[[Category:He:מצגים]]