= T3D Technical Documentation =
This documentation serves as a technical and development reference for maintenance and further development.
== Functioning ==
The HTML documentation is created in 2 steps:
{{{
#!html
}}}
[[BR]]
First, the TTCN-3 files are parsed and the information required for step two is written into XML files. These files are then used to generate the HTML files via XSL-Stylesheets. The XSL-Transformations are done by the Saxon XSLT Processor.
=== Creating the XML Files ===
TTCN-3 trees are generated by TRex and are then traversed by '''Visitors''' which gather all relevant information to be written into the XML files. The '''Visitors''' are instantiated for every TTCN-3 file:
{{{
#!html
}}}
[[BR]]
==== Visitors ====
There are currently 3 Visitors:[[BR]]
- '''T3DVisior''' - gathers information used to generate the '''project.xml'''
- '''!DependencyVisitor''' - gathers information used to generate the '''dependencies.xml'''
- '''!ImportVisitor''' - gathers information used to generate the '''imports.xml'''
===== Creating new Visitors =====
To create a new Visitor to implement new functionalities or to gather new information from the TTCN-3 files, the following code can be used.
'' Basic structure of the new Visitor: ''
{{{
package org.etsi.t3d.visitor;
import de.ugoe.cs.swe.trex.core.analyzer.rfparser.LocationAST;
public class NewVisitor extends AbstractVisitor {
@Override
public void finish() {
}
@Override
public void init() {
}
/*
visitNodeType(LocationAST node) functions
*/
}
}}}
'' visitNodeType(LocationAST node) '' functions are called when nodes of certain types are traversed. For example, '' visitFunctionDef(LocationAST node) '' is called when a '' !FunctionDef '' node is found. This node is represented by the '' node '' parameter. See '' !AbstractVisitor.java '' for a full list of those functions.
====== Adding the new Visitor to T3D.java ======
The following code shows where to implement the new Visitor in T3D.java, so it will function properly.[[BR]][[BR]]
'' T3D.java: ''
{{{
/* ... */
public void run(String[] args) {
/* ... */
for (int i = 0; i < ttcn3Resources.size(); i++) {
analyzer = analyzerFactory.getTTCN3Analyzer(ttcn3Resources.get(i));
T3DVisitor visitor = new T3DVisitor(xmlPrinter);
DependencyVisitor dependencyVisitor = new DependencyVisitor(depPrinter);
ImportVisitor importVisitor = new ImportVisitor(importPrinter);
NewVisitor newVisitor = new NewVisitor();
// ...
newVisitor.acceptDFS((LocationAST) analyzer.getParser().getAST());
// ...
}
/* ... */
}
/* ... */
}}}
==== Structure of the generated XML files ====
===== project.xml =====
This file contains the most comprehensive information and represents an abstracted version of the source TTCN-3 files, including module structure, the individual elements, their bodies (if configured so), and T3Doc comments for every module, group, and element of the processed TTCN-3 files. It serves as a basis for the main and the module parameter / test case views.
[[BR]][[BR]]DTD:
{{{
}}}
====== Examples ======
{{{
#!html
|
TTCN-3 |
XML |
| Behaviour |
testcase tc2() runs on sampleComponent1 system sampleComponent3{
map(mtc:p1, system:p1)
var sampleComponent2 component2, component3;
component2 := sampleComponent2.create;
component3 := sampleComponent2.create;
component2.start(f3());
component3.start(f4(1, "a"));
unmap(mtc:p1, system:p1)
}
|
<behaviour><keyword>testcase</keyword> <link loc="testcases-tc2-328.html">tc2</link> ()
<keyword>runs</keyword> <keyword>on</keyword> <link loc="configuration-sampleComponent1-235.html">sampleComponent1</link>
<keyword>system</keyword> <link loc="configuration-sampleComponent3-365.html">sampleComponent3</link> <constructbody id="id319">{
<keyword>map</keyword> ( mtc:p1, system:p1 )
<keyword>var</keyword> <link loc="configuration-sampleComponent2-455.html">sampleComponent2</link> component2, component3;
component2 := sampleComponent2.create;
component3 := sampleComponent2.create;
component2.start ( <link loc="functions-f3-1119.html">f3</link> () );
component3.start ( <link loc="functions-f4-1347.html">f4</link> ( 1, "a" ) );
<keyword>unmap</keyword> ( mtc:p1, system:p1 )
}</constructbody>
</behaviour>
|
| Path |
group group1{
group group1_1{
group group1_1_1{
//...
}
}
}
|
<path>
<path_group loc="groupTest-group1_1_1-341.html" name="group1_1_1">
<path_group loc="groupTest-group1_1-321.html" name="group1_1">
<path_group loc="groupTest-group1-304.html" name="group1">
</path_group>
</path_group>
</path_group>
</path>
|
}}}
===== import.xml =====
This file contains information about the imports and dependency relations of the processed TTCN-3 modules. It serves as a basis for the import / module dependency view.
[[BR]][[BR]]DTD:
{{{
}}}
===== dependencies.xml =====
This file can be thought of as a blend between an abstracted version of the main project.xml file and a low-level version of the import.xml file, featuring a compact representation of the low-level dependencies at the module definition (element) level - it contains all the module definitions and all the known elements referenced directly within each module definition. There is no separate view associated to this file, since it is basically a compact representation of the main view and its main intent is the use with third-party tools to perform custom tasks, such as slicing or markup of definitions related to a particular module definition (e.g. approved / locked definitions, etc.).
[[BR]][[BR]]DTD:
{{{
}}}
===== log.xml =====
This file contains all informations, warnings and errors for each TTCN-3 module that are logged by T3D.
[[BR]][[BR]]DTD:
{{{
}}}
=== Generation of HTML files ===
The HTML documentation is generated with the '''project.xml''' and the '''imports.xml''':
{{{
#!html
}}}
[[BR]]
The ''' Main View ''' and ''' Module Parameter/Testcase View ''' of the documentation are generated with the ''' html.xsl ''' stylesheet using the ''' project.xml ''' and the ''' Import View ''' is generated with the ''' html_import.xsl ''' stylesheet using the ''' imports.xml '''.
==== Structure of the XSL-stylesheets ====
Below, the structure and templates of the XSL-Stylesheets are described to simplify making modifications. See {$T3D_HOME}/css/doc.css for descriptions of the HTML elements.
===== html.xsl =====
Structure of the html.xsl:
{{{
| Template | Parameters | Function |
| main_allElements |
$this = module|group|element
$currentindex = complete construct index
|
calls views template
inserts $currentindex
calls header template
calls element_withcomment template
|
| mp_allTables |
$testcases = testcases
$parameters = parameters
|
generates div_mp element for groups, modules and the MP/TC index |
| html_head |
$title = title of page |
generates head element |
| views |
$main = location of Main View documentation of the current element
$mp = location of MP/TC View documentation of the current element
$import = location of Import View documentation of the current element
$togglemode
|
generates div_views element and T3D Generation Stamp |
| main_index |
$modulename = name of the current module |
generates div_modules element
generates div_index element of the Main View of modules, elements and the index
|
| main_groupindex |
$grouplocation = location of the current group |
generates div_modules element
generates div_index of the Main View of groups
|
| index_grouplist |
$this = groups
$prefix = '' or 'mp_'
|
generates list of hyperlinks to all groups given in parameter $this |
| index_elementlist |
$this = elements
$prefix = '' or 'mp_'
$type = type of elements
|
generates list of hyperlinks to all elements given in parameter $this |
| mp_index |
$modulename = name of the current module |
generates div_modules element
generates div_index of the MP/TC View
|
| index_modulelist |
$prefix = '', 'mp_' or 'import_' |
generates list of hyperlinks to all modules |
| header |
$this = module|group|element
$prefix = '', 'mp_' or 'import_'
|
generates p_header element |
| element_withcomment |
$this = module|group|element |
generates div_content element
generates div_comment element
generates div_element element
|
| path |
$this = module|group|element
$prefix = '', 'mp_' or 'import_' |
calls path_group template
|
| path_group |
$this = module|group|element
$prefix = '', 'mp_' or 'import_' |
generates the group part of the path navigation
|
| mp_testcase_table |
$this = testcases |
generates the MP/TC View table of testcase elements
|
| mpview_path_testcase |
$this = mpview_TestcaseDefs
$first = true|false
|
generates Path part of the MP/TC View table of testcase elements |
| match mpview_ModuleParDef |
|
generates the MP/TC View table of module parameter elements
|
| mpview_path_modulepar |
$this = module|group|element
$first = true|false |
generates Path part of the MP/TC View table of module parameter elements |
}}}
===== html_import.xsl =====
The following table contains descriptions of parameters and function of the used XSLT templates in ''' html_import.xsl '''.
{{{
#!html
| Template | Parameters | Function |
| import |
$module = name of the current module
$importname = name of imported module |
generates a list of imports by $module from $importname |
| importby |
$imports = list of indirect imports |
generates a list of $imports |
| show_imports |
$module = module
$currentmodule = currently selected module |
selects a color for $currentmodule and calls the colored_module template |
| colored_module |
$module = module
$color = class of $module |
generates a colored hyperlink to $currentmodule (used for list of modules in the middle column)
|
| html_head |
$title = title of page |
generates head element |
| legend |
|
generates Import View Legend |
}}}
==== Using new XSL-Stylesheets and/or XML files ====
New XSL-Transformations can be executed by using the following code.[[BR]]
'' XSL-Transformation: ''
{{{
String foldername = getProperOutputPath() + "/" + getSubPath();
String xmlFileName = "name.xml";
String xsltFileName = "name.xsl";
String outputFileName = "outputName";
System.setProperty("javax.xml.transform.TransformerFactory", "net.sf.saxon.TransformerFactoryImpl");
TransformerFactory tfactory = TransformerFactory.newInstance();
Transformer transformer;
try {
transformer = tfactory.newTransformer(new StreamSource(new File(xsltFileName)));
//transformer.setParameter("parameterName", );
transformer.transform(new StreamSource(new File(foldername + "/" + xmlFileName)),
new StreamResult(new FileOutputStream(foldername + "/" + outputFileName)));
} catch (TransformerConfigurationException e) {
e.printStackTrace();
} catch (TransformerException e) {
e.printStackTrace();
} catch (FileNotFoundException e) {
e.printStackTrace();
}
}}}
=== Javascript ===
To toggle the visibility of certain elements in the HTMl documentation (e.g. navigation items), a Javascript file called '' doc.js '' is used. It can be found in {$T3D_HOME}/js.
[[BR]]
==== Functions ====
The Javascript file consists of the following functions:
- ''' getElementsByClass(searchClass,node,tag) ''': returns all HTML elements of a certain class
- ''' toggleConstructbodies(hide) ''': toggles visibility of all construct bodies in the Main View of elements/groups/modules if hide == true
- ''' toggleImportDetails() ''': toggles visibility of all details in the Import View of a module
- ''' togglePaths(hide) ''': toggles visibility of all Path columns in the MP/TC View of module parameters/test cases/groups/modules if hide == true
- ''' toggleHideNotes() ''': toggles visibility of all '' (toggle) '' notes in the Main View of elements/groups/modules
- ''' toggleElement(element) ''': toggles the visibility of '' element ''
- ''' toggle(elementName) ''': calls ''' toggleElement() ''' with the element with the Id '' elementName ''
- ''' mp_init(listName) ''': collapses all construct lists in the construct index of the MP/TC View, except '' listName ''
- ''' init(listName) ''': calls ''' toggleHideNotes() ''' and collapses all construct lists in the construct index of the Main View, except '' listName ''