Search Targets

Summary

Search Targets provides a mechanism to add links to the OraPanel for searching a repository using some of the fields on the current page as the search criteria.

For example, here is a OraPanel with a link to search Ancestry ("ANC") using the fields from a Find a Grave memorial:

ORA includes several predefined Search Targets. They are disabled by default. You may edit the Search Targets to enable any that you wish to use. You may also add your own Search Targets.

Search Targets create a link to the target site. Any site that has a search form that can be filled-in by a URL with query parameters can be used with the ORA Search Targets feature. Many, many sites support query URLs.

Search Targets use an ORA Template to define the URL. ORA creates the rest of the HTML required for the link. If the template does not create any text, the Search Target link is omitted from the OraPanel. That makes it possible to include or exclude certain Search Targets based on the page conditions, such as which fields are present, the collection ID, etc.

Editing Search Targets

You open the Search Targets panel using the [Search Targets...] button on the OraSettings page.

• Use the Search Target pull-down menu to select a search target to edit. When you choose a search target, ORA will set the properties in the panel using the selected Search Target.
• Use the Enabled checkbox to enable or disable the current Search Target. Disabled Search Targets are ignored when ORA creates the OraPanel.
• Use the Trace checkbox to enable or disable tracing as ORA formats the URL Template for the current Search Target.
• Use the Delete This Search Target... button to delete the current Search Target. You will be prompted to confirm the action. A deleted template cannot be restored except by recreating it manually, so be careful.
• Use the Link Text textbox to define the label ORA will use when it adds a link to the OraPanel for this Search Target. It's usually best to use a short text value, such as an abbreviation, to avoid cluttering the OraPanel.
• Use the URL Template textbox to edit the template that will create a URL ORA will use to perform a search. See the examples below.
• Use the Add Search Target... button to add a new Search Target. You will be prompted to enter the name of the Search Target.

URL Parameters

The URL Template creates a value that ORA inserts into the HREF parameters of an HTML link. Those URLs will include query parameters, and the syntax rules for query parameters require that some characters are encoded. ORA includes a Transform that encodes text for use as a query parameter: urlParameter.

You should always use the urlParameter transform when including Field values in the URL.

Filtering

If the URL Template for a Search Target does not produce any text, ORA will not add a link to the OraPanel for that Search Target. You can use that capability to omit Search Target links that are not pertinent to the current page. You may also wish to omit a Search Target link if the Field values required to make a useful search URL are not present.

Required Fields

To omit a Search Target if the current page does not include the Fields required to construct a useful search URL, use the Multiple value test reference to ensure none of the required fields are empty. You may use Fields on the current page or standardized Fields that ORA makes available to the URL Template. Typically, you include a conditional expression as the outermost expression.

For example, to require values in both the qf.Givenname and qf.Surname fields:

<[??:qf.Givenname:qf.Surname]
# Construct URL here
>

Current Service

To omit a Search Target if the current page is not part of a particular ORA Service, use a Value test reference to require that Page.ServiceName matches the desired service.

For example, to include a Search Target only if the current page is on Find a Grave:

<[?:Page.ServiceName=Find a Grave]
# Construct URL here
>

The ORA Service names are:

Careful! The names listed above do not always match the names shown in the service names list on the OraSettings page.

Collection

To omit a Search Target based on the current collection, use a Value test reference to require that Page.Collection ID or Page.Collection Name matches the desired collection.

For example, to include a Search Target only if the current page is part of Ancestry's "1930 United States Federal Census" collection using Page.Collection ID:

<[?:Page.Collection ID=6224]
# Construct URL here
>

The Page.Collection ID value is more reliable than the Page.Collection Name value because repositories sometimes change collection names. However, you may also use the Page.Collection Name to filter Search Targets if you desire.

For example, to include a Search Target only if the current page is part of Ancestry's "1930 United States Federal Census" collection using Page.Collection Name:

<[?:Page.Collection Name=1930 United States Federal Census]
# Construct URL here
>

Combining Filter Terms

To combine filters to determine if a Search Target link should appear on the current page, add as many Value tests as necessary to the outer conditional expression. It's best to put the most restrictive filter expressions first.

For example, to require that the current page has values in the qf.Givenname and qf.Surname fields, and to also require that the current page is on Find a Grave:

<[?:Page.ServiceName=Find a Grave][??:qf.GivenName:qf.Surname]
# Construct URL here
>

The Page.ServiceName filter is first because it is more restrictive than the Field values filter: many, many pages will have GivenName and Surname values, but only a small subset of them will be on Find a Grave.

Generic Service

Many pages fall under the Generic Service. Use the Page.Collection ID, Page.HostName, or Page.URL values to omit Search Target links unless they reside on the pages where you want them to appear.

Fields

To simplify URL Templates, ORA attempts to find Fields that are useful in search URLs and provides access to those fields via standardized names. ORA assigns the "qf." prefix to the fields and they are only available in the URL Template of a Search Target definition. ORA recognizes many different Field name variations, but it's impossible for ORA to recognize all possible variations and you may have to allow for field names that are specific to a particular collection.

For example, [qf.Surname] in a URL Template will produce the value of the best surname field that ORA finds, and that field may have been named "Surname", "Last Name", or other variations, and ORA may have extracted the value from a field that contains both given name and surname.

When possible, use the Field names listed below when authoring URL Templates to allow your Search Target to apply to most repositories and collections.

