This function allows you to find a hypertarget matching the specified set of keys that may exist anywhere in the whole generated documentation.

This function returns a correct result only during the generation phase. During the estimation phase, it always returns null.

To know exactly which phase currently is, use the generator property: output.estimationPhase

Note: Be careful when using this function (especially, within enabling conditions of template components and filtering expressions)! Incorrect use may cause the following side effects:

  • The hypertargets defined within the affected components may be generated incorrectly (therefore, hyperlinks targeted to them may never be generated).
  • If such components include Element Iterators or call Element Iterators from themselves, the generation progress bar may be distorted (which may result in a premature filling it up or, vice versa, filling only part of it when the generation is actually about to finish).

Parameters:

targetKey

Specify a single key. It is the same as calling: findHyperTarget (Array(targetKey))
targetKeys
Specify a set of keys (in the form of Array) by which the hypertarget is to be searched for.

Each hypertarget is identified by a set of keys, which may be objects of any type. The keys are generated automatically for each hypertarget during the estimation phase by the FlexQuery expressions specified for each key in the hypertarget definition (within the properties of a template component).

A hypertarget is matched to the specified keys by matching those keys to the hypertarget's keys.

Any two individual keys are matched simply by comparing them using the Java method: Object.equals().

However, matching two sets of keys is not so simple. This is controlled by the next parameters.

keyMatching
Specify how a hypertarget is matched to the specified set of keys.

The following table shows all possible values of this parameter, the meaning of each value and the sign how it is represented in the Template Designer's Document Hyperlink Dialog (where the hyperlink's keys have the same usage as in this function).

Value Meaning Sign
"sube" The specified keys must be a subset of or equal to the hypertarget's keys.

That means that each of the specified targetKeys must have a separate equal pair among the hypertarget's keys. If any two specified keys are equal, they should match to different hypertarget's keys (e.g. if the specified keys include {"one", "one"}, the matching hypertarget must also contain two keys {"one", "one"}).

Note: This value is used by default when no keyMatching is specified.

"equiv" The specified keys must be equal to the hypertarget's keys.

This is the same as in case of "sube", however, in addition, the hypertarget must have no other keys besides those matching to the specified ones.

"supe" The specified keys must be a superset of or equal to the hypertarget's keys.

This condition is opposite to "sube". Each of the hypertarget's keys must have a separate equal pair among the specified targetKeys. If any two hypertarget's keys are equal, they should match to different specified keys (e.g. if the hypertarget's keys include {"one", "one"}, the specified keys must also contain {"one", "one"}).

Using requiredKeyCount parameter (see below), you can also specify which targetKeys must be matched in any case.

requiredKeyCount
This parameter is used only when keyMatching == "supe".

It allows you to set which of the specified keys must be matched in any case. Those will be the first 'requiredKeyCount' elements of the targetKeys array.

The minimal possible value of this parameter is 1 (that is, the first key in the array must always be matched). This is also its default value. If the actual passed value is < 1, it will be replaced with 1.

The maximal possible value is the number of specified targetKeys (i.e. the array size). So the passed value will be corrected accordingly.

Note: In the case when keyMatching != "supe", this parameter is ignored.

Returns:

A GOMHyperTarget object that describes the hypertarget or null if no hypertarget can be found (as well as during the estimation phase).

If several hypertargets exist that equally match to the specified parameters, the returned one is selected according the following rules (listed in priority order):

  1. The hypertarget belongs to the same output document as the one being generated by this template.
  2. In case of keyMatching == "sube", it has the minimal number of keys.

    In case of keyMatching == "supe", it has the maximal number of keys.

  3. It was generated/added the first.
See Also:
Array(), GOMHyperTarget type, GOMOutputInfo.estimationPhase