On This Page
advertisement

Summary

ORA's Template Library provides a way for users to store frequently-used template text in a library. A template in the library may be used by any collection template. This helps reduce repetition in collection templates.

The Template Library feature is a text pre-processor that modifies the collection template before the usual template processing begins. The text in a library template is inserted into a collection template anywhere the collection template refers to a library template.

The diagram below shows an example of how a collection template is modified by a reference to a library template.

Template Library Example

For Library Templates provided by John Cardinal or contributed by other users, see Importable Library Templates.

Editing Templates

You open the Template Library using the [Templates...] button on the OraSettings page to open the Edit Library Templates panel:

Template Library Settings
  • Use the Add Template... button to add a new template to the library. You will be prompted to enter the name of the template.
  • Use the Current Template pull-down menu to select a template to edit. When you choose a template from the pull-down menu, ORA will set the textbox to the text of the template you select.
  • Use the textbox to edit the current template.
  • Use the Rename Template... button to rename the current template. You will be prompted to enter the new name of the template.
  • Use the Delete Template... button to delete the current template from the library. You will be prompted to confirm that you really do want to delete the template.

Template References

To insert a library template into a collection template, you add a library template reference to the collection template. You may add a library template reference to both Text Templates and Auto Type Templates in any collection in any repository.

You may create library templates that are intended for use with only a subset of the collections you use, but that is up to you.

A library template reference uses syntax that is similar to Variable References:

[lib.name]
  • lib. is a special prefix that indicates that the name that follows identifies a library template and not a field value.
  • name is the name of a template in your template library.

Template Contents

A library template may include any template text that you would otherwise include in a Text Template or Auto Type Template:

  • Variables references such as [Name]
  • Conditional expressions such as <Address: [Address]>
  • Assignment References for prompts or other purposes
  • Auto Type Control Sequences
  • Literal Text
  • Comment Lines
  • References to other library templates (Be careful of endless loops!)

Typically, a library template will provide only a portion of the output of the collection template where it is referenced, but how much or how little to specify in a library template is up to you.

Template Reference Parameters

As described above in the Template References section, you add a library template reference to insert a library template into a collection template. The full syntax is:

[lib.name:parameter1:parameter2:...]

You may include zero, one, or more parameters.

To use a parameter inside the library template, enclose the parameter number in braces. For example, to refer to parameter 1, use {1} and to refer to parameter 2 use {2}.

Inside the library template you may provide a default value for a parameter. For example, if parameter 1 is optional and should default to "Record Id", you would use this text in the library template: {1:Record Id}.

Using Field Names as Parameters

To implement a library template that operates on a field that is supplied in a parameter, the library template reference should include the field name and should not enclose the name in brackets.

  • Correct: [lib.County:Birth Place]
  • Incorrect: [lib.County:[Birth Place]]

In the library template, to use the parameter to refer to a field, enclose the parameter reference inside brackets:

[{1}]

After the Template Library pre-processor modifies the template, the resulting text is:

[Birth Place]

In the library template, you may add transform parameters after the reference to the parameter:

[{1}:split:,:2]

After the Template Library pre-processor modifies the template, the resulting text is:

[Birth Place:split:,:2]

Conditional Sections

A library template may include conditional sections that are included only if the associated parameter is provided in the template reference. A conditional section begins with {{n: where "n" is the parameter number. The conditional section ends with the next }} characters.

Conditional sections may not be nested.

Example Template with Conditional Sections

The library template below has six conditional sections that are inserted into the collection template only if the associated parameter (2 through 7) is provided.

<
{{2:<[{2}]>}}
{{3:<[+:{1:, }][{3}]>}}
{{4:<[+:{1:, }][{4}]>}}
{{5:<[+:{1:, }][{5}]>}}
{{6:<[+:{1:, }][{6}]>}}
{{7:<[+:{1:, }][{7}]>}}
>

The template accommodates up to seven parameters where the first is an optional delimiter that defaults to ", " and the remaining six are field names. The template concatenates the fields together using a conditional expression but only includes sub-expressions for fields whose names are included in the template reference.

If the template above was named "concatPlace", you would call it as shown in the examples below. Assume that the fields mentioned in the example have these values:

  • City: Boston
  • County: Suffolk
  • State: Massachusetts
  • Country: (empty)

Example References

[lib.concatPlace::City:State]

Result: Boston, Massachusetts

[lib.concatPlace::City:County:State]

Result: Boston, Suffolk, Massachusetts

[lib.concatPlace:; :City:County:State:Country]

Result: Boston; Suffolk; Massachusetts

Parameters and RegEx

If your Library Template includes a RegEx pattern, and that pattern includes a RegEx repeat quantifier "{n}", ORA treats the repeat quantifier as a reference to a template parameter. Unfortunately, escaping the "{" and "}" characters doesn't help.

There is a workaround: if you add a leading zero to the repeat count, the Template Library parser will not treat the repeat quantifer as a reference to a parameter. For example, use "{02}" where you would normally use "{2}".

Recommendations

  1. Include comments at the beginning of Library Templates that describe the template and how to use it. Comments begin with a "#" as the first character in the line.
  2. The first comment should explain the usage, i.e., how to construct the Library Template reference. Begin the usage comment with the text, "Usage:".

Example:

# Usage: [lib.EnterClear:fieldName]
# If Field value is "ENTER", sets the field to empty.
 
<[?:{1}!=ENTER]|[=:{1}:]>

Export Templates

Clicking the [Export Templates…] button opens a "Select Templates to Export" panel. The panel includes a list of all your Library Templates. Each template in the list has a checkbox. Click the checkbox to select the templates you want to export.

Select Templates to Export

You may click the [All] or [None] buttons to change all the templates to checked or unchecked, respectively.

After selecting the templates you want to export, click the [Export to Clipboard] or [Export to File…] button.

  • Export to Clipboard will copy the selected templates to the clipboard. This is useful if you want to copy the templates to a different browser on the same PC.

  • Export to File... will copy the selected template to an external file. OraHost will prompt you for the filename and location where you want to save the selected templates. The templates are written to a single file with the extension ".ora-templates". This is useful if you want to copy the templates to a different PC or share them with another user.

Import Templates

Clicking the [Import Templates…] button opens a panel with two choices, [Import from Clipboard...] and [Import from File...]

Import from Clipboard or File

  • Import from Clipboard... will read templates from the clipboard. This is useful if you want to import templates that were placed on the clipboard by ORA running in a different browser on the same PC.

  • Import from File... will read templates from an external file. OraHost will prompt you for the filename and location of the file you want to use. This is useful if you want to copy templates from a different PC or from another user.

Whichever option you choose, [Import from Clipboard…] or [Import from File...], ORA will open a "Select Templates to Import" panel. The panel includes a list of Library Templates that ORA found in the clipboard text or the external file. Each template in the list has a checkbox. Click the checkbox to select the templates you want to import.

Select Templates to Import

You may click the [All] or [None] buttons to change all the templates to checked or unchecked, respectively.

After selecting the templates you want to import, click the [Import] button.

If a template you import has the same name as an existing template, the imported template will replace the existing template. There is no warning, so use caution.

Copyright © 2024 by John Cardinal