Report-writing tutorial - Revision history

Patsyblefebre: /* Report class */ http://pythonhosted.org/Gramps/gen/gen_plug.html#module-gen.plug._docgenplugin

2013-02-13T03:36:43Z

‎Report class: http://pythonhosted.org/Gramps/gen/gen_plug.html#module-gen.plug._docgenplugin

Patsyblefebre: Gramps

2013-02-01T04:43:59Z

Gramps

Patsyblefebre: /* Using MenuReportOptions */ format

2012-12-28T03:40:56Z

‎Using MenuReportOptions: format

Patsyblefebre: /* Using ReportOptions */ format

2012-12-28T03:40:12Z

‎Using ReportOptions: format

Patsyblefebre: /* Report class */ format

2012-12-28T02:28:41Z

‎Report class: format

Patsyblefebre: /* Report class */ format

2012-12-28T02:27:17Z

‎Report class: format

Patsyblefebre: /* Document interface */ format

2012-12-28T02:26:19Z

‎Document interface: format

Patsyblefebre: /* Overview */ two

2012-12-28T02:24:38Z

‎Overview: two

Patsyblefebre: Addons development

2012-12-28T02:20:16Z

Addons development

Patsyblefebre: views

2012-12-28T02:18:50Z

views

@@ Line 84: / Line 84: @@
 ;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.python.org/Gramps/gen/gen_plug.html#module-gen.plug._options ReportOptions] class passed to the report.
+;self.options_class : The [http://pythonhosted.org/Gramps/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.

@@ Line 2: / Line 2: @@
 {{languages}}
-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.
+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:
@@ Line 17: / Line 17: @@
 ===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 [http://packages.python.org/Gramps/gen/gen_plug.html#module-gen.plug._docgenplugin 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.
 ===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.
+;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 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.
+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 [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.
+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.
@@ Line 70: / Line 70: @@
 ===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
+* Gramps database instance
 * options class instance
 * user class instance
@@ Line 122: / Line 122: @@
+   }
 </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 knows about, but which are not necessarily present in all reports:
+* 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 knows about, but which are not necessarily present in all reports:
 <pre>
 def enable_options(self):
@@ Line 130: / Line 130: @@
+     }
 </pre>
-All the common options are already taken care of by the core of GRAMPS.
+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:
 <pre>
@@ Line 352: / Line 352: @@
 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 running in a window, graphical user interface)
+* REPORT_MODE_GUI (available for 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)

@@ Line 177: / Line 177: @@
 <pre>
-    def add_menu_options(self, menu):
+def add_menu_options(self, menu):
-        """
+    """
-        Add options to the menu for this report.
+    Add options to the menu for this report.
-        """
+    """
-        category_name = _("Report Options")
+    category_name = _("Report Options")
-        what_types = BooleanListOption(_('Select From:'))
+    what_types = BooleanListOption(_('Select From:'))
-        what_types.add_button(_('People'), True)
+    what_types.add_button(_('People'), True)
-        what_types.add_button(_('Families'), False)
+    what_types.add_button(_('Families'), False)
-        what_types.add_button(_('Places'), False)
+    what_types.add_button(_('Places'), False)
-        what_types.add_button(_('Events'), False)
+    what_types.add_button(_('Events'), False)
-        menu.add_option(category_name, "what_types", what_types)
+    menu.add_option(category_name, "what_types", what_types)
 </pre>

@@ Line 102: / Line 102: @@
 ====Using ReportOptions====
 <pre>
-  class OptionsClassName(ReportOptions):
+class OptionsClassName(ReportOptions):
-      def __init__(self,name,person_id=None):
+    def __init__(self,name,person_id=None):
-          ReportOptions.__init__(self,name,person_id)
+        ReportOptions.__init__(self,name,person_id)
 </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>
