Returns the absolute path name of the first document file that was (or will be) produced by the specified template (or a list of templates).

If such a document does not exist (i.e. neither of the specified templates will ever produce any document), the function returns an empty string.

It may be especially helpful, when you need to setup the content of a frameset document generated by a frameset template (see Output File | Frameset Structure tab in the frameset template's properties dialog). Using this function, you can specify which generated documents should be initially loaded into particular frame windows.

This function returns a correct result only during the generation phase (even though the interested document may not have been physically generated yet). During the estimation phase, the function will always return an empty string.

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

Parameter:

templateNames

Specifies one or several template names (separated with ';').

Each specified template name should be the name of the template file (i.e. the last name in the file pathname's name sequence) with or without ".tpl" extension. The letter case of the specified template name will be ignored.

The function returns the pathname of the document that has been created the first among those generated by one of the specified templates during the whole generation session.

See Also:

documentByHyperTarget(), 'output.estimationPhase' generator variable.

Example 1

The following call will return the pathname of the document file which is generated the first either by 'overview-summary.tpl' template or 'class.tpl' template:

documentByTemplate("overview-summary;class")
Let's see where it is needed. Suppose, we construct a set of templates which can generated a framed documentation by a number of classes or a single class. Our documentation may contain detailed documents for each class (generated by class.tpl) plus a single overview summary document for all classes (generated by overview-summary.tpl).

Now, we want our documentation to display the summary document only when there are more than one documented classes (otherwise, the summary will contain just one item and will be redundant). If only one class documented, we would like to see its details immediately.

To achieve this, we construct/call the overview-summary.tpl in such a way that it will never produce any output when less than 2 classes are processed. Then, the documentByTemplate() call specified above would setup the main frame window as needed.

Example 2

Suppose, the template 'all-diagram-index.tpl' is designed to produce a single document with an index of all diagrams in our documentation. We have constructed that template so that it never produces anything if there are no diagrams to be documented.

Now, in some other document, we would like to have a link to that diagram index, so we could invoke the index when we click on that link. However, in addition to that, we do not want the text of that link to appear when there is no index document!

Here is how this problem could be solved. We just need to specify in the component generating the link the following Enabling Condition:

documentByTemplate("all-diagram-index") != ""