Report-writing tutorial

From Gramps
Revision as of 15:44, 3 January 2008 by Romjerome (talk | contribs) (Overview)
Jump to: navigation, search

Introduction

This tutorial covers the basics of writing a simple report using the 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:

  • The number of people in the database
  • The number of males and females
  • The number of unique surnames.
  • The most common surname

As of version 3.0, also a simple access database API is available, with accompanying Quick Reports.

Overview

Before going into details, it is useful to note that the report should have three basic parts:

Report class 
This is the code that takes data from the 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 BaseDoc 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.
Registration statement 
This is a single call to register_report() function in the PluginMgr --> 404 Not Found <-----Glh 10:32, 3 January 2008 (EST) module. It is trivial, but without it your report will not become available to GRAMPS, even if it is otherwise perfectly written.

A report can potentially be generated as a standalone report, as a 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

GRAMPS attempts to abstract the output document format away from the report. By coding to the BaseDoc --> 404 Not Found <-----Glh 10:32, 3 January 2008 (EST) class, the report can generate its output in the format desired by the end user. The document passed to the report (self.doc) 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.

A document is composed of paragraphs, tables, and graphics objects. Tables and graphics objects will not be covered in this tutorial.

The report defines a set of paragraph and font styles, along with their default implementation. The user can override the definition of each style, allowing the user to customize the report. Each paragraph style must be named uniquely, to prevent collisions when printed in a book format. It is recommended to prefix each paragraph style with a three letter code unique to the report.

Paragraph and font styles are defined in the make_default_style() function of the options class. The paragraphs are grouped into a StyleSheet, which the make_default_style() function defines. For the example report (DbSummary), the paragraph styles are defined as below:

    def make_default_style(self, default_style):

        # Define the title paragraph, named 'DBS-Title', which uses a
        # 18 point, bold Sans Serif font with a paragraph that is centered

        font = BaseDoc.FontStyle()
        font.set_size(18)
        font.set_type_face(BaseDoc.FONT_SANS_SERIF)
        font.set_bold(True)

        para = BaseDoc.ParagraphStyle()
        para.set_header_level(1)
        para.set_alignment(BaseDoc.PARA_ALIGN_CENTER)
        para.set_font(font)
        para.set_description(_('The style used for the title of the page.'))

        default_style.add_style('DBS-Title',para)

        # Define the normal paragraph, named 'DBS-Normal', which uses a
        # 12 point, Serif font.

        font = BaseDoc.FontStyle()
        font.set_size(12)
        font.set_type_face(BaseDoc.FONT_SERIF)

        para = BaseDoc.ParagraphStyle()
        para.set_font(font)
        para.set_description(_('The style used for normal text'))

        default_style.add_style('DBS-Normal',para)

Defining the classes

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 database instance
  • Person object instance
  • options class instance

The first is the database to work with. The second is the person on whom the report is centered. The third is the instance of the options class defined in the same report, see next section. Here's an example of a report class definition:

  from ReportBase import Report, ReportUtils, ReportOptions

  class ReportClassName(Report):
      def __init__(self,database,person,options_class):
          Report.__init__(self,database,person,options_class)

The Report class's constructor will initialize several variables for the user based off the passed values. They are:

self.doc 
The opened document instance ready for output. This is of the type BaseDoc --> 404 Not Found <----Glh 10:32, 3 January 2008 (EST), and is not a normal file object.
self.start_person 
The Person instance containing the start or center person (the person selected) when the report was called.
self.database 
The GrampsDbBase database object
self.options_class 
The ReportOptions class passed to the report

Anything else the report class needs in order to produce the report should be obtained from the options_class object. For example, you may need to include the additional code in the report class constructor to obtain any options you defined for the report.

Report class must provide a write_report method. This method should dump the report's contents into the already opened document instance.

      def write_report(self):
          self.doc.start_paragraph("ABC-Title")
          self.doc.write_text(_("Some text"))
          self.doc.end_paragraph()

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 write_report() method will be called. So if you wrote that beautiful method listing something really important, make sure it is eventually called from within the write_report(). Otherwise nobody will see it unless looking at the code.

Options class

  class OptionsClassName(ReportOptions):
      def __init__(self,name,person_id=None):
          ReportOptions.__init__(self,name,person_id)
  • It should set new options that are specific for this report, by overriding the set_new_options() method which defines options_dict and options_help dictionaries:
      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"),
        }
  • It should also enable the "semi-common" options that are used in this report, by overriding the enable_options method which defines enable_dict dictionary. The semi-commons are the options which GRAMPS knows about, but which are not necessarily present in all reports:
      def enable_options(self):
          # Semi-common options that should be enabled for this report
          self.enable_dict = {
              'filter'    : 0,
          }

All the common options are already taken care of by the core of GRAMPS.

  • 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:
      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()
  • Finally, the default definitions for the user-adjustable paragraph styles must be defined here, to form a 'default' stylesheet:
      def make_default_style(self,default_style):
          f = BaseDoc.FontStyle()
          f.set_size(10)
          f.set_type_face(BaseDoc.FONT_SANS_SERIF)
          p = BaseDoc.ParagraphStyle()
          p.set_font(f)
          p.set_description(_("The style used for the person's name."))
          default_style.add_style("ABC-Name",p)

