Advanced Topics

Understanding Data References

This topic is for advanced and technically-minded users only.

The Basics

Data references are expressions, normally written within pairs of percentage signs (e.g. %INDI%), which are used to provide a way of referring to particular items of data in your project, such as records or particular fields within records. They can be used for advanced customizations of diagrams, websites, family tree CDs or DVDs, books, reports (including the content of sentences in narrative reports), and queries.  They can also be used for some advanced customizations of Family Historian itself - such as the Record Window, record selector dialogs, the Property Box caption, and data entry within the Property Box.  In all of these cases, you can do extensive customizations without needing to understand anything about data references and without even needing to know that they exist (the slight exception being queries where, if you create your own queries, you are likely to come across examples of them - but even here, you don't usually need to do anything with them, or understand them, yourself).  But for advanced customizations - customizations which go beyond normal requirements - it may be helpful to understand what data references are, and how you can use them.

The first thing to know about data references is that you very rarely have to construct them yourself. Family Historian will almost always do it for you, whenever you need them.  We said that a data reference is a way of identifying particular items of data - such as a field within a given record type. For example a NAME field in INDIvidual records is identified as %INDI.NAME%.  A data reference can also be used to identify fields in linked records. For example, if you want to know, for a given INDIvidual, what their father's name is, you could use the following expression:

%INDI.FAMC>HUSB>NAME%

This looks intimidating, but is actually not as complex as it looks. The parts have the following meaning:

INDI We're starting with a given INDIvidual
FAMC> Within the Individual's record, we want the (first) link to the FAMily they belonged to as a Child.
HUSB> We're interested in the HUSBand field in this family record (i.e. the father). This field represents another link - this time from the family record to another individual record.
NAME Within that linked Individual record, we want the person's NAME.

What if the husband had more than one name, and you wanted the second name? In that case, you would insert '[2]' after the NAME field, to indicate that it is the 2nd NAME that is wanted. i.e.:

%INDI.FAMC>HUSB>NAME[2]%

In Family Historian, a person can have any number of families as a child too (e.g. you could record the birth family, multiple foster families, an adoption family, etc). What if you were interested in the person's third family as a child? In that case, you would insert a '[3]' after the FAMC field (but before the '>' link indicator). That is, you would write the data reference as:

%INDI.FAMC[3]>HUSB>NAME[2]%

Not all fields can have an 'index' in this way. If you had put the [3] after 'HUSB', this would never have matched anything, because a family record cannot have more than two parents. For interest, though, it might sometimes make sense to put a [2] after 'HUSB' (or after 'WIFE') because Family Historian supports same sex relationships, so a family can have two male partner/parent figures or two female partner/parent figures.

Of course, if you used this expression for a given individual, who did not have 3 families as a child, or if the 3rd family had no male parent, or if there was one, but that person only had one name (or none), then this expression would return no data. The query result set cell, or diagram box (portion of) that you used it for, would simply be blank.

It's worth understanding how to edit data reference to use indices, because Family Historian will not do this for you automatically. Data references generated by Family Historian are always for the first instance of a field only. If you want the 2nd or 3rd value of a field, you have to edit the data reference yourself.

Relative Data References

The textual parts of data references are called 'tags'.  For example, 'INDI' is a tag.  So too are 'FAMC', 'HUSB' and 'NAME'.  Ordinary data references start with a tag that references a record.  'INDI' for example, is the tag for an Individual record.  In some contexts it is permissible to use data references that begin with a special tag, 'FACT', to reference the 'current' fact (you can do this in 'fact' queries and in sentence templates for narrative reports - which are about facts).  Data references are always applied with respect to a given data item - either explicitly supplied, or implied by the context.  Normally this will be a record or a fact.  But what if it isn't?  In that case, you must use a relative data reference.

Relative data references do not begin with a tag. They begin with a single '~' character followed by a '.' or '>'. For example %~.BIRT.DATE% is a relative data reference that could be used instead of %INDI.BIRT.DATE%. Relative data references cannot be used in all the places that ordinary data references can be used.  The only Family Historian functions that you can use relative data references with, are the functions GetField and GetFieldText.  [Plugin authors please note: although GetField and GetFieldText are the only two built-in functions that can use relative data references, they can however be used everywhere within the Family Historian API].

Shortcuts

There are some items of data which are difficult or impossible to access using a standard data reference. Suppose, for example, you want a data reference that will show, for any given person, what their spouse’s date of birth was? You might think you could use this data reference:

%INDI.FAMS>HUSB.BIRT.DATE%

That would work fine if the person you started with was a woman. But if it was a man, it would simply return that person’s own date of birth and not their spouse’s. What you need for this kind of situation is a shortcut.

Family Historian supports a number of shortcuts.  The most commonly-used ones are these:

~FATH
~MOTH
~SPOU
~CHIL
~SHAR

These shortcuts are to a person’s father(s), mother(s), spouse(s), child(ren) and witnessed event(s).  Note that although they begin with a '~' character, the second character is not a '.' or a '>', so they are not relative data references.

These shortcuts can only be used in the context of an Individual record (e.g. %INDI.~FATH>NAME% or %INDI.~SPOU[2]>NAME%).

You can continue a data reference containing a shortcut as if it were any other data reference to an Individual. So, for example,

%INDI.~SPOU>BIRT.DATE%

will, for any individual, give you the date of birth of their first spouse.

Shortcuts can have indices like any ordinary field. So,

%INDI.~SPOU[2]>BIRT.DATE%

will return a person’s second spouse’s date of birth.

The Father and Mother shortcuts are actually not essential. There is nothing that you can do with them that you can’t do without them. The Spouse, Child and Witnessed event shortcuts allow you to do things you couldn’t otherwise do.

It might appear that

%INDI.~CHIL[2]%

is equivalent to

%INDI.FAMS>CHIL[2]%

However, that is not correct. The former will return a given person’s 2nd child - i.e. by any marriage. The latter will return a person’s 2nd child of their first marriage (or relationship), and will return NULL if there were fewer than 2 children in this relationship.

The Witnessed Event shortcut, ~SHAR (short for 'SHARED' - Witnessed events are also known as 'shared events'), is used to reference events (or attributes - but more usually events) in which the Individual participated as a Witness - such as a bridesmaid at a marriage event.  If a person participated in more than one event, you will need to use an index to access all of them.  When a person is a witness to an event, you can record details about the way they participated.  For example, you can record their role, a note, and an override of the default sentence that will be used to describe their role in a report.  You can also provide source citations details for their involvement.  All these details can be accessed using the Witnessed Event shortcut.  To access the witnessed event details, use a chevron (>) after the shortcut (e.g. %~SHAR>DATE%).  To access the witnesses role details with respect to the event, use a dot (.) after the shortcut (e.g. %_SHAR.ROLE%).  The table below gives examples of the two ways of using the Witnessed Event shortcut.

%INDI.~SHAR>% Person's first witnessed event.
%INDI.~SHAR[2]>% Person's second witnessed event.
%INDI.~SHAR[3]>% Person's third witnessed event.
%INDI.~SHAR>DATE% Date of person's first witnessed event
%INDI.~SHAR>NOTE2% Note about the same event (note that NOTE2 just means 'local note' - the 2 is not an index).
%INDI.~SHAR.NOTE2% Note about the person's role as a witness in this event.  Note that a '.' is used instead of a '>' in the previous example.
%INDI.~SHAR.ROLE% Person's role in their first witnessed event.
%INDI.~SHAR._SENT% Override sentence used for the person's witness sentence, describing their role in this event.

Note that the first 5 examples use a chevron (>) after the shortcut, and the remaining 3 use a dot (.).

As well as the shortcuts described above, Family Historian also uses shortcuts with metafields.  These are described in the section Data References and Metafields below.

Qualifiers

As well as specifying which item of data you wish to reference, Data references also allow you, at least in some cases, to specify how you wish the data in question to be displayed. They do this using qualifiers. To see a list of qualifiers associated with any given field, open the Query Window, make sure that you are viewing an Individual query, and select the Columns field. Find ‘Individual’ (first item in the list) and then ‘Name’. When you expand ‘Name’ you will see a list of words in capitals, all with a colon at the front of their name. These are qualifiers. The qualifier :SURNAME first, for example, will extract just the surname from a person’s name. So, for example, to see a person’s spouse’s surname, you could use

%INDI.~SPOU>NAME:SURNAME%

You don’t have to remember qualifier names. Whenever you wish to create a data reference, you simply expand the item you wish to qualify and you will see a list of all available qualifiers. When you select each qualifier, a description field below the list explains what that qualifier is for.

Name fields have 16 qualifiers. Dates have between 15 and 17 qualifiers (see Date Formats). Places have 4. Other fields mainly have no qualifier.

Advanced Indices

As we saw earlier, you can use indices within a data reference if you want to access an item which isn’t the first instance of its kind. For example,

%INDI.~SPOU[2]>NAME:SURNAME%

will give you a person’s 2nd spouse’s surname. But what if you want to see the surname of the person’s last spouse? In that case, you should use [last] as the index. e.g.:

%INDI.~SPOU[last]>NAME:SURNAME%

If you want to see the 2nd last spouse’s surname, you need this version:

%INDI.~SPOU[last-1]>NAME:SURNAME%

This will return nothing (null) if a person only has one spouse.

To see the 3rd last spouse’s surname use

%INDI.~SPOU[last-2]>NAME:SURNAME%

This will return nothing for a given person, if that person has fewer than three spouses.

Sometimes you may want the 3rd index if there is one, but the 2nd if there are only 2, or the first if there is only one. You can achieve this using the ‘<’ character in front of the index. So, for example,

%INDI.NAME[<2]%

will return a person’s 2nd name if they have more than one, and the first if they only have one. It is not quite the same as

%INDI.NAME[last]%

because the former would never return any index value greater than 2. The latter will always return the last item, however many instances there may be.

It is possible to set a flag on events and attributes to indicate that a fact is a preferred fact.  For example, you may have recorded numerous occupations for a given person, but one of them may be the occupation that they were most closely associated with; and you may choose to mark this occupation as the preferred one, by setting the Preferred flag for that fact.   You can reference a preferred fact by using [preferred] as the index. e.g.:

%INDI.OCCU[preferred]%

If a given person has no occupation which has the Preferred flag set, this will return the first one.

Sometimes you may want to just find a Preferred fact - that is, return nothing if there is no fact of that type with the Preferred flag set.  To do that, you can use the [prefonly] index.  e.g.

%INDI.OCCU[prefonly]%

This will match the first occupation which has the 'Preferred' flag set, or return nothing if there is no 'Preferred' occupation.

The [preferred] and [prefonly] indices can only be used with facts (events or attributes).  They are not valid in any other context.

Another useful index is the year index:

%INDI.CENS[year=1881]%

will return the census event that is dated 1881. Similarly, this

%INDI.CENS[year=1891]%

will return the Census event dated 1891.

Finally, there is also the looping index. This is only used in text templates (see Understanding Text Templates) in text schemes and provides a mechanism whereby an item in a text scheme can be repeated for all instances. A looping index has a ‘+’ after the index number, and means ‘repeat for all instances, starting with this one’. For example, an item with this text template:

%IND.OCCU[1+]%

would show all occupations, starting with the first.

Looping indices only work within text templates in text schemes.

REJECTED, Private and Tentative FACTS - AND INDEX FLAGS

All indices, by default, will not match any fact which has the 'Rejected' flag set, even if they would otherwise be a match.  So for example, if a given fact has the Preferred flag set, and the Rejected flag set, by default it will not be matched, even if you use the Preferred index.  You can override this, however, by setting an Index flag.  There are 3 index flags.  Each of them is 2 characters (case-sensitive).  The flags are:

"+r" means "include rejected facts" (i.e. override the default which is to exclude them).  "-p" means "exclude private facts" (i.e. override the default which is to include them).  "-t" means "exclude tentative facts".  Index flags must come after the rest of the index, and must be preceded by a comma.  They can be combined.  So for example, the following are all valid expressions:

%INDI.OCCU[3,+r]%

This will return the 3rd Occupation fact, whether or not any or all of them are flagged as rejected.  %INDI.OCCU[3]% would return the third non-rejected Occupation fact (or nothing if there are fewer than three non-rejected Occupation facts).

%INDI.OCCU[1,-p]%

This will return the 1st non-private (and non-rejected) Occupation fact, or nothing if there is no non-private Occupation fact.

%INDI.OCCU[1+,-p,-t]%

This is an example of a looping index (described above).  It will exclude all private, tentative and rejected facts (remember that rejected facts are excluded by default).

%INDI.OCCU[last,+r,-p]%

This will return the last fact which is not private (whether or not it has been flagged as rejected).

%INDI.OCCU[preferred,+r]%

This will return the first fact marked as preferred, or the first if none; but it will not exclude rejected facts.

Index flags only have meaning when used to index facts (Individual facts or Family facts).

Indices AND THE PROPERTY BOX

The Property Box can be customized (see Customize Property Box).  You can even add custom items if you wish, using data references to specify the field that the item relates to.  Data references used in Property Box customizations must use a simple numeric index or the [preferred] index, if you want the field to be editable.  Other indices can be used (except the looping index), but the resulting field will be read-only.  By default, fields displaying on the main tab of the Property Box, use the [preferred] index if appropriate.

Contextual Data References

Contextual data references are data references which only have meaning in their specific context of use.  For example, a particular diagram might show the members of a given family.  You might wish the box to indicate, in some way, which if any of the children are adopted.  In order to reference that information, you can't simply use a data reference which indicates whether the child was adopted by his family (that is, family-as-child) because he may have more than one recorded family-as-child.  You need to be able to access his relationship to the specific family being displayed in that context in that diagram.  How do you know which family is the relevant one?  For this, you need to use a contextual data reference.

When you come to create a data reference, the possible contextual data references that can be used in that context will be listed in the helper dialog that you use to insert data references.  The table below gives a list of all possible contextual data references, and the contexts in which they can be used.

Label Data Reference Via Link Context of Use
Current Spouse %CUR~SPOU>% yes Diagrams - text schemes and box conditions (Text and Box tabs of Diagram Options)
Current Family As Spouse %CUR~FAMS>% yes Diagrams - text schemes and box conditions
Current Family as Child %CUR~FAMC>% yes Diagrams - text schemes and box conditions
Current Spouse's Family as Spouse %CUR~SP_FAMS>% yes Diagrams - text schemes and box conditions
Current Spouse's Family as Child %CUR~SP_FAMC>% yes Diagrams - text schemes and box conditions
Base Person %CUR_BASE% no Diagrams - text boxes and 'pie shape with text' items (Format dialog, Text tab)
Tree Root %CUR_TREE_ROOT% no Diagrams - text schemes and box conditions
Tree Root Family %CUR_TREE_ROOT_FAM% no Diagrams - text schemes and box conditions
Diagram Root %CUR_DGM_ROOT% no Diagrams - text schemes and box conditions
Diagram Root Family %CUR_DGM_ROOT_FAM% no Diagrams - all contexts
Diagram Root Couple's Family %CUR_DGM_ROOT_COUPLE_FAM% no Diagrams - all contexts
Other Individual %CUR_OTHER_IND% no 'How Related' report - e.g. in Book Settings.
File Root %CUR_FILE_ROOT% no Nearly everywhere
File Owner %CUR_FILE_OWNER% no Nearly everywhere
File Header %CUR_FILE_HEADER% no Nearly everywhere
Current Principal %CUR_PRIN% no In narrative report sentences and sentence templates, to refer to the first or current principal for the event (or attribute).
Other Principal %CUR_PRIN2% no In narrative report sentences and sentence templates, to refer to the second or 'other' principal for the event (or attribute).  Will only reference anything in family events or attributes.
Current Witness %CUR~WITN>% yes In narrative report sentences and sentence templates for witnesses, to refer to the current witness.
Current Source Citation %CUR~CITN>% yes In footnote or short footnote formats for a source citation, to refer to the current source citation.

Please note: the format of the first 5 contextual data references changed slightly in version 6.0.5.  The old versions, which had an underscore (_) instead of the tilda character (~), are depreciated but still supported for to ensure backwards compatibility with earlier versions of the software.

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, %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. 

There are 2 kinds of contextual data reference.  Some of them begin 'CUR~' and some begin 'CUR_'.  They all begin with one or the other.  The ones that begin 'CUR~' all end with a chevron (>) and have 'yes' in the 'Via Link' column, whereas the ones that begin 'CUR_' do not end in a chevron and have 'no' in the 'Via Link' column.  The first kind don't just refer directly to a record or other data item.  They refer to it via a link from another  record.  This is the meaning of the 'Via Link' column.  The first five contextual data references operate via links, as does the last (%CUR~WITN>%).  The remainder - the second kind - simply reference a record directly. 

Why do some contextual data references operate via a link? They do so because the link may itself have useful information associated with it, that you may wish to reference. For example, if a person is adopted, the fact that they are adopted is stored in the Relationship sub-field which qualifies the link connecting the person to their family-as-child record. To access sub-fields that qualify a field (that is, 'child' fields) you use a dot (.) instead of a chevron (>). And that is true also of links and contextual data references that operate via links. So, to access the Relationship field (which has tag 'PEDI') for a person in the context of a diagram box, to show what their relationship to their parents was, you would use %CUR~FAMC.PEDI% - that is, with a dot (.) instead of a chevron (>). The table below gives some examples of the different ways some of these via-link contextual data references can be used.

%CUR~FAMC.PEDI% Link qualifier.  References person’s relationship to their parents.
%CUR~FAMC>HUSB>% Linked record.  References person’s father.
%CUR~FAMS.NOTE2>%
Link qualifier.  References qualifying note about person’s link to their spouse family.
%CUR~FAMS>CHIL[1]>%
Linked record.  References person’s first child in the person’s spouse family that is associated with the current context.
%CUR~SP_FAMC.PEDI% Link qualifier.  References person’s spouse’s relationship to their parents.
%CUR~SP_FAMC>WIFE>%
Linked record.  References person’s spouse’s mother.
%CUR~WITN.ROLE%
Link qualifier.  References to the role of the current witness (in the current event).
%CUR~WITN.SOUR[1]>% Link qualifier.  References a source citation for the current witness (i.e. a source for their participation in the current event).
%CUR~WITN>SEX%
Linked record.  References the sex of the witness.


Contextual data references are not all references to Individual records.  Some of them refer to Family records, or other record types.  The last (%CUR-WITN>%) is a reference (via a link) to a fact - that is, to a data item which is not a record of any kind.

Sometimes it may be necessary to refer to contextual information which is not actually stored in record data.  The function GetContextInfo is available in these cases.

Note: There is also a function GetContextItem which can be used as an alternative to some contextual data references.  At one point, it provided functionality which could not be achieved using contextual data references.  However, since version 6.0.5 that is no longer the case.  So although it has been retained to ensure backwards compatibility with expressions used with previous versions of Family Historian, it is recommended that you do not use it, but use an equivalent contextual data reference instead.

How to Use Contextual Data References

Contextual data references will be available, whenever you add a data reference to a given context.  For example, to modify a text scheme for a diagram (text schemes determine the contents of boxes in diagrams) you open a diagram and choose Options from the Diagram menu.  Then, on the 'Text' tab, select the text scheme you wish to modify and click Edit.  This will open the Edit Text Scheme dialog.  When you add or edit a Text Scheme Item, the Edit Text Scheme Item dialog is displayed.  The first field on this dialog is a template, which specifies what data you want to include.  To the right of the Template field is an << Insert button.  Clicking this button opens the Data Reference Assistant dialog which allows you to reference either an Individual record or (by expanding the row referring to it) specified fields from the Individual record.  It also allows you to reference a number of different contextual data references, and (if you expand them) fields relating to them.

Another example is narrative report sentence templates.  Narrative reports use sentence templates to determine what sentences will be generated for each fact (event or attribute) mentioned in the report.  To view an example of a sentence template, click on Fact Types on the Tools menu.  Select any listed fact type and click Edit.  The Fact Definition dialog includes a field labelled 'Sentence Template'.  If you wish to add a data reference to a sentence template, click on the << Insert Code button to the right of the Sentence Template field.  Choose Data Reference... in the dropdown menu that appears.  This time the Data Reference  Assistant dialog references a data item called 'Fact (event or attribute)' and allows you to select and insert sub-fields for it.  But it also allows you to insert contextual data references to the principal and second principal, and (if you expand them) sub-fields relating to them.  If you close the Data Reference Assistant dialog, and click on the Roles button, you will able to specify different roles that witnesses to this fact type can have.  You can also specify a Witness Sentence Template for the sentences that will be generated for these roles.  If you click on the << Insert Code button to the right of the Witness Sentence Template field and again choose Data Reference..., you will find that the listed contextual data references now additionally include the Witness contextual data reference.

Data references can be used in a great many more contexts than these.  But in each context of use, the contextual data references that are appropriate to that context will be listed.

DATA REFERENCES And Metafields

Source records linked to Source Template records can have fields which are defined within the Source Template - see Sources and Source Templates.  Fields of this kind are called metafields.  Citations to Source records that are linked to Source Template records can also have metafields.  All metafields have the same tag: '_FIELD'.  You can refer to the first metafield within a source record like this: %SOUR._FIELD%. Metafields can have an index like any other field, so you can refer to the second metafield like this: %SOUR._FIELD[2]%. Data references for metafields within citations, if used within a Footnote or Short Footnote format (Source Template format), require the contextual data reference 'CUR~CITN'.  So, for example, you can use %CUR~CITN._FIELD% to refer to the first metafield in a citation.

Instead of referencing metafields via their tag, it may be more helpful sometimes to reference them using a shortcut.  Data reference shortcuts have a tilde (~) in front of them.  Every metafield is associated with a field definition (stored in a Source Template record), which includes a field name and a field code.  So, for example, a field named "Record Title" would have a field code derived from the field name: {Record_Title} (field codes are usually written with curly brackets around them).  Every field code has an equivalent data reference shortcut, which consists of a tile character (~), followed by a 3-letter type prefix, followed by the field code name in uppercase.  So, for example, if a Source record has the "Record Title" metafield of our example, and if this is a text field, it can be referenced like this: %SOUR.~TX-RECORD_TITLE%.  If the Record Title field were a citation-specific field rather than a Source record field, it could be referenced from the citation with this data reference: %CUR~CITN.~TX-RECORD_TITLE%. 

The table below shows the 3-letter type prefix to use for each metafield type in data reference shortcuts.

Field Type 3-letter Type Prefix
Text TX-
Name NM-
Date DT-
Place PL-
Repository RP-
Enumeration EN-
URL UL-

If you try to use a tag that is not valid for the context of use, the data reference will fail (you will normally see an error message).  If you try to use a shortcut to a metafield, for a Source record or citation that does not have such a metafield (either because it is not associated with a Source Template record or because its associated Source Template record has no such metafield), the data reference will not fail and you won't see an error message.  Instead, the data reference will simply not return any value (exactly as if the field existed but was empty).

When inserting data references into expressions, the Data Reference Assistant dialog is commonly-used to make generating data references easier.  The Data Reference Assistant dialog can be used to generate ordinary data references to metafields using tags.  It does not generate data references to metafields using shortcuts.  You can generate these yourself.  To do that, replace _FIELD with the shortcut name, preceded by a tilde.

Using the Query Window to Browse Data References

Sometimes it is useful to be able to browse fields and see what data reference you could use to reference them from a given starting point.  You can use the Query Window for this.  Open the Query Window and select a query.  If you want to view data references from the point-of-view of an Individual record, choose an Individual query, such as 'All Individuals'.  If you want to see data references from the point-of-view of some other record type, choose a query of that type (for facts, choose a Fact query, such as 'All Facts').  Then click on the 'Columns' tab.  At the bottom of the Fields list on the left-hand side is a little black triangle.  Click on this to display a dropdown menu and choose Show Data Reference in Box from this menu.  Now when you click on any field in the Fields list, the appropriate data reference will be displayed in the box below the Fields list, and you can select it, and copy it by pressing Ctrl-C.