Anyone who has written sentence templates (used in the generation of narrative reports) may be struck by the similarity between sentence templates and source template formats. Although there are many points of similarity, there are also important differences and you are advised to be careful not to confuse the two, and to treat them as separate and distinct. In general, as we shall see below, the expressions you can use to construct source template formats, described below, are more flexible and powerful than the expressions that can be used within sentence templates. For more on Sentence Templates, see Sentence Template Codes.
Source templates are used to define special additional fields that are required for sources of a given type. For example, if your source is a Cemetery, the source template definition might include Cemetery Name and Cemetery Address as fields to be used for sources of this type (see Sources and Source Templates). Source templates are defined using source template definitions. Every field defined as part of a source template definition, has a name and a code. The code name is automatically generated from the field name. Field codes can only be used within formats associated with their own source template definition. There are 4 kinds of formats associated with each source template definition. These are:
Source Template formats are defined in the Source Template Definition Dialog. They use field codes to reference the values of fields for a given Source record, or for a given citation to a Source record. For example, suppose Family Historian needs to generate a Bibliography entry for a given Source record, in a report. It will look for the Source Template record linked to the Source record, and it will use the Bibliography Format stored in that Source Template record as its plan for how to generate the entry. Field codes within the format will be replaced with the actual field values found in the specific Source record. But what if the Source record is not linked to a Source Template record? What, in other words, if it is a generic Source record? In that case, Family Historian will use the generic Bibliography Format instead. You can view and configure generic formats in the Generic Source Formats Dialog - there are 3 of them (there is no generic Record Title Format because auto-generation of record titles is not supported for generic Source records). Generic source formats are normally generated automatically by Family Historian, based on default settings or on field options you pick in the Generic Source Formats Dialog. However, you can if you wish customize these formats yourself. Generic source formats are a little more complex than source template formats because they do not use field codes, and instead use data references. Source template formats can use data references too, but usually don't. The use of data references within formats is described in the section How to Use Data References or Functions within Formats below. For more information, see Generic Source Formats.
A field defined within a source template definition becomes a field in a Source record, for Source records created from that source template, unless the Citation-specific box is ticked for that field. In that case, the field becomes a field in the link which links a particular item of data to the Source record (this is how Source citations are implemented: as links between ordinary items of data and Source records). A citation-specific field is called that because it is only relevant to the particular item of data that is linked to the Source record, and not to all items of data linked to that Source record.
You cannot use citation-specific fields with record title formats, or with bibliography formats, as these both relate to the Source record, independent of any citation. Footnote formats and short footnote formats, however, can contain any field code associated with the source template for the Source record in question - that is, both Source record fields and citation-specific fields.
Formats are made up of a combination of text and expressions. Text just means anything that isn't an expression. For example, the Record Title Format for the template "Manuscript Records: Document", in the Advanced collection, looks like this:
Manuscript Record Document: {Collection} - {Document_Title}
This format is made up of 4 parts:
There is no limit to the number of expressions that a format can contain, or the number of items of text.
You could type field codes into Format boxes, but there is an easier way. Every format box in the Source Template Definition Dialog has an button to the right of it. Click on this button to insert a field code. A dropdown menu will offer you a list of fields (and, in most cases, Styles - see next). Remember that citation-specific field codes are not valid in the context of Record Title Formats or Bibliography Formats, so these fields will be greyed in those contexts.
Styles - that is italics, bold, underline and 'caps' (that is, forced upper-case) - can be used in all formats except Record Title formats. Styles are specified using special style codes. The following table lists the available style codes:
| Style | Style code |
|---|---|
| Italics on | <i> |
| Italics off | </i> |
| Bold on | <b> |
| Bold off | </b> |
| Underline on |
<u> |
| Underline off |
</u> |
| Caps on |
<caps> |
| Caps off |
</caps> |
There is no need to remember these style codes, You can add any style using the the button to the right of each of the Format boxes (except the Record Title format box). Style codes can be used wherever ordinary text can be used. So, for example, suppose you wanted to copy the previous "Manuscript Record Document" example and use it as your Bibliography format, but you wanted the collection name to be output in capital letters, underlined. In that case you could use this:
Manuscript Record Document: <u><caps>{Collection}</caps></u> - {Document_Title}
If a given Source record had a collection called "Stan's Effects" and a document title of "Memories", the Bibliography entry for this Source record would look like this:
Manuscript Record Document: STAN'S EFFECTS - Memories
In some cases, field codes can have a qualifier. Qualifiers are written in upper case, as a suffix to the code name, separated by a colon (:). For example, a {film_repository} code, with the LOCATION qualifier - written as {film_repository:LOCATION} - would refer to the location of a particular repository, rather than the name of the repository.
The following table lists all field code qualifiers and the field types they can be used with (see Source Template Field Definition Dialog for more on field types):
| Qualifier | Field Type | Description |
|---|---|---|
| BOOK | Text | Style Qualifier - see Style Qualifiers below. |
| TITLE | Text | Style Qualifier - see Style Qualifiers below. |
| REVERSE | Name | The name "John Smith" will be displayed as "Smith, John". |
| SURNAME | Name | The name "John Smith" will be displayed as "Smith". |
| GIVEN | Name | The name "John Smith" will be displayed as "John". |
| YEAR |
Date |
The date "3rd June 1987" will be displayed as "1987". |
| LOCATION |
Repository |
The location of the Repository record will be displayed, instead
of the name of the Repository. |
Most qualifiers affect the content of the text that replaces the field code. These are content qualifiers. But two of them do not affect the content. Instead they affect the way the content is presented. These are style qualifiers. The two style qualifiers are BOOK and TITLE. They can be added to any Text type field - but only in Formats which support style qualifiers; which is all of them except Record Title Formats. 'BOOK' is intended to be used for book titles. 'TITLE' is intended to be used for all other kinds of titles (e.g. document, newspaper or magazine titles).
By default, any field code which has the BOOK or TITLE qualifier will be displayed in italics. However, this is configurable in the Sources tab of Preferences. This is why it is often preferable to use the BOOK or TITLE qualifiers rather than style codes. If you specify style details using style codes, you will always get those specific styles. But if you specify styles using the BOOK or TITLE qualifier, you can easily change the appearance of these items whenever you want to.
Style qualifiers can be applied to field codes (see Field Code Qualifiers above), and also to data references and functions (see Data References, Functions and Style Qualifiers below).
A field code, such as {collection} is an example of a simple expression, but you can create much more complex angle-bracket expressions if you wish to.
If a given field has no value, when an expression with that field's
code is resolved, the field code will be simply removed from the
sentence that is output, without being replaced by anything. If
you want to add a prefix and/or suffix to a field code, but only if the
value of the field code is not blank, put angle brackets <> around
the code, and add the prefix after the opening angle bracket, and add
the suffix before the closing angle bracket - like this: <prefix
{code} suffix>. Suppose, for example, you wanted the
Document Title to appear within double quotes, you could change the
Record Title format, in the example above, to look like this:
Manuscript Record Document: {Collection} - <"{Document_Title}">
Of course, you don't have to put angle brackets before and after the double quotes. The problem if you don't though, is that if there were no Document Title, you'd get two double quotes appearing at the end of the record title, with nothing between them. The angle brackets prevent that, and ensures that the double quotes are only output if the Document Title is not blank.
It might appear that the hyphen should also be placed within angle brackets, as you also won't want a trailing hyphen if the Document Title is blank. To learn about why it is not necessary to do that, see Special-handling for Top-level Text below.
You can use angle brackets around more than one field code - in fact around as many as you like. Suppose you have two or more fields that you want to appear within ordinary round brackets, but you don't want the round brackets to appear if the fields are all blank. In that case you can enclose all of the field codes within angle brackets, and add the round brackets as prefixes and suffixes, like this:
<({code1}, {code2} and {code3})>
Suppose the values for the three field codes were 'apple', 'pear' and 'banana', respectively, this would result in text that looks like this:
(apple, pear and banana)
If all 3 codes were blank, no text would be displayed for the expression.
What if code1 and code3 were blank, but code2 wasn't? It might seem that you would get something messy and undesirable like this:
(, pear and )
In fact you wouldn't get that. This is because within an angle-bracket expression, Family Historian will automatically detect the parts that are expressions (and remember that a field code is a simple expression) and has special rules for handling the remaining parts. It will treat anything that appears before the first expression as the prefix, anything that appears after the last expression as the suffix, and anything that appears between expressions as a separator. So, in our example, Family Historian will view the angle-bracket expression as containing these 7 parts:
In this case, the prefix is the first (opening) round bracket, the suffix is the last (closing) round bracket, and the comma, and the word 'and', are both separators. The rule for prefixes and suffixes is that they will appear (and will only appear) if any of the expressions between them are not blank. The rule for separators is that in each case, they will appear (and will only appear) if any of the expressions to the left of them are not blank, and if the expression immediately to the right of them is not blank.
So, to take our example, if {code1} is blank and {code3} is blank, but {code2} is 'pear', the angle-bracket expression <({code1}, {code2} and {code3})> would result in this:
(pear)
If {code3} is blank, {code1} is 'apple', and {code2} is 'pear', you'd get this:
(apple, pear)
If {code2} is blank, {code1} is 'apple', and {code3} is 'banana',you'd get this:(apple and banana)
As we've seen, an angle-bracket expression can consist of a prefix, a suffix, and one more field codes, and separators. Actually a more accurate statement is that an angle-bracket expression can consist of a prefix, a suffix, and one more expressions, and separators. Wherever you have a field code, you can instead, if you wish, have an angle-bracket expression - even if the field code is already occurring within an angle-bracket expression. In fact, you can have as many angle-bracket expressions within angle-bracket expressions within angle-bracket expressions ... as you want. This is called nesting and it is a very powerful and useful feature of angle-bracket expressions that they support nesting.
Another common scenario is that you might want alternative text to be output, if a particular field or expression is blank. Within an angle-bracket expression, a vertical bar after the main part, indicates alternative text, to be output if the main part is blank. For example, this expression
<{code1}|EMPTY!>
... would put out the value of {code1} if not blank, but would put out the text 'EMPTY!' if {code1} was blank. The value after the vertical bar does not have to be plain text. Like the main part, it can be any kind of mixture of text and expressions (field codes or angle-bracket expressions). So, for example, if you want the value of {code2} to be output if the value of {code1} is blank, you could use this:
<{code1}|{code2}>
Each angle bracket expression can have multiple vertical bars - as many as you like. The 2nd part - i.e. the part after the first vertical bar - is only output if the 1st part (the part before the first vertical bar) is blank. The 3rd part (the part after the 2nd vertical bar) is only output if the 2nd part is blank. And so on. So, for example, consider the following expression:
<{code1}|{code2}|{code3}>
In this case, {code2} is only output if {code1} is blank, and {code3} is only output if both {code1} and {code 2} are blank.Style codes are explained in the Style Codes section above. You can use style codes within angle-bracket expressions if you wish to; but style codes - even though they contain angle brackets - do not count as angle-bracket expressions, or indeed any kind of expression, for present purposes. For example, this is an example of a valid angle-bracket expression:
<<i>{Collection}</i>>
That whole expression is an angle-bracket expression, that consists of 3 parts:Suppose you had added more text to the prefix or suffix, as in this example which puts the whole thing within round brackets:
<(<i>{Collection}</i>)>
This expression as a whole still only has 3 parts. The prefix in this case is "(<i>". The suffix in this case is "</i>)";
An angle bracket expression which does not contain a field code or any other expression, resolves to nothing. So, for example "<one>" will always produce a blank result. However, if an angle bracket expression contains a vertical bar, the expression after the bar (or between the bar and the next bar, if there is another one) does not have to contain an expression of any kind. Any constant text following the bar (unless it is placed inside another angle bracket expression) will always be output regardless, if the first part resolves to nothing. So, for example, "<one|two>" resolves to "two". This is because the first part, before the bar, resolves to nothing (because it contains no expression); whereas the expression after the bar is output as it stands (even though it also contains no expression).
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 "{Document_Title}" to appear exactly like that and not be treated as a code, write it like this "\{Document_Title}". The word "{Document_Title}" (without the escape character) will be output. Even the escape character itself can be 'escaped' in this way.
Given the power of angle-bracket expressions, many formats could be written as one big angle-bracket expression, containing nested angle-bracket expressions where necessary. However they might not be very readable. To keep formats as simple as possible, a few special rules have been introduced to minimize the need for expressions. Family Historian attaches special significance (at the top-level only - this does not apply within an angle-bracket expression) to commas, dashes, colons, semi-colons, and full-stops. Call these special characters. The follow special rules apply:
| Characters | Rule |
|---|---|
| Full-stops and semi-colons | Only output if some text has been output since the last full-stop or semi-colon was encountered, or since the start of the Format text if there haven't been any prior full-stops or semi-colons. |
| Commas, colons and dashes | Same requirement, but have the additional requirement that they
are only output if some text (other than more commas, colons and
dashes) will follow them, before the next semi-colon or
full-stop. For these purposes, later commas, colons and dashes that are encountered before any text is found, and before a semi-colon or full-stop is encountered, are deemed to have been displaced by the earlier comma, colon or dash (even if the earlier comma, colon or dash is not output). |
Take the following example:
Manuscript Record Document: {Collection} - {Document_Title}.
Let us suppose that the field codes {Collection} and {Document_Title} resolve to nothing (i.e. the Collection field and Document Title field are both blank). The text "Manuscript Record Document" is not an expression, and it does not contain any special characters; so it will always be output exactly like that. The colon however will not be output because, although some text does precede it, no text will follow it until the the full-stop is reached (the dash doesn't count). The dash is also not output. It was displaced by the colon - even though the colon wasn't output. The full-stop, however, will be output (there hasn't been any prior full-stop or semi-colon, but there has been text since the start of the format - namely "Manuscript Record Document"). So you would get this:
Manuscript Record Document.
Now suppose that the document title is "Memories" and the Collection is blank. The text "Manuscript Record Document" is output as before. The colon is also output because the text 'Memories' will follow it (not immediately but before the full-stop, after skipping over the dash). The dash is not output. It has been displaced by the colon. And the full-stop is also output . So you get this:
Manuscript Record Document: Memories.
Finally suppose that the document title is "Memories" and the Collection is "Stan's Effects". In that case the colon is output because text precedes and follows it. The dash is also output for the same reason (it has not been displaced by the colon in this case). And the full-stop is also output. So you get this
Manuscript Record Document: Stan's Effects - Memories.
These rules may not be what you want for all purposes. If so, you should be able to achieve what you want by using angle-bracket expressions.
There is also special-handling of spaces in top-level text (text that is is not within any angle-bracket expression). Take this example:
{Collection} {Document_Title} {Page_Number} {Repository}
In total, there are 3 spaces, separating the 4 expressions. Without special-handling, if {Document_Title} and {Page_Number} were both blank, you would get 3 spaces between the values for {Collection} and {Repository}. Family Historian will ensure that each item is automatically separated by one space, and never less or more than one space. It will also ensure that there is no space before the special-characters comma, full-stop, colon or semi-colon, but that there is one space immediately after them, if they are followed by more text. If the dash character separates two items, a space will be added both before and after the dash.
If these rules are not what you want, you can override them by putting the relevant expression inside angle brackets, in which case the usual angle bracket expression rules will apply instead. So, for example, if you wanted no spaces between any of the expressions in the previous example, you could achieve this by writing it like this:
<{Collection}{Document_Title}{Page_Number}{Repository}>
If you wanted the usual spacing between all the items except that you wanted {Document_Title} and {Page_Number} to be separated by a dash, with no space before or after the dash, you could write it like this:
{Collection} <{Document_Title}-{Page_Number}> {Repository}
This section 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 of interest if you have complex and advanced requirements that cannot be met in other simpler ways.
In the instructions above, only two kinds of expression were mentioned: field codes and angle bracket expressions. In fact, there are two other kinds of expression that you can use, and the above instructions apply to these also. They are data references and functions. 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 source template formats. Doing so allows you to reference any field associated directly or indirectly with the current context. When inserted into source template formats, data references must be wrapped within curly brackets {}. This is in addition to the percentage signs that ordinarily wrap data references.
Data references to fields within a Source record begin with the SOUR tag. You can use these kinds of data references in all 4 source template formats. Within Footnote and Short Footnote formats you may also wish to refer to the citation (the link), and fields attached to the citation. References to citations, in the Footnote and Short Footnote format context, must use a contextual data reference, beginning 'CUR~CITN'. For example, to refer to the assessment field (which is a field within the citation and not a field on the Source record) you could use: %CUR~CITN.QUAY%. This data reference will not work in the context of a Record Title format or a Bibliography Format because those formats are not associated with any particular citation. In the context of a Footnote and Short Footnote format, you can reference the Source record like this: %CUR~CITN>%. So, for example, an alternative to %SOUR.AUTH% in the context of a Footnote or Short Footnote Format, is %CUR~CITN>AUTH%. %SOUR.AUTH% will also work in Bibliography and Record Title formats though, whereas %CUR~CITN>AUTH% will not work in those contexts.
The table below shows examples of data references that could be used in formats, and the contexts in which they would be valid. Notice that two examples (the second and fourth) use shortcuts to metafields. To learn more about metafields, and how you can reference them using data reference shortcuts, see the section Data References and Metafields in Understanding Data References.
| {%SOUR.AUTH%} | Valid in Footnote, Short Footnote, Bibliography and Record Title Formats. References the Author field of a Source record. |
| {%SOUR.~TX-COLLECTION%} | Uses a shortcut to reference a Source record metafield. This is valid in all 4 Formats, but will only actually return anything if used in relation to a Source record, or a citation to a Source record, which has a text metafield called 'Collection'. |
| {%CUR~CITN.QUAY%} | Valid in Footnote and Short Footnote Formats only. References the Assessment field attached to the source citation (the link to a Source record). |
| {%CUR~CITN.~TX-EVALUATION%} | Valid in Footnote and Short Footnote Formats only. Uses a shortcut to reference a citation metafield. Will only actually return anything if used in relation to a citation which has a text metafield called 'Evaluation' |
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 source template format, 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 can be data references, or other function calls, as well as quoted text (e.g. "Title:" in the 4th example below). If you want the quoted text to be treated as Source template format text and parsed accordingly (so that field codes are resolved, as well as angle bracket expressions), you must put the text itself in square brackets. There is an example of this in the table below (the 5th). As always, when passing a text parameter as argument to a function, any double quote characters within the text itself must be doubled.
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 few examples of what you can do. To learn more, see Understanding Functions.
| Function call | Meaning |
|---|---|
| {=GetRecord()} |
In all 4 Formats, this call will return the name of the Source
record. Is equivalent to {=GetRecord(%SOUR%)}. |
| {=GetRecord(%CUR~CITN%)} |
If used in the context of a Footnote or Short Footnote format,
this call will return the name of the record containing the
citation. |
| {=GetLabelledText(%SOUR.TEXT%,"Title:")} | In all 4 Formats, this function will return the title (text labelled 'Title:') within the 'Text from Source' field in the Source record - if there is any such text. |
| {=GetLabelledText(%CUR~CITN.DATA.TEXT%,"Title:")} | If used in the context of a Footnote or Short Footnote format,
this function will return the title (text labelled 'Title:')
within the 'Text from Source' field attached to the citation - if
there is any such text. |
| {=LeftText(["{author}"],3)} | If used in a context in which {author} is a valid field code, this function will return the leftmost 3 letters of the author's name. |
Style qualifiers, BOOK and TITLE, can be used with both data references and functions. For data references, the style qualifiers appears between the closing percentage sign, and the closing curly bracket. So, for example, {%SOUR.AUTH%:TITLE} is valid and will apply the TITLE style (as configured in Preferences) to the Source record's Author field.
Do not confuse style qualifiers with data reference qualifiers.
Both kinds of qualifiers are written in upper case, preceded by a
colon. But data reference qualifiers appear before the closing
percent sign. Style qualifiers appear after it. See Understanding
Data References for more information about data reference
qualifiers.
For functions the style qualifiers appears between the closing round bracket for the function, and the closing curly bracket. So, for example, {=GetRecord():TITLE} will return the name of the Source record and will also apply the style associated with TITLE.