Terry's ORA Tips

Intermediate Template Methods

This page updated 29 Jul 2020

Version note: Applies to ORA 1.06 or later

This article describes some methods for constructing Templates in Online Repository Assistant (ORA) that extend the techniques described in my article on Template Basics. Other articles in my ORA Section cover other topics about using the software.

Topics Included in this Article
Using Value Test Variables
Testing the value of a field to control output
Conditionals Revisited
Understanding Conditionals more thoroughly
Conditionals using Alternatives
Selecting between multiple elements to produce the desired output
Plus and Minus Variables
Changing the output depending on whether a prior element produces output
The Assignment Variable
A handy tool for testing Templates, and more
Text Template Fields
Using the output of a Text Template in another Template
Conclusions
Additional comments and links on Templates

My Template Basics article described how to get started creating Templates to expand the ability of ORA to simplify the process of extracting data from genealogical services and recording it in your genealogy program. This article builds on that foundation using additional ORA features to further reduce the need to manually edit the data collected by ORA. Like the basics article, this article uses Text Templates for all examples, but all methods described here apply equally to Auto Type Templates, which are discussed in my article on Auto Type Templates.

Using Value Test Variables

In some cases you don't want to include the actual data in a field in your data, but instead want to enter some other output based on what that data is. For example, the 1900 U.S. census recorded whether a family owned or rented their home. Ancestry has recorded this data, but only as "R" or "O" which is how ORA collects it. Value Test Variables allow you to check a field to see if the contents are a certain value, then produce some other output if it does.

Value Test Variables are placed within Conditional brackets to produce output only if the test passes. They are formed by placing a question mark and colon – " ?: " – inside the square brackets of a normal Variable, before the name of the field, and placing an " = " sign after the name of the field followed by the number or text that is being tested for, again within the square brackets. Here is an example based on the "House Owned or Rented" field from the 1900 U.S. census:

<[?:House Owned or Rented=R]rented their home>

The output of this Template segment depends on the value in the "House Owned or Rented" field, as shown in the following table:

Value in Field Template Output
field = R rented their home
field = O {nothing}
field empty, something else, or does not exist {nothing}

In practice, when using a field that you expect to have one of two values you would probably use a pair of such terms, like this:

<[?:House Owned or Rented=R]rented their home><[?:House Owned or Rented=O]owned their home>

The output of the pair of terms would then be:

Value in Field Template Output
field = R rented their home
field = O owned their home
field empty, something else, or does not exist {nothing}

More robust Templates for this purpose can be created combining these Value Test Variables with more elaborate Conditional expressions, or with the Alternatives feature described in the following sections.

Should you want to test whether a field is not equal to a particular value, insert a " ! " in front of the " = " sign, like this:

<[?:State!=Virginia]>

Conditionals Revisited

My article on Template Basics described the use of Conditional brackets to deal with Variables that may be empty or not exist in a given record. The section above describes a similar use of Conditional brackets with Value Test Variables. A fuller understanding of how Conditional expressions operate may aid in creating useful expressions in more elaborate constructions.

The basic rule is that a Conditional expression produces output if all of its contents evaluate as "true." What does this mean? These points may help:

<[Age]>

would produce these results:

Value in Field Evaluation Template Output
Age = 20 true 20
Age empty or does not exist false {nothing}
<[?:Age=20][Age]>

would produce these results:

Value in Field Evaluation Template Output
Age = 20 true 20
Age = 25 false {nothing}
Age empty or does not exist false {nothing}
<was age [Age]>

would produce these results:

Value in Field Evaluation Template Output
Age = 20 true was age 20
Age empty or does not exist false {nothing}
<age [Age]and born in [State]>

would produce these results:

Value in Field Evaluation Template Output
Age = 20 & State = Virginia true age 20 and born in Virginia
Age empty & State = Virginia false {nothing}
Age = 20 & State empty false {nothing}
Age empty State empty false {nothing}
<age [Age]<and born in [State]>>

would produce these results:

Value in Field Evaluation Template Output
Age = 20 & State = Virginia true age 20 and born in Virginia
Age = 20 & State empty true age 20
Age empty & State = Virginia false {nothing}
Age empty State empty false {nothing}
<She was <age [Age]><and born in [State]>>

would produce these results:

