manual
389
edits
Changes
Clarify where to find additional information
{{Out of date}}
{{languages}}
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 Gramps version 3.02, there is also a [[Simple Access API|simple access]] database [http://www.gramps-project.org/docs/ API] is available, with accompanying [[Quick ReportsViews]], [[Gramplets]] and [[Addons development|Addons]].
==Overview==
Before going into details, it is useful to note that the report should have three two basic parts. As explained on the [[Addons_Development|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 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://wwwpackages.gramps-projectpython.org/docsGramps/gen/ BaseDocgen_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 Gramps, 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.
Paragraph and font styles are defined in the <tt>make_default_style()</tt> function of the options class. The paragraphs are grouped into a <tt>StyleSheet</tt>, which the <tt>make_default_style()</tt> function defines. For the example report (<tt>DbSummary</tt>), the paragraph styles are defined as below:
<pre>
</pre>
===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* Person object instance
* options class instance
* user class instanceThe 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. 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>
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://wwwpackages.gramps-projectpython.org/docs BaseDocGramps/gen/gen_plug.html#module-gen.plug._docgenplugin docgen], and is '''not''' a normal file object.;self.start_person database : The [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gen.lib.person PersonGrampsDbBase] instance containing the start or center person (the person selected) when the report was calleddatabase object.;self.database options_class : The [http://www.gramps-projectpythonhosted.org/docsGramps/gen/gen_libgen_plug.html#module-gen.lib GrampsDbBase] database object;selfplug.options_class : The [http://www.gramps-project.org/devdoc/api/2.2/private/ReportBase._ReportOptions.ReportOptions-class.html _docgenplugin ReportOptions] class passed to the reportAnything 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. 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.
===Options class===
* Options class should derive from [http://wwwpackages.gramps-projectpython.org/devdocGramps/apigen/2gen_plug.2/private/ReportBasehtml#module-gen._ReportOptionsplug._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-classlevel widget handling below.html ====Using ReportOptions] class:====
<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>
===Registration statement=Using MenuReportOptions==== * Registration should define internal name The <tt>MenuReportOptions</tt> can be used in place of <tt>ReportOptions</tt> to present the report (preferably, single string user with non-special ascii characters, usable a standard interface for running the report identification from . Instead of parsing options, you generate a menu using one or more of the command line and classes available in the options storage, as well as for forming sane filename for storing its own styles)<tt>gen.plug. It should also define report's category (textmenu</graphics/code), translated name (the one to display tt>. All these are initialzed in menus), and the modes that should be enabled for the report <tt>add_menu_options</tt> function (standalone, book item, command linewhich is a required function when you inherit from <tt>MenuReportOptions</tt>). Finally, both report class and options class should be passed to registration. Here's the For example registration statement:
<pre>
</pre>
==Implementation==
class DbSummaryOptions(ReportOptions):
def __init__(self, name, person_id=Nonedatabase):
ReportOptions.__init__(self, name, person_iddatabase)
def make_default_style(self, default_style):
# 18 point, bold Sans Serif font with a paragraph that is centered
font = BaseDocdocgen.FontStyle()
font.set_size(18)
font.set_type_face(BaseDocdocgen.FONT_SANS_SERIF)
font.set_bold(True)
para = BaseDocdocgen.ParagraphStyle()
para.set_header_level(1)
para.set_alignment(BaseDocdocgen.PARA_ALIGN_CENTER)
para.set_font(font)
para.set_description(_('The style used for the title of the page.'))
# 12 point, Serif font.
font = BaseDocdocgen.FontStyle()
font.set_size(12)
font.set_type_face(BaseDocdocgen.FONT_SERIF)
para = BaseDocdocgen.ParagraphStyle()
para.set_font(font)
para.set_description(_('The style used for normal text'))
class DbSummaryReport(Report):
def __init__(self, database, person, options_class):
Report.__init__(self, database, person, options_class)
def write_report(self):
</pre>
===Registering the Reportreport===The * 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 must '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 registered before GRAMPS can find itset to True.* Finally, both report class and options class should be passed to registration. Here's the example registration statement:
<pre>
</pre>
