Introduction
Data References refer to items of data held within Records, and are used within Expressions that occur most commonly in:
- Queries to specify Columns, Row filters, and Titles
- Diagram Text Schemes to define the content of Diagram Boxes
- Diagram > Options > Boxes > Conditions to define box style
- Reports to define Data items in certain Report Sections
- Customise or Print Records Window Columns or Named List Columns
- Captions and Custom Fields in Property Boxes
- Narrative Report Fact Sentence Templates since ƒh V6
- Override Templates for Fact displays since ƒh V6
For a full list see (ƒh7) Expressions and Contexts of Use or (ƒh6) Expressions and Contexts of Use.
Expressions are composed from two ƒh features:
Data References that often appear enclosed within percentage signs, e.g.%INDI.BIRT%
- Functions that begin with an = sign (except when used within another Function), e.g.
=RecordId()
Data References
Data References identify Data items within Records. For example, the following Expression is a Data Reference that specifies a particular Individual Birth Event:
%INDI.BIRT%
For full details see the help pages linked at the top of this article including several new features added in ƒh6 and ƒh7.
The structure of Data References in all versions of ƒh up to version 6 is derived from the The Gedcom Standard, Release 5.5 dated 2nd January 1996.
The Basics
You should rarely need to construct a Data Reference yourself, because ƒh offers a Data Reference Assistant (DRA) associated with every type of Expression. For example, in a Query Window, on the Columns tab, there is a Fields DRA panel on the left, and on the Rows tab, the Expression box has an ellipsis […] DRA button to the right.
Basically each Data Reference is composed of Tags that identify Data. These are separated by either a dot.
or a greater than >
sign, and the whole reference is usually enclosed within percent %
signs.
For example, to identify for any given INDIvidual, the NAME of their father, you could use the following Data Reference:
%INDI.FAMC>HUSB>NAME%
This looks intimidating, but is not as complex as it appears, and the parts have the following meaning: The available Tags are always offered and explained by the relevant Data Reference Assistant, and Record links are listed with a trailing double greater than >> symbol. The Tags are mostly the same as used in GEDCOM but there are a few exceptions. For example, in GEDCOM the There can be more than one instance of many of the Data fields. An Individual can have more than one Name, more than one Child, or more than one Census entry. Each instance is identified by an index in square brackets [1]. If no index is supplied, then the first instance is assumed by default. So for example: For more options, see the help pages linked at the top of this article. These Indices are one of the rare cases where a Data Reference must be manually edited, because they cannot be selected using a Data Reference Assistant. An ordinary Data Reference starts with a tag that identifies a record, but in some contexts the Data Reference can be relative to a subsidiary tag such as a Fact in a Fact Query or a Sentence Template in later versions of ƒh. In some cases the initial tilde ~ can be followed by > instead of a dot. Relative data references also apply to parameters of some Functions and throughout ƒh Plugins. Some data items are difficult or impossible to access using an ordinary Data Reference. To solve this problem ƒh supports five dummy Tags called Shortcuts that begin with a tilde ~ symbol. So for example: The available Shortcuts are always offered and explained by the relevant Data Reference Assistant, and are listed with an upward pointing arrow prefix. A Data Reference in some cases can specify how the data is displayed by using a Qualifier. These are appended to the last Tag separated by a colon The available Qualifiers are always offered and explained by the relevant Data Reference Assistant. So for example: Contextual Data References were added in ƒh V6 and only have meaning in their specific context of use, mostly within Diagrams where the currently displayed Family couple needs to be identified. Elsewhere: Narrative Sentence Templates: Contextual data references behave like ordinary data references, in that you can expand them to refer to any detail of the record in question. For example, Sentence Template Data References were added in ƒh V6 and only have meaning in specific template contexts. For more detail, see towards the end of (ƒh7) Sentence Template Codes or (ƒh6) Template Codes. Typically the data reference is enclosed in curly brackets and its context is the current fact, e.g. To refer to witness details from a witness sentence template requires the use of the Version 7 introduced the ability to have embedded links to other records within Note fields. To access these, the reference is e.g. for a link to an individual within the Text from Source for a Source: Note1: a linked object should have the same index no matter how many times they are linked in the Note. Note2: Replace
INDI
Start with an INDIvidual Record
FAMC
Within this Record, follow the > link to the FAMily they belong to as a Child
HUSB
The father is identified by the HUSBand field in this Family Record and another > link leads to another Individual Record
NAME
Within that linked Individual Record we find the NAME field of the father
NOTE
tag is used with the format @N321@
to link to a Note Record, or with any other text for a Local Note. Whereas, Data References use the tags NOTE>
and NOTE2
respectively to make the distinction clear. Data References also use a special Tag format for custom Events (EVENT-<event_name>
) and Attributes (_ATTR-<attr_name>
).Indices
%INDI.NAME[2]%
identifies the 2nd Name
%INDI.CENS[4]%
identifies the 4th Census Event
%INDI.CENS[last]%
is an advanced index to identify the last Census Event
%INDI.CENS[year=1881]%
is an advanced index to identify the 1881 Census Event
Relative Data References
~.PLAC
identifies the Place field of a Fact
~.DATE
identifies the Date field of a Fact
Shortcuts
~FATH
identifies the father of an Individual
~MOTH
identifies the mother of an Individual
~CHIL
identifies a child of an Individual
~SPOU
identifies a spouse of an Individual or a Family Record
~CURSPOU
identifies the spouse of an Individual for any particular Diagram Box
%INDI.~CHIL[2]%
identifies the 2nd child of an Individual by any marriage
%INDI.~SPOU[1]>BIRT.DATE%
identifies the date of birth of the 1st spouse of an Individual
Qualifiers
:
symbol.
%INDI.NAME:SURNAME%
displays just the Surname of an Individual
%INDI.BIRT.DATE:YEAR%
displays just the Year of Birth of an Individual
%INDI.DEAT.PLAC:SHORT%
displays just the first item up to the first comma in the Death Place field
Contextual Data References
%CUR_SPOU% and %CUR_SPOU>%
Current Spouse
%CUR_FAMS% and %CUR_FAMS>%
Current Family As Spouse
%CUR_FAMC% and %CUR_FAMC>%
Current Family as Child
%CUR_SP_FAMS% and %CUR_SP_FAMS>%
Current Spouse’s Family as Spouse
%CUR_SP_FAMC% and %CUR_SP_FAMC>%
Current Spouse’s Family as Child
%CUR_BASE%
Base Person
%CUR_TREE_ROOT%
Tree Root
%CUR_TREE_ROOT_FAM%
Tree Root Family
%CUR_DGM_ROOT%
Diagram Root
%CUR_DGM_ROOT_FAM%
Diagram Root Family
%CUR_DGM_ROOT_COUPLE_FAM%
Diagram Root Couple’s Family
%CUR_OTHER_IND%
Other Individual in ‘How Related’ report
%CUR_FILE_ROOT%
File Root nearly everywhere
%CUR_FILE_OWNER%
File Owner nearly everywhere
%CUR_FILE_HEADER%
File Header nearly everywhere
%CUR_PRIN%
First or current principal for the fact
%CUR_PRIN2%
Second or other principal for the Family fact
%CUR~WITN% and %CUR~WITN>%
Current witness
%CUR_SPOU>SEX%
refers to the sex of the Individual’s current spouse, and %CUR_FILE_ROOT.SEX%
refers to the sex of the current file root.Sentence Template Data References
{%FACT.PHON%}
refers to the fact phone number.%CUR~WITN%
contextual data reference shown above.
{%CUR~WITN>NAME:GIVEN%}
Returns the Witness record forename
{%CUR~WITN.NOTE2%}
Returns the Witness role local Note
Embedded Link Data References (V7)
%SOUR.TEXT._LINK_I[1]>%
for the first linked individual%SOUR.TEXT._LINK_I[2]>%
for the second linked individual_I
with _S
for links to Sources, _R
for Repositories etc.