Value in Field Evaluation Template Output
Age = 20 & State = Virginia true She was age 20 and born in Virginia
Age = 20 & State empty true She was age 20
Age empty & State = Virginia true She was born in Virginia
Age empty & State empty false {nothing}

We may now observe that the Conditional expression about rented vs. owned home written at the end of previous section, which was:

<[?:House Owned or Rented=R]rented their home><[?:House Owned or Rented=O]owned their home>

can be written more simply as:

<<[?:House Owned or Rented=R]rented><[?:House Owned or Rented=O]owned> their home>

Using nested Conditionals this way produces the same results but allows us to write the shared text "their home" only once. The savings would be even more evident if there was shared introductory text; perhaps "Reporting that they "

Conditionals Using Alternatives

ORA offers another method of using Conditionals called Alternatives. With this feature you enter a series of expressions within a single pair of Conditional brackets, with the expressions separated by a " | " character. ORA evaluates each expression in turn, starting with the first. It outputs the first expression which evaluates as true and ignores any that follow. If none evaluate as true there is no output.

Each individual expression is written as if it were a stand-alone Conditional expression and may contain one or more Variables, literal text, and even conditional terms.

An example of this method to output the city and state fields from a record is as follows:

< [City], [State]| [City]| [State]>

It would produce these results:

Value in Field Template Output
City = Richmond & State = Virginia Richmond, Virginia
City = Richmond & State empty Richmond
City empty & State = Virginia Virginia
City empty & State empty {nothing}

It can be useful to enclose an Alternatives expression with another conditional that contains literal text. If we were to write our home rented or owned expression in this format it would look like this:

<<[?:House Owned or Rented=R]rented|[?:House Owned or Rented=O]owned> their home>

This expression makes use of the fact, described in the preceding section, that when a Conditional expression contains other Conditional expressions and the outer term contains only literal text, nothing will be output unless at least one of the inner Conditionals evaluates as true.

Plus and Minus Variables

For Templates that include output from multiple Variables, in some cases we may want the output to vary based on whether or not an earlier Variable has produced any output. To cite a simple example, suppose we have a Template with Variables for city, county, and state, but in some records one or more of those fields is empty. We want a comma in the output between the place names that are present in the record, but no extra commas when some fields are empty.

The Plus and Minus Variables are designed to solve this very issue. There are four variations of these two Variables:

These variables must be placed within Conditional brackets, and the segments formed by those Conditionals must be nested within outer Conditionals at the same level as the other segments the the Plus and Minus Variables are to test. A simple example may help. Suppose we have this Template segment using the [+:text] Variable, where the "text" is a comma followed by a space:

<<[City]><[+:, ][County]><[+:, ][State]>>

The following are some of the possible outputs:

Values of City Value of County Value of State Sample Output
Atlanta ‎Fulton Georgia Atlanta, Fulton, Georgia
Atlanta {empty} Georgia Atlanta, Georgia
{empty} Fulton Georgia Fulton, Georgia
Atlanta Fulton {empty} Atlanta, Fulton

Notice in this example that the [+:, ] Variable is included within the segments with the county and state Variables. This important, because it means that the comma and space will only be output if that field is not empty. One might be tempted to use this simpler Template segment instead:

<[City], ><[County], ><[State]>

This will work, but only if the state field is always populated. If it is not, this format will produce a comma after the name of the county which we don't want. Use of the [+:text] Variable is required if the last Variable may not produce output.

As noted above, the versions of the Plus and Minus Variable without the text parameter produce no output themselves but are used to control output of literal text or other Variables. The following example, taken loosely from the 1790 U.S. census, may help. Suppose we have two fields in a Collection: "under 15" and "over 15." We want output like this if both fields are populated:

2 people under age 15, 3 over age 15

but this output if only the second is populated:

3 people over age 15

Note that the word "people" is to appear with the output from the second Variable only if there is no output from the first. The following Template segment uses the [+] Variable to produce the desired output:

<<[under 15] people under age 15><[+], [over 15] over age 15|[over 15] people over age 15>>

The Template segment has two parts. The first, in yellow above, produces output from the "under 15" field. The second, in green, produces output from the "over 15" field. The second part itself contains two parts within an Alternatives Conditional, as shown below:

<<[under 15] people under age 15><[+], [over 15] over age 15|[over 15] people over age 15>>

