Changes

Jump to: navigation, search

Report-writing tutorial

973 bytes added, 12:08, 12 September 2021
m
Typo in code variable name : "fist" instead of "first"
{{languages}}{{stub|Report-writing tutorial}}
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 most common surname
As of {{man tip|From Gramps version 3.2, there is also a |A [[Simple Access API|simple access]] database [httphttps://www.gramps-project.org/docs/ API] available, with accompanying [[Quick Views]], [[Gramplets]] and [[Addons development|Addons]].}}
==Overview==
Before going into details, it is useful to note that the report should have two basic parts. As This is explained on the [[Addons_Development|Addonsdevelopment]] page, these go that the source code goes into two different files: # the source code Gramps Plugin Registration (''*.gpr.py'') file (e.g.: <code>report.gpr.py) </code># and a Gramps Plugin Registration the main source code file (''*.py'') e.g.: <code>report.gpr.py).</code>
===report.gpr.py=== ;Registration statement : This initializes the report by a single call to the <tt>[https://gramps-project.org/docs/gen/gen_plug.html#module-gramps.gen.plug._pluginreg register()]</tt> function. It is trivial, but without it your report will not become available to Gramps, even if it is otherwise perfectly written.
;Report class : This is the code that takes data from the Gramps database and organizes it into the document structure. This structure A report can later potentially be printedgenerated as a standalone report, viewedas a Gramps Book item, or written into and as a file in command line report. The registration determines which modes are enabled for a variety of formatsgiven report. This The report class uses the [http://packages.python.org/Gramps/gen/gen_plug.html#module-gen.plug._docgenplugin docgen] interface does not have to abstract away know anything about the output format detailsmode.;Options The options class : This is the code that provides means there to obtain provide options necessary interface for the report using a variety of all available mechanismsmodes.
===report.gpr.py===* [[Report-writing_tutorial#Registering_the_report]]
;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.py===
A report ;Report class : This is the code that takes data from the Gramps database and organizes it into the document structure. This structure can potentially later be generated as a standalone reportprinted, as a Gramps Book itemviewed, and as or written into a command line report. The registration determines which modes are enabled for file in a given reportvariety of formats. The report This class does not have uses the [https://gramps-project.org/docs/gen/gen_plug.html#module-gen.plug._docgenplugin docgen] interface to know anything about abstract away the modeoutput format details. The options ;Options class : This is there the code that provides means to provide obtain options interface necessary for all the report using a variety of available modesmechanisms.
==Document interface==
The [[Report Generation]] article provides an overview of the 'docgen' interfaces that are available for outputting documents.
The [[Report API]] article provides more details about the interfaces.
The developer [httphttps://packages.pythongramps-project.org/Grampsdocs/gen/gen_plug.html#module-gen.plug._docgenplugin docgen] api documentation provides a detailed specification of the interfaces.
Gramps attempts to abstract the output document format away from the report. By coding to the [httphttps://packages.pythongramps-project.org/Grampsdocs/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.
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_Gramps_{{man version}}_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:
{{stub}}<!-- need to check code is correct for Gramps 5.1.x -->
compare to <code>gramps\plugins\textreport\summary.py</code> starting at [https://github.com/gramps-project/gramps/blob/master/gramps/plugins/textreport/summary.py#L297 line 297]
<pre>
def make_default_style(self, default_style):
</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 [httphttps://packages.pythongramps-project.org/Grampsdocs/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://pythonhostedwww.gramps-project.org/Grampsdocs/gen/gen_plug.html#module-gen.plug._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.
# Options specific for this report
self.options_dict = {
'my_fist_optionmy_first_option' : 0,
'my_second_option' : '',
}
self.options_help = {
'my_fist_optionmy_first_option' : ("=num","Number of something",
[ "First value", "Second value" ],
True),
==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.
<pre>
** 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 <code>require_active </code> should be set to <code>True</code>.
* Finally, both report class and options class should be passed to registration.
Here's the [[Quick_Views#Analysis:_registering_the_report|example registration ]] statement:
<pre>
register(REPORT,
description = _("Produces a ..."),
version = '1.0',
gramps_target_version = '35.21',
status = STABLE,
fname = 'filename.py',
See an existing book report for more details.
 
== Manually installing your report ==
Install in the plugins directory of your Gramps user directory.
 
== Example output ==
Start Gramps and your tutorial report will be available from the reports menu as ....
 
Run the report and this is what the output looks like ....
==See also==
* [[Report_API|Report API]]
* [[Report_Generation|Report Generation]] (describing output format options)* [[Gramps_Data_Model|Gramps Data Model]]
[[Category:Addons]]
[[Category:Developers/General]]
[[Category:Developers/Tutorials]]
[[Category: Plugins]]
[[Category:Reports]]
4,530
edits

Navigation menu