Understanding Text Templates

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

The most important thing to know about Text Templates is that you never have to construct them yourself! Family Historian will always do it for you, whenever you need them.

What Are Text Templates?

Text templates are used in text schemes to specify exactly what data is output for a given data item such a birth.

Text Schemes are listed in the Text tab of the Diagram Options Dialog. If you select a text scheme listed there and click Edit, the Edit Text Scheme dialog is displayed, showing all the items used in the text scheme (listed on the right), most of which will usually be data items - that is items which correspond to particular events or attributes, such as birth or occupation.

All data items have Text Templates. To view the text template select a data item in the Items Used list and click on Edit. The Edit Text Scheme Item dialog is displayed. If the item has a template, it will be displayed in the top-left hand corner. If there is no template field, the item is not a data item.

The text template determines what text will appear in boxes in diagrams, relating to that particular item of data, when this text scheme is used.

You Never Have To Write Your Own Text Template

This bears repeating. Even if you wish to create your own custom text schemes, there is no need for most users to ever write or edit text templates. You can create small or large, simple or complex text schemes, without ever needing to use templates or understand how they work (see Create a Simple Text Scheme for an example of how to create a text scheme - no editing of text templates is needed).

However, if you have very specific requirements which are not otherwise met, you may wish to ‘drop down’ to the level of editing text templates yourself. In which case, this section is for you.

You can, if you wish, edit the template for existing items. You can also add a new item with no pre-existing template, and write one from scratch if you wish. You do this by adding <Custom Item> from the list of Available Items in the Edit Text Scheme dialog. The Edit Text Scheme Item dialog will again be displayed, but with no details already provided.

The Basics

Every template consists of a mixture of constant text or expressions. ‘Constant text’ is any word that you wish to appear unchanged in the output. An expression is either a data reference or a function. To learn more about data references, see Understanding Data References. To learn more about functions, see Understanding Functions.

Data references appear within percentage marks and look like this:

%INDI.BIRT.DAT%

Functions are preceded by an ‘=‘sign and look something like this

=RecordId()

Any text which is not part of a data reference or a function is constant text.

Worked Example

1. Add Constant Text

Create a text scheme called demo and save it with no data items. Use the Apply button in the Text tab of the Diagram Options dialog to make it the current text scheme. Notice that all boxes in the Diagram Window are blank. Now edit the text scheme and add <Custom Item> as the first item. When the Edit Text Scheme Item appears, type “Died” (without the quotes) into the Template field and press the Test button. Notice that this is a valid template. Press OK to close the window that says that the template is valid. Press OK to close the Edit Text Scheme Item dialog. Press Apply to update your changes. If you can see boxes in the Diagram Window, behind the dialogs you have open, you should see that they all now contain the word ‘Died’.

2. Add Data References

Now double-click on the Died item in the Items Used list to re-open the Edit Text Scheme Item dialog. Position your cursor after the word ‘Died’ in the template and add a space. Then click on the Insert button to add a data reference. The Data Reference Assistant dialog appears. Expand Individual > Events > Death and select Date under Death. Click on the Insert button. Your template should now look like this:

Died %INDI.DEAT[1].DATE%

You could have just typed this in, but it’s usually easier to use the Data Reference Assistant dialog. Add “ in “ (one space before and one after ‘in’) and insert a data reference to the place of death in the same way as before, except that you select Place under Death instead of Date.

You should now have a template that looks like this:

Died %INDI.DEAT[1].DATE% in %INDI.DEAT[1].PLACE%

Conceptually, this template is made up of the following 4 components:

1.  “Died” Constant text
2.  %INDI.DEAT[1].DATE% Data Reference (to date of death)
3.  “in” Constant text
4.  %INDI.DEAT[1].PLAC% Data Reference (to place of death)

Press OK to close the Edit Template Line dialog and then Apply to apply the changes to the Text Scheme. Looking at the Diagram Window in the background, you should now see that it has changed as follows:

Where a person had no death event at all, their box will be blank. The word ‘Died’ will no longer appear.

Where a person has a death date but no place details you should see something like this:

Died 12 January 1943

Where a person has a death place but no death date you should see something like thisL

Died in Monte Camino, Italy

And where a person has both a death date and place, you should see something like this:

Died 12 January 1943 in Monte Camino, Italy

You may wonder: why does the word ‘Died’ not appear when there is no death date or place? Why does ‘ in ‘ not appear if there is no death place? See next.

3. The Constant Text Rules

There are 2 rules covering the display of constant text:

(a) Constant text is output if at least one expression after it in the template returns some text.

or

(b) Constant text in a template is output if there is no expression after it in the template, and either no expression before it, or the previous expression returned some text.