Registration statement

  • Registration should define internal name of the report (preferably, single string with non-special ascii characters, usable for report identification from the command line and in the options storage, as well as for forming sane filename for storing its own styles). It should also define report's category (text/graphics/code), translated name (the one to display in menus), and the modes that should be enabled for the report (standalone, book item, command line). Finally, both report class and options class should be passed to registration. Here's the example registration statement:
  from PluginUtils import register_report
  register_report(
      name = 'shortname',
      category = CATEGORY_TEXT,
      report_class = ReportClassName,
      options_class = OptionsClassName,
      modes = MODE_GUI | MODE_BKI | MODE_CLI,
      translated_name = _("Totally new report"),
      status = _("Alpha"),
      author_name = "A. U. Thor",
      author_email = "[email protected]",
      description = _("Produces totally new report")
      )

The first two arguments set string identifier and the category (in this case we are considering text report). The next two pass the report class and options class. The modes argument is set to the bit-wise sum (the OR statement) of all three possible modes: GUI (standalone report generated from GRAMPS running in a window), BKI (book item), and CLI (command line interface). This means that the report will be available in all three modes. The rest should be self-explanatory.

Implementation

Defining the Report Options class

In this example, no special options are required. This makes the options class very simple. All that is necessary is to define the default styles.

class DbSummaryOptions(ReportOptions):

    def __init__(self, name, person_id=None):

        ReportOptions.__init__(self, name, person_id)

    def make_default_style(self, default_style):

        # Define the title paragraph, named 'DBS-Title', which uses a
        # 18 point, bold Sans Serif font with a paragraph that is centered

        font = BaseDoc.FontStyle()
        font.set_size(18)
        font.set_type_face(BaseDoc.FONT_SANS_SERIF)
        font.set_bold(True)

        para = BaseDoc.ParagraphStyle()
        para.set_header_level(1)
        para.set_alignment(BaseDoc.PARA_ALIGN_CENTER)
        para.set_font(font)
        para.set_description(_('The style used for the title of the page.'))

        default_style.add_style('DBS-Title',para)

        # Define the normal paragraph, named 'DBS-Normal', which uses a
        # 12 point, Serif font.

        font = BaseDoc.FontStyle()
        font.set_size(12)
        font.set_type_face(BaseDoc.FONT_SERIF)

        para = BaseDoc.ParagraphStyle()
        para.set_font(font)
        para.set_description(_('The style used for normal text'))

        default_style.add_style('DBS-Normal',para)

Defining the Report class

The actual implemention of the DbSummary report is rather simple. No additional work needs to be done to initialize the class, so the parent __init__ routine is called.

All the work is done in the write_report() function. This function uses a GrampsCursor to iterate through the map of Person objects and gathers some simple statistics.

The only thing of any complication is the determination of the most common surname. A python dictionary is used to store the number of times each surname is used. Each time a surname is encountered, the value in the dictionary is incremented. The results are then loaded into a list and sorted, allowing us to find the most common name by looking at the last entry in the list.

class DbSummaryReport(Report):

    def __init__(self, database, person, options_class):

        Report.__init__(self, database, person, options_class)

    def write_report(self):

        cursor = self.database.get_person_cursor()

        data = cursor.first()

        males = 0
        females = 0
        total = 0
        surname_map = {}
        while data:
            person = RelLib.Person()
            person.unserialize(data[1])

            if person.get_gender() == RelLib.Person.MALE:
                males += 1
            if person.get_gender() == RelLib.Person.FEMALE:
                females += 1
            total += 1

            surname = person.get_primary_name().get_surname()

            if surname_map.has_key(surname):
                surname_map[surname] += 1
            else:
                surname_map[surname] = 1

            data = cursor.next()
        cursor.close()

        slist = []
        for key in surname_map.keys():
            slist.append((surname_map[key],key))
        slist.sort()

        self.doc.start_paragraph("DBS-Title")
        self.doc.write_text(_("Database Summary"))
        self.doc.end_paragraph()

        self.doc.start_paragraph('DBS-Normal')
        self.doc.write_text(_('Number of males : %d') % males)
        self.doc.end_paragraph()

        self.doc.start_paragraph('DBS-Normal')
        self.doc.write_text(_('Number of females : %d') % females)
        self.doc.end_paragraph()

        self.doc.start_paragraph('DBS-Normal')
        self.doc.write_text(_('Total people : %d') % total)
        self.doc.end_paragraph()

        self.doc.start_paragraph('DBS-Normal')
        self.doc.write_text(_('Number of unique surnames : %d') % len(slist))
        self.doc.end_paragraph()

        self.doc.start_paragraph('DBS-Normal')
        self.doc.write_text(_('Most common surname : %s') % (slist[-1][1]))
        self.doc.end_paragraph()

Registering the Report

The report must be registered before GRAMPS can find it.

from PluginUtils import register_report

register_report(
    name = 'database_summary',
    category = const.CATEGORY_TEXT,
    report_class = DbSummaryReport,
    options_class = DbSummaryOptions,
    modes = MODE_GUI,
    translated_name = _('Database Summary Report'),
    status=_('Beta'),
    description=_('Generates a summary of the database'),
    author_name="put author's name here",
    author_email="put email address here"
    )

A complete copy of the report can be downloaded (1.66 KB) for testing and experimentation.