FlexDoc/Javadoc - JavadocClassic - Templates
Main Templates
Main templates are those that can be specified for interpretation directly either with -template option on the Javadoc command line or in the Doclet GUI. Each main template effectively represents a separate documentation generator.See Also: FlexDoc/Javadoc | Features | How It Works | Actual Doclets as Template Sets
FramedDoc.tpl
This is a main template to generate framed HTML Java API documentation identical to the standard JavaDoc.
It works by calling all other templates that generate various documentation pages/files as well as it produces
'index.html'
– the frameset file to display the documentation.
See also: FramedDoc.tpl | Template Interpretation.
The following screenshot shows the template's root section block, where calling of all subtemplates happens (click to enlarge):
Here is a sample documentation generated with this template (click a screenshot to view the real HTML):
Template Location:
-
{flexdoc-javadoc}/templates/
classic/FramedDoc.tpl
Controlled By Parameters:
Called From:
Calls:
- init.tpl, overview.tpl, overview-frame.tpl, module.tpl, module-frame.tpl, package.tpl, package-frame.tpl, package-summary.tpl, package-use.tpl, class.tpl, class-summary.tpl, class-use.tpl, class-tree.tpl, allclasses-frame.tpl, index-all.tpl, index-letter.tpl, deprecated-list.tpl, constant-values.tpl, serialized-form.tpl, help-doc.tpl, element-list.tpl
Template Interpretation
The FramedDoc.tpl template is interpreted as follows:-
First, the “Template Init Expression” specified in the template properties is processed:
- That, in turn, invokes the execution of “Init” stock-section: This stock-section generates no output. Rather, it calls from itself the init.tpl template to create element maps. Element maps are essentially hash-maps, which help to resolve very complicated queries. They are used in almost all other templates (including even init.tpl itself) and are critical for the working of the whole template set.
-
Further, the template's root section block is processed:
It does the following:
- overview.tpl template is called to generate the Overview page for the whole documentation.
- overview-frame.tpl template is called to generate the upper-left frame navigation page.
- allclasses-frame.tpl template is called to generate a navigation page with the list of all documented classes.
-
All included modules are iterated.
For each module:
- module.tpl template generates the Module Documentation page.
- module-frame.tpl template generates the module navigation page.
-
All included packages are iterated. For each package:
- package.tpl template generates the Package Documentation page.
- package-frame.tpl template generates the package navigation page.
- class-tree.tpl template generates the Class/Interface Hierarchy page for the package.
- class-use.tpl template generates the Package Usage page.
-
All classes in the package that are to be documented are iterated. For each class:
- class.tpl template generates the Class Documentation page.
- class-use.tpl template generates the Class Usage page.
- class-tree.tpl template is called to generate the Class/Interface Hierarchy page for all packages.
- deprecated-list.tpl template generates the Deprecated API page.
- constant-values.tpl template generates the Constant Field Values page.
- serialized-form.tpl template generates the Serialized Form page.
- class-summary.tpl template generates the All Classes index.
- package-summary.tpl template generates the All Packages index.
-
The documentation Index is generated:
- First, a temporary “index” element map is created, which is essential for building of the index (see the “generate index” Folder Section | Properties | Processing | Init Expression tab)
- If index splitting was specified, all relevant index letters are iterated and the index-letter.tpl template is called for each to generate a separate file.
- Otherwise, the index-all.tpl template is called to generate the single index page.
- help-doc.tpl template generates the documentation Help page.
- element-list.tpl template generates the Package List file.
Generation of Frameset
The HTML frameset file (normally named'index.html'
)
starts the whole documentation to display particular HTML documents in three frame windows:
The frameset file is generated according to the definition specified in the “Output File | Frameset Structure” tab of the FramedDoc.tpl properties dialog:
The expression specified in the “Source Expression” field (on the right panel) should return the pathname (or URL) of a document to be initially loaded in the given frame.
However, the initial content of the detail frame may be overridden dynamically by the Javascript, which is inserted
in index.html
according the “HTML Head Expression”:
This particular Javascript obtains a URL parameter (specified after '?' in the initial URL) passed to
index.html
.
If the parameter exists, the detail frame will be reloaded according to the new URL found in the parameter.
That allows you to construct URLs like this one:
which will open the frameset documentation directly on a specified page.
SingleDoc.tpl
This main template generates single-file JavaDoc (both RTF and HTML). It works similar to FramedDoc.tpl, however, now all subtemplates called from it generate sections of the same single output file. Here are a few screenshots of such an output: Template Location:-
{flexdoc-javadoc}/templates/
classic/SingleDoc.tpl
Controlled By Parameters:
Called From:
Calls:
- init.tpl, title-page.tpl, TOC.tpl, overview.tpl, module.tpl, package.tpl, class.tpl, about.tpl demo-incomplete.tpl
Using styles to render CSS classes
As the HTML markup in Java doc-comments becomes more sophisticated, now the JDK API source code uses CSS classes to style various things. Among them, the following three kinds of tables: RTF), to achieve a similar result in those formats, FlexDoc/Javadoc can render some HTML elements and CSS classes using template formatting styles.SingleDoc.tpl main template includes the definitions of such rendering for all the three user table styles. Here is how it is done for striped tables:
-
An
HTML Rendering Rule is defined to render <table>
elements with'striped'
CSS class: -
The formatting styles to render striped tables. The 2nd and 3rd screenshots is the style for striped rows.
- Now, the same striped table can be rendered in RTF as well:
Template Parameters
This section explains what template parameters are for, how they are defined and used in templates. For the details about particular parameters provided by the JavadocClassic template set, please see: JavadocClassic | Parameters.
The parameters defined in main templates are used:- To control the execution of the entire template application
- To pass certain data directly from the command line to be inserted in the generated output (e.g. “Window Title” parameter)
Additionally, template parameters are extensively used internally, across the whole template set:
- To pass data between templates (i.e. subtemplates)
- As shortcuts to the values that are calculated only once per a template call and further frequently used both within that template and the subtemplates called from it (see also Default Value Expression and Auto-Passed properties).
How parameters are defined
To be accessed within a template, any template parameters must be defined in the “Parameters” tab of the template properties:
Definition of single parameter
A template parameter is defined with the series of properties:Here are the descriptions of most important template parameter properties:
Property | Description |
---|---|
Name |
Specify the parameter internal name.
This name uniquely identifies the parameter within the template. It is also used to automatically pass the parameter value to equally named parameters in called subtemplates (see Auto-Passed property). This very name must be specified with a -p option, when you want to pass the parameter value from the command line. |
Title |
Specify the parameter title, which it will appear in the Parameter Inspector.
The title is in effect a very short description of the parameters. |
Description |
Specify the parameter full description that will be shown in the bottom panel
of the Parameter Inspector when the parameter is selected.
The description may include some HTML markup.
It may also include |
Enabling Condition |
Specify a boolean FlexQuery that determines whether the parameter is enabled.
When that query is specified it is calculated dynamically each time the template starts.
When the query returns The disabling of the parameter indicates that according to all other settings this parameter is not expected to be actually used during the processing, that is its value is irrelevant. The disabled parameter won't accept any external value and, instead, is assigned only with its default value (see Default Value property). In the Parameter Inspector, the enabling condition is evaluates also each time any other parameters changed. The disabled parameters are shown with the disable color and cannot be edited. |
Group |
Specify whether the parameter is the head of a parameter group.
The group constitutes a node of the parameter tree, in which the parameters are organized in the Parameter Inspector. The group may have additional properties, such as its own enabling condition, which may disable all the parameters within the group. A parameter marked as a group may still serve as the actual parameter (that is, to have its own value) or may be just the group heading (with the void value). |
Type | Specify the data type of the parameter value. |
List |
Specify whether this is a multi-valued parameter.
See Also: Documentation | FlexDoc Doclet | Handling Template Parameters | Multi-valued (list) parameters |
Default Value | Specify the default value of the parameter. |
Specify the FlexQuery to calculate the default value of the parameter.
When specified, the query provides the default value of the parameter. (It will override any default value specified statically in the Default Value property). The default value query is calculated dynamically (after the template processing has been started and the parameter default value is requested the first time). In the Parameter Inspector, the Default Value Expression is evaluated also each time when any other parameters changed, to refresh the value of the parameter when it is set as default.
In JavadocClassic template set, it is supported the mapping of some
Standard Doclet options
to the default values of corresponding template parameters.
This is implemented exactly here in the Default Value Expression property with the use of |
|
Fixed |
Indicates that the parameter value is fixed.
A fixed parameter is assigned only with its default value specified in the template. However, unlike disabled parameters, it is expected to be used and won't be shown in the Parameter Inspector as disabled. This setting is needed because the same parameter (used across the template set) may be editable in one main template and fixed in other, because the only constant value makes sense for it. (For example, such is “Generate | Overview” parameter.) |
Auto-Passed |
Indicates that by default the value of this parameter will be automatically passed (propagated) to all subtemplates
called from the given one. (This will happen even when some of the intermediately called subtemplates
do not define this parameter).
This property is
This parameter auto-passing is widely used in FlexDoc templates! For instance, many internal parameters are defined only to represent certain values calculated dynamically once per a template call. Further, such a parameter is automatically passed to other subtemplates, where the same value may be needed again. This allows avoiding the calculation of the same value many times, thereby improving the performance of the whole template application. |
Hidden |
Indicates that the parameter must be invisible in the Parameter Inspector.
This is typically needed for internal parameters defined within main templates. (See the note to Auto-Passed property for why such parameters are needed.) |
Parameter Inspector
By the parameter definitions specified in a main template the Parameter Inspector dialog is constructed. It is invoked from the Doclet GUI to allow specifying all the parameters interactively: See Also: Documentation | FlexDoc Doclet | Handling Template ParametersHow parameters are used in templates
Template parameters are used in FlexQuery expressions specified in templates to control various properties of template components (such as enabling conditions and etc.)
The only way to access template parameters is using one of the Template Parameters functions.
The getParam()
function is main of them.
You can find all those functions (along with their descriptions) the Expression Assistant dialog invoked from the Template Designer | Help menu as well as from any of the FlexQuery Expression Editors (by clicking the "?" button).