Difference between revisions of "Quick Views"
(→Code: out of date... needs more fixing) |
(→Notes) |
||
(19 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
− | Quick reports are reports that are available in the context menu's of person, family, ... | + | Quick Views (previously called ''Quick reports'' but show up in "Available Gramps Update for Addons" as ''Quickreport'') 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. | They are easy to make by users, even with limited coding knowledge. | ||
+ | |||
+ | [[Image:GrampsQuickViewReportEdit-40.png|thumb|right|400px|Quick View context menu on Person Editor]] | ||
==Introduction== | ==Introduction== | ||
− | + | 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. | |
− | 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 | + | |
+ | For them, starting in Gramps 3.0 a new tool has been constructed: the Quick Views. 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 Access API|simple database access]] and simple document interface has been constructed, so as to hide as much complexity as possible. | Accompanying this, a [[Simple Access API|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== | ==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 | + | 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: | For the terminal users, you can get there as follows: | ||
Line 20: | Line 20: | ||
==Example 1== | ==Example 1== | ||
===Code=== | ===Code=== | ||
− | [[File: | + | [[File:QuickViewReport-people-context-menu-popup-41.png|thumb|right|400px|Quick View context menu on Person View]] |
− | [[File:Siblings quick report result.png|thumb|right| | + | [[File:Siblings quick report result.png|thumb|right|400px|Quick View Report example result output]] |
How better than to learn something than using an example? | How better than to learn something than using an example? | ||
Line 37: | Line 37: | ||
<pre> | <pre> | ||
+ | #------------------------------------------------------------------------ | ||
# File: Siblings.py | # File: Siblings.py | ||
#------------------------------------------------------------------------ | #------------------------------------------------------------------------ | ||
+ | |||
from gramps.gen.simple import SimpleAccess, SimpleDoc | from gramps.gen.simple import SimpleAccess, SimpleDoc | ||
− | from | + | from gramps.gui.plug.quick import QuickTable |
− | from | + | from gramps.gen.ggettext import gettext as _ |
− | |||
− | |||
− | |||
− | |||
− | |||
def run(database, document, person): | def run(database, document, person): | ||
Line 61: | Line 58: | ||
sdoc.title(_("Siblings of %s") % sdb.name(person)) | sdoc.title(_("Siblings of %s") % sdb.name(person)) | ||
sdoc.paragraph("") | sdoc.paragraph("") | ||
− | |||
− | |||
− | |||
# grab our current id, so we can filter the active person out | # grab our current id, so we can filter the active person out | ||
Line 69: | Line 63: | ||
gid = sdb.gid(person) | 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 | # loop through each family in which the person is a child | ||
Line 78: | Line 79: | ||
# only display if this child is not the active person | # only display if this child is not the active person | ||
if sdb.gid(child) != gid: | if sdb.gid(child) != gid: | ||
− | + | stab.row(child, | |
− | |||
sdb.gender(child), | sdb.gender(child), | ||
− | sdb.birth_date(child))) | + | sdb.birth_date(child)) |
+ | document.has_data = True | ||
+ | stab.write(sdoc) | ||
+ | </pre> | ||
+ | You will also need a Gramps registration file: | ||
+ | |||
+ | <pre> | ||
#------------------------------------------------------------------------ | #------------------------------------------------------------------------ | ||
− | # | + | # File: Siblings.gpr.py |
− | |||
− | |||
#------------------------------------------------------------------------ | #------------------------------------------------------------------------ | ||
− | register( | + | |
− | name = ' | + | register(QUICKREPORT, |
+ | id = 'siblings', | ||
+ | name = _("Siblings"), | ||
+ | description = _("Display a person's siblings."), | ||
+ | version = '1.0', | ||
+ | gramps_target_version = '4.1', | ||
+ | status = STABLE, | ||
+ | fname = 'siblings.py', | ||
+ | authors = ["Donald N. Allingham"], | ||
+ | authors_email = ["[email protected]"], | ||
category = CATEGORY_QR_PERSON, | category = CATEGORY_QR_PERSON, | ||
− | + | runfunc = 'run' | |
− | + | ) | |
− | |||
− | |||
− | |||
− | |||
− | |||
</pre> | </pre> | ||
===Analysis: registering the report=== | ===Analysis: registering the report=== | ||
− | + | ||
− | Let's analyse | + | Let's analyse the above. We start at the bottom where the report is registered with '''register'''. This is the function Gramps will look for in your file. You need to give: |
− | *{{man label|name}} = a unique name: a name | + | *{{man label|name}} = a unique name: a name Gramps identifies the plugin with, don't use spaces or strange symbols. |
*{{man label|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. | *{{man label|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. | ||
− | *{{man label|run_func}} = the function you create in this plugin and that | + | *{{man label|run_func}} = the function you create in this plugin and that Gramps will execute when the user selects your quick report in the menu |
* {{man label|translated_name}} = the name of the report as it will appear in the menu | * {{man label|translated_name}} = the name of the report as it will appear in the menu | ||
− | * {{man label|status}} = is your report '''Stable''' or '''Unstable'''. Not used at the moment. On distributing | + | * {{man label|status}} = is your report '''Stable''' or '''Unstable'''. Not used at the moment. On distributing Gramps we only include stable reports. |
*{{man label|description}} = a description of what your plugin does. This appears in a tooltip over the menu | *{{man label|description}} = a description of what your plugin does. This appears in a tooltip over the menu | ||
*{{man label|author_name}} = your name | *{{man label|author_name}} = your name | ||
Line 113: | Line 121: | ||
===Analysis: the run function=== | ===Analysis: the run function=== | ||
+ | |||
If the user clicks in the quick report menu on your report, the run function is executed with three parameters: | If the user clicks in the quick report menu on your report, the run function is executed with three parameters: | ||
<center> | <center> | ||
− | ''' | + | '''run(database, document, person)''' |
</center> | </center> | ||
− | So, your report received from gramps the database on which to work, the document on which to write, and the | + | So, your report received from gramps the database on which to work, the document on which to write, and the person of the object the user is on. For a person quick report, this is a person, for family, a family. |
− | |||
In this example, the function called is | In this example, the function called is | ||
Line 126: | Line 134: | ||
===Analysis: accessing the data=== | ===Analysis: accessing the data=== | ||
− | Now that your plugin runs, you need to open the database, start the document, access data, and write it out. | + | 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 Access API|Simple Database API]]. So, |
− | We do this using the [[Simple Access API|Simple Database API]]. So, | + | |
<pre> | <pre> | ||
# setup the simple access functions | # setup the simple access functions | ||
Line 133: | Line 141: | ||
sdoc = SimpleDoc(document) | sdoc = SimpleDoc(document) | ||
</pre> | </pre> | ||
+ | |||
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: | 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: | ||
+ | |||
<pre> | <pre> | ||
# display the title | # display the title | ||
sdoc.title(_("Siblings of %s") % sdb.name(person)) | sdoc.title(_("Siblings of %s") % sdb.name(person)) | ||
sdoc.paragraph("") | sdoc.paragraph("") | ||
− | |||
− | |||
</pre> | </pre> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | Note that we use '''_''' for every string for translation, which comes from the line: | |
+ | |||
<pre> | <pre> | ||
− | + | from gramps.gen.ggettext import gettext as _ | |
</pre> | </pre> | ||
− | |||
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! | 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! | ||
+ | |||
<pre> | <pre> | ||
# grab our current id, so we can filter the active person out | # grab our current id, so we can filter the active person out | ||
Line 172: | Line 172: | ||
# only display if this child is not the active person | # only display if this child is not the active person | ||
if sdb.gid(child) != gid: | if sdb.gid(child) != gid: | ||
− | + | stab.row(child, | |
− | + | sdb.gender(child), | |
− | + | sdb.birth_date(child)) | |
− | + | document.has_data = True | |
+ | stab.write(sdoc) | ||
</pre> | </pre> | ||
Line 181: | Line 182: | ||
==Example 2== | ==Example 2== | ||
− | A second example can be found in the | + | |
+ | A second example can be found in the Gramps code. See [https://github.com/gramps-project/gramps/blob/master/gramps/plugins/quickview/all_events.py 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== | ==Notes== | ||
− | The possibilities are enormous. If you are an experienced | + | The possibilities are enormous. If you are an experienced programmer, 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. |
+ | |||
+ | See: [https://github.com/gramps-project/gramps/tree/master/gramps/plugins/quickview https://github.com/gramps-project/gramps/tree/master/gramps/plugins/quickview] | ||
[[Category:Developers/General]] | [[Category:Developers/General]] |
Revision as of 00:53, 8 July 2015
Quick Views (previously called Quick reports but show up in "Available Gramps Update for Addons" as Quickreport) 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.
Contents
Introduction
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 Views. 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
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:
Create a python file named Siblings.py and add the following content:
This page's factual accuracy may be compromised due to out-of-date information. Please help improve the Gramps Wiki as a useful resource by updating it. |
#------------------------------------------------------------------------ # File: Siblings.py #------------------------------------------------------------------------ from gramps.gen.simple import SimpleAccess, SimpleDoc from gramps.gui.plug.quick import QuickTable from gramps.gen.ggettext import gettext as _ 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)
You will also need a Gramps registration file:
#------------------------------------------------------------------------ # File: Siblings.gpr.py #------------------------------------------------------------------------ register(QUICKREPORT, id = 'siblings', name = _("Siblings"), description = _("Display a person's siblings."), version = '1.0', gramps_target_version = '4.1', status = STABLE, fname = 'siblings.py', authors = ["Donald N. Allingham"], authors_email = ["[email protected]"], category = CATEGORY_QR_PERSON, runfunc = 'run' )
Analysis: registering the report
Let's analyse the above. We start at the bottom where the report is registered with register. 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(database, document, person)
So, your report received from gramps the database on which to work, the document on which to write, and the person of the object the user is on. For a person quick 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,
# 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 _ for every string for 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.
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 programmer, 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.
See: https://github.com/gramps-project/gramps/tree/master/gramps/plugins/quickview