Sample Report for new developers

I created a sample report that might be usable as a template for new developers to create a Report (easier than learning to create an Add-On). It tries to leverage a lot of the options available as a demonstration. This report has a selector for 4 types of reports. It also has a filter option and some other user inputs. It has 2 tabs in the report view, which is illustrative. And provides either tabular or CSV output.

I added extra documentation to make it easier to follow. Is there any interest in this?


Just downloaded it and got a couple errors.
In the console:
2022-12-04 20:04:26.744: WARNING: line 308: Plugin error (from 'samplereport'): No module named 'form'
Also noticed that comment line 117 has 2 spelling typos.

Could you move this ‘SampleReport’ folder from your forked addons-source repository to its own repository? GitHub’s ZIP download utility packs the ENTIRE 8MB fork with over 130 folders the way the repository is now organized.

I haven’t been able to look yet but could you do something that NO other report does yet? Make an Output option to a new Gramps Note?

There are a few reports that would be very helpful as inclusion… like the Database Differences Report or Database Summary Report. Of course, I can output to a text file then copy to a Note and flush the text file. But that is a bunch of extra busy work.

(But I’m also hoping that hotlinked worklists … like Paul’s Import Merge tool’s report list … might be something that can eventually be output to a Note. It would let users tackle a huge merge task in livable sessions.)

Fixed the error and the comment. You can remove the ‘import form’ line at around line 60 if you dont want to download again.

Moved the code to

Not sure I follow. A Report, by its nature, cannot do an update on the database. So I dont follow the idea of outputting to a Gramps Note.

The purpose of this is to be used as a sample for other people who might want to generate a report for the first time. So the output is fairly simple. The 4 options in this report are

  • Attributes with Values: Print all of the attributes of the filtered person list
  • Associations: Print all of the people with Associations and the associated person
  • Birth date with location: Print all of the birth date and locations for the filtered list
  • Death date with location: Print all of the death date and locations for the filtered list

If people want to use standard (Database Summary or Database Differences) Reports as samples for learning how to write a Report, they can do that (and don’t need SampleReport ). In that case, maybe I should not even publish this.

Every sample with a variety of functions or option is useful for people starting their adventure in coding. Thank you for creating this and the impulse to share with others.

When I first read the posting, my immediate thought was: hmm, maybe I can discover how to make a report print an era appropriate Place or Name without wading through reams of uncommentd code.

And leverage that knowledge to discover how to hack the report in another support thread that is always printing the modern Place name.

1 Like

Until the commit of the “OK” button, is it actually ‘updating’ the database? Yeah, that is a technicality. But won’t ‘not yet being committed’ keep the object from interfering with the database being polled? (Maybe uncommitted objects are part of the proxy tree/database that has mentioned a few times recently.)

My example of a couple reports that might benefit wasn’t a suggestion to make the mod. It was just places I thought I might experiment if there was an example of how to do such a thing. It probably is not even possible without creating an new ‘document writer’ addon that will splice in everywhere.

Yes! Much easier to grab for people who have not yet graduated to the GitHub desktop tools. Then it is easy to use the Isotammi ZIPinstall addon tool to put it in the correct Gramps User Directory folder directly from the Downloads folder.

The API for getting a date title from an event is place_displayer.display(). If you include the 3rd arguemnt (date), then the place title returned is date-specific. If you do not include it, it is the default title. For example:

place_title = place_displayer.display(self.database, place, place_date)


place_title = place_displayer.display(self.database, place)

I just updated the SampleReport to print the Place title in the Birth and Date reports to be based on the date of the birth/death event.

1 Like

A new user on Facebook posted a question about whether there was a Gramps reports Sample Book.

(There’s a Sample Reports wiki page that was started in 2007 … but it didn’t get past the worklist/index stage. They may have realized it would be as much of a maintenance woe as the Add-on List and the defunct downloadable wiki manual.)

I was wondering if perhaps requiring a ‘book’ definition (keyed to the Example.gramps tree) with each Report might be a ‘good thing’. Or maybe just adding a hook for a book definition to the Gramps Plugin Registration to augment the help_url hook.

An automated book collator could provide an avenue for a smart regenerated sample report book. (And emphasize the utility of the Book feature at the same time.) The assumption being that the author of a report is the best person to configure options to show a single page (or one page per layout section) of their report.

@GaryGriffin Thanks for creating this sample report that future developers can use to refer to when creating their own. Such contributions help the Gramps developer community grow and flourish.

A minor thing, but the code in the Gramps-Modules repo still has the #import form error @emyoulation mentioned. Perhaps the fix needs to be merged from your original fork?

It’s nice that your report shows how to do a few different things, but no report can show everything one can or would want to do. You’ve learned a lot by writing this and other reports so while that’s fresh in your mind, would you consider reviewing the Report-writing tutorial wiki and see if any information could be added to make it more comprehensive?

Some things that could be added to the wiki -

  • Information about using StandardReportOptions - how to use them, and which ones are the minimum each report should support? For example the Translation option (combined with date option) is important for global usage
  • Error trapping - usually nothing goes wrong, but there aren’t many examples of how to pop up an error that can be acknowledged and the error corrected
  • Show reuse of utility methods from gramps code so that each report doesn’t implement logic for iterating the db to gather information about people, people’s families, etc. Each time the code is re-written variations and subtle differences arise in the output.

Once again, thanks for the time you put in to this!

1 Like