advertisement

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.

Templates consist of literal text, variable references, and conditional expressions.

Variable references may include transforms. For general information about using transforms, see below. For information about specific transforms, see the Transforms help page.

Literal Text

Literal text is any text that is not part of a Variable Reference or Conditional Expression. Use literal text to add punctuation, labels, or other text to the output.

Variable References

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.

Conditional Expressions

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.

Examples

  1. Include the Date field value in the output with a prefix of "; Date: ":
    <; Date: [Date]>
  2. Include "Place: City", "Place: State", or "Place: City State" depending on which values are present:
    <Place:< [City]>< [State]>>

Alternatives

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] in <, [A]<, [B]><, [C]>>, the outer variable and text will appear even if all the nested conditions are false.

Example

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.

Transforms

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:

[field-name:transform]

Parameters

Some transforms have parameters:

[field-name:transform:parameter1:parameter2]

Chaining

You may specify several transforms in succession. This is called "chaining".

[field-name:transform1:transform2:...]

For example:

[Children:numberToWords:capitalize]

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).

Special Variables

Value Test

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 as shown in the list below.

In the list, assume that "Name" is a field in the current record. The comparand is the value in the expression, so in [?:Name=Maureen], the comparand is "Maureen".

  • Not Empty: [?:Name] — This variable will have a true value if the Name field is not empty.
  • Equal: [?: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: [?:Name/ee/ ]

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.

Examples

  1. 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 <[?:City],> does.

  2. Include "Owned" if the "Own or Rent" field is equal to "o" or "O":
    <[?: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.

  3. Include "Owned" if the "Own or Rent" field starts with "o" (lowercase oh), "O" (uppercase oh) or "0" (zero):
    <[?:Own or Rent/^[o0]/]Owned>

    The Regular Expression /^[o0]/ will only match values that begin with either "o", "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.

Value Test - Dates

When evaluating a Value Test, if ORA determines that both the field value and the comparand value are dates, it uses a date comparison rather than a string comparison. In a date comparison, the parts of each date (year, month, and day) are converted to numbers and the parts are compared in year, month, day sequence.

You may specify the comparand value using any of the formats that ORA recognizes as a date, so "1 MAR 1998" is valid as is "1998-03-01".

Both the field value and the comparand may be full dates or partial dates. Full dates include year, month, and day. Partial dates include a year only or a year-and-month only. ORA uses the parts in the comparand to determine which parts to compare.

The field value and the comparand value may have a different number of parts. So, for example, if the "Date" field is "3 FEB 1905" and the Value Test is [?:Date=1905], the field value has year, month, and day, but the comparand value is a year only. ORA uses the comparand value to determine which parts to compare, so in this example it will compare the year values only, and the result is true.

When the field value does not have all the parts that are specified in the comparand value, ORA will assume a "worst case" value for each missing part. This can lead to confusing results when the field value is close to the comparand value. For example, if the "Date" field is "1905" and the Value Test is [?:Date<FEB 1905], the result is false. However, that does not mean that [?:Date>FEB 1905] is true, and in fact, the result is also false. ORA treats the "Date" field value as ambiguous when it has less than the required parts, and so ORA doesn't know if "1905" is greater than or less than "FEB 1905". See the table below for more examples.

Examples

Value of Date Field Value Test Reference Result
1 JAN 1900[?:Date<1900]False
The comparand date has a year only, so ORA only compares the year from the date field ("1900") to the comparand ("1900"). "1900" is not less than "1900", so the result is false.
1 JAN 1900[?:Date=1900]True
The comparand date has a year only, so ORA only compares the year from the date field ("1900") to the comparand ("1900"). "1900" is equal to "1900", so the result is true.
1 JAN 1900[?:Date>1900]False
The comparand date has a year only, so ORA only compares the year from the date field ("1900") to the comparand ("1900"). "1900" is not greater than "1900", so the result is false.
1899[?:Date<1900]True
The comparand date has a year only, so ORA only compares the year from the date field ("1899") to the comparand ("1900"). "1899" is less than "1900", so the result is true.
1899[?:Date=1900]False
The comparand date has a year only, so ORA only compares the year from the date field ("1899") to the comparand ("1900"). "1899" is not equal to "1900", so the result is false.
1899[?:Date>1900]False
The comparand date has a year only, so ORA only compares the year from the date field ("1899") to the comparand ("1900"). "1899" is not greater than "1900", so the result is false.
1900[?:Date<FEB 1900]False
The comparand date has a year and month, but the field value has a year only. ORA uses the "worst-case" value for the month, which is December for a "less than" comparison. It compares the adjusted field value ("DEC 1900") to the comparand ("FEB 1900"). "DEC 1900" is not less than "FEB 1900", so the result is false.
1900[?:Date=FEB 1900]False
The comparand date has a year and month, but the field value has a year only. For an "equal to" comparison, the field value must have all the date parts that exist in the comparand, and in this example, it does not, so the result is false.
1900[?:Date>FEB 1900]False
The comparand date has a year and month, but the field value has a year only. ORA uses the "worst-case" value for the month, which is January for a "greater than" comparison. It compares the adjusted field value ("JAN 1900") to the comparand ("FEB 1900"). "JAN 1900" is not greater than "FEB 1900", so the result is false.
1899[?:Date<FEB 1900]True
The comparand date has a year and month, but the field value has a year only. ORA uses the "worst-case" value for the month, which is December for a "less than" comparison. It compares the adjusted field value ("DEC 1899") to the comparand ("FEB 1900"). "DEC 1899" is less than "FEB 1900", so the result is true.
1899[?:Date=FEB 1900]False
The comparand date has a year and month, but the field value has a year only. For an "equal to" comparison, the field value must have all the date parts that exist in the comparand, and in this example, it does not, so the result is false.
1899[?:Date>FEB 1900]False
The comparand date has a year and month, but the field value has a year only. ORA uses the "worst-case" value for the month, which is January for a "greater than" comparison. It compares the adjusted field value ("JAN 1899") to the comparand ("FEB 1900"). "JAN 1899" is not greater than "FEB 1900", so the result is false.

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.

  • The [+] 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.
  • The [-] 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.
  • The [+:text] variable always returns true. It will insert the specified text if the output of the prior nesting level is not empty.
  • The [-: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.

Example

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.

Assignment

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:

[=:name:value]

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

"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:

NovaScotiaGenealogy.com Marriage Record

"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 "Tab.Title":

NovaScotiaGenealogy.com Marriage Collection "Tab.Title" Template

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:

NovaScotiaGenealogy.com Marriage Record with custom Tab.Title

See the Tab.Title Template Suggestions page for Tab.Titles you may wish to add to you ORA configuration.

Variable Templates

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:

Heading:var.State
Template:[Place:replace:, USA$::gi:split:,:-1]

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 "[var.State]".

Advanced Techniques

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 [Citation Detail].

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.

Valid State

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.

Conditional Prompt

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:

<[?:City]|[=:City]>

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.

On This Page