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:
{docflex-javadoc}/templates/JavadocPro/FramedDoc.tpl
Controlled By Parameters:
See: DocFlex/Javadoc | JavadocPro | Parameters | Parameter Tree
Called From:
generator (doclet)
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
'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:
http://www.filigris.com/products/docflex_javadoc/templates/JavadocPro/demo/html/index.html?java/lang/StackOverflowError.htmlwhich will open the frameset documentation directly on a specified page.
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:![]()
{docflex-javadoc}/templates/JavadocPro/PlainDoc.tpl
Controlled By Parameters:
See: DocFlex/Javadoc | JavadocPro | Parameters | Parameter Tree
Called From:
generator (doclet)
Calls:
init.tpl, title-page.tpl, TOC.tpl, overview.tpl, package.tpl, class.tpl, about.tpl
The parameters defined in main templates are used:
Additionally, template parameters are extensively used internally, across the whole template set:
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). Note: 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. Note: 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 ${include <url>} macros, which are expanded dynamically
with the content of the external files referenced from them.
This makes possible to store the actual parameter descriptions (or parts of them) separately from
the templates.
|
|
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 false the parameter becomes disabled.
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 | DocFlex 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.
|
||
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 true by default. However, the auto-passing stops
|
|
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.) |
See Also: Documentation | DocFlex Doclet | Handling Template Parameters![]()
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).
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:
Using an element map, it is possible. The element map is created as the following:
On the screenshot above, the function![]()
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:
{docflex-javadoc}/templates/JavadocPro/lib/init.tpl
Called From:
FramedDoc.tpl, PlainDoc.tpl
The next screenshots show both an HTML page and an RTF section produced by this template (click to see in full size):![]()
Template Location:
{docflex-javadoc}/templates/JavadocPro/lib/overview.tpl
Controlled By Parameter Group:
Generate | Overview
Called From:
FramedDoc.tpl, PlainDoc.tpl
Calls:
navbar.tpl, package-summary.tpl, class-summary.tpl, inline-tag.tpl, see-link.tpl, about.tpl
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:
{docflex-javadoc}/templates/JavadocPro/lib/package.tpl
Controlled By Parameter Group:
Generate | Package Overviews
Called From:
FramedDoc.tpl, PlainDoc.tpl
Calls:
navbar.tpl, annotations.tpl, class-summary.tpl, inline-tag.tpl, see-link.tpl, about.tpl
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:
{docflex-javadoc}/templates/JavadocPro/lib/class.tpl
Controlled By Parameter Group:
Generate | Class Detail
Called From:
FramedDoc.tpl, PlainDoc.tpl
Calls:
navbar.tpl, annotations.tpl, inline-tag.tpl, see-link.tpl, about.tpl
'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:
{docflex-javadoc}/templates/JavadocPro/lib/class-summary.tpl
Controlled By Parameters:
Called From:
FramedDoc.tpl, overview.tpl, package.tpl
Calls:
navbar.tpl. inline-tag.tpl, about.tpl
The next screenshots show an HTML page generated by this template (click to see the real HTML):![]()
Template Location:
{docflex-javadoc}/templates/JavadocPro/lib/package-use.tpl
Controlled By Parameter:
Generate | Cross-Reference Pages | Use (Package/Class)
Called From:
FramedDoc.tpl
Calls:
navbar.tpl, inline-tag.tpl, about.tpl
The next screenshots show an HTML page generated by this template (click to see the real HTML):![]()
Template Location:
{docflex-javadoc}/templates/JavadocPro/lib/class-use.tpl
Controlled By Parameter:
Generate | Cross-Reference Pages | Use (Package/Class)
Called From:
FramedDoc.tpl
Calls:
navbar.tpl, inline-tag.tpl, about.tpl
'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:
{docflex-javadoc}/templates/JavadocPro/lib/class-tree.tpl
Controlled By Parameter:
Generate | Cross-Reference Pages | Tree (Class Hierarchy)
Called From:
FramedDoc.tpl
Calls:
navbar.tpl, about.tpl
'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:
{docflex-javadoc}/templates/JavadocPro/lib/deprecated-list.tpl
Controlled By Parameter:
Generate | Cross-Reference Pages | Deprecated List
Called From:
FramedDoc.tpl
Calls:
navbar.tpl, inline-tag.tpl, about.tpl
'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:
{docflex-javadoc}/templates/JavadocPro/lib/index-all.tpl
Controlled By Parameter Group:
Generate | Cross-Reference Pages | Index
Called From:
FramedDoc.tpl
Calls:
navbar.tpl, index-letter.tpl, about.tpl
'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:
{docflex-javadoc}/templates/JavadocPro/lib/index-letter.tpl
Controlled By Parameter Group:
Generate | Cross-Reference Pages | Index
Called From:
FramedDoc.tpl, index-all.tpl
Calls:
navbar.tpl, inline-tag.tpl, about.tpl
The next screenshots show an HTML page generated by this template (click to see the real HTML):![]()
Template Location:
{docflex-javadoc}/templates/JavadocPro/lib/serialized-form.tpl
Controlled By Parameter:
Generate | Cross-Reference Pages | Serialized Form
Called From:
FramedDoc.tpl
Calls:
navbar.tpl, annotations.tpl, inline-tag.tpl, see-link.tpl, about.tpl
'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:
{docflex-javadoc}/templates/JavadocPro/lib/constant-values.tpl
Controlled By Parameter:
Generate | Cross-Reference Pages | Constant Field Values
Called From:
FramedDoc.tpl
Calls:
navbar.tpl, about.tpl
Here is a sample help page generated by this template (click on the screenshot to see the real HTML):![]()
Template Location:
{docflex-javadoc}/templates/JavadocPro/lib/help-doc.tpl
Controlled By Parameter:
Generate | Help
Called From:
FramedDoc.tpl
Calls:
navbar.tpl, about.tpl
Sample output (click on the screenshot to see HTML):![]()
Template Location:
{docflex-javadoc}/templates/JavadocPro/lib/overview-frame.tpl
Called From:
FramedDoc.tpl
Sample output (click on the screenshot to see HTML):![]()
Template Location:
{docflex-javadoc}/templates/JavadocPro/lib/all-classes-frame.tpl
Called From:
FramedDoc.tpl
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:
{docflex-javadoc}/templates/JavadocPro/lib/package-frame.tpl
Called From:
FramedDoc.tpl
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 DocFlex 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:![]()
The first Location Rule collects all packages directly specified on the Javadoc command line. The second Location Rule collects the packages of all classes directly specified on the Javadoc command line. Both Location Rules are interpreted against the template's root element, which is associated with the![]()
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:
The package-list.tpl template is called from the FramedDoc.tpl main template (where the corresponding Call Template section it is specified to produce a plain-text file -- not an HTML file as all other subtemplates).![]()
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:
{docflex-javadoc}/templates/JavadocPro/lib/package-list.tpl
Called From:
FramedDoc.tpl
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:
Generate | Overview | Package Summary
Template Location:
{docflex-javadoc}/templates/JavadocPro/lib/package-summary.tpl
Called From:
overview.tpl
Calls:
inline-tag.tpl
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:
{docflex-javadoc}/templates/JavadocPro/lib/title-page.tpl
Controlled By Parameter:
Generate | Title Page
Called From:
PlainDoc.tpl
Currently, the Table Of Contents is available only in RTF documentation (generated with PlainDoc.tpl main template). However, 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:![]()
To have the Table Of Contents generated, the document should be loaded in MS Word and the {TOC} field updated. For instance, you can press Ctrl-A (select all) and then F9 (update selected fields).Overview....................... Package Summary............. All Classes Summary......... package1....................... class1...................... class2...................... ... package2....................... ... ...
On the following screenshot you can see a sample Table Of Contents produced with this template (after updating/building it in MS Word):
Template Location:
{docflex-javadoc}/templates/JavadocPro/lib/TOC.tpl
Controlled By Parameter:
Generate | Table Of Contents
Called From:
PlainDoc.tpl
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:
{docflex-javadoc}/templates/JavadocPro/lib/navbar.tpl
Controlled By Parameter Group:
Generate | Navigation bar
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
Here is the template's the root section block (click to see in full size):![]()
The following are the screenshots of two main stock-section of this template. Stock-sections are template components that work similar to procedures of ordinary programming languages. Each stock-section can be called from different locations of the template (including even from itself).![]()
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:
{docflex-javadoc}/templates/JavadocPro/lib/annotations.tpl
Called From:
class.tpl, package.tpl, serialized-form.tpl
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:
{docflex-javadoc}/templates/JavadocPro/lib/see-link.tpl
Called From:
class.tpl, inline-tag.tpl, overview.tpl, package.tpl, serialized-form.tpl
{@tag ...}
They can be placed directly within Java comments to be replaced automatically by Javadoc
with certain values (see
JAVADOC TAGS
for details).
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.![]()
NOTE: 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:
{docflex-javadoc}/templates/JavadocPro/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.tplCalls:
see-link.tpl
{docflex-javadoc}/templates/JavadocPro/lib/about.tpl
This template adds the About section at the bottom of each separate output document. It displays the information about DocFlex/Javadoc product along with the hyperlinks to this website.
Template Location:
{docflex-javadoc}/templates/JavadocPro/lib/about.tpl
Controlled By Parameter:
Generate | About (footer)
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, PlainDoc.tpl, serialized-form.tpl