Text Templates may be used to create citation text or some other combination of field values that you want to paste into your genealogy application. Text Templates are processed when ORA is creating the Control Panel.
You may add one or more Text Templates for a collection. The output of each Text Template for the current collection is added to the bottom of the Control Panel.
For information about adding and editing Text Templates, see the Editing Templates section of the OraSettings help page.
Field values are inserted into the output using variable references.
[Name] is an example of a variable reference. When processing that variable reference, ORA will insert the Name field value into the output.
A variable reference starts with "
[" and ends with "
]". The text inside must match the label of one of the fields in the Control Panel with exceptions as described below in the Special Variables section.
When processing a variable reference, ORA substitutes the value of the field into the output in place of the variable reference.
In its simplest form, a conditional expression is used to insert a prefix and or suffix with a variable.
<; Date:[Date]> is an example of a conditional expression. If the Date field value is not empty, ORA will insert "; Date: " and the Date field value into the output. If the Date field is empty, the "; Date: " prefix will not be inserted into the output.
A conditional expression starts with "
<" and ends with "
If a conditional expression includes more than one variable reference, all the variable references must be "true" or the conditional expression will be considered "false". For most variable references, a non-empty field value is considered "true" and an empty field value is "false".
You may nest conditional expressions.
If an outer conditional expression includes only literal text, at least one of its nested conditional expressions must be true or the outer expression's literal text will be suppressed.
Spaces are significant in ORA templates, and that includes spaces in conditional expressions.
- Include the Date field value in the output with a prefix of "; Date: ":
<; Date: [Date]>
- Include "Place: City", "Place: State", or "Place: City State" depending on which values are present:
<Place:< [City]>< [State]>>
Alternatives are conditional expressions where the conditional text includes multiple expressions separated by
|. The expressions are evaluated left-to-right and the first expression that produces text is included in the output. Any remaining expressions are ignored.
The general form is:
< expression1 | expression2 | ... >
Alternatives include special handling for literal text:
- If an outer conditional expression has text only, such as the comma in
<, <[A]><[B]>>, the outer text will be suppressed unless at least one of the inner conditions is true.
- If an outer conditional expression has a variable reference, with or without text, such as the
<, [A]<, [B]><, [C]>>, the outer variable and text will appear even if all the nested conditions are false.
Include "Place: City, State" if either or both of City and State are present. This is an improvement on a prior example because this example includes the comma usually inserted between place components:
<Place:< [City], [State]| [City]| [State]>>
In the inner conditional expression, the first alternative is chosen if both City and State have non-empty values. The second alternative is chosen only if the first alternative was not chosen, and the City field is not empty. The third and final alernative will be chosen only if the first two were not chosen and if the State field is not empty.
If none of the inner expressions produce any output, i.e., if both City and State are empty, the literal text "Place:" will not appear in the output. If an outer expression has literal text only because all of its inner expressions were empty, the outer expression is considered "false" and the literal text is ignored. This allows you to design templates that include or omit labels based on the presence or absense of multiple fields.
ORA supports several transform functions where you can change a value before inserting it in the output. See the Transforms page for a description of the available transforms.
The general form is:
Some transforms have parameters:
You may specify several transforms in succession. This is called "chaining".
If you are chaining transforms, and using a transform that includes optional parameters, you must specify all parameters, optional or not, before you add any subsequent transform(s).
If a variable reference begins with "
?:", ORA treats it as a value test. Value tests are used in conditional expressions to vary the output of a template based on the value of a field.
The value test variable relies on the method ORA uses to process conditional expressions. Each conditional expression is evaluated based on the true or false result of each variable reference or nested conditional expression. In the simple case of
[Name], the result is true if the field is not empty and false otherwise. However, ORA doesn't actually depend on the variable inserting text into the output. It evaluates whether the function that processed the variable returned true or false. This means it is possible for a variable reference to return true even though it did not append any text to the output.
There are several forms of the value test. In the following list, assume that "Name" is a field in the current record.
- Not Empty:
[?:Name]— This variable will have a true value if the Name field is not empty.
[?:Name=Maureen]— This variable will have a true value if the Name field is equal to "Maureen".
- Not Equal:
[?:Name!=Maureen]— This variable will have a true value if the Name field is not equal to "Maureen".
- Greater Than:
[?:Age>5]— This variable will have a true value if the Age field is greater than 5. The comparison is numeric if both the field value and the comparand are numeric.
- Greater Than or Equal To:
[?:Age>=5]— This variable will have a true value if the Age field is greater than or equal to 5. The comparison is numeric if both the field value and the comparand are numeric.
- Less Than:
[?:Age<5]— This variable will have a true value if the Age field is less than 5. The comparison is numeric if both the field value and the comparand are numeric.
- Less Than or Equal To:
[?:Age<=5]— This variable will have a true value if the Age field is less than or equal to 5. The comparison is numeric if both the field value and the comparand are numeric.
- Regular Expression:
[?:Name/ee/]— This variable will have a true value if the Name field contains "ee" or "EE", etc.
The default Regular Expression flags value is "i". You may disable that flag by passing a space character after the trailing
/, for example:
When comparing to another value (Equal, Not Equal) or evaluating a Regular Expression, all comparisons are done case-insensitive meaning that a lowercase character and an uppercase character are considered the same character.
- Include "Place: City, State" if either or both of City and State are present. This is a variation of a prior example that demonstrates how to use a value test for a non-empty field:
<Place:< [City]><<[?:City],> [State]>>
The comma between City and State is inserted only if City is not empty; that's what
- Include "Owned" if the "Own or Rent" field is equal to "
o" or "
<[?:Own or Rent=o]Owned>
The value test
<[?:Own or Rent=o]is true if the Own or Rent field is equal to uppercase or lowercase "
O" (Oh). If it is true, then the literal text "Owned" that follows it in the expression will be inserted in the output.
- Include "Owned" if the "Own or Rent" field starts with "
o" (lowercase oh), "
O" (uppercase oh) or "
<[?:Own or Rent/^[o0]/]Owned>
The Regular Expression
/^[o0]/will only match values that begin with either "
O", or "
0". If the Own or Rent field starts with one of those characters, then the literal text "Owned" that follows it in the expression will be inserted in the output.
This expression would be useful if records were transcribed by character recognition and some instances of letter "
O" were mistranscribed as zeroes.
Plus or Minus
If a variable reference begins with "
+" (plus) or "
-" (minus), the output will vary based on the prior output of the template. The plus and minus variables simplify templates where you want to vary the output based on the output from prior field values. The plus and minus variables are intended to be used in conditional expressions and they inspect the output of the prior nesting level.
There are four variations of the plus and minus variables.
[+]variable returns true if the prior output is not empty. It is used to process an alternative only if prior sibling expressions have produced text. You can use it to add a field value to the output only if one or more prior fields are not empty.
[-]variable is the opposite of
[-]returns true if there is no prior output. You can use it to add a field value to the output only if one or more prior fields are empty.
[+:text]variable always returns true. It will insert the specified text if the output of the prior nesting level is not empty.
[-:text]variable always returns true. It will insert the specified text if the output of the prior nesting level is empty.
The most common use of these variables is to insert a comma or other punctuation between fields where one or more of the fields may be empty and you do not want the punctuation before the first non-empty field.
Include "Place: City, County, State" with commas between the second and subsequent fields. This is a more difficult variation of prior examples but shows the simplest solution overall.
<Place: <<[City]><[+:, ][County]><[+:, ][State]>>>
The City, County, and State fields are all conditional. They are enclosed by an outer conditional expression so that the <[+:, ]> variable inspects the output of the three fields and not the literal "Place: " that is at the outer-most level and should only appear if at least one of the place fields is not empty.
If a variable reference begins with "
=:", ORA treats it as a value assignment. You may use a value assigment to change the value of an existing field or to create a new field name and value. Value assignments are used in testing templates or in circumstances where you want to be prompted to enter a value.
An Assignment Reference does not create any output, and the result of the expression is always true.
The general form is:
The name parameter is required.
- If you specify the name of an existing field, its value will be changed for the duration of the template evaluation.
- If you specify a name that does not match the name of an existing field, the assignment will create a new field name and value that will exist for the duration of the template evaluation.
- If the name value includes any of the following characters, they will be changed to a space:
: / = ! < >
The value parameter is optional.
- If you do not enter a colon following the name, you will be prompted to enter a value for the field. If you click the [Cancel] button in response to an assignment prompt, ORA will stop evaluating the template and the template will produce an empty value.
- If you enter a colon and no other characters, the value will be an empty string. You can use this expression to unset a field value.
- If you enter a colon and additional characters, the value will be set to whichever characters you supply.
- If you enter a colon and additional characters that begin with "
[" and end with "
]", ORA will treat the value as a field reference and use that field reference to determine the value to assign. The field reference may include transforms.
If there is any character, even a space, before the leading "
[" or after the trailing "
]", ORA will treat the characters as literal text and not as a field reference.
Assignment References are useful during template testing. You can add one or more assigments to the beginning of a template to review the template output for values that don't occur in the current collection record but may occur in other records.
Assignment References are also useful if your template has two or more references to a transform expression. Rather than repeat the expression, save the result of the transform in a new field and refer to that field multiple times.
You may use Assignment References to prompt you to enter a value. This usage is not recommended in Text Templates because you will br prompted every time you visit a record in the collection. That will be annoying. For Auto Type Templates, however, a prompt may be useful and the prompt will only occur when you click the Control Panel button associated with the Auto Type Template.
Special Text Templates
Tab.Title" Text Templates do not appear in the ORA Control Panel and their values are not available to other templates.
If the Heading value of a Text Template is "
Tab.Title", ORA will evaluate the template and use the result as the title for the browser tab when the collection appears in a browser tab. Adding a
Tab.Title Text Template is useful when the tab title assigned by the repository is confusing or not useful.
For example, the Nova Scotia Historical Vital Statistics repository sets the tab title to "Item View" when viewing record images:
"Item View" is not useful when you have multiple tabs open and you want to switch back to a particular tab. To customize the tab title for records in the NovaScotiaGenealogy.com Marriage collection, add a Text Template named "
The template above sets the tab title to "surname1/surname2 year" using the
split transform to extract the last word in a name field as the surname. For my usage, the icon for NovaScotiaGenealogy.com is enough to identify the repository. The surnames of the spouses and the year provide enough context to identify a marriage record in most if not all circumstances where I have records open in multiple tabs.
Customize the "
Tab.Title" template to suit your preference.
After adding or modifying the Text Template, refresh the ORA Control Panel to see the custom tab title:
See the Tab.Title Template Suggestions page for Tab.Titles you may wish to add to you ORA configuration.
Text Templates whose headings begin with "
var." do not appear in the ORA Control Panel.
If the Heading value of a Text Template begins with "
var.", ORA will evaluate the template and save its value in the field collection (as is true of
most other Text Templates) but it will not show the Text Template in the Control Panel.
Adding one or more Text Templates whose labels begin with "
var." is useful for creating values that you use in subsequent Text Templates or Auto Type Templates. This centralizes the definition of a value so you can define it once and use it in multiple places.
For example, if you want to parse a state value from a place field, you might create a Text Template as follows:
The template presumes that the Place value ends with the state name, or with the state name followed by ", USA". The template removes any trailing ", USA" text in the place value then splits it by the comma character and returns the last part.
In a subsequent template, you can refer to the Text Template value with "
Text Template Fields
When ORA processes a Text Template for a collection, the result is added to the Control Panel. The result is also added to the fields that are associated with the collection. This can be useful for generating intermediate results that are subsequently used by other templates. Any Text Template can refer to the field for any other Text Template with a lower number, and any Auto Type Template can refer to any Text Template.
The field name is the heading of the Text Template. So, for example, if you add a Text Template with the heading "Citation Detail", you can refer to the output of the template in a subsequent template using
You may use this capability to reduce or eliminate repetitive computation of the same value, such as when you have two or more Auto Type Templates that transform a field to match your data entry standards.
It can be confusing to test templates that refer to an other Text Template because Text Templates are only evaluated when viewing a record in the collection. If you change a Text Template, then immediately test another template that refers to the changed Text Template, you won't see any difference. You have to visit or refresh the Control Panel for a record in the collection so that ORA will update the Text Template values for that collection.
An abbr Transform may be used to determine if a state value is valid.
<[?:State:abbr:us_states]valid state|invalid state>
If the State field value is not a valid state name, the value of
[?:State:abbr:us_states] will be false. Substitute the output you want when the state is valid or invalid in place of the text used in the example.
You may use the same technique with the other lookup tables.
An Assignment Reference without a value produces a prompt for the user to enter a value. If you only want the prompt if a field is not present in a record or meets some other criteria, you can nest the Assignment Reference in a conditional expression:
If the "City" field is empty, the Value Test
[?:City] will be false and the second alternative will be evaluated. That alternative includes the Assignment Reference which is a prompt because it has no value, and the user will be prompted.
This page last changed on 09 Oct 2020.