Difference between revisions of "Rule expansions"
m (→Section) |
m (→Add-on Rules: placeholder for other Rules (increase visibility for downloads)) |
||
(28 intermediate revisions by 2 users not shown) | |||
Line 5: | Line 5: | ||
{{man tip| 1=Changes to Rules are inconspicuous|2=New built-in Rules appear without any fanfare. Plus there a so many of them, grouped in so many subcategories that they may remain concealed.<br />Addons require downloading and installation, so the addon Rules have more visibility than the builtins. Plus they can be searched as a category in the Plugin Manager.}} | {{man tip| 1=Changes to Rules are inconspicuous|2=New built-in Rules appear without any fanfare. Plus there a so many of them, grouped in so many subcategories that they may remain concealed.<br />Addons require downloading and installation, so the addon Rules have more visibility than the builtins. Plus they can be searched as a category in the Plugin Manager.}} | ||
[[File:Preferences UpdateAddons-Rule-51.png|thumb|right|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Preferences: Check for Updated Addons showing Rules]] | [[File:Preferences UpdateAddons-Rule-51.png|thumb|right|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Preferences: Check for Updated Addons showing Rules]] | ||
− | Rules are the basic building blocks of | + | Rules are the basic building blocks of custom [[Filter|Filters]]. |
− | |||
− | |||
+ | With the release of [[Template:Releases/5.1.0|Gramps version 5.1]], the first addon Rules were [https://github.com/gramps-project/addons-source/tree/master/FilterRules posted as examples of coding a Filter Rule addon]. [[{{Version manual}}_Addons#Installing_Addons_in_Gramps|Installing similarly to any other addon]], a New Rule appears as a menu item within [[Gramps_{{Version manual}}_Wiki_Manual_-_Filters#Add_Rule_dialog|Add Rule dialog]] while [[Gramps_{{Version manual}}_Wiki_Manual_-_Filters#Define_Filter_dialog|Defining a custom Filter]]. | ||
+ | Filters created with these Rules can tested, cloned or deleted using the [[Gramps_5.1_Wiki_Manual_-_Filters#CategoryName_Filters_dialog|Filter Editor]]. The dialog is invoked from the {{Man menu|Edit}} menu in each Category view. | ||
<!-- | <!-- | ||
* Find Families/People having Events with a specific Role | * Find Families/People having Events with a specific Role | ||
:([https://github.com/gramps-project/addons-source/blob/master/FilterRules/hasrolerule.py source] and [https://github.com/gramps-project/addons-source/blob/master/FilterRules/hasrolerule.gpr.py info]) | :([https://github.com/gramps-project/addons-source/blob/master/FilterRules/hasrolerule.py source] and [https://github.com/gramps-project/addons-source/blob/master/FilterRules/hasrolerule.gpr.py info]) | ||
− | :This example shows how to create a rule which applies to 2 Categories (Families & People) where with an Event having a spefic | + | :This example shows how to create a rule which applies to 2 Categories (Families & People) where with an Event having a spefic [[Gramps_Glossary#event_role|Event Role]] |
* hassourcefilter.py Fix FilterRules to recognize local po files 29 days ago | * hassourcefilter.py Fix FilterRules to recognize local po files 29 days ago | ||
Line 21: | Line 21: | ||
* isrelatedwithfiltermatch.gpr.py Fix FilterRules to recognize local po files | * isrelatedwithfiltermatch.gpr.py Fix FilterRules to recognize local po files | ||
− | |||
: [https://github.com/gramps-project/addons-source/pull/274 Proposed #274] New filter rule 'familieswitheventfiltermatch' | : [https://github.com/gramps-project/addons-source/pull/274 Proposed #274] New filter rule 'familieswitheventfiltermatch' | ||
: [https://github.com/gramps-project/addons-source/pull/275 Proposed #275] New filter rule 'personshavingfamilyfiltermatch' | : [https://github.com/gramps-project/addons-source/pull/275 Proposed #275] New filter rule 'personshavingfamilyfiltermatch' | ||
--> | --> | ||
− | |||
− | |||
− | Open the Plugin Manager from the Help menu and use its Search box to filter the view to only those addons which have a row or filename which include the 'Rule' term. | + | =locating Filter Rule Add-Ons= |
+ | [[File:EnhancedPlugInManager-addon-SearchRule 51win.png|thumb|right|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Search for '''''Rule''''' in the Enhanced Plugin Manager]]The [[Plugin_Manager_Plugin|Plugin Manager]] can be used for more than installing & updating plug-in modules. It can help you discover the growing capabilities that might not be obvious. | ||
+ | |||
+ | Open the {{Man menu|Plugin Manager}} from the {{Man menu|Help}} menu and use its Search box to filter the view to only those addons which have a row or filename which include the 'Rule' term. | ||
[[File:EnhancedPlugInManager-addon-Info 51win.png|thumb|right|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Info on 'People related to ''<filter>''' addon Rule]] | [[File:EnhancedPlugInManager-addon-Info 51win.png|thumb|right|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Info on 'People related to ''<filter>''' addon Rule]] | ||
+ | Add-on Rules that have been peer-reviewed will be added to Gramps' Update Manager system. This automates the installation process | ||
+ | |||
+ | When manually installed, each add-on rule's Python source code (<code>.py</code>) file and Gramps Plugin Registration (<code>.gpr.py</code>) file will be located in the <code>\gramps{{Version manual}}\plugins\FilterRules\</code> subdirectory of your [[Gramps_{{Version manual}}_Wiki_Manual_-_User_Directory|User Directory]] | ||
+ | |||
+ | Looking at the Info on any currently installed Rule will verify the file location where add-on rules have been installed. | ||
{{-}} | {{-}} | ||
==Add-on Rules== | ==Add-on Rules== | ||
{{-}} | {{-}} | ||
+ | {{-}} | ||
+ | Multilingual internationalization services [https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html .po & .pot] files using gettext. | ||
+ | |||
+ | ===People related to <filter>=== | ||
+ | [[File:Rule_Person_Filter_Win.png|thumb|right|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Searching by Rule name]]{{icon|peop}}'''Person • General filters''' [[{{Version manual}}_Addons|add-on]] rule to find [[Gramps_Glossary#person|Person(s)]] matching a specified filter. | ||
+ | Matches people who are related to anybody matched by a person filter.{{-}}[[File:Pythongadget.png|left|150px|link=https://github.com/gramps-project/addons-source/tree/master/FilterRules]]<code>'''isrelatedwithfiltermatch'''</code> provided as [https://github.com/gramps-project/addons-source/tree/master/FilterRules <code>sample '''.gpr.py''' & '''.py''' code</code> for writing add-on filter rules]. Demonstrates piping the output of one custom Filter into another.{{-}} | ||
+ | ---- | ||
+ | ===People with events with a selected role=== | ||
+ | [[File:Rule_PersonEvent_Role_Win.png|thumb|right|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Searching for Person Rules which include the 'role' term.]] | ||
+ | {{icon|peop}}'''Person • Event filters''' [[{{Version manual}}_Addons|add-on]] rule to find [[Gramps_Glossary#person|Person(s)]] having any [[Gramps_Glossary#event|Event]] with a specified [[Gramps_Glossary#event_role|Event Role]]. | ||
{{-}} | {{-}} | ||
+ | ===Families with Events with a selected role=== | ||
+ | [[File:Rule_FamiliesEvent_Role_Win.png|thumb|right|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Searching by Rule name]] | ||
+ | {{icon|fami}}'''Families • Event filters''' [[{{Version manual}}_Addons|add-on]] rule to find [[Gramps_Glossary#family|Families]] having any Family member or shared Family level [[Gramps_Glossary#event|Event]] with a specified [[Gramps_Glossary#event_role|Event Role]].{{-}}[[File:Pythongadget.png|left|150px|link=https://github.com/gramps-project/addons-source/tree/master/FilterRules]]<code>'''hasrolerule'''</code> provided as [https://github.com/gramps-project/addons-source/tree/master/FilterRules <code>sample '''.gpr.py''' & '''.py''' code</code> for writing add-on filter rules]. Demonstrates including category variants of a rule in the same add-on.{{-}} | ||
+ | ---- | ||
+ | ===Source matching parameters=== | ||
+ | [[File:Rule_Sources_Parameters_Win.png|thumb|right|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Searching by Rule name]] | ||
+ | {{icon|sour34}}'''Sources • General filters''' [[{{Version manual}}_Addons|add-on]] rule to find [[Gramps_Glossary#source|Sources]] based on the following parameters: ''Title'', ''Author'', ''Abbreviation'', ''Publication''. | ||
+ | |||
+ | This add-on rule has similar options to the standard Filter Gramplet for the [[Gramps_{{Version manual}}_Wiki_Manual_-_Entering_and_editing_data:_detailed_-_part_2#New_Source_dialog|Source]] [[Gramps_{{Version manual}}_Wiki_Manual_-_Categories#Sources_Category|Category View]]. It can be used to save complex filter parameters.{{-}}[[File:Pythongadget.png|left|150px|link=https://github.com/gramps-project/addons-source/tree/master/FilterRules]]<code>'''hassourcefilter'''</code> provided as sample [[Addons_development#Create_a_Gramps_Plugin_Registration_file|.gpr.py]] & '''.py''' code for [https://github.com/gramps-project/addons-source/tree/master/FilterRules writing add-on filter rules]. Demonstrates text based filtering with RegEx options.{{-}} | ||
+ | ---- | ||
===People Separated less than <N> degrees of <Home person>=== | ===People Separated less than <N> degrees of <Home person>=== | ||
− | [[File: | + | [[File:Rule_DegreesOfSep_HomePerson_Win.png|thumb|right|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Searching for Person Rules which include the 'degrees' term.]] |
+ | {{icon|peop}}'''Person • Relationship filters''' [[{{Version manual}}_Addons|add-on]] rule to find [[Gramps_Glossary#person|Person(s)]] having a relationship to the ''[[Gramps_Glossary#home_person|Home Person]]'' within a specified degree of [[Genealogy_Glossary#consanguinity|Consanguinity]] and [[Genealogy_Glossary#affinity|Affinity]]. | ||
+ | The [[Gramps_Glossary#home_person|Home person]] is point of reference for calculating ('''<N>''') Degrees. For '''N''', Minimum value is 1, Maximum is value 32. | ||
+ | |||
+ | * '''Degree 1''': person/spouse + children ( <zero N> ancestors, because the selected person is generation 1 + 1N descendants) | ||
+ | * '''Degree 2''': person plus person’s parents, siblings, niece/nephew, children, grandchildren, etc. (= 1N ancestors + 2N descendants) | ||
+ | * '''Degree 3''': persons grandparents and 3 generations down. (= 2N ancestors + 3N descendants). | ||
+ | |||
+ | The ancestors and descendants generations have an offset of 1 to mimic the built-in filter rule behavior. | ||
+ | |||
+ | [https://gist.github.com/Mattkmmr/4d0369cbee38bdf14395cb2f4505fb8a GitHub Repository files] | ||
{{-}} | {{-}} | ||
===People Separated less than <N> degrees of <person>=== | ===People Separated less than <N> degrees of <person>=== | ||
− | [[File: | + | [[File:Rule_DegreesOfSep_PersonID_Win.png|thumb|right|450px|Fig. {{#var:chapter}}.{{#vardefineecho:figure|{{#expr:{{#var:figure}}+1}}}} Searching Person rules by 'degrees' term; roll-over hint for ID.]] |
+ | {{icon|peop}}'''Person • Relationship filters''' [[{{Version manual}}_Addons|add-on]] rule to find [[Gramps_Glossary#person|Person(s)]] having a relationship to a specified Person within a specified degree of [[Genealogy_Glossary#consanguinity|Consanguinity]] and [[Genealogy_Glossary#affinity|Affinity]]. | ||
+ | |||
+ | [https://github.com/gramps-project/addons-source/pull/283 GitHub Repository files] | ||
+ | {{-}} | ||
+ | ==Add-on Rules needing additional documentation== | ||
+ | {{stub}} | ||
+ | ===Descendants of <person> sharing yDNA with each other=== | ||
+ | Matches descendants of a <person> sharing yDNA | ||
+ | |||
+ | ===Events of families matching a <family filter>=== | ||
+ | Events of families matching a <family filter> | ||
+ | |||
+ | ===Families matching <event filter>=== | ||
+ | Matches families that are matched by an event filter | ||
+ | |||
+ | ===Matrilineal progenitrix of <person>=== | ||
+ | Matches the earliest recorded matrilineal ancestor mother. | ||
+ | |||
+ | ===Mitochondrial inheritance of <filter>=== | ||
+ | Matches recorded descendants of a filter result following mitochondrial inheritance patterns. | ||
+ | |||
+ | ===Mitochondrial inheritance of <person>=== | ||
+ | Matches recorded descendants of person following mitochondrial inheritance patterns. | ||
+ | |||
+ | ===Patrilineal progenitor of <person>=== | ||
+ | Matches the earliest recorded patrilineal ancestor father. | ||
+ | |||
+ | ===People who are part of families matching <filter>=== | ||
+ | People who are part of families matching <filter> | ||
+ | |||
+ | ===The Active Person=== | ||
+ | The active Person | ||
+ | |||
+ | ===X-chromosomal ancestors of <person>=== | ||
+ | Matches ancestors of <person> following a X-chromosomal inheritance pattern. | ||
+ | |||
+ | ===X-chromosomal descendants of <person>=== | ||
+ | Matches descendants of <person> following a X-chromosomal inheritance pattern. | ||
+ | |||
+ | ===Y-chromosomal inheritance of <person filter>=== | ||
+ | Matches recorded descendants of a filter result following Y-chromosomal inheritance patterns. | ||
+ | ===Y-chromosomal inheritance of <person>=== | ||
+ | Matches recorded descendants of person following Y-chromosomal inheritance patterns. | ||
{{-}} | {{-}} | ||
Line 82: | Line 160: | ||
* Fix Custom filter update when created via sidebar. | * Fix Custom filter update when created via sidebar. | ||
− | = | + | =Developing New Rule Add-Ons = |
Beginning with version 5.0, Gramps implemented an database API (application programming interface) infrastructure supporting user selectable backends. This new exploration of database support lead developer to extend the add-on (plug-in) framework to support expanding Filter Rules via the Plugin Manager. | Beginning with version 5.0, Gramps implemented an database API (application programming interface) infrastructure supporting user selectable backends. This new exploration of database support lead developer to extend the add-on (plug-in) framework to support expanding Filter Rules via the Plugin Manager. | ||
Line 90: | Line 168: | ||
--> | --> | ||
− | = Resources = | + | == Resources == |
* [https://github.com/gramps-project/addons-source/tree/master/FilterRules Sample addon Filter code] | * [https://github.com/gramps-project/addons-source/tree/master/FilterRules Sample addon Filter code] | ||
== See also == | == See also == | ||
Line 117: | Line 195: | ||
[[Category:Addons]] | [[Category:Addons]] | ||
[[Category:Plugins]] | [[Category:Plugins]] | ||
− | + | [[Category:How do I...]] | |
<!-- | <!-- | ||
Line 209: | Line 287: | ||
{{man warn|1=WarningTitle/Heading |2=warning text }}</onlyinclude> | {{man warn|1=WarningTitle/Heading |2=warning text }}</onlyinclude> | ||
--> | --> | ||
− |
Revision as of 05:10, 5 May 2020
Contents
- 1 Rule Ammendments
- 2 locating Filter Rule Add-Ons
- 2.1 Add-on Rules
- 2.2 Add-on Rules needing additional documentation
- 2.2.1 Descendants of <person> sharing yDNA with each other
- 2.2.2 Events of families matching a <family filter>
- 2.2.3 Families matching <event filter>
- 2.2.4 Matrilineal progenitrix of <person>
- 2.2.5 Mitochondrial inheritance of <filter>
- 2.2.6 Mitochondrial inheritance of <person>
- 2.2.7 Patrilineal progenitor of <person>
- 2.2.8 People who are part of families matching <filter>
- 2.2.9 The Active Person
- 2.2.10 X-chromosomal ancestors of <person>
- 2.2.11 X-chromosomal descendants of <person>
- 2.2.12 Y-chromosomal inheritance of <person filter>
- 2.2.13 Y-chromosomal inheritance of <person>
- 3 The Evolution of of Rules as Add-Ons
- 4 Developing New Rule Add-Ons
Rule Ammendments
Rules are the basic building blocks of custom Filters.
With the release of Gramps version 5.1, the first addon Rules were posted as examples of coding a Filter Rule addon. Installing similarly to any other addon, a New Rule appears as a menu item within Add Rule dialog while Defining a custom Filter.
Filters created with these Rules can tested, cloned or deleted using the Filter Editor. The dialog is invoked from the Edit menu in each Category view.
locating Filter Rule Add-Ons
The Plugin Manager can be used for more than installing & updating plug-in modules. It can help you discover the growing capabilities that might not be obvious.
Open the Plugin Manager from the Help menu and use its Search box to filter the view to only those addons which have a row or filename which include the 'Rule' term.
Add-on Rules that have been peer-reviewed will be added to Gramps' Update Manager system. This automates the installation process
When manually installed, each add-on rule's Python source code (.py
) file and Gramps Plugin Registration (.gpr.py
) file will be located in the \gramps5.2\plugins\FilterRules\
subdirectory of your User Directory
Looking at the Info on any currently installed Rule will verify the file location where add-on rules have been installed.
Add-on Rules
Multilingual internationalization services .po & .pot files using gettext.
Person • General filters add-on rule to find Person(s) matching a specified filter.
Matches people who are related to anybody matched by a person filter.
isrelatedwithfiltermatch
provided as sample .gpr.py & .py code
for writing add-on filter rules. Demonstrates piping the output of one custom Filter into another.
People with events with a selected role
Person • Event filters add-on rule to find Person(s) having any Event with a specified Event Role.
Families with Events with a selected role
Families • Event filters add-on rule to find Families having any Family member or shared Family level Event with a specified Event Role.
hasrolerule
provided as sample .gpr.py & .py code
for writing add-on filter rules. Demonstrates including category variants of a rule in the same add-on.
Source matching parameters
Sources • General filters add-on rule to find Sources based on the following parameters: Title, Author, Abbreviation, Publication.
This add-on rule has similar options to the standard Filter Gramplet for the Source Category View. It can be used to save complex filter parameters.
hassourcefilter
provided as sample .gpr.py & .py code for writing add-on filter rules. Demonstrates text based filtering with RegEx options.
People Separated less than <N> degrees of <Home person>
Person • Relationship filters add-on rule to find Person(s) having a relationship to the Home Person within a specified degree of Consanguinity and Affinity.
The Home person is point of reference for calculating (<N>) Degrees. For N, Minimum value is 1, Maximum is value 32.
- Degree 1: person/spouse + children ( <zero N> ancestors, because the selected person is generation 1 + 1N descendants)
- Degree 2: person plus person’s parents, siblings, niece/nephew, children, grandchildren, etc. (= 1N ancestors + 2N descendants)
- Degree 3: persons grandparents and 3 generations down. (= 2N ancestors + 3N descendants).
The ancestors and descendants generations have an offset of 1 to mimic the built-in filter rule behavior.
People Separated less than <N> degrees of <person>
Person • Relationship filters add-on rule to find Person(s) having a relationship to a specified Person within a specified degree of Consanguinity and Affinity.
Add-on Rules needing additional documentation
This article's content is incomplete or a placeholder stub. |
Descendants of <person> sharing yDNA with each other
Matches descendants of a <person> sharing yDNA
Events of families matching a <family filter>
Events of families matching a <family filter>
Families matching <event filter>
Matches families that are matched by an event filter
Matrilineal progenitrix of <person>
Matches the earliest recorded matrilineal ancestor mother.
Mitochondrial inheritance of <filter>
Matches recorded descendants of a filter result following mitochondrial inheritance patterns.
Mitochondrial inheritance of <person>
Matches recorded descendants of person following mitochondrial inheritance patterns.
Patrilineal progenitor of <person>
Matches the earliest recorded patrilineal ancestor father.
People who are part of families matching <filter>
People who are part of families matching <filter>
The Active Person
The active Person
X-chromosomal ancestors of <person>
Matches ancestors of <person> following a X-chromosomal inheritance pattern.
X-chromosomal descendants of <person>
Matches descendants of <person> following a X-chromosomal inheritance pattern.
Y-chromosomal inheritance of <person filter>
Matches recorded descendants of a filter result following Y-chromosomal inheritance patterns.
Y-chromosomal inheritance of <person>
Matches recorded descendants of person following Y-chromosomal inheritance patterns.
The Evolution of of Rules as Add-Ons
Gramps 5.1.1 (Sept. 2019)
- Fix bug 0011114: resolve crashes in withinarea filter rule:
- Avoid bad coordinates in the ref place
- Avoid alphabetic characters in filter rules
- Could not convert string to float by using withinarea filter rule
- Difference between sidebar filter and filter rule
- Fix Bug 0011293 Fix internationalization issue where untranslated English GUI items appear in Event filter
Gramps 5.1.0 (Aug. 2019)
- New feature : Filter Rules can now be expanded through the addons interface.
- Filter Rule editor, save pane position
- Fix Bugs 0007950 and 0011430: Name Filter rule now supports multiple attribute: Check all values of an attribute type and not only the first one
- filters rule have children person filter: Check all families of a person for children and not only the first
- Person Sidebarfilter:
- Fix Person Sidebarfilter when using ‘Event’ and Reg expressions
- In personsidebarfilter, search on each part of name Instead of requiring that the entire search string matches a single one of the Person’s names, the function will require that each word in the search string matches any of the Person’s name fields.
- Fix exception when merging with active sidebar filter
Gramps 5.0.2 (Aug. 2019)
- Fix bug 0010509: resolves silent fail - relationship path between filter rule when parent is missing
- Fix crash when using sidebar filter and merging in another view
- Fix Place Tree view when using enclosed by sidebar filter
- Fix Relationship Graph; extra people when using filters & subgraphs
Gramps 5.0.1 (Dec. 2018)
- Fix bug 0010685: resolves crash in IsDuplicatedAncestorOf filter rule on tree loop
- Fix Person Sidebarfilter when using ‘Event’ and Reg expressions
- Fix FilterParser for much older 3.x custom_filters.xml files
- Fix crash when a filter with loop in definition is defined
- Fix view so column widths are preserved when using filters
Gramps 5.0.0 (Jul. 2018)
- Fix Custom filter update when created via sidebar.
Developing New Rule Add-Ons
Beginning with version 5.0, Gramps implemented an database API (application programming interface) infrastructure supporting user selectable backends. This new exploration of database support lead developer to extend the add-on (plug-in) framework to support expanding Filter Rules via the Plugin Manager.
The 5.1 release changed the default database backend from BSDDB (Berkeley database) to SQLite. With the broader group of user familiar with optimizing searches, it made sense to open Gramps to the specialized knowledge.
Resources
See also
- Git introduction
- https://github.com/gramps-project/addons-source - Source code (Git)
- Gtk+ widget gallery - Gnome development sample code
- https://github.com/gramps-project/addons - downloadable .tgz files
- Addons Development
- Writing a Plugin
- Policy for Committing code contributions
- [Gramps-devel]: Filter rules as plugins?
- [Gramps-users]: A question on writing filters
- [Gramps-devel]: New filter rules on Names
- [Gramps-devel]: Sequencing of filter rules?
- [Gramps-devel]: filter rules
- [Gramps-users]: Gramplet writing - newbie help needed
- based on the Gramps-users archived threads: