15,534
edits
Changes
→Document interface
{{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.
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 [[Gramps_4.2_Wiki_Manual_-_Settings#Customize_report_output_formats|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 <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:
===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
;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.database : The [http://www.gramps-project.org/docs/gen/gen_lib.html#module-gen.lib GrampsDbBase] database object.
;self.options_class : The [http://packages.pythonpythonhosted.org/Gramps/gen/gen_plug.html#module-gen.plug._options _docgenplugin 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.
}
</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>
def enable_options(self):
}
</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>
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)
* [[Report_Generation|Report Generation]]
[[Category:Addons]]
[[Category:Developers/General]]
[[Category:Developers/Tutorials]]
[[Category: Plugins]]
[[Category:Reports]]
