Difference between revisions of "Specification:Relationship Calculator"

From Gramps
Jump to: navigation, search
m (How to write a relationship calculator: correct API links)
(How to write a relationship calculator)
Line 13: Line 13:
 
==How to write a relationship calculator==
 
==How to write a relationship calculator==
 
The framework for relationship calculator plugins is in place. Here are the rules the language-specific plugins must obey to be compatible with the framework:
 
The framework for relationship calculator plugins is in place. Here are the rules the language-specific plugins must obey to be compatible with the framework:
# The relationship plugins (here and below referred to as <code>rel</code> plugins) must define a class that can be instantiated with the [http://www.gramps-project.org/devdoc/api/2.2/private/GrampsDb._GrampsDbBase.GrampsDbBase-class.html GrampsDbBase] instance as its argument and that has a <code>get_relationship</code> method obeying the following rules:
+
# The relationship plugins (here and below referred to as <code>rel</code> plugins) must define a class that can be instantiated with the [http://www.gramps-project.org/devdoc/api/2.2/private/GrampsDb._GrampsDbBase.GrampsDbBase-class.html GrampsDbBase] instance as its argument and that has a <code>get_relationship()</code> method obeying the following specifications:
#* The arguments of <code>get_relationship</code> method are two [http://www.gramps-project.org/devdoc/api/2.2/private/RelLib._Person.Person-class.html Person] objects. To be determined is the relationship of the second person to the first person.
+
#* The <code>get_relationship()</code> method takes '''two''' input arguments, which are two instances of the [http://www.gramps-project.org/devdoc/api/2.2/private/RelLib._Person.Person-class.html Person] class. To be determined is the relationship of the second person to the first person.
#* The values returned by the function are the string of the relationship (e.g. "father", or "grandson") and the list of the closest common ancestors of these two persons.
+
#* The <code>get_relationship()</code> method returns a tuple with '''two''' values:
 +
#*# The string of the relationship (e.g. "father", or "grandson")
 +
#*# The list of the closest common ancestors of these two persons.
 
#* For the sake of the following example, assume that the above function is defined in <code>src/plugins/rel_xx.py</code> (where <code>xx</code> is your language code), and it's name is <code>get_relationship(first_person,second_person)</code>. Also assume that it returns a pair of values: <code>(rel_string, acnestor_list)</code>.
 
#* For the sake of the following example, assume that the above function is defined in <code>src/plugins/rel_xx.py</code> (where <code>xx</code> is your language code), and it's name is <code>get_relationship(first_person,second_person)</code>. Also assume that it returns a pair of values: <code>(rel_string, acnestor_list)</code>.
 
#* Text strings returned by the function should be in the UNICODE character set. GNOME expects all displayed strings to be UNICODE characters, and most report formats use UNICODE. While it may be tempting to use ISO-8859 or other character sets, these will not display correctly and will cause errors.
 
#* Text strings returned by the function should be in the UNICODE character set. GNOME expects all displayed strings to be UNICODE characters, and most report formats use UNICODE. While it may be tempting to use ISO-8859 or other character sets, these will not display correctly and will cause errors.
# The <code>rel</code> plugin must register itself with the plugins system as the <code>relcalc</code> tool. This is done by inserting the following code at the end of your <code>rel_xx.py</code> plugin:
+
# The relationship plugin must register itself with the plugin system as the <code>relcalc</code> tool. This is done by inserting the following code at the end of your <code>rel_xx.py</code> file:
  
 
     from PluginMgr import register_relcalc
 
     from PluginMgr import register_relcalc
        register_relcalc(RelationshipCalculatorClass,["xx","XX",
+
    register_relcalc(RelationshipCalculatorClass,["xx","XX","xx_YY","xxxxxx","Xxxxxx","Xxxxxxx_xx"])
                "xx_YY","xxxxxx","Xxxxxx","Xxxxxxx_xx"])
+
  
