Difference between revisions of "Addon:SyncAssociation"

From Gramps
Jump to: navigation, search
(See also)
(The Hack)
(29 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
{{languages|Addon:SyncAssociation}}
 
{{languages|Addon:SyncAssociation}}
 
{{Third-party plugin}}
 
{{Third-party plugin}}
 +
The {{man label|Sync Associations}} Tool addon is designed to add a reciprocal [[Gramps_{{man version}}_Wiki_Manual_-_Entering_and_editing_data:_detailed_-_part_1#Associations|Association]] if it is missing. For instance, if you create a GodFather association between A and B, this tool will create the matching Godchild association between B and A.
  
The {{man label|SyncAssociation}} Tool addon is designed to add a reciprocal [[Gramps_{{man version}}_Wiki_Manual_-_Entering_and_editing_data:_detailed_-_part_1#Associations|Association]] if it is missing. For instance, if you create a GodFather association between A and B, this tool will create the matching Godchild association between B and A.
+
=Usage=
 +
The {{man label|Sync Associations}} tool is run from the menu {{man menu|Tools > Family Tree Processing > Sync Associations...}}. It will scan and modify your family tree with no interaction nor feedback of the changes being made. (Although the Persons receiving a reciprocal association will have a freshened Modify Date.) So be certain to [[How_to_make_a_backup|make a backup]] beforehand... in case the result is not what you expected.  
  
=Usage=
+
This tool is designed to create reciprocal Associations that are implied by explicit Associations records. Any Sources or Notes referenced by the original Association will be cross-referenced to the new reciprocal relationship Association.  
It is designed to be used for completing the reciprocal association. The following associations create their reciprocal
 
  
 +
==Table of supported Associations==
 +
The following Associations imply a reciprocal relationship:
 
{| {| {{prettytable}}
 
{| {| {{prettytable}}
 
!Association name
 
!Association name
 
!Reciprocal association name
 
!Reciprocal association name
 
|-
 
|-
|Godfather
+
|[https://en.wikipedia.org/wiki/Godfather Godfather]
 
|Godchild
 
|Godchild
 
|-
 
|-
|Godmother
+
|[https://wikipedia.org/wiki/Godmother Godmother]
|Godchild
+
|[https://wikipedia.org/wiki/Godparent Godchild]
 
|-
 
|-
|Landlord
+
|[https://wikipedia.org/wiki/Landlord Landlord]
 
|Tenant
 
|Tenant
 
|-
 
|-
|DNA
+
|[[Genealogy_Glossary#dna|DNA]]
 
|DNA
 
|DNA
 
|-
 
|-
|cM
+
|[https://wikipedia.org/wiki/Centimorgan cM]
 
|cM
 
|cM
 
|}
 
|}
 +
 +
See below to [[#Add_Types_to_the_Sync_Association_Gramplet|Add Types to the Sync Association Gramplet]]
  
 
{{-}}
 
{{-}}
 
== Example ==
 
== Example ==
 +
 +
Create a new Family Tree and import the [[Example.gramps]] file.
 +
 +
[[File:Addon-SyncAssociation-Godfather-example1.png|thumb|600px|right]]
 +
View the Person Association information for example person, Fernandez El Fernandez, Avis III. He is the Godfather of Garner von Zielinski, Lewis Anderson Sr.
 +
{{-}}
 +
 +
[[File:Addon-SyncAssociation-FinalGodchild-example1.png|thumb|600px|right]]
 +
Now view the person referenced in the Godfather association, Garner von Zielinski, Lewis Anderson Sr. Note that he is the Godfather of Garner, Anderson but does not have an association with his Godfather.
 +
{{-}}
 +
 +
[[File:Addon-SyncAssociation-InitialGodchild-example1.png|thumb|600px|right]]
 +
After running the {{man label|Sync Associations}} tool, a window describing the actions taken will appear. The possible actions are
 +
 +
* <N> Reciprocal associations created
 +
* All reciprocal associations exist, none created
 +
* No existing associations, so no reciprocal ones needed
 +
 +
Now view the person again. The Godchild association has been added. If there were Notes or Citations on the initial Association, they would also be referenced.
 +
{{-}}
 +
 +
=Add Types to the Sync Association Gramplet=
 +
How do I add a new relationship Type to the [[Addon:SyncAssociation|Sync Associations]] tool?
 +
== Not for the casual user ==
 +
The list of Association Types was not designed to be changed via the interface. (It was intended for a specific Association and does not '''''have''''' any interface.) But you can manually change the Gramplet code as a temporary hack.  Unfortunately, the next time that Gramplet is updated, any temporary hacks will be wiped out.
 +
 +
To add more ‘official’ reciprocal relationship will take time. The quickest turnaround would be for users to manually change the Association Types in the system and, once they have verified the the Types as functioning, then submit the patched line of associations as an Enhancement Request.
 +
 +
== What variations of Syncs can be added? ==
 +
Associations can be symmetrical or reciprocal.  That is to say, the relationship is described the same way from either side (co-workers) or inverse/mirror of one another (guardian and ward)
 +
 +
As an example, perhaps you want to log the Association of a [https://wikipedia.org/wiki/Namesake Namesake] to their [https://wikipedia.org/wiki/Eponym Eponym].  The Junior-Senior namesake relationships are implied via the Name Suffix and loosely refined via the Family relationship.  But namesakes that skip a generation (or are honoring a famous person/thing) are more easily tracked via Associations.  It sure would be nice for there to be less work to set the Reciprocal Association.
 +
 +
When considering Associations, note that they do not have a datespan. So logged Associations should probably be limited to those that are expected to be lifelong.
 +
== The modification ==
 +
If you go to line 57 of syncAssociations.py you will see:
 +
 +
<pre>
 +
ASSOC_LOOKUP = {
 +
"cM": "cM",
 +
"DNA": "DNA",
 +
"Godfather": "Godchild",
 +
"Godmother": "Godchild",
 +
"Landlord": "Tenant"
 +
}
 +
</pre>
 +
 +
You need to add lines with a similar format (quoted string then colon then quoted string then comma)
 +
 +
Once the new Associations Types have tested and work as expected, submit an [[Using the bug tracker|feature request]] to included it in the addon.
  
 
= Issues =
 
= Issues =
* Limited list of association currently known
+
* Limited list of association currently known. [[#Add_Types_to_the_Sync_Association_Gramplet|Adding additional relationships]] requires adding to the [https://github.com/gramps-project/addons-source/tree/maintenance/gramps51/SyncAssociations source code] in the <code>ASSOC_LOOKUP</code> table
 +
* No help link to here.
  
 
= See also =
 
= See also =
* [[Gramps_{{man version}}_Wiki_Manual_-_Entering_and_editing_data:_detailed_-_part_1#Associations]]
+
* Gramps {{man version}} Manual - [[Gramps_{{man version}}_Wiki_Manual_-_Entering_and_editing_data:_detailed_-_part_1#Associations| Entering and Editing: Associations]]
 
* [[Roles, Relationships & Associations]]
 
* [[Roles, Relationships & Associations]]
 +
* [[Add a godfather-godmother]]
 +
  
 
[[Category:Plugins]]
 
[[Category:Plugins]]
 
[[Category:Addons]]
 
[[Category:Addons]]
 
[[Category:Developers/General]]
 
[[Category:Developers/General]]
 +
[[Category:How do I...]]

Revision as of 00:59, 25 October 2020

Gramps-notes.png

Please use carefully on data that is backed up, and help make it better by reporting any comments or problems to the author, or issues to the bug tracker
Unless otherwise stated on this page, you can download this addon by following these instructions.
Please note that some Addons have prerequisites that need to be installed before they can be used.
This Addon/Plugin system is controlled by the Plugin Manager.

The Sync Associations Tool addon is designed to add a reciprocal Association if it is missing. For instance, if you create a GodFather association between A and B, this tool will create the matching Godchild association between B and A.

Usage

The Sync Associations tool is run from the menu Tools > Family Tree Processing > Sync Associations.... It will scan and modify your family tree with no interaction nor feedback of the changes being made. (Although the Persons receiving a reciprocal association will have a freshened Modify Date.) So be certain to make a backup beforehand... in case the result is not what you expected.

This tool is designed to create reciprocal Associations that are implied by explicit Associations records. Any Sources or Notes referenced by the original Association will be cross-referenced to the new reciprocal relationship Association.

Table of supported Associations

The following Associations imply a reciprocal relationship:

Association name Reciprocal association name
Godfather Godchild
Godmother Godchild
Landlord Tenant
DNA DNA
cM cM

See below to Add Types to the Sync Association Gramplet


Example

Create a new Family Tree and import the Example.gramps file.

Addon-SyncAssociation-Godfather-example1.png

View the Person Association information for example person, Fernandez El Fernandez, Avis III. He is the Godfather of Garner von Zielinski, Lewis Anderson Sr.

Addon-SyncAssociation-FinalGodchild-example1.png

Now view the person referenced in the Godfather association, Garner von Zielinski, Lewis Anderson Sr. Note that he is the Godfather of Garner, Anderson but does not have an association with his Godfather.

Addon-SyncAssociation-InitialGodchild-example1.png

After running the Sync Associations tool, a window describing the actions taken will appear. The possible actions are

  • <N> Reciprocal associations created
  • All reciprocal associations exist, none created
  • No existing associations, so no reciprocal ones needed

Now view the person again. The Godchild association has been added. If there were Notes or Citations on the initial Association, they would also be referenced.

Add Types to the Sync Association Gramplet

How do I add a new relationship Type to the Sync Associations tool?

Not for the casual user

The list of Association Types was not designed to be changed via the interface. (It was intended for a specific Association and does not have any interface.) But you can manually change the Gramplet code as a temporary hack. Unfortunately, the next time that Gramplet is updated, any temporary hacks will be wiped out.

To add more ‘official’ reciprocal relationship will take time. The quickest turnaround would be for users to manually change the Association Types in the system and, once they have verified the the Types as functioning, then submit the patched line of associations as an Enhancement Request.

What variations of Syncs can be added?

Associations can be symmetrical or reciprocal. That is to say, the relationship is described the same way from either side (co-workers) or inverse/mirror of one another (guardian and ward)

As an example, perhaps you want to log the Association of a Namesake to their Eponym. The Junior-Senior namesake relationships are implied via the Name Suffix and loosely refined via the Family relationship. But namesakes that skip a generation (or are honoring a famous person/thing) are more easily tracked via Associations. It sure would be nice for there to be less work to set the Reciprocal Association.

When considering Associations, note that they do not have a datespan. So logged Associations should probably be limited to those that are expected to be lifelong.

The modification

If you go to line 57 of syncAssociations.py you will see:

ASSOC_LOOKUP = {
"cM": "cM",
"DNA": "DNA",
"Godfather": "Godchild",
"Godmother": "Godchild",
"Landlord": "Tenant"
}

You need to add lines with a similar format (quoted string then colon then quoted string then comma)

Once the new Associations Types have tested and work as expected, submit an feature request to included it in the addon.

Issues

See also