11
edits
Changes
From Gramps
Created page with "Category:Plugins Category:Developers/General ''This is a Third-party plugin. Currently, this is more of a proof-of-concept than a fully featured ..."
[[Category:Plugins]]
[[Category:Developers/General]]
''This is a [[Third-party Plugins|Third-party plugin]]. Currently, this is more of a proof-of-concept than a fully featured plugin. This plugin is still useful given the limitations specified below.''
== Description ==
[[Image:FilteredDescendantReport.png|thumb|right|400px|Sample Filtered Descendant Report Dialog]]
The ''Filtered Descendant Report'' is directly based on the ''Detailed Descendant Report''. As such, it
includes all the options ''Detailed Descendant Report'' in addition to some new ones. Because multiple
family branches can be included, the Henry and d'Aboville numbering systems may not be as useful
(considering that people common to more than one branch will get the number assigned to them when they
are first found). These numbering systems should probably be removed at some point.
The main difference is that a filter can be used to determine who to include in the report (so that
you can have several family branches) instead of basing all the descendants from a single person. The
key is to find at least one common person to all the rules in the filter. If at least one common
person is found, the generations can be aligned so that it doesn't matter if the head of each branch
is in the same generation.
In order to support this report, enhanced versions of some of the Gramps code is included so as to
not require modifications of the Gramps core itself. Hopefully, the enhanced changes will find their
way into the core, in which case they would be removed from this plugin. A list of enhancements can
be found after the list of differences.
'''CAVEAT''': in order for the plugin UI to work correctly, the patch from bug #4593 needs to be applied (until
the version of Gramps with the change is released). This patch isn't necessary for the plugin to work,
just for the case where changing the filter updates the Title field. See
http://www.gramps-project.org/bugs/view.php?id=4593.
'''CAVEAT''': the filter is meant to be an OR filter (At least one rule must apply), meaning that we are
expecting the report to consist of one or more family branches, where each rule dictates the start of a branch.
This plugin has NOT been stress tested over different varieties of rules. It does work with one or more
rules and will treat the filter as if 'At least one rule must apply' is set (even if not). The plugin
will complain if no common people are found across all rules.
'''CAVEAT''': the only supported output file format currently is ''OpenDocument Text Enhanced''. Running
the plugin with any other output format will cause an error (because the other format backends haven't
been updated to support the needed enhancements).
'''CAVEAT''': this is a first version, and as such has much missing that people might want. One obvious one
is support for ALL backend report formats, not just ODF. Also, when specifying the date for photo
captions, the date is currently ONLY listed in U.S. format (see below). Also, no translation for
messages (everything is currently English-only). This version is being released to get the ball rolling,
see if there is any interest outside myself :-{}, and possibly to get my enhancement changes into the core
if they seem useful.
== Differences ==
Differences from ''Detailed Descendant Report'' are as follows:
1) Instead of a 'Center Person' to start descendants from, there is now a 'Filter'.
As explained above, the filter can have one or more rules to allow multiple branches to be in the same
report. A person, common to ALL rules will align the generations. If no common person is found, an
error will be issued.
2) Report Title
An added option allows the user to specify the report title. For ''Detailed Descendant Report'', this
is automatically set based on the name of the 'Center Person'. For ''Filtered Descendant Report'', this is
automatically set to the name of the selected filter, but can be overridden by the user.
3) Turn URLs into real links
This option (on the '''Content''' tab) tells the plugin whether to turn any http, https, or mailto links found
in text (i.e. notes, endnotes, etc.) to be real clickable links. Turning this option off results in the
behavior found in ''Detailed Descendant Report'' (that is, no URLs are made clickable). Turning it on will
cause those URLs found to be clickable in the output file (if possible).
4) Do not include information marked private
This option (on the '''Content''' tab) tells the plugin whether to add information to the report that has
been marked 'private'. Turning this option off results in the behavior found in
''Detailed Descendant Report'' (that is, all information is included in the report). Turning it on
will cause the plugin to NOT include anything marked private. After all, what good is the private
flag if it's not respected?
5) Include partners
Just a label change for the modern age.
6) Add caption under image from Gallery
This option (on the new '''Caption''' tab) tells the plugin whether to include captions under photos or not.
6) Caption Format
This option (on the new '''Caption''' tab) specifies what should be in photo captions. The following variables
are available:
$c - FirstName LastName (excludes middle name if there is one)
$C - LastName, FirstName (excludes middle name if there is one)
$p - Photo date
$P - Photo date surround by parenthesis
The difference between $p and $P is that if the caption "($p)" is specified and there is no
date for a given photo, you will wind up with "()", whereas $P would be a blank string (no empty parenthesis).
'''CAVEAT''': currently, $p and $P display the date in U.S. format, that is "Month, Day Year" (depending on what's
available) and ONLY when there is a single date (not span or range for example).
7) Image cropping
Images now appear in the report document exactly how they appear within the Gramps UI. That is, if an image
has been cropped, it will be cropped the same way in the report. The ''Detailed Descendant Report''
behavior was to just insert the image so that the report showed the entire image.
== Enhancements ==
=== Date ===
Added styles (ISO & US) which are (currently) only applied if there is a single date
=== _DeepRelationshipPathBetween ===
Can send in None for the progress bar so that this function can be used without GUI feedback
=== Endnotes ===
Added support for turning URLs into clickable links
=== ImgManip ===
Turned image manipulation functions into a real class so that an image file only needs to be opened
once (instead of everytime an ImgManip function is called). Also added a method to return the image
DPI (if available). This supports showing cropped images in the report file.
=== ODFDoc ===
Enhanced to do the following:
* save photo styles like it does for notes (this enables having cropped images)
* image captions
* making URLs clickable
=== SubstKeywords ===
Added support for the following variables:
$c -> Name - FirstName LastName (NO middle name)
$C -> Name - LastName, FirstName (NO middle name)
$p -> Date of preferred photo
$P -> Date of preferred photo surrounded by parenthesis
[[Category:Developers/General]]
''This is a [[Third-party Plugins|Third-party plugin]]. Currently, this is more of a proof-of-concept than a fully featured plugin. This plugin is still useful given the limitations specified below.''
== Description ==
[[Image:FilteredDescendantReport.png|thumb|right|400px|Sample Filtered Descendant Report Dialog]]
The ''Filtered Descendant Report'' is directly based on the ''Detailed Descendant Report''. As such, it
includes all the options ''Detailed Descendant Report'' in addition to some new ones. Because multiple
family branches can be included, the Henry and d'Aboville numbering systems may not be as useful
(considering that people common to more than one branch will get the number assigned to them when they
are first found). These numbering systems should probably be removed at some point.
The main difference is that a filter can be used to determine who to include in the report (so that
you can have several family branches) instead of basing all the descendants from a single person. The
key is to find at least one common person to all the rules in the filter. If at least one common
person is found, the generations can be aligned so that it doesn't matter if the head of each branch
is in the same generation.
In order to support this report, enhanced versions of some of the Gramps code is included so as to
not require modifications of the Gramps core itself. Hopefully, the enhanced changes will find their
way into the core, in which case they would be removed from this plugin. A list of enhancements can
be found after the list of differences.
'''CAVEAT''': in order for the plugin UI to work correctly, the patch from bug #4593 needs to be applied (until
the version of Gramps with the change is released). This patch isn't necessary for the plugin to work,
just for the case where changing the filter updates the Title field. See
http://www.gramps-project.org/bugs/view.php?id=4593.
'''CAVEAT''': the filter is meant to be an OR filter (At least one rule must apply), meaning that we are
expecting the report to consist of one or more family branches, where each rule dictates the start of a branch.
This plugin has NOT been stress tested over different varieties of rules. It does work with one or more
rules and will treat the filter as if 'At least one rule must apply' is set (even if not). The plugin
will complain if no common people are found across all rules.
'''CAVEAT''': the only supported output file format currently is ''OpenDocument Text Enhanced''. Running
the plugin with any other output format will cause an error (because the other format backends haven't
been updated to support the needed enhancements).
'''CAVEAT''': this is a first version, and as such has much missing that people might want. One obvious one
is support for ALL backend report formats, not just ODF. Also, when specifying the date for photo
captions, the date is currently ONLY listed in U.S. format (see below). Also, no translation for
messages (everything is currently English-only). This version is being released to get the ball rolling,
see if there is any interest outside myself :-{}, and possibly to get my enhancement changes into the core
if they seem useful.
== Differences ==
Differences from ''Detailed Descendant Report'' are as follows:
1) Instead of a 'Center Person' to start descendants from, there is now a 'Filter'.
As explained above, the filter can have one or more rules to allow multiple branches to be in the same
report. A person, common to ALL rules will align the generations. If no common person is found, an
error will be issued.
2) Report Title
An added option allows the user to specify the report title. For ''Detailed Descendant Report'', this
is automatically set based on the name of the 'Center Person'. For ''Filtered Descendant Report'', this is
automatically set to the name of the selected filter, but can be overridden by the user.
3) Turn URLs into real links
This option (on the '''Content''' tab) tells the plugin whether to turn any http, https, or mailto links found
in text (i.e. notes, endnotes, etc.) to be real clickable links. Turning this option off results in the
behavior found in ''Detailed Descendant Report'' (that is, no URLs are made clickable). Turning it on will
cause those URLs found to be clickable in the output file (if possible).
4) Do not include information marked private
This option (on the '''Content''' tab) tells the plugin whether to add information to the report that has
been marked 'private'. Turning this option off results in the behavior found in
''Detailed Descendant Report'' (that is, all information is included in the report). Turning it on
will cause the plugin to NOT include anything marked private. After all, what good is the private
flag if it's not respected?
5) Include partners
Just a label change for the modern age.
6) Add caption under image from Gallery
This option (on the new '''Caption''' tab) tells the plugin whether to include captions under photos or not.
6) Caption Format
This option (on the new '''Caption''' tab) specifies what should be in photo captions. The following variables
are available:
$c - FirstName LastName (excludes middle name if there is one)
$C - LastName, FirstName (excludes middle name if there is one)
$p - Photo date
$P - Photo date surround by parenthesis
The difference between $p and $P is that if the caption "($p)" is specified and there is no
date for a given photo, you will wind up with "()", whereas $P would be a blank string (no empty parenthesis).
'''CAVEAT''': currently, $p and $P display the date in U.S. format, that is "Month, Day Year" (depending on what's
available) and ONLY when there is a single date (not span or range for example).
7) Image cropping
Images now appear in the report document exactly how they appear within the Gramps UI. That is, if an image
has been cropped, it will be cropped the same way in the report. The ''Detailed Descendant Report''
behavior was to just insert the image so that the report showed the entire image.
== Enhancements ==
=== Date ===
Added styles (ISO & US) which are (currently) only applied if there is a single date
=== _DeepRelationshipPathBetween ===
Can send in None for the progress bar so that this function can be used without GUI feedback
=== Endnotes ===
Added support for turning URLs into clickable links
=== ImgManip ===
Turned image manipulation functions into a real class so that an image file only needs to be opened
once (instead of everytime an ImgManip function is called). Also added a method to return the image
DPI (if available). This supports showing cropped images in the report file.
=== ODFDoc ===
Enhanced to do the following:
* save photo styles like it does for notes (this enables having cropped images)
* image captions
* making URLs clickable
=== SubstKeywords ===
Added support for the following variables:
$c -> Name - FirstName LastName (NO middle name)
$C -> Name - LastName, FirstName (NO middle name)
$p -> Date of preferred photo
$P -> Date of preferred photo surrounded by parenthesis