In this second illustration of the same Template segment the two halves of the second part are shown in separate colors. The part in green produces output without the word "people." It is used when the "under 15" field exists. The teal part does include the word "People" and is used when the "under 15" field is empty.

The [+] variable, in pink, controls whether or not the green part is used. If there is output from the first term, in yellow, the [+] Variable returns true and the green term is used. The Alternatives Conditional is then finished and the blue term is ignored. But if there is no output from the yellow term the [+] Variable returns false and the whole green term is ignored, causing the second element in the Alternatives Conditional to come into play. The teal part then produces output.

Note that the whole expression is enclosed in outer Conditional brackets, also colored in pink. Both the element containing the pink [+] Variable and the yellow term it is testing are at the same nesting level. This is essential, and is an easy point to miss, causing unexpected results.

A more complex example using this method can be seen in my 1830/1840 US Census example.

The Assignment Variable

The Assignment Variable allows you to assign a value to a field. The Variable begins with " =: " followed by two parameters. The first is the name of the field, and is required. The second is the value to be assigned to that field, and allows the Assignment Variable be used in any of the following ways:

Assign the Value of a Field

If the second parameter is a Variable, the value of that Variable is assigned to the field named in the first parameter. The Variable in the second parameter may be the same as in the first parameter, and may be modified with Transformations. For Example:

Assignment Variable Value of Name Assigned Value
[=:Subject:[Name]] ‎John Jones John Jones
[=:Surname:[Name:split: :-1]] John Jones Jones
[=:Name:[Name:uppercase]] JOHN JONES John Jones

In the first example, the value of Name is assigned to a new Variable, Subject.

In the second example, the last segment of the value of Name is assigned to a new Variable, Surname.

In the third example, the value of Name is changed to initial capitals by the :uppercase Transformation, then the new value is assigned to the original Variable, Name.

Assigning Test Values

If the second parameter of the Assignment variable is text, that text is assigned to the Variable specified in the first parameter. This is used mainly in testing of Templates. It allows you to assign a value to a field, either overriding the actual value ORA has collected, or defining a new field that does not exist in the current record. Using this Variable allows you to test various values of a field without having to find a record that contains the value you want to test. Similarly, you can test a Template's response to a field that may not exist in the current record without having to search for record that does contain that field. For example:

Assignment Variable Value of Name Assigned Value
[=:Name:John Jones] Bill A. Smith John Jones
[=:Name:John Jones] {empty} John Jones

Creating a Prompt

If no second parameter of the Assignment variable is provided, ORA will prompt the user to enter a value manually when a Template is used. This is useful when an Auto Type Template is to type data which does not appear in any field, for example a data item that appears in an image but is not indexed in the record. For example:

Assignment Variable Value Entered Assigned Value
[=:Family Number] ‎321 321
[=:Source Number] 512 512

The first example might be used for a census record when the family number is not indexed, but appears in an image of the original document.

The second example might be used when a Template is to be used to create citations to multiple source definitions in the genealogy program, and the user is to enter the number of the source to be cited for this record.

All prompts are presented before the Template produces any output, no matter where they are placed in the Template code. I generally find them most convenient to place them before any other code.

Using Assignment Variables to create a prompt is not recommended for Text Templates because you will receive the prompt every time you visit a record in the Collection associated with that Template.

Removing Value from Field

If the second parameter of the Assignment Variable is indicated by including the colon, but no value is provided, the current value in the Variable in the first parameter will be removed. Example:

Assignment Variable Value of Name Assigned Value
[=:Name:] ‎John Jones {empty}

Note that this form differs from that used to create a prompt in that a colon is placed after the first parameter, while that colon is omitted to create a prompt.

Text Template Fields

A very useful, if somewhat advanaced, technique is to create a Text Template, the output of which will appear in the Control Panel, and then use that output as in input field in another Template. This method can be useful when several Templates require the same processing of data, by creating one Template to do that processing then using the result repeatedly. One application of this can be seen in my article on Templates Designed to be Copied.

Several rules apply to use of this method:

Conclusions

This article describes what I find to be as the most useful of the many available Template tools. For more information I suggest the following:

ReigelRidge Home Terry's Tips Home Contact Terry

 

Fewer than ten copies of my book, A Primer for The Master Genealogist, remain.
If you have been thinking of getting a copy now would be a good time.

Details are can be seen here.

 

Copyright 2000- by Terry Reigel