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:
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:
|
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 specifiedtargetKeys
. 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 whichtargetKeys
must be matched in any case.⊇
requiredKeyCount
This parameter is used only whenkeyMatching == "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 thetargetKeys
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:
ASee Also:GOMHyperTarget
object that describes the hypertarget ornull
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):
- The hypertarget belongs to the same output document as the one being generated by this template.
- In case of
keyMatching == "sube"
, it has the minimal number of keys.In case of
keyMatching == "supe"
, it has the maximal number of keys.- It was generated/added the first.
Array()
,GOMHyperTarget
type,GOMOutputInfo.estimationPhase