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.
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 , 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 list and click on . 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.
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 text 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 in the Edit Text Scheme dialog. The Edit Text Scheme Item dialog will again be displayed, but with no details already provided.
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.
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".
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:
Press to close the Edit Text Scheme Item dialog and then 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 this
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.
There are 2 rules covering the display of constant 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:
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)).
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, and 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:
| FactText | This function is typically used in diagram text schemes. It allows you to output fact information (that is, event or attribute information) and to control the way the information is presented and formatted. You specify whether to include date and place details, and if so, in what format. You can specify how to combine the two items of text (date and place) by adding an optional prefix and/or suffix. You can also optionally supply text to separate date and place details if both exist, and you can optionally supply alternative text to use if both place and date are empty. |
|---|---|
| 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. |
| CombineText_AB | This function is typically used in diagram text schemes. It can be used with in different ways, depending on the type of format string which is passed as the third parameter. The type 1 format string allows you to combine 2 items of text (A and B) by adding an optional prefix and/or suffix. You can also optionally supply text to separate A and B if not empty, and you can optionally supply alternative text to use if both A and B are empty. |
| 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. The most commonly-used function is the FactText function. It is recommended to look at the text templates used in standard text schemes for examples of usage of this function.
See Understanding Functions for a complete list of functions.
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.