If ORA does not standardize the Field value you need, use the collection-specific Field name. If the collection includes a common value but using an uncommon Field name, consider adding a Text Template to make an alias of the Field.

When including URL parameters in the output of the URL Template, you should use the urlParameter transform.

&surname=[qf.Surname:urlParameter]

Query Fields List

The table below shows the Fields ORA creates. They all have a "qf." prefix and are only available to URL Templates.

Date Fields

When ORA finds a date of interest (birth, marriage, death, or burial), it creates a Field for the year extracted from that date. So, for example, if ORA finds a Field named "Birth Date" on the current page, it extracts the year from that Field and creates the query field "qf.Birth Year". ORA also creates other Fields based on the value of the source Field.

The Search Target date Fields include birth, marriage, death, and burial. For each of those events, the possible date fields are:

GeoCoordinates

When ORA finds latitude and longitude values in either a single Field or split across two Fields, it creates the qf.Latitude and qf.Longitude Fields. These fields are intended for use with mapping service links.

The values must be in decimal degrees format. ORA ignores values in other formats.

Geocoordinates are not common in genealogy data with the exception of burial / gravestone collections.

Host Name Fields

At the time of ths writing, two ORA services use multiple domains, Ancestry and Findmypast. To enable URL Templates to refer to the domain associated with your last login, ORA provides the following special Query Fields.

Text Templates

If records in a collection do not use one of the Field names that ORA detects, you can add a Text Template to the collection where the Heading is the name part of the associated Query Fields name.

For example, if the collection has a field named "Subject" which is the person's name, you can add a Text Template as follows to give ORA the hint it needs:

• Heading: Name
• Template: [Subject]

Fields created by Text Templates are given precedence over other Fields when ORA is searching for Query Fields.

Query Fields in the Console Log

When editing or testing URL Templates, you may find it useful to see which Query Fields ORA found while creating the OraPanel. ORA writes a Query Fields summary in the browser's Console Log. This summary provides a list of the Query Fields ORA found on the current page, their values, and the source fields from which those values were copied. The current page is where ORA draws the OraPanel with Search Links.

To review the Query Fields summary, open the Developer Tools window and switch to the Console tab if it is not the current tab or view. The Query Fields summary should be near the bottom of the Console output, but you may have to scroll up.

In the Firefox, Chrome, and Edge, and most other browsers, you open the Developer Tools window by pressing F12. Opera uses a menu command, Menu > Developer > Developer Tools.

The Query Fields summary will be similar to the list shown below on the right.

The Developer Tools panel may open in its own window, or in the same window as the current page. You may close the Developer Tools panel using an "X" in the upper-right corner of the panel. The details vary by browser. In browsers that open the Developer Tools panel with F12, you may also close it with F12.

Template Tracing

If the Trace checkbox is checked, ORA will include a trace of the evaluation of the template in the Console Log. The trace shows the logic and true/false results processed during the template evaluation. The entries are indented to show the nesting of conditional expressions. If your URL Template does not produce the output you expect, the trace may help you determine why.

See the instructions above for opening the browser's Console Log.

Predefined Targets

ORA includes several predefined Search Targets. They are disabled by default. You may edit the Search Targets to enable any that you wish to use.

ORA copies predefined Search Targets from its private list to your list of Search Targets. Usually, you can ignore the distinction between your copy of a predefined Search Target and ORA's private copy.

Predefined Search Targets are designed to work from any page where ORA draws an OraPanel and where the minimum Fields required by the URL Templates are present. For example, you can be viewing a page that ORA processes with its Generic Service and click a link that searches Ancestry or some other repository.

ORA assigns a version number to predefined Search Targets. ORA shows the version number beneath the Search Target Name.

Predefined Target Updates

If an ORA update includes a change to a predefined Search Target, ORA will update your copy of the Search Target to keep your copy synchronized with the most-recent version provided by ORA. ORA will only update the URL Template. It will not change the Enabled, Trace, or Link Text properties.

If you edit the URL Template of a predefined Search Target, ORA will no longer consider the Search Target a copy of the predefined Search Target. That means ORA will not keep the Search Target's URL Template synchronized with the predefined Search Target.

Put another way, if you edit the URL Template, that breaks the connection between your Search Target and the predefined Search Target. However, you may edit the Enabled, Trace, or Link Text properties without breaking the connection.

If there is no predefined version number visible when the Search Target appears on the Edit Search Targets panel, the Search Target is not a copy of a predefined Seach Target. If the Search Target was predefined, the link has been broken by editing the URL Template.

Restore a Predefined Target

If you edited the URL Template of a predefined Search Target and you want to restore the link between your Search Target and the predefined Search Target:

1. Click the ORA icon to open the OraSettings page and open the Search Targets panel via the [Search Targets...] button.
2. Choose the Search Target you want to restore.
3. Delete your Search Target using the [Delete This Search Target] button on the Search Targets panel.
4. Close all your browser windows.
5. Start your browser again.
6. Click the ORA icon to open the OraSettings page and open the Search Targets panel via the [Search Targets...] button.

After following the procedure above, you will see the predefined Search Target in the list of Search Targets and it will have a predefined version number.

Predefined Targets List

Here are the Search Targets provided with ORA showing names, abbreviations, and the current version number:

The Search Targets for specifc collections are intended as examples.