-      def set_new_options(self):
+def set_new_options(self):
-          # Options specific for this report
+    # Options specific for this report
-          self.options_dict = {
+    self.options_dict = {
-              'my_fist_option'    : 0,
+        'my_fist_option'    : 0,
-              'my_second_option'  : '',
+        'my_second_option'  : '',
-−
+    }
-          self.options_help = {
+    self.options_help = {
-              'my_fist_option'    : ("=num","Number of something",
+        'my_fist_option'    : ("=num","Number of something",
-                                     [ "First value", "Second value" ],
+                               [ "First value", "Second value" ],
-                                     True),
+                               True),
-              'my_second_option'  : ("=str","Some necessary string for the report",
+        'my_second_option'  : ("=str","Some necessary string for the report",
-                                     "Whatever String You Wish"),
+                               "Whatever String You Wish"),
-−
+  }
 </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 knows about, but which are not necessarily present in all reports:
 <pre>
-      def enable_options(self):
+def enable_options(self):
-          # Semi-common options that should be enabled for this report
+    # Semi-common options that should be enabled for this report
-          self.enable_dict = {
+    self.enable_dict = {
-              'filter'    : 0,
+        'filter'    : 0,
-−
+    }
 </pre>
 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:
 <pre>
-      def add_user_options(self,dialog):
+def add_user_options(self,dialog):
-          option_menu = gtk.OptionMenu()
+    option_menu = gtk.OptionMenu()
-          self.the_menu = gtk.Menu()
+    self.the_menu = gtk.Menu()
-          for item_index in range(10):
+    for item_index in range(10):
-              item = _("Item numer %d") % item_index
+        item = _("Item numer %d") % item_index
-              menuitem = gtk.MenuItem(item)
+        menuitem = gtk.MenuItem(item)
-              menuitem.show()
+        menuitem.show()
-              self.the_menu.append(menuitem)
+        self.the_menu.append(menuitem)
-          option_menu.set_menu(self.the_menu)
+    option_menu.set_menu(self.the_menu)
-          option_menu.set_history(self.options_dict['my_first_option'])
+    option_menu.set_history(self.options_dict['my_first_option'])
-          dialog.add_option(_('My first option'),option_menu)
+    dialog.add_option(_('My first option'),option_menu)
-          self.the_string_entry = gtk.Entry()
+    self.the_string_entry = gtk.Entry()
-          if self.options_dict['my_second_option']:
+    if self.options_dict['my_second_option']:
-              self.the_string_entry.set_text(self.options_dict['my_second_option'])
+        self.the_string_entry.set_text(self.options_dict['my_second_option'])
-          else:
+    else:
-              self.the_string_entry.set_text(_("Empty string"))
+        self.the_string_entry.set_text(_("Empty string"))
-          self.the_string_entry.show()
+    self.the_string_entry.show()
-          dialog.add_option(_('My second option'),self.the_string_entry)
+    dialog.add_option(_('My second option'),self.the_string_entry)
-      def parse_user_options(self,dialog):
+def parse_user_options(self,dialog):
-          self.options_dict['my_second_option'] = unicode(self.the_string_entry.get_text())
+    self.options_dict['my_second_option'] = unicode(self.the_string_entry.get_text())
-          self.options_dict['my_first_option'] = self.the_menu.get_history()
+    self.options_dict['my_first_option'] = self.the_menu.get_history()
 </pre>
 * Finally, the default definitions for the user-adjustable paragraph styles must be defined here, to form a 'default' stylesheet:
 <pre>
-      def make_default_style(self, default_style):
+def make_default_style(self, default_style):
-          f = docgen.FontStyle()
+    f = docgen.FontStyle()
-          f.set_size(10)
+    f.set_size(10)
-          f.set_type_face(docgen.FONT_SANS_SERIF)
+    f.set_type_face(docgen.FONT_SANS_SERIF)
-          p = docgen.ParagraphStyle()
+    p = docgen.ParagraphStyle()
-          p.set_font(f)
+    p.set_font(f)
-          p.set_description(_("The style used for the person's name."))
+    p.set_description(_("The style used for the person's name."))
-          default_style.add_style("ABC-Name",p)
+    default_style.add_style("ABC-Name",p)
 </pre>

@@ Line 90: / Line 90: @@
 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>
-      def write_report(self):
+def write_report(self):
-          self.doc.start_paragraph("ABC-Title")
+    self.doc.start_paragraph("ABC-Title")
-          self.doc.write_text(_("Some text"))
+    self.doc.write_text(_("Some text"))
-          self.doc.end_paragraph()
+    self.doc.end_paragraph()
 </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.

@@ Line 75: / Line 75: @@
 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>
-  from ReportBase import Report, ReportUtils, ReportOptions
+from ReportBase import Report, ReportUtils, ReportOptions
-  class ReportClassName(Report):
+class ReportClassName(Report):
-      def __init__(self, database, options_class, user):
+    def __init__(self, database, options_class, user):
-          Report.__init__(self, database, options_class, user)
+        Report.__init__(self, database, options_class, user)
 </pre>
 The Report class's constructor will initialize several variables for the user based off the passed values. They are:

@@ Line 35: / Line 35: @@
 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>
-    def make_default_style(self, default_style):
+def make_default_style(self, default_style):
-        # Define the title paragraph, named 'DBS-Title', which uses a
+    # Define the title paragraph, named 'DBS-Title', which uses a
-        # 18 point, bold Sans Serif font with a paragraph that is centered
+    # 18 point, bold Sans Serif font with a paragraph that is centered
-        font = docgen.FontStyle()
+    font = docgen.FontStyle()
-        font.set_size(18)
+    font.set_size(18)
-        font.set_type_face(docgen.FONT_SANS_SERIF)
+    font.set_type_face(docgen.FONT_SANS_SERIF)
-        font.set_bold(True)
+    font.set_bold(True)
-        para = docgen.ParagraphStyle()
+    para = docgen.ParagraphStyle()
-        para.set_header_level(1)
+    para.set_header_level(1)
-        para.set_alignment(docgen.PARA_ALIGN_CENTER)
+    para.set_alignment(docgen.PARA_ALIGN_CENTER)
-        para.set_font(font)
+    para.set_font(font)
-        para.set_description(_('The style used for the title of the page.'))
+    para.set_description(_('The style used for the title of the page.'))
-        default_style.add_style('DBS-Title',para)
+    default_style.add_style('DBS-Title',para)
-        # Define the normal paragraph, named 'DBS-Normal', which uses a
+    # Define the normal paragraph, named 'DBS-Normal', which uses a
-        # 12 point, Serif font.
+    # 12 point, Serif font.
-        font = docgen.FontStyle()
+    font = docgen.FontStyle()
-        font.set_size(12)
+    font.set_size(12)
-        font.set_type_face(docgen.FONT_SERIF)
+    font.set_type_face(docgen.FONT_SERIF)
-        para = docgen.ParagraphStyle()
+    para = docgen.ParagraphStyle()
-        para.set_font(font)
+    para.set_font(font)
-        para.set_description(_('The style used for normal text'))
+    para.set_description(_('The style used for normal text'))
-        default_style.add_style('DBS-Normal',para)
+    default_style.add_style('DBS-Normal',para)
 </pre>

@@ Line 13: / Line 13: @@
 ==Overview==
-Before going into details, it is useful to note that the report should have three 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).
+Before going into details, it is useful to note that the report should have 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===

@@ Line 10: / Line 10: @@
 * The most common surname
-As of Gramps version 3.2, there is also a [[Simple Access API|simple access]] database [http://www.gramps-project.org/docs/ API] available, with accompanying [[Quick Views]], [[Gramplets]] and [[Addons_Development|Addons]].
+As of Gramps version 3.2, there is also a [[Simple Access API|simple access]] database [http://www.gramps-project.org/docs/ API] available, with accompanying [[Quick Views]], [[Gramplets]] and [[Addons development|Addons]].
 ==Overview==