Quick Views

From Gramps
Revision as of 04:24, 3 March 2012 by Romjerome (Talk | contribs)

Jump to: navigation, search

Quick reports are reports that are available in the context menu's of person, family, ...

They are easy to make by users, even with limited coding knowledge.

Introduction

Quick Report context menu on Person Editor

Many users want to produce a report quickly for their specific needs, but are hindered by the fact they do not want to learn python fully, nor the intricacies of a complicated program like GRAMPS.

For them, starting in GRAMPS 3.0 a new tool has been constructed: the quick reports. These reports are short textual reports that the user can register with GRAMPS, so they automatically appear in the context menu's. Accompanying this, a simple database access and simple document interface has been constructed, so as to hide as much complexity as possible.

Where to store my quick report

A quick report is one single file. You can store it in your plugins directory. Go into your home folder and go to the hidden directory .gramps. In this directory you will find the plugins directory. Just add your plugin there, and it will appear within GRAMPS.

For the terminal users, you can get there as follows:

cd ~/.gramps/grampsxx/plugins

Example 1

Code

Quick Report context menu on Person View

How better than to learn something than using an example? Here it goes. We want a report to show all siblings of a person. That is, brothers and sisters from all families the person is part of. The quick report is then the following:

  26 from Simple import SimpleAccess, SimpleDoc
  27 from gettext import gettext as _
  28 from PluginUtils import register_quick_report
  29 from ReportBase import CATEGORY_QR_PERSON
  30 
  31 # define the formatting string once as a constant. Since this is reused
  32 
  33 __FMT = "%-30s\t%-10s\t%s"
  34 
  35 def run(database, document, person):
  36     """
  37     Loops through the families that the person is a child in, and display
  38     the information about the other children.
  39     """
  40 
  41     # setup the simple access functions
  42     sdb = SimpleAccess(database)
  43     sdoc = SimpleDoc(document)
  44 
  45     # display the title
  46     sdoc.title(_("Siblings of %s") % sdb.name(person))
  47     sdoc.paragraph("")
  48 
  49     # display the header of a table
  50     sdoc.header1(__FMT % (_("Sibling"), _("Gender"), _("Birth Date")))
  51 
  52     # grab our current id, so we can filter the active person out
  53     # of the data
  54 
  55     gid = sdb.gid(person)
  56 
  57     # loop through each family in which the person is a child
  58     for family in sdb.child_in(person):
  59 
  60         # loop through each child in the family
  61         for child in sdb.children(family):
  62 
  63             # only display if this child is not the active person
  64             if sdb.gid(child) != gid:
  65                 sdoc.paragraph(__FMT % (
  66                         sdb.name(child),
  67                         sdb.gender(child),
  68                         sdb.birth_date(child)))
  69 
  70 #------------------------------------------------------------------------
  71 #
  72 #
  73 #
  74 #------------------------------------------------------------------------
  75 register_quick_report(
  76     name = 'a_unique_name_with_no_spaces',
  77     category = CATEGORY_QR_PERSON,
  78     run_func = run,
  79     translated_name = _("Siblings"),
  80     status = _("Stable"),
  81     description= _("Display a person's siblings."),
  82     author_name="your name",
  83     author_email="your email"
  84     )

Analysis: registering the report

The above code is GPL licensed, written by Don. Let's analyse this. We start at the bottom where the report is registered with register_quick_report. This is the function GRAMPS will look for in your file. You need to give:

  • name = a unique name: a name GRAMPS identifies the plugin with, don't use spaces or strange symbols.
  • category = a special constant indicating where the report will be shown. You can use CATEGORY_QR_PERSON to see the report on person editor and view, or CATEGORY_QR_FAMILY to see the report on family editor or view.
  • 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 or Unstable. Not used at the moment. On distributing GRAMPS we only include stable reports.
  • 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...

Analysis: the run function

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

run_function(database, document, handle)

So, your report recieved from gramps the database on which to work, the document on which to write, and the handle (=unique identifier) of the object the user is on. For a person quick report, this is a person handle, for family, a family handle.


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,

  41     # setup the simple access functions
  42     sdb = SimpleAccess(database)
  43     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:

 45     # display the title
 46     sdoc.title(_("Siblings of %s") % sdb.name(person))
 47     sdoc.paragraph("")
 49     # display the header of a table
 50     sdoc.header1(__FMT % (_("Sibling"), _("Gender"), _("Birth Date")))

Note that we use _ for every string for translation, which comes from the line

 27 from gettext import gettext as _

You can replace this by

 46     sdoc.title("Siblings of %s" % sdb.name(person))

to just try it out for yourself, without a translation option.

As we will write a list, it is usefull to define the structure of your text one time, and reuse this. That is the __FMT constant, defined as

 33 __FMT = "%-30s\t%-10s\t%s"

So we have 30 spaces for the Sibling field, then a tab (\t), then 10 spaces for the Gender, another tab and the last stringfield for the birth date.

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!

  52     # grab our current id, so we can filter the active person out
  53     # of the data
  54 
  55     gid = sdb.gid(person)
  56 
  57     # loop through each family in which the person is a child
  58     for family in sdb.child_in(person):
  59 
  60         # loop through each child in the family
  61         for child in sdb.children(family):
  62 
  63             # only display if this child is not the active person
  64             if sdb.gid(child) != gid:
  65                 sdoc.paragraph(__FMT % (
  66                         sdb.name(child),
  67                         sdb.gender(child),
  68                         sdb.birth_date(child)))

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

Example 2

A second example can be found in the GRAMPS code. See all_events.py. In this report, all events for a person are printed, and all events for a family. Two quick reports are hence registered, one for person, and one for family.

Notes

The possibilities are enormous. If you are an experienced hacker, there is no need to limit yourself to the simple database API. Also, if you make a real report, you can at the same time register a quick report with default settings.