Difference between revisions of "Adapt a built-in Report"

From Gramps
Jump to: navigation, search
m (See also)
m
 
(21 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{Languages|Adapt_a_built-in_Report}}
 
{{Languages|Adapt_a_built-in_Report}}
{{man warn|1=&#x1F6A7; Work In Progress|2=This wikipage is an outline from a template being roughed in. Please don't edit '''''just yet'''''. Instead, contribute suggestions on the Discussion page. <br /><br />This page is not planned be linked to a public page until about 2 weeks after 8 April 2021. <br /><br />If this notice remains after that date, please feel welcome to remove this notice and consider the content 'fair game' for unlimited editing.}}
+
A question was posted to the [[Contact#Official|Discourse forum]] wondering if there were tips somewhere for copying an internal Gramps report to a make an experimental addon?  
==Purpose==
 
A question was posted to the Discourse forum wondering if there were tips somewhere for copying an internal Gramps report to a make an experimental add-on?  
 
  
 
It seems like more people would be intrigued with the possibilities of tweaking reports without the risk of breaking a feature. Particularly one that they use often enough that tweaking it seemed like a good idea.
 
It seems like more people would be intrigued with the possibilities of tweaking reports without the risk of breaking a feature. Particularly one that they use often enough that tweaking it seemed like a good idea.
  
Making a duplicate add-on sidesteps putting the original at risk. However, there are differences between built-ins and 3rd party add-ons. It seemed like that might require at least converting the library paths and making a new <code>.gpr.py</code> registration file. What else?
+
Making a duplicate addon sidesteps putting the original at risk. However, there are differences between built-ins and 3rd party addons. It seemed like that might require at least converting the library paths and making a new <code>.gpr.py</code> registration file. What else?
  
 
==A reply privately shared==
 
==A reply privately shared==
In a private message, GaryG privately replied and sent a few copies of reports generated that address the question.  
+
In a private message ''{on March 28th}'', GaryG privately replied and sent a few copies of reports generated that are examples of internal reports converted to the Addon format.  
  
In the sample cases, Gary had taken the Detailed Ancestor and Detailed Descendant stock reports and added the ability to include *all* images for everyone. The Detailed individual report had that functionality, but the ancestor/descendant did not.
+
In the sample cases, Gary had taken the Detailed Ancestor and [[Addon:Descendant_and_Detailed_Descendant_Book_Reports|Detailed Descendant]] stock reports and added the ability to include *all* images for everyone. The Detailed individual report had that functionality, but the ancestor/descendant did not.
  
 +
==Find the original Addon Python source==
 +
Reports can be difficult to find in the Gramps collection of source code. There are a wide variety of report flavors: text and graphical reports, Quick Reports, reporting View modes and reporting Gramplets. And each can be built-in or be a 3rd Party Addon.
 +
 +
So, the first step is to find the master copy of the module generating the report.
 +
 +
Third party addons are easy to locate within the <code>gramps51\plugins</code> subdirectory of the [[Gramps_{{man version}}_Wiki_Manual_-_User_Directory|User Directory]]. You just make a duplicate of the report and modify the duplicate to be distinct (both to Gramps and how the modified report will appear in the GUI) from the original.
 +
 +
For the built-ins, we''' start with the [[Gramps_{{man version}}_Wiki_Manual_-_Command_Line#report_action_option|CLI Reports list]] from a stock installation of Gramps:
 +
<pre>
 +
Available names are:
 +
  ancestor_chart            - Ancestor Tree
 +
  ancestor_report          - Ahnentafel Report
 +
  birthday_report          - Birthday and Anniversary Report
 +
  calendar                  - Calendar
 +
  descend_chart            - Descendant Tree
 +
  descend_report            - Descendant Report
 +
  det_ancestor_report      - Detailed Ancestral Report
 +
  det_descendant_report    - Detailed Descendant Report
 +
  endofline_report          - End of Line Report
 +
  family_descend_chart      - Family Descendant Tree
 +
  family_group              - Family Group Report
 +
  familylines_graph        - Family Lines Graph
 +
  fan_chart                - Fan Chart
 +
  hourglass_graph          - Hourglass Graph
 +
  indiv_complete            - Complete Individual Report
 +
  kinship_report            - Kinship Report
 +
  navwebpage                - Narrated Web Site
 +
  notelinkreport            - Note Link Report
 +
  number_of_ancestors      - Number of Ancestors Report
 +
  place_report              - Place Report
 +
  records                  - Records Report
 +
  rel_graph                - Relationship Graph
 +
  statistics_chart          - Statistics Charts
 +
  summary                  - Database Summary Report
 +
  tag_report                - Tag Report
 +
  timeline                  - Timeline Chart
 +
  WebCal                    - Web Calendar
 +
</pre>
 +
 +
<pre>
 +
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\view\view.gpr.py
 +
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\importer\import.gpr.py
 +
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\export\export.gpr.py
 +
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\mapservices\mapservice.gpr.py
 +
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\tool\tools.gpr.py
 +
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\gramplet\gramplet.gpr.py
 +
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\textreport\textplugins.gpr.py
 +
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\quickview\quickview.gpr.py
 +
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\docgen\docgen.gpr.py
 +
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\drawreport\drawplugins.gpr.py
 +
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\graph\graphplugins.gpr.py
 +
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\webreport\webplugins.gpr.py
 +
</pre>
  
 
==ch-ch-ch-changes==
 
==ch-ch-ch-changes==
Line 20: Line 71:
 
#  Update the <code>.gpr.py</code> registration file to point to the correct file and correct classes.
 
#  Update the <code>.gpr.py</code> registration file to point to the correct file and correct classes.
  
Attaching are 2 samples with the old (names ending with report.py) and the new code (names ending with reporti.py) as well as the revised <code>.gpr.py</code> files. The old code may have changed since I wrote the new code quite a while ago - so every diff may not be important.
+
Attached are 2 samples with the old (names ending with report.py) and the new code (names ending with reporti.py) as well as the revised <code>.gpr.py</code> files. The old code may have had updates. The adaptation was written quite a while ago - so every diff may not be significant.
 +
 
 +
==Not yet converted...==
 +
{{stub}}
 +
Apart from filing a bug report and waiting for someone qualified to do something about it, you will have to modify the code.
 +
 
 +
Unfortunately the Detailed Descendant and Detailed Ancestor reports are part of the main program and are not plugins.
 +
 
 +
The result of that is that you have to modify the code of the existing program,
 +
Both the ancestor and descendant report programs are to be found (Linux) <code>/usr/lib/python3/dist-packages/gramps/plugins/textreport</code> directory. Root permission will be required. Compare the two files, They do similar things so there should be some similarities. Look for the formatting codes (eg DAR-Title) to give some idea of what the program is printing in a given bit of code.
 +
 
 +
Oh yes, and get a book on Python programming.
 +
 
 +
Always keep a copy of the original file for when you really screw up.
 +
 
 +
When you change a file you will need to close and reopen Gramps to see the changes take effect.
 +
 
 +
Don’t be afraid to have a go, and good luck.
 +
 
 +
If you do manage to get it working, then keep a copy of your modified file, because the next Gramps update will overwrite everything that you have done.
 +
 
 +
This may come across as critical of the development team. that is not my intention. They have higher priorities than fixing things which do work well, even if some of us wished they worked differently.
 +
 
 
== See also ==
 
== See also ==
 +
* [[Addons development]]
 
* [[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_2|substitution values for Reports]]
 
* [[Gramps_{{man version}}_Wiki_Manual_-_Reports_-_part_2|substitution values for Reports]]
 
* [[Report-writing_tutorial|Report writing tutorial]]
 
* [[Report-writing_tutorial|Report writing tutorial]]
 
* [[Report_snippets|Report snippets]]
 
* [[Report_snippets|Report snippets]]
 
* [[Sample_reports|Sample reports]]
 
* [[Sample_reports|Sample reports]]
 +
* [[Signals and Callbacks]]
 +
Reference tools of available Data fields:
 +
* Gramps [[Gramps_Data_Model|data model]]
 +
* [[Addon:Isotammi_addons#SuperTool|Supertool]] Third-party addon
 
Sample Report Specifications
 
Sample Report Specifications
 
* [[Specification:Ahnentafel_Report|Ahnentafel Report]]
 
* [[Specification:Ahnentafel_Report|Ahnentafel Report]]
Line 43: Line 121:
 
:[https://sourceforge.net/p/gramps/mailman/search/?q=%22Group+As+name%22 threads with "Group As name"]
 
:[https://sourceforge.net/p/gramps/mailman/search/?q=%22Group+As+name%22 threads with "Group As name"]
 
-->
 
-->
 
{{DEFAULTSORT:How do I...new category location|noreplace}}
 
[[Category:Tutorial]]
 
[[Category:WikiContributors]]
 
[[Category:How do I...]]
 
  
 
<!--
 
<!--
Line 91: Line 164:
 
{{subst:WikiContributorRecruiting}
 
{{subst:WikiContributorRecruiting}
 
</pre>
 
</pre>
-->
 
  
 
== (Section) ==
 
== (Section) ==
Line 180: Line 252:
 
{{man note|Example Note |Notes text.}}
 
{{man note|Example Note |Notes text.}}
 
{{man warn|1=WarningTitle/Heading |2=warning text }}</onlyinclude>
 
{{man warn|1=WarningTitle/Heading |2=warning text }}</onlyinclude>
 +
-->
 +
[[Category:Developers/Tutorials]]
 +
[[Category:Developers/General]]

Latest revision as of 00:45, 1 December 2023

A question was posted to the Discourse forum wondering if there were tips somewhere for copying an internal Gramps report to a make an experimental addon?

It seems like more people would be intrigued with the possibilities of tweaking reports without the risk of breaking a feature. Particularly one that they use often enough that tweaking it seemed like a good idea.

Making a duplicate addon sidesteps putting the original at risk. However, there are differences between built-ins and 3rd party addons. It seemed like that might require at least converting the library paths and making a new .gpr.py registration file. What else?

A reply privately shared

In a private message {on March 28th}, GaryG privately replied and sent a few copies of reports generated that are examples of internal reports converted to the Addon format.

In the sample cases, Gary had taken the Detailed Ancestor and Detailed Descendant stock reports and added the ability to include *all* images for everyone. The Detailed individual report had that functionality, but the ancestor/descendant did not.

Find the original Addon Python source

Reports can be difficult to find in the Gramps collection of source code. There are a wide variety of report flavors: text and graphical reports, Quick Reports, reporting View modes and reporting Gramplets. And each can be built-in or be a 3rd Party Addon.

So, the first step is to find the master copy of the module generating the report.

Third party addons are easy to locate within the gramps51\plugins subdirectory of the User Directory. You just make a duplicate of the report and modify the duplicate to be distinct (both to Gramps and how the modified report will appear in the GUI) from the original.

For the built-ins, we start with the CLI Reports list from a stock installation of Gramps:

 Available names are:
   ancestor_chart            - Ancestor Tree
   ancestor_report           - Ahnentafel Report
   birthday_report           - Birthday and Anniversary Report
   calendar                  - Calendar
   descend_chart             - Descendant Tree
   descend_report            - Descendant Report
   det_ancestor_report       - Detailed Ancestral Report
   det_descendant_report     - Detailed Descendant Report
   endofline_report          - End of Line Report
   family_descend_chart      - Family Descendant Tree
   family_group              - Family Group Report
   familylines_graph         - Family Lines Graph
   fan_chart                 - Fan Chart
   hourglass_graph           - Hourglass Graph
   indiv_complete            - Complete Individual Report
   kinship_report            - Kinship Report
   navwebpage                - Narrated Web Site
   notelinkreport            - Note Link Report
   number_of_ancestors       - Number of Ancestors Report
   place_report              - Place Report
   records                   - Records Report
   rel_graph                 - Relationship Graph
   statistics_chart          - Statistics Charts
   summary                   - Database Summary Report
   tag_report                - Tag Report
   timeline                  - Timeline Chart
   WebCal                    - Web Calendar
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\view\view.gpr.py
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\importer\import.gpr.py
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\export\export.gpr.py
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\mapservices\mapservice.gpr.py
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\tool\tools.gpr.py
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\gramplet\gramplet.gpr.py
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\textreport\textplugins.gpr.py
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\quickview\quickview.gpr.py
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\docgen\docgen.gpr.py
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\drawreport\drawplugins.gpr.py
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\graph\graphplugins.gpr.py
C:\Program Files\GrampsAIO64-5.1.3-2\gramps\plugins\webreport\webplugins.gpr.py

ch-ch-ch-changes

The important changes

  1. Change the Class names to be unique. Each report has 2 classes - one for the code and one for the report. In my cases, I added a trailing ‘i’.
  2. Change the name of the report styles. This is necessary if you are using books, not absolutely required if not. For the Descendant report I changed the style prefix from DDR to DDRI, for instance. I didn’t change the Ancestor report.
  3. Update the .gpr.py registration file to point to the correct file and correct classes.

Attached are 2 samples with the old (names ending with report.py) and the new code (names ending with reporti.py) as well as the revised .gpr.py files. The old code may have had updates. The adaptation was written quite a while ago - so every diff may not be significant.

Not yet converted...

Gramps-notes.png

This article's content is incomplete or a placeholder stub.
Please update or expand this section.


Apart from filing a bug report and waiting for someone qualified to do something about it, you will have to modify the code.

Unfortunately the Detailed Descendant and Detailed Ancestor reports are part of the main program and are not plugins.

The result of that is that you have to modify the code of the existing program, Both the ancestor and descendant report programs are to be found (Linux) /usr/lib/python3/dist-packages/gramps/plugins/textreport directory. Root permission will be required. Compare the two files, They do similar things so there should be some similarities. Look for the formatting codes (eg DAR-Title) to give some idea of what the program is printing in a given bit of code.

Oh yes, and get a book on Python programming.

Always keep a copy of the original file for when you really screw up.

When you change a file you will need to close and reopen Gramps to see the changes take effect.

Don’t be afraid to have a go, and good luck.

If you do manage to get it working, then keep a copy of your modified file, because the next Gramps update will overwrite everything that you have done.

This may come across as critical of the development team. that is not my intention. They have higher priorities than fixing things which do work well, even if some of us wished they worked differently.

See also

Reference tools of available Data fields:

Sample Report Specifications