Fact Types Dialog

Template Codes

Template Codes are mainly used to define sentences for narrative reports. There are two kinds of sentences: Principal sentences and Witness sentences. Principal sentences define a fact from the point-of-view of the principal (or from the point of view of one of them if there are two).  Witness sentences describe a fact from the point-of-view of a witness.  A Witness can be defined more than once, with more than one role, for any given fact - in which case they will get a Witness sentence for each role, in any narrative report about the Witness.  A Principal isn't usually defined as a Witness in their own fact, but they can be if required.  Even if they are, however, they will nevertheless only get one sentence for the fact, in any narrative report about the Principal - and this will be a Principal sentence.

Most template codes can be used in either Principal sentences or Witness sentences - but not all. Where a code can only be used in one context, this will be mentioned in the code description.

To learn more about sentences (and witnesses, principals and roles), see the help for the Witnesses Dialog, which also explains how to override sentences.  This  can be a good way of testing your sentence templates to make sure that they deliver the results you were expecting.  To clear an overridden sentence, simply delete all contents of the sentence field and click elsewhere or tab away.

Simple sentences can be defined using standard codes.  However, if you have more complex requirements, you can also use data references or even functions in sentence templates (see How to Add Data References or Functions to Sentence Templates below).

Standard Data Codes

Code: {individual}

Will be replaced by the name of the individual or 'he' or 'she', depending on the context.

Name of Individual (or Him/Her)

Code: {individual/him/her}

Will be replaced by the name of the individual or 'him' or 'her', depending on the context.

Name of Individual (or His/Her)

