;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 the [http://www.gramps-project.org/docs/ docgen] interface to abstract away the output format details.

+

;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 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.

;Options class : This is the code that provides means to obtain options necessary for the report using a variety of available mechanisms.

Line 28:

Line 28:

==Document interface==

==Document interface==

−

GRAMPS attempts to abstract the output document format away from the report. By coding to the [http://www.gramps-project.org/docs 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.

+

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.

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

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

Line 70:

Line 70:

==Defining the classes==

==Defining the classes==

===Report class===

===Report class===

−

The user's report class should inherit from the Report class contained within the Report module. The constructor should take two arguments (besides class instance itself, usually denoted by 'self' name):

+

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

* GRAMPS database instance

* options class instance

* options class instance

−

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

+

* user class instance

+

The first is the database to work with. The second is the instance of the options class defined in the same report, see next section. The third is an instance of the User class, used for interaction with the user. Here's an example of a report class definition:

<pre>

<pre>

from ReportBase import Report, ReportUtils, ReportOptions

from ReportBase import Report, ReportUtils, ReportOptions

class ReportClassName(Report):

class ReportClassName(Report):

−

def __init__(self, database, options_class):

+

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

−

Report.__init__(self, database, options_class)

+

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

</pre>

</pre>

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

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 [http://www.gramps-project.org/docs docgen], and is '''not''' a normal file object.

+

;self.doc : The opened document instance ready for output. This is of the type [http://packages.python.org/Gramps/gen/gen_plug.html#module-gen.plug._docgenplugin docgen], and is '''not''' a normal file object.

;self.options_class : The [http://www.gramps-project.org/devdoc/api/2.2/private/ReportBase._ReportOptions.ReportOptions-class.html ReportOptions] class passed to the report.

+

;self.options_class : The [http://packages.python.org/Gramps/gen/gen_plug.html#module-gen.plug._options ReportOptions] class passed to the report.

You'll probably need a start-person for which to write the report. This person should be obtained from the <tt>options_class</tt> object through the PersonOption class which will default to the active person in the database. Anything else the report class needs in order to produce the report should be obtained from the <tt>options_class</tt> 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.

You'll probably need a start-person for which to write the report. This person should be obtained from the <tt>options_class</tt> object through the PersonOption class which will default to the active person in the database. Anything else the report class needs in order to produce the report should be obtained from the <tt>options_class</tt> 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.

Line 98:

Line 99:

===Options class===

===Options class===

−

* Options class should derive from [http://www.gramps-project.org/docs/ ReportOptions] class. Usually for a common report the <tt>MenuReportOptions</tt> class should be derived from. <tt>MenuReportOptions</tt> will abstract most of the lower-level widget handling below.

+

* Options class should derive from [http://packages.python.org/Gramps/gen/gen_plug.html#module-gen.plug._options ReportOptions] class. Usually for a common report the <tt>MenuReportOptions</tt> class should be derived from. <tt>MenuReportOptions</tt> will abstract most of the lower-level widget handling below.

====Using ReportOptions====

====Using ReportOptions====

Line 379:

Line 380:

See an existing book report for more details.

See an existing book report for more details.

+

+

==See also==

+

+

* [[Report_API|Report API]]

+

* [[Report_Generation|Report Generation]]

[[Category:Developers/General]]

[[Category:Developers/General]]

[[Category:Developers/Tutorials]]

[[Category:Developers/Tutorials]]

[[Category: Plugins]]

[[Category: Plugins]]

+

[[Category:Reports]]

Revision as of 02:38, 3 March 2012

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.

Overview

Before going into details, it is useful to note that the report should have three basic parts. As explained on the Addons page, these go into two different files: the source code file (e.g.: report.py) and a Gramps Plugin Registration file (e.g.: report.gpr.py).

report.py

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 the 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 register() function. 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 docgen 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:

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

options class instance

user class instance

The first is the database to work with. The second is the instance of the options class defined in the same report, see next section. The third is an instance of the User class, used for interaction with the user. Here's an example of a report class definition:

You'll probably need a start-person for which to write the report. This person should be obtained from the options_class object through the PersonOption class which will default to the active person in the database. 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.

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

Options class should derive from ReportOptions class. Usually for a common report the MenuReportOptions class should be derived from. MenuReportOptions will abstract most of the lower-level widget handling below.

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:

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:

Using MenuReportOptions

The MenuReportOptions can be used in place of ReportOptions to present the user with a standard interface for running the report. Instead of parsing options, you generate a menu using one or more of the classes available in gen.plug.menu. All these are initialzed in the add_menu_options function (which is a required function when you inherit from MenuReportOptions). For example:

In this example a BooleanListOption object is created that presents the user with a group of check boxes, one is created for each call to add_button. Finally the object is added to the menu with menu.add_option(). The category name is used to generate tabs on the report dialog.

Then to access the selected values once the user runs the report, you make a call the menu object from within the report's __init__ function. For example, to access the "what_types" that are selected from the menu above you would add the following code:

In the example, the option class is retrieved by the get_option_by_name() function. The string must match the name you passed as the second argument to menu.add_option() when you created the menu. Then a list of the selected item titles is retrieved with get_selected() and stored as a class member for later use.

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.

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.

Registering the report

Registration is set into a name.gpr.py file

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 the report's...

category (text/graphics/code)

translated name (the one to display in menus)

modes that should be enabled for the report (standalone, book item, command line)

If the report requires an active person to run, then require_active should be set to True.

Finally, both report class and options class should be passed to registration.

The list should only include those options which are valid for this report.

The rest of the options should be self-explanatory.

Book Report

To turn a report into one that will work as a book report, you may need to add the following:

from gen.plug.docgen import IndexMark
# Write the title line.
# Set in INDEX marker so that this section will be identified
# as a major category if this is included in a Book report.
title = self._('My Report')
mark = IndexMark(title, INDEX_TYPE_TOC, 1)
self.doc.start_paragraph('MYREPORT-section')
self.doc.write_text(title, mark)
...