Terry's ORA Tips

Intermediate Template Methods

This page updated 10 Feb 2024

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   10 Feb 2024
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	Including data not indexed in Templates, and more
Adding Comments	Using Comment lines to document complex Templates
Conclusions	Additional comments and links on Templates

My Template Basics article describes 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. You can also test whether the contents are more than, less than, or not equal to the specified value.

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:

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

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:

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:

There is also a special form of the Value Test Variable that uses Regular Expressions to test for a specified pattern in the field value rather than a testing or a literal string of letters or numbers. In this form the Regular Expression is enclosed in slash characters. The first example above would look like this in this form:

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

A more useful application of the Regular Expression form would use a more complex pattern than a simple literal text. This example tests whether the value of the Variable "Occupation" begins with a vowel, and if it does outputs "an" and if not outputs "a":

<[?:Occupation/^[aeiou]/]an|a>

For more information on using Regular Expressions see my article on Using Regular Expressions in ORA.

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:

• A simple field Variable is "true" if the field it refers to exists in the record and is non empty. So for the expression:

would produce these results:

• A Value Test Variable is "true" if the field it refers to exists, and its value matches that specified in the test. So for the expression:

would produce these results:

• When a Conditional expression contains literal text in addition to Variables, the literal text is output when the expression evaluates as "true" and is not if it evaluates as "false."So for the expression:

would produce these results:

• When a Conditional expression contains more than one Variable, all of them must be "true" or there is no output. So the expression:

would produce these results:

• Conditionals may be "nested." When a Conditional expression contains a second Conditional element, only those terms outside the inner Conditionals need to be "true" for the outer terms to be output. So the expression:

would produce these results:

• But a special rule applies with nested Conditionals when the outer term contains only literal text. In that case at least one of the inner terms must evaluate as "true" for there to be any output. So the expression:

would produce these results:

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:

It would produce these results:

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:

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:

• [+]
  Returns true if the prior elements produced output. It produces no output itself, but is used in a Conditional Alternatives segment with other elements to produce output only if the prior segment did produce output.

• [-]
  Returns true if the prior elements did not produce output. It produces no output itself, but is used in a Conditional Alternatives segment with other elements to produce output only if the prior segment did not produce output.

• [+:text]
  Outputs the specified text only if the prior segments did produce output. Always returns true so that other elements within the same Conditional segment can be output.

• [-:text]
  Outputs the specified text only if the prior segments did not produce output. Always returns true so that other elements within the same Conditional segment can be output regardless of whether or not this variable produced output.

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

The following are some of the possible outputs:

This example illustrates three important points in using the plus and minus variables:

1. The plus and minus Variables must be enclosed within an outer pair of Conditionals that also enclose the terms whose output they are to test. This is highlighted below, where the same Template segment is used, with the outer conditionals colored in green:.

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

2. The element whose output is being tested must be at the same nesting level as the plus and minus variables. This is shown below, again with the same Template segment, but with each of the three elements colored a different color to illustrate they are all peers of one another within the outer Conditionals:

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

3. The [+:, ] Variables must be included within the same Conditionals as the Variables they are to introduce. If they are not the comma and space will be output if that field is empty. In the same Template segment again, in the illustration below Conditionals that enclose both the [+:, ] Variables the following the county and state Variables marked with color:

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

One might be tempted to use this simpler Template segment instead of using the [+, ] Variables shown in the above example:

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:

but this output if only the second is populated:

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:

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:

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 blue 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 Transforms. For Example:

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 :capitalize Transform, then the new value is assigned to the original Variable, Name.

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:

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.

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:

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.

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:

Assigning Values that Can be Used in Other Templates – Persistent Variables

In all the examples above, the Variable created or populated with the Assignment Variable is "temporary." That is, it only exists within the Template that creates it. No other Templates will have access to that Variable. There is a variation of the Assignment Variable that creates a Variable that can be accessed by other Templates. This variation is created by beginning with two equal signs instead of one, creating a "persistent" Variable.

The Variable created will appear in the OraPanel (which is automatically refreshed to receive it) and is thus available for use by both Text Templates and Auto Type Templates. Persistent Variables remain when the OraPanel is refreshed, but are removed if the webpage is refreshed or if you navigate to a new page.

Any of the forms of Assignment Variables may be used to create a Persistent Variable, but perhaps the most useful is when it is used to generate a prompt to enter a value that is not indexed in the record, so that value can be used by more than one Template. Example:

In this application, the Assignment Variable that creates the prompt must be in a Template that is used before other Templates that will use the value. If the Templates will be used in a specific sequence, place the Assignment Variable in the first one that will use the value. If the sequence in which the Templates that will use the value from the prompt may vary, the Assignment Variable to create it can be placed in each Template, testing first to see if it has already been created with a Value Test Variables as in the following example:

In this example, a Value Test Variable is placed within an Alternative Conditional structure as discussed above. If the Reg Date Variable already exists, the Value Test Variable will return True, and the Conditional statement is satisfied with no output. But if the Reg Date Variable does not exist, the second half of the Conditional statement comes into play and the persistent Assignment Variable prompts the user for the date.

Adding Comments

Recalling the purpose of a set of Template code created some time in the past can be difficult, making updates or corrections more challenging. Adding Comments to document parts of a Template that may not be obvious can help. Comments can also help keep track of logical sections of a long Template. Comments are added by placing the " # " symbol as the first character in a line, as in this example:

[=Name:[Name:capitalize]]
# start code to capitalize "Mc" prefix
[=:Name:[Name:replace:\b(Mc)([a-z]):$1;$2]]
[Name:split:;:1][Name:split:;:2:capitalize]
# end code to capitalize "Mc" prefix

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:

• For a review of the basics of Template writing, see my article on Template Basics.
• For description of how to use Transforms to modify the format of the data when output by Templates, see my article on Transforms
• For a complete list of available Transforms and other Templates tools see the Help page on Text Templates.
• For some examples of the use of the techniques described here see my Template Examples.
• For help with using the techniques described here in Auto Type Templates, see my article on Auto Type Templates.
• For some more advanced techiques see my article on Advanced Template Methods.

Copyright 2000- by Terry Reigel