Code: {individual's}

Will be replaced by the name of the individual or 'his' or 'her', depending on the context.

Him/Her

Code: {him/her}

Will be replaced by 'him' or 'her', depending on the sex of the individual.

His/Her

Code: {his/her}

Will be replaced by 'his' or 'her', depending on the sex of the individual.

Principal

Code: {principal}

Witness sentences only.  Used with individual facts. Will be replaced by the name of the fact-owner.  For example, if the fact is baptism, it will be replaced by the name of the person being baptised.

Principal(s)

Code: {principals}

Witness sentences only.  Used with family facts. Will be replaced by the name of the fact-owners.  For example, if the fact is marriage, it will be replaced by the name of the two people being married.

Name of Spouse (or Her/Him)

Code: {spouse/her/him}

Principal sentences only.  Used with family facts. Will be replaced by the name of the individual's spouse or 'her' or 'him', depending on the context.

Names of Couple (or They)

Code: {couple}

Principal sentences only.  Used with family facts. Will be replaced by the names of the two participants in a family fact (e.g. marriage), or by 'they', depending on the context.

Date

Code: {date}

Will insert the date in a text format, with an appropriate prefix. For example, if the date is an exact day, the prefix will be 'on' (e.g. on "30th January, 2001"). If the date is a month or year, the prefix will be 'in' (e.g. in 1998). If the date is a range or a period, again appropriate prefixes will be used.

Unlike other template codes, the date code can be qualified to specify a particular date format. See Advanced Features of Template Codes below.

Age

Code: {age}

Used with Individual facts only. Inserts details of the person's age at the time of the event, if recorded.

Age Range

Code: {age range}

Used with Individual facts only. Inserts details of the person's age at the time of the event, if recorded. If no age information has been recorded, the person's possible age range will be calculated from their date of birth, and the fact date, if these have been supplied.

Their Ages

Code: {their ages}

Principal sentences only.  Used with Family facts only. Inserts details of the ages of the parents in a family record at the time of the event, if recorded.

Their Age Ranges

Code: {their age ranges}

Principal sentences only.  Used with Family facts only. Inserts details of the ages of the parents in a family record, at the time of the event, if recorded. If no age has been recorded for either parent, that person's possible age range will be calculated from their date of birth, and the fact date, if these have been supplied.

Place (with prefix 'in')

Code: {place}

Inserts the place name (usually in the 'Tidy' format where repeated commas are reduced to a single comma), with the prefix 'in'.

Tip: In narrative reports you can opt to only use the first part of a place name when replacing template codes for places, if that particular place has already been mentioned in full earlier in the same section. This avoids unnecessary repetition of information and is enabled by default. See the Use Short Form for Repeated Place Names option in the Main tab of the Options dialog for the narrative report in question.

Place (with no prefix)

Code: {_place}

Inserts the place name (usually in the 'Tidy' format where repeated commas are reduced to a single comma), with no prefix. If you want a prefix, but just don't want 'in', see How to Add a Prefix or Suffix to Any Template Code below.

Secondary Place

Code: {_place2}

Used with immigration and emigration events only as each of these, unlike all other fact types, are associated with 2 places: the place the person immigrated to and the place they emigrated from. This code causes the secondary place to be inserted.

Cause

Code: {cause}

Inserts the cause, if any, associated with the relevant fact.

Address

Code: {address}

Inserts the address, if any, associated with the relevant fact.

Tip: see How to Add a Prefix or Suffix to Any Template Code below, for suggestions about how to add a prefix to an address.

Note

Code: {note}

Inserts the note, if any, associated with the relevant fact.

Fact Label (e.g. 'Occupation')

Code: {label}

Inserts the fact label (e.g. 'Occupation').

Fact Value (e.g. 'Accountant')

Code: {value}

Only used with attributes. Inserts the fact value.

Fact Value (with a/an prefix)

Code: {a/an value}

Only used with attributes. Inserts the fact value prefixed by 'a' if the value begins with a consonant (e.g. 'a sailor') or by 'an' if the value begins with a vowel (e.g. 'an airman').

Abbreviation

Code: {abbr}

Will be replaced by the fact abbreviation if there is one, or the fact label if there isn't.

'Child' or 'Children'

Code: {'children'}

Used with the Child Count field only. Is replaced by the word 'child' if the person had 1 child only. Otherwise it is replaced by the word 'children'.

'Spouse' or 'Spouses'

Code: {'spouses'}

Used with the Marriage Count field only. Is replaced by the word 'spouse' if the person had 1 spouse only. Otherwise it is replaced by the word 'spouses'.

Blank

Code: {blank}

Uses this code on its own if you don't want a sentence to appear.

ROLE Codes

Role codes are a special kind of data code, used with witness information.

Role Name

Code: {role name}

Witness sentences only.  Will be replaced by the current witness's role in the current fact (e.g. the word 'bridesmaid' if that was their role).

Role Holders

Code: {role=____}

The blank must be filled by one or more role names or the words 'principal' or 'principals'.  Multiple values are allowed and must be separated by a comma.  For example, {role=bridesmaid} will be replaced by a comma-separated list of all witnesses that have the role 'bridesmaid'.  The expression {role=bridesmaid,best man,principal} will return a list of everyone who is either a witness with the role 'bridesmaid', a witness with the role 'best man', or a principal, for the fact in question.  If a person qualifies to be in the list more than once, they will only be listed once.  This code may be used in both principal and witness sentences.  In practice, it will almost always be 'wrapped' within angle brackets like this: "<The bridesmaids were {role=bridesmaid}.>" (see How to Add a Prefix or Suffix to any Template Code below).

Role Holder (if singular)

Code: {role(single)=____}

This code behaves exactly like the code {role=____} above, except that if more than one person qualifies to be in the list, it will return nothing.  This means that an expression such as "<the bridesmaid was {role(single)=bridesmaid}>" will be blank in its entirety, if there is more than one bridesmaid.

Role Holders (if plural)

Code: {role(plural)=____}

Again, this code behaves exactly like the code {role=____} above, except that it will return nothing unless more than one person qualifies to be in the list.  This means that an expression such as "<the bridesmaids were {role(plural)=bridesmaid}>" will be blank in its entirety, if there were no bridesmaids, or just one.

Other Role Holders

Code: {other=____}

Witness sentences only.  This code behaves exactly like the code {role=____} above, except that the current witness is excluded from the list of people. This makes it possible to construct witness sentences like this "{individual} was a bridesmaid.<  The other bridesmaids were {other=bridesmaid}.>."

Other Role Holder (if singular)

Code: {other(single)=____}

Witness sentences only.  This code behaves exactly like the code {role(single)=____} above,  except that the current witness is excluded from the list of people.

Other Role Holders (if plural)

Code: {other(plural)=____}

Witness sentences only.  This code behaves exactly like the code {role(plural)=____} above,  except that the current witness is excluded from the list of people.

Formatting Codes

Formatting codes are used to control the presentation of information.

New Line

Code: <br>

Forces a new line to be started.

New Paragraph

Code: <para>

Forces a new paragraph to be started.

Advanced Features of Template Codes

How to Use a Specific Date Format

The {date} template code is unique amongst all other template codes, in that it alone can be qualified to specify a particular required format. To qualify the date code, add a colon followed by the qualifier. For example, the code {date:YEAR} will return the year part (only) of the date. The code {date:ABBREV3} will return the date in ABBREV3 format. The code {date:DAY_OF_WEEK} will return the day of the week of the date. See Date Formats for a complete list of qualifiers and the date formats they produce.

Please note that the simple {date} code automatically adds various prefixes (different ones depending on the date type) and other language elements, to make the date information fit correctly into a narrative sentence. When you qualify a date, no such additional language elements are added. If you want prefixes, you will have to add them yourself (see next).

How to Add a Prefix or Suffix to Any Template Code

If a given field has no value the template code will be simply removed from the sentence that is output, without being replaced by anything.

For example, if you had a template:

{individual} was born at {address} {date}

and you had no address information for John Smith, the sentence generated for his birth event might be, say,

John Smith was born at on 19th January, 1903.

Notice the unwanted occurrence of the word 'at'. To avoid this happening you need to attach the 'at' to the address as a prefix, so that it only appears when there is an address. You do this by putting angle brackets <> around the template code. Any text within the angle brackets will only be output if the template code is not empty. So for example, if you changed the template code to

{individual} was born <at {address}> {date}

the sentence generated would be

John Smith was born on 19th January, 1903.

and the unwanted 'at' would no longer appear.

You can use this technique to add a prefix and/or suffix to any data code.  Formatting codes may be included within the angle brackets if required.  So, for example,

<<para>{note}<para>>

is valid and ensures that if a note is added, a new paragraph will be inserted before and after it.

How to Add Data References or Functions to Sentence Templates

This section describes advanced features.  It is primarily intended for advanced and technically-minded users (especially the part about functions). In other words - please do not be discouraged if it makes no sense to you.  These features are only needed if you have  complex and advanced requirements that cannot be met using standard template codes.

Data references and functions are both advanced features.  The former are described in Understanding Data References and the latter are described in Understanding Functions.  You can add data references or functions to sentence templates.  Doing so allows you to reference any field associated directly or indirectly with the current context.  When inserted into narrative sentences, data references must be wrapped within curly brackets {}.   This is in addition to the percentage signs that ordinarily wrap data references.  Although data references can be typed 'by hand', you are strongly recommended to use the Data Reference Assistant dialog to insert them wherever possible, as it will make it much easier to get the results you want.  For example, to open the Data Reference Assistant dialog when editing a sentence template in the Fact Definition dialog, click on the << Insert Code button to the right of the Sentence Template field and then choose Data Reference from the dropdown menu that appears.   To open the Fact Definition dialog, incidentally, click on Fact Types on the Tools menu, select the fact type you wish to edit and press the Edit button.  The Data Reference Assistant dialog is not available if you choose to edit the Sentence field by hand (that is, override the template) in the Fact tab of the Property Box.  In that case, you would have to type data references by hand if you wish to use them.  Functions must always be typed by hand.

Data references that reference the current event or attribute itself, or a sub-field of it, begin with the 'FACT' tag.  Some examples are shown in the table below.  Please note that in the first two examples, there is a standard template code which is the equivalent to the data reference.  Where you can use a standard template code instead of a data reference, you are recommended to do so as the former are simpler and therefore easier to understand.

Data Reference*	Meaning
{%FACT.DATE%}	Date of the current fact (i.e. equivalent to {date}).   Example: "{individual} was born {%FACT.DATE%}"
{%FACT.NOTE2%}	Note about the current fact (i.e. equivalent to {note}).   Example: "{individual} was born {date} {%FACT.NOTE2%}"
{%FACT.NOTE2.SOUR>%}	First source for the note about the current  fact.  Example: "{individual} was born {date} {note} <(source: {%FACT.NOTE2.SOUR>%})>".  Note: as this example iillustrates, you can use angle brackets with data references and functions, to add prefixes or suffixes.  See How to Add a Prefix or Suffix to Any Template Code above.  In the example, the prefix is "(source:" and the suffix is the closing bracket, ")".
{%FACT.PHON%}	A phone number associated with the current fact.  Example: "{individual} was resident {date} {place} <(tel: {%FACT.PHON%})>"
{%FACT.PLAC>LATLONG%}	{%FACT.PLAC>LATLONG%}    Latitude and longitude of the place at which the fact occurred.  Example: "{individual} was born {date} {place} <(lat/long: {%FACT.PLAC>LATLONG%} )>"

^{* As always if you try these out, please remember that data references only return data if the data has been recorded.  If there is no telephone number recorded for a given fact, for example, any data reference for it will return nothing.}

What if you want to reference more detailed information about the principal in an event (or attribute) than you get using a standard template code?  In that case, you must use a contextual data reference – specifically one  that begins CUR_PRIN - as in {%CUR_PRIN%}.  That expression is similar to the standard template code {individual} but there are some important differences.  First, {individual} will often in practice be replaced by 'he' or 'she' when a sentence is generated .  That will not happen with {%CUR_PRIN%}.  Second, in a witness sentence, {individual} refers to the current witness, whereas {%CUR_PRIN%} still refers to the principal (or the first principal, if there are two) in the current fact.

Some facts (such as a marriage or divorce event) have more than one principal.  To refer to the second principal, there is another contextual data reference: CUR_PRIN2.  The expression {%CUR_PRIN2%}  is similar to the standard template code {spouse/her/him} but the latter will often be replaced by 'her' or 'him' when a sentence is generated  and that will not happen with {%CUR_PRIN2%}.  Also, {spouse/her/him} cannot be used in a witness sentence, whereas {%CUR_PRIN2%} can - it refers to the second principal (or nothing, if there isn't one).

As we have seen, both CUR_PRIN and  CUR_PRIN2 can be used in both principal and witness sentences.  There is also a third type of contextual data reference, beginning CUR~WITN, which can only be used in the context of a witness sentence – to refer to the witness.  The table below gives some examples of all three:

Data Reference*	Meaning
{%CUR_PRIN%}	Current or first principal.   Example: "{%CUR_PRIN%} was born {date}".
{%CUR_PRIN2%}	Other  or second principal (i.e. equivalent to {spouse}.   Example: "{%CUR_PRIN%} married {%CUR_PRIN2%} {date}".
{%CUR_PRIN.FAMC>HUSB>%}	Current or first principal's father
{%CUR_PRIN.FAMC>WIFE>%}	Current or first principal's mother
{%CUR_PRIN.FAMC>HUSB>FAMC>HUSB>%}	Current or first principal's paternal grandfather
{%CUR_PRIN.FAMC>HUSB>FAMC>HUSB>NAME:SURNAME%}	Current or first principal's paternal grandfather's surname
{%CUR_PRIN2.BIRT.DATE:YEAR%}	Other or second principal's year of birth
{%CUR~WITN>%}	Current witness (witness sentences only)
{%CUR~WITN.ROLE%}	Current witness's role in the current current event (witness sentences only)
{%CUR~WITN.NOTE2%}	Note about current witnesses role in the current event  (witness sentences only)
{%CUR~WITN>NAME:SURNAME%}	Current witnesses' surname (witness sentences only)
{%CUR~WITN>FAMC>HUSB>NAME:SURNAME%}	Current witnesses' father's surname (witness sentences only)

The concept of a function will be familiar to everyone who has ever done any programming or written scripts using scripting tools.  When you use a function in the context of a sentence template, the function call must be wrapped within curly brackets, just as data references are.  The start of a function call is always marked by an equals sign; so this must come immediately after the opening curly bracket.  A typical function call will take a number of parameters.  The arguments to these parameters will often be data references, or other function calls.  You can't use a standard template code as an argument to a function.

Family Historian has over 100 functions (sometimes called 'built-in' functions to distinguish them from the Family Historian API functions), providing a wide variety of services.  The table below gives just a handful of examples of what you can do.  To learn more, see Understanding Functions. 

Function call	Meaning
{=TextPart(%FACT.PLAC%, 2)}	The 2nd comma-separated part (if there is one) of the place where the current event or attribute occurred.  For example, if the relevant place was "Glen Park, San Francisco, California, United States", this call would return 'San Francisco' and would work in any narrative sentence template.  See the TextPart help for more details on using this function.
{=TextPart(%CUR~WITN>BIRT.PLAC%, -2)}	The second-last comma-separated part of the birth place of the current witness.  For example, if the witness was born in "Glen Park, San Francisco, California, United States", this call would return 'California'.  This example uses a contextual data reference that will only work in the context of a witness sentence.  See the TextPart help for more details on using this function.
{=GetLabelledText(%CUR~WITN.NOTE2%, "Occupation:")}	The 'GetLabelledText' function returns the section of a note (up to the end of the paragraph) that follows the specified label – in this case 'Occupation:'.  So, for example, if you used the Census event to record each person mentioned in the census as a witness, you could add a note for each witness and record their occupation in the note on a line beginning 'Occupation:'.  Then you could use the expression on the left to insert the recorded occupation for each witness into the relevant witness sentence. You could record other details such as age in the same note, and reference them using the same technique, but with a different label (e.g. 'Age:'). The example also  uses a contextual data reference that will only work in the context of a witness sentence.  See the GetLabelledText help for more details on using this function.
{=TextIf(%CUR~WITN>SEX% = "Male", "his", "her")}	The 'TextIf' function returns a different result depending on a condition.  In this example, the function will return the word 'his' if the current witness is male, and 'her' if the current witness is female. This example also uses a contextual data reference that will only work in the context of a witness sentence.  See the TextIf help for more details on using this function.
{=RecordId(%CUR_PRIN%)}	Inserts the record id of the current or first principal for the current event or attribute. Will work in any narrative sentence template.  See the RecordId help for more details on using this function.
{=RecordId(%CUR~WITN>%)}	Inserts the record id of the current witness. Uses a contextual data reference that will only work in the context of a witness sentence.  See the RecordId help for more details on using this function.

The Escape Character

Occasionally you may wish to prevent a character from having a special meaning.  To do this, place '\' in front of the character.  For example, if you want the word "{date}" to appear exactly like that and not be treated as a code, write it like this "\{date}".  The word "{date}" (without the escape character) will be output.  Even the escape character itself can be 'escaped' in this way.