FlexDoc/Javadoc - JavadocClassic - Templates
- Main Templates
- Template Parameters
- Initialization Subtemplates
- Basic Content Subtemplates
- Cross-Reference Page Subtemplates
- Support File Subtemplates
- Section Subtemplates
- Fragment Subtemplates
1. 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, package.tpl, package-use.tpl, package-frame.tpl, package-list.tpl, class.tpl, class-summary.tpl, class-use.tpl, class-tree.tpl, index-all.tpl, index-letter.tpl, deprecated-list.tpl, constant-values.tpl, serialized-form.tpl, help-doc.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.
-
All packages that contain classes to document are iterated.
For each package:- package.tpl template generates the Package Overview 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 Details page.
- class-use.tpl template generates the Class Usage page.
- class-tree.tpl template is called to generate the Class/Interface Hierarchy page for the whole documentation.
-
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.
- 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.
- help-doc.tpl template generates the documentation Help page.
- package-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:
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”:
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:
2. 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:
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).
3. Initialization Subtemplates
init.tpl
This template produces no output. Instead, it is called only once from either SingleDoc.tpl or FramedDoc.tpl main templates before any other processing starts. The template's job is to create element maps.
Element maps are essentially hash-maps. They map keys to sets of Doclet DSM's elements
(which represent the objects operated by
Doclet API).
Most commonly, as the keys are used the element unique identifiers (see GOMElement.id
),
which means that some sets of elements are mapped to other sets of elements.
This can be used to quickly find by certain elements some other elements according to specific functional relations.
That makes possible resolving very complicated queries and provides capabilities for sophisticated data mining.
Here's an example. From the Java source code (via the Doclet API), we can easily obtain the following things:
- The list of all classes in the project
- For a given class – the list of all interfaces it directly implements
- For a given class – its superclass
- For a given interface – the list of all interfaces it directly extends
Using an element map, it is possible. The element map is created as the following:
- All classes in the project are iterated.
- For each class (according to the items 2-4 in the list above), we find all interfaces that class directly or indirectly implements.
- For each found interface and the class implementing it, we add a mapping so that the interface's element ID becomes a key and the element representing the class is put in the map by that key.
putElementByKeys()
puts in the element map
"all-known-implementing-classes"
a single element representing a class, however,
by several keys at once. Those keys are the unique identifiers of all interfaces that the class
directly/indirectly implements. The list of interfaces is obtained using
Location Rules.
The function getElementIds()
converts the enumeration of elements
(representing the found interfaces) into an array of their unique IDs.
The "all-known-implementing-classes"
element map is further used
within the class.tpl template to generate that very list for a particular interface.
You can find a lot more information about Element Maps, Location Rules and the functions to work with them at: Template Designer | Help | Assistant... | Functions | By Category | “Elements / Attributes” | “Element Maps” and “Location Paths & Rules”.
Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/init.tpl
Called From:
4. Basic Content Subtemplates
overview.tpl
This template generates the Overview page/section (an equivalent of the overview-summary.html file generated by the Standard Doclet). The next screenshots show both an HTML page and an RTF section produced by this template (click to see in full size):
![]() |
![]() |
Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/overview.tpl
Controlled By Parameter Group:
Called From:
Calls:
package.tpl
This template generates a Package Overview page/section for every Java package being documented (an equivalent of the package-summary.html file generated by the Standard Doclet), which includes package description, tags and summary tables of contained classes. On the following screenshots you can see both an HTML page and an RTF section generated by this template for the same package (click the screenshot to see in full size):
![]() |
![]() |
Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/package.tpl
Called From:
Calls:
class.tpl
This template generates a Class Details page/section for a class/interface/enum or an annotation type.The class details may include the class description, various reference lists about it, as well as the details of all documented members of that class (except nested classes). This provides the bulk of the whole Java API documentation.
It is the most complex template, whose only little part is visible on this screenshot:
On the following screenshots you can see both an HTML page and an RTF section generated by this template for the same class (click to see in full size):
![]() |
![]() |
Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/class.tpl
Called From:
Calls:
5. Cross-Reference Page Subtemplates
class-summary.tpl
This template generates the «All Class Summary» page ('all-classes-summary.html'
file),
which is loaded when clicking on «All Classes» item in the navigation bar
in framed HTML documentation.
That page is is a replacement of the standard 'allclasses-noframe.html'
file (generated by the
Standard Doclet),
which is intended to view in NO FRAMES mode.
Unlike the standard one, All Class Summary page shows not just the list of pure class names but rather a summary of all classes with the first sentence description of each class. It is also available in the FRAMES mode.
Here is the template's screenshot:
On the following screenshot you can see a sample “All Classes Summary” page generated by this template (click to see the real HTML): Additionlly, this template is used also as a section subtemplate to generate class summaries included in both the general Overview and Package Overviews.Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/class-summary.tpl
- Generate | Cross-Reference Pages | All Classes Summary
- Generate | Overview | All Classes Summary
- Generate | Package Overviews | Class Summary
Called From:
Calls:
package-use.tpl
This template generates a «Use» page for each documented package. The page describes which packages and classes use any API of the given package. The next screenshots show an HTML page generated by this template (click to see the real HTML):Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/package-use.tpl
Called From:
Calls:
class-use.tpl
This template generates a «Use» page for each documented class. The page describes which packages, classes, methods, constructors and fields use any API of the given class. The next screenshots show an HTML page generated by this template (click to see the real HTML):Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/class-use.tpl
Called From:
Calls:
class-tree.tpl
This template generates class/interface hierarchy pages (all'overview-tree.html'
and 'package-tree.html'
files).
These are the pages you reach using the «Tree» button in the navigation bar.
The next screenshots show an HTML page generated by this template (click to see the real HTML):
Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/class-tree.tpl
Called From:
Calls:
deprecated-list.tpl
This template generates the deprecated API page ('deprecated-list.html'
file), which contains the list of deprecated APIs,
and the «Deprecated» link in the navigation bar to that page.
The next screenshots show an HTML page generated by this template (click to see the real HTML):
Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/deprecated-list.tpl
Called From:
Calls:
index-all.tpl
This template generates a single index page ('index-all.html'
file).
It is used when no splitting of the index into multiple files has been specified (the parameter
“Generate | Cross-Reference Pages | Index | Split”
is false
).
Here is the template's screenshot:
It is a simple template. Actually it does little more but calls the index-letter.tpl template to generate the index section for each particular letter.Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/index-all.tpl
Called From:
Calls:
index-letter.tpl
This template generates for a particular letter either a section of the whole index file
(i.e. 'index-all.html'
generated by index-all.tpl) or
a corresponding separate index page ('index-files/index-n.html'
file).
In which mode the template is run depends on the setting of the
“Generate | Cross-Reference Pages | Index | Split”
parameter.
The letter, for which the particular index section/page will be generated, is passed to the template via the
context element.
The following screenshots show an HTML page generated by this template (click to see the real HTML):
Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/index-letter.tpl
Called From:
Calls:
serialized-form.tpl
This template generates the serialized form page, which provides information about serializable and externalizable classes. The next screenshots show an HTML page generated by this template (click to see the real HTML):Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/serialized-form.tpl
Called From:
Calls:
constant-values.tpl
This template generates the constant field values page ('constant-values.html'
file),
which lists the static final fields and their values.
The next screenshots show an HTML page generated by this template (click to see the real HTML):
Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/constant-values.tpl
Called From:
Calls:
6. Support File Subtemplates
help-doc.tpl
This template generates the Help page. This is the page you reach using the «Help» button in the navigation bar. Here is a sample help page generated by this template (click on the screenshot to see the real HTML):Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/help-doc.tpl
Called From:
Calls:
overview-frame.tpl
This template generates the primary navigation page, which includes the lists all packages and other primary links. It is used in the upper-left "overview" frame. Sample output (click on the screenshot to see HTML):Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/overview-frame.tpl
Called From:
all-classes-frame.tpl
This template generates a navigation page with the list of all documented classes. It is loaded in the lower-left "summary" frame. Sample output (click on the screenshot to see HTML):Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/all-classes-frame.tpl
Called From:
package-frame.tpl
This template generates a separate navigation page for each documented package, which is loaded into the lower-left "summary" frame on clicking on the corresponding package in the "overview" frame.The page contains the link to the package overview and the list of all documented classes in that package along with the links to the corresponding class details. The classes are grouped by their functional roles (such as interfaces, ordinary classes, exceptions etc.)
Sample output (click on to see the HTML):Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/package-frame.tpl
Called From:
package-list.tpl
This template generates a Package List file, which is a plain-text file that lists the names of all documented packages (or those containing the documented classes).
This file is used by Javadoc to generate hyperlinks to an external Java API documentation, whose location is specified with
-link
or
-linkoffline
options on the Javadoc command line.
The package-list
file generated by this template allows linking any other Java API documentation (including one generated
by the Standard Doclet)
to the framed HTML documentation produced with FramedDoc.tpl template.
(Note: The opposite is possible as well, as FlexDoc Doclet also supports
-link
and
-linkoffline
options.)
Here is the template's screenshot:
It is a very simple template, which consists of the only Element Iterator section that produces the package list. Here is how the iteration scope is specified:
com.sun.javadoc.RootDoc
instance received by the doclet. (The repeating packages are eliminated from the result collection.)
When the parameter
“Filter Classes & Members | Suppress empty packages”
is true
, all packages that contain no documented classes must be deleted from the list too.
This is done by the following filter expression:
On the following screenshot you can see a package-list
file produced by this template (it is included in the
framed HTML demo documentation):
Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/package-list.tpl
Called From:
7. Section Subtemplates
package-summary.tpl
This template is used only to generate package summary included in the general Overview (produced overview.tpl template). Of couse, the same could be equally done with a stock-section specified within overview.tpl itself. So, why is there a separate template?Because, when grouping of packages is specified (see “Generate | Overview | Package Summary | Package Groups” parameter), the Overview may include several package summary tables, each for a particular package group.
Every such a table will have its own heading (the group heading) and, in the case of RTF documentation, when the table is broken between several pages, that heading would be interesting to have repeated on each page, e.g. as a part of the page heading. But this is possible to program only when the package summary table is generated by a separate template!
Controlled By Parameter:
Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/package-summary.tpl
Called From:
Calls:
title-page.tpl
This template generates the Title Page (which will be the front page of the RTF documentation). By default, this template just prints (with a large font and centered) the text specified in the “Documentation Title” parameter. That text may also include some HTML markup, which will be recognized and rendered.However, you may easily edit title-page.tpl template and add/change whatever you need (e.g. you can add you company logo or other images). So, the real purpose of this template is to be a placeholder for any customer-specific information!
Sample output:
Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/title-page.tpl
Controlled By Parameter:
Called From:
TOC.tpl
This template generates the Table Of Contents of the documentation. Table Of Contents is available in both RTF documentation and single file HTML (generated with SingleDoc.tpl main template).In case of RTF, it is not actually generated. Rather, a special RTF “{TOC}” field is inserted. The real Table Of Contents is generated by MS Word according to that field and style/level paragraph settings specified on the headings of some documentation section. This produces the Table Of Contents with the following structure:
-
Overview....................... Package Summary............. All Classes Summary......... package1....................... class1...................... class2...................... ... package2....................... ... ...
On the left screenshot you can see a sample Table Of Contents produced with this template (after updating/building it in MS Word); on the right is what this template generates in case of HTML:
![]() |
![]() |
Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/TOC.tpl
Controlled By Parameter:
Called From:
8. Fragment Subtemplates
navbar.tpl
This template generates all navigation bars found the framed HTML documentation.Each navigation bar for a particular page type is generated by the corresponding Area Section visible on the template screenshot (click to see in full size):
The necessary section is activated (enabled) according to the value of the template parameter'$type'
passed internally to this template from the calling one, which generates the whole page.
The expanded Area Section below is specified to generate navigation bars for class documentation pages (which are generated by the class.tpl template):
Here is how such a navigation bar looks: On the next screenshot you can see how another section is programmed to generate navigation bars for index pages (generated by the index-all.tpl / index-letter.tpl templates): Below is an example of its output: The letter bar at the bottom is generated separately by the “Letter Bar” stock-section:Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/navbar.tpl
Controlled By Parameter Group:
Called From:
- class-summary.tpl, class-tree.tpl, class-use.tpl, class.tpl, constant-values.tpl, deprecated-list.tpl, help-doc.tpl, index-all.tpl, index-letter.tpl, overview.tpl, package-use.tpl, package.tpl, serialized-form.tpl
navbar-bottom.tpl
Generates overall footer of each detail page in framed HTML documentation including footer navigation bar, bottom text and «About» section.Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/navbar-bottom.tpl
Called From:
- class-summary.tpl, class-tree.tpl, class-use.tpl, class.tpl, constant-values.tpl, deprecated-list.tpl, help-doc.tpl, index-all.tpl, index-letter.tpl, overview.tpl, package-use.tpl, package.tpl, serialized-form.tpl
Calls:
annotations.tpl
This template generates the list of annotations (along with all related hyperlinks) of a package, class, member or constructor/method parameter, like shown on the following screenshots (annotations are highlited with red boxes):
This particular stock-section reproduces a single annotation (as it would be specified in the Java code):
Another stock-section that reproduces the annotation's element value:Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/annotations.tpl
Called From:
see-link.tpl
This template processes a user-defined cross-reference to related documentation.
When Javadoc parses Java comments, it creates by each
@see
or
{@link}
tag a
com.sun.javadoc.SeeTag
object.
Those objects should be processed by a doclet into cross-reference hyperlinks (to the location both within the generated documentation and external ones).
The see-link.tpl template does just this. The following screenshots show its root section block both in collapsed and expanded form:
Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/see-link.tpl
Called From:
inline-tag.tpl
This template processes most of the inline tags. The inline tags are those looking like:-
{@tag ...}
In fact, Javadoc does not fully process the inline tags by itself. Rather, it only parses them and provides for further processing to a doclet via Doclet API. It is the doclet, who has to replace the inline tags with the useful values according to their meanings.
That is exactly what this template does (as part of the doclet). Here is how it looks when open in the Template Designer (click to enlarge):
Each section catches and processes a specific inline tag. On the following screenshot, those sections are shown when expanded: If you need to program processing of your own inline tags, the inline-tag.tpl template is where you can do this.
The {@inheritDoc}
tag that can be used in a method comments requires a very special processing, which is programmed locally in class.tpl template,
where a method's documentation is also generated.
Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/inline-tag.tpl
Called From:
- class-summary.tpl, class-use.tpl, class.tpl, deprecated-list.tpl, index-letter.tpl, overview.tpl, package-summary.tpl, package-use.tpl, package.tpl, serialized-form.tpl
about.tpl
This template adds the About section at the bottom of each separate output document. It displays the information about FlexDoc/Javadoc product along with the hyperlinks to this website.Template Location:
-
{flexdoc-javadoc}/templates/
classic/lib/about.tpl
Controlled By Parameter:
Called From: