4,862
edits
Changes
m
GRAMPS Gramps attempts to abstract the output document format away from the report. By coding to the [http://packages.python.org/Gramps/gen/gen_plug.html#module-gen.plug._docgenplugin docgen] class, the report can generate its output in the format desired by the end user. The document passed to the report (<tt>self.doc</tt>) could represent an HTML, OpenDocument, PDF or any of the other formats supported by the user. The report does not have to concern itself with the output format details, since all details are handled by the document object.
def write_report(self): self.doc.start_paragraph("ABC-Title") self.doc.write_text(_("Some text")) self.doc.end_paragraph()
class OptionsClassName(ReportOptions): def __init__(self,name,person_id=None): ReportOptions.__init__(self,name,person_id)
def set_new_options(self): # Options specific for this report self.options_dict = { 'my_fist_option' : 0, 'my_second_option' : '', } self.options_help = { 'my_fist_option' : ("=num","Number of something", [ "First value", "Second value" ], True), 'my_second_option' : ("=str","Some necessary string for the report", "Whatever String You Wish"), }
def enable_options(self): # Semi-common options that should be enabled for this report self.enable_dict = { 'filter' : 0, }
def add_user_options(self,dialog): option_menu = gtk.OptionMenu() self.the_menu = gtk.Menu()
for item_index in range(10): item = _("Item numer %d") % item_index menuitem = gtk.MenuItem(item) menuitem.show() self.the_menu.append(menuitem)
option_menu.set_menu(self.the_menu) option_menu.set_history(self.options_dict['my_first_option'])
dialog.add_option(_('My first option'),option_menu)
self.the_string_entry = gtk.Entry() if self.options_dict['my_second_option']: self.the_string_entry.set_text(self.options_dict['my_second_option']) else: self.the_string_entry.set_text(_("Empty string")) self.the_string_entry.show() dialog.add_option(_('My second option'),self.the_string_entry)
def parse_user_options(self,dialog): self.options_dict['my_second_option'] = unicode(self.the_string_entry.get_text()) self.options_dict['my_first_option'] = self.the_menu.get_history()
def make_default_style(self, default_style): f = docgen.FontStyle() f.set_size(10) f.set_type_face(docgen.FONT_SANS_SERIF) p = docgen.ParagraphStyle() p.set_font(f) p.set_description(_("The style used for the person's name.")) default_style.add_style("ABC-Name",p)
def add_menu_options(self, menu): """ Add options to the menu for this report. """ category_name = _("Report Options") what_types = BooleanListOption(_('Select From:')) what_types.add_button(_('People'), True) what_types.add_button(_('Families'), False) what_types.add_button(_('Places'), False) what_types.add_button(_('Events'), False) menu.add_option(category_name, "what_types", what_types)
Gramps
{{languages}}
This tutorial covers the basics of writing a simple report using the GRAMPS Gramps report infrastructure. It covers the process of handling options, building a document and creating the report.
The goals of this report are to create a database summary report. It will include the following information in the report:
===report.py===
;Report class : This is the code that takes data from the GRAMPS Gramps database and organizes it into the document structure. This structure can later be printed, viewed, or written into a file in a variety of formats. This class uses the [http://packages.python.org/Gramps/gen/gen_plug.html#module-gen.plug._docgenplugin docgen] interface to abstract away the output format details.
;Options class : This is the code that provides means to obtain options necessary for the report using a variety of available mechanisms.
===report.gpr.py===
;Registration statement : This initializes the report by a single call to the <tt>register()</tt> function. It is trivial, but without it your report will not become available to GRAMPSGramps, even if it is otherwise perfectly written.
A report can potentially be generated as a standalone report, as a GRAMPS Gramps Book item, and as a command line report. The registration determines which modes are enabled for a given report. The report class does not have to know anything about the mode. The options class is there to provide options interface for all available modes.
==Document interface==
A document is composed of paragraphs, tables, and graphics objects. Tables and graphics objects will not be covered in this tutorial.
===Report class===
The user's report class should inherit from the Report class contained within the Report module. The constructor should take three arguments (besides class instance itself, usually denoted by 'self' name):
* GRAMPS Gramps database instance
* options class instance
* user class instance
Report class '''must''' provide a <tt>write_report()</tt> method. This method should dump the report's contents into the already opened document instance.
<pre>
</pre>
The rest of the report class is pretty much up to the report writer. Depending on the goals and the scope of the report, there can be any amount of code involved. When the user generates the report in any mode, the class constructor will be run, and then the <tt>write_report()</tt> method will be called. So if you wrote that beautiful method listing something really important, make sure it is eventually called from within the <tt>write_report()</tt>. Otherwise nobody will see it unless looking at the code.
====Using ReportOptions====
<pre>
</pre>
* It should set new options that are specific for this report, by overriding the <tt>set_new_options()</tt> method which defines <tt>options_dict</tt> and <tt>options_help</tt> dictionaries:
<pre>
</pre>
* It should also enable the "semi-common" options that are used in this report, by overriding the <tt>enable_options</tt> method which defines <tt>enable_dict</tt> dictionary. The semi-commons are the options which GRAMPS Gramps knows about, but which are not necessarily present in all reports:
<pre>
</pre>
All the common options are already taken care of by the core of GRAMPSGramps.
* For any new options set up in the options class, there must be defined UI widgets to provide means of changing these options through the dialogs. Also, there must be defined methods to extract values of these options from the widgets and to set them into the class-variable dictionary:
<pre>
</pre>
* Finally, the default definitions for the user-adjustable paragraph styles must be defined here, to form a 'default' stylesheet:
<pre>
</pre>
<pre>
</pre>
There are arguments for the report class and options class. The <tt>report_modes</tt> argument is set to a list of zero or more of the following modes:
* REPORT_MODE_GUI (available for GRAMPS Gramps running in a window, graphical user interface)
* REPORT_MODE_BKI (available as a book report item)
* REPORT_MODE_CLI (available for the command line interface)