A data reference to a birth date, for example, will return no text for a given individual if there is no recorded birth date for that individual.

The reason ‘Died’ on its own is output is that it passes (b). If you have a death date but no place, rule (a) means that ‘Died’ will be output, but the ‘in’ part will not be output.

Suppose your template was this:

Died %INDI.DEAT[1].DATE% (in %INDI.DEAT[1].PLACE%)

i.e. we’re putting the death place in brackets to get a result like this:

Died 12 January 1943 (in Monte Camino, Italy)

This template has 5 components:

1.  “Died” Constant text
2.  %INDI.DEAT[1].DATE% Data Reference (to date of death)
3.  “in (” Constant text
4.  %INDI.DEAT[1].PLAC% Data Reference (to place of death)
5.  “)” Constant text

Rule (a) on its own would imply that you would not get final bracket in. It is rule (b) that ensures that you do. It also ensures that if there is no place of death, you just get

Died 12 January 1943

without either “in or “)”being output (i.e. components 3 and 5 both fail rules (a) and (b)).

4. Use of Functions in Text Templates

Functions are used in text templates in two ways: they may be used to provide data of some kind. For example, the =RecordId() function can be used to return a person’s record id. The =AhnentafelNumber() function can be used to display an ancestor’s ahnentafel number.

There are, however, some functions which are specifically designed not to provide data, as such, but to extend what you can do with text templates. These are the text template functions:

CombineText This function is typically used in diagram text schemes. It allows you to combine text by adding a prefix and/or suffix to the text returned by a given data reference; or to optionally supply alternative text to use if no text is returned.
ExistsText This function is typically used in diagram text schemes. It allows you to specify a data reference, and text to be output if, and only, if data is found for the specified data reference.
ForceText This function is typically used in diagram text schemes. It simply outputs the text specified. It is useful because an ordinary label is only output if the data reference following it matches some data. If you want the label to be output regardless, use ForceText.
NotExistsText This function is typically used in diagram text schemes. It allows you to specify a data reference, and text to be output if, and only, if data is not found for the specified data reference.

These functions greatly extend the flexibility of text templates. For example, in the standard text “Birth, Marriage, Death & Occupations (full)”, the following template is used for the Occupation item:

=ExistsText(%INDI.OCCU[1+]%,"Occ.") %INDI.OCCU[1+]% %INDI.OCCU[1+].DATE:COMPACT% in %INDI.OCCU[1+].PLAC:TIDY%

This template has 5 components:

1.  =ExistsText(%INDI.OCCU[1+]%,"Occ.") Function (containing a data reference as the first parameter, and constant text as the second)
2.  %INDI.OCCU[1+]% Data Reference (to occupation)
3. %INDI.OCCU[1+].DATE:COMPACT% Data Reference (to occupation date)
4. “in “ Constant text
5.  %INDI.OCCU[1+].PLAC:TIDY% Data Refence (to occupation place)

Why not just use “Occ.” (abbreviated label for ‘Occupation’) as constant text for the first component? Well you could. But this item is part of a group (see Item Groups). The second line of the group is a note about the occupation. Suppose you had no details about the occupation at all except a note? In that case, presumably you do want to see the note, and you want the ‘Occ.’ label to appear - as this is needed to make it clear what the Occupation Note is about. The =ExistsText function ensures that we put out the ‘Occ.’ label if we have any data at all about the person’s occupation.

If we had used the =ForceText function instead, it would have been simpler. But then the label would have been output even if we had no data at all about the occupation; which is not what we want.

See Understanding Functions for a complete list of functions.

5. Using Indices to Create Loops

Often when we add a data item to a text scheme, we want to show all instances of the item. We don’t want to see just the first occupation or the first residence, we want to see all occupations and all residences. To achieve this, we use a looping index within a data reference. An ordinary index looks like the ‘1’ in this:

INDI.OCCU[1]

This will return a person’s first occupation. To return a person’s 2nd occupation use this:

INDI.OCCU[2]

If we add a ‘+’ after the index it becomes a looping index, like this:

INDI.OCCU[1+]

This means: output one line for each occupation that this person has, starting with the first.

You can use looping indices within a single item, or within an item group. In either case, you must ensure that all indices used in all data references in the template or templates involved, use the same looping index.

An Item Group only repeats if the first group item contains a looping index. If it does, other group items should contain looping indices too to be consistent with it. See Item Groups for more on Item Groups.

See Understanding Data References for more information about the use of Indices in Data References.

Tip: Don’t confuse template codes in narrative sentences with data references. You can’t use template codes in text templates, and you can’t use data references in narrative sentence templates.

The CHM file was converted to HTML by chm2web software.