:where <code>RelationshipCalculatorClass</code> is the class whose method is the <code>get_relationship</code> and the items in quotes are language identifiers that '''may possibly''' be associated with your language. For example, different systems use <code>ru</code>, <code>RU</code>, <code>ru_RU</code>, <code>koi8r</code>, <code>ru_koi8r</code>, <code>russian</code>, <code>Russian</code>, <code>ru_RU.koi8r</code>, etc. to identify the Russian language.
+
:where <code>RelationshipCalculatorClass</code> is the class whose method is the <code>get_relationship()</code> and the items in quotes are language identifiers that '''may possibly''' be associated with your language. For example, different systems use <code>ru</code>, <code>RU</code>, <code>ru_RU</code>, <code>koi8r</code>, <code>ru_koi8r</code>, <code>russian</code>, <code>Russian</code>, <code>ru_RU.koi8r</code>, etc. to identify the Russian language.
  
  
 
That's it for the requirements. The example <code>relcalc</code> plugins can be found in <code>src/Relationship.py</code> and <code>src/plugins/rel_ru.py</code>.
 
That's it for the requirements. The example <code>relcalc</code> plugins can be found in <code>src/Relationship.py</code> and <code>src/plugins/rel_ru.py</code>.

Revision as of 16:10, 9 March 2007

This article provides the rationale and requirements for the Relationship Calculator plugin for GRAMPS, and it's localisation.

Why have different relationship calculators?

Different cultures and regions tend to view relationships in different ways. In the United States (and probably other English speaking regions), you can encounter a third cousin, twice removed, which in other regions is meaningless. Other cultures have different terms for your mother's grandfather and your father's grandfather, while English speaking regions would refer to both as a great-grandfather.

By providing relationship calculators, several problems are resolved.

  • Meaningful relation descriptions are returned localized for the user's region.
  • The relationship calculator plugin can return the relationship outside of the Relationship Calculator, allowing relationships to be used in reports and other areas.
  • Translators do not have to worry about trying to translate strings such as "third cousin twice removed" into a local phrase that has no equivalent.

How to write a relationship calculator

The framework for relationship calculator plugins is in place. Here are the rules the language-specific plugins must obey to be compatible with the framework:

  1. The relationship plugins (here and below referred to as rel plugins) must define a class that can be instantiated with the GrampsDbBase instance as its argument and that has a get_relationship() method obeying the following specifications:
    • The get_relationship() method takes two input arguments, which are two instances of the Person class. To be determined is the relationship of the second person to the first person.
    • The get_relationship() method returns a tuple with two values:
      1. The string of the relationship (e.g. "father", or "grandson")
      2. The list of the closest common ancestors of these two persons.
    • For the sake of the following example, assume that the above function is defined in src/plugins/rel_xx.py (where xx is your language code), and it's name is get_relationship(first_person,second_person). Also assume that it returns a pair of values: (rel_string, acnestor_list).
    • Text strings returned by the function should be in the UNICODE character set. GNOME expects all displayed strings to be UNICODE characters, and most report formats use UNICODE. While it may be tempting to use ISO-8859 or other character sets, these will not display correctly and will cause errors.
  2. The relationship plugin must register itself with the plugin system as the relcalc tool. This is done by inserting the following code at the end of your rel_xx.py file:
    from PluginMgr import register_relcalc
    register_relcalc(RelationshipCalculatorClass,["xx","XX","xx_YY","xxxxxx","Xxxxxx","Xxxxxxx_xx"])
where RelationshipCalculatorClass is the class whose method is the get_relationship() and the items in quotes are language identifiers that may possibly be associated with your language. For example, different systems use ru, RU, ru_RU, koi8r, ru_koi8r, russian, Russian, ru_RU.koi8r, etc. to identify the Russian language.


That's it for the requirements. The example relcalc plugins can be found in src/Relationship.py and src/plugins/rel_ru.py.