Toolkit: SiteMap

Configuration file
The layout of the Site Map
Synonym file
How to execute the application

The SiteMap application is an application that creates a HTML-table describing the contents of a treebrowse structure. For an example of the result of the SiteMap application see.

Configuration file

To make the application work as you want it to you have to specify a number of parameters in a configuration file. Each row in the configuration file defines one parameter. The order of the rows does not matter. Each part of a row is separated with a "tab character (/t)". The name of the parameters are not case sensitive. Space characters to the left or right of an item will be removed.

Below is an example of how a configuration file may look.

includesubtree
wwwroot
datafile
startDir
resultfile
relativepath
bgcolor
fgcolor
headerfile
footerfile
maxlevels
delimeters
convertampersand
levelstyle
levelstyle
levelstyle
levelfont
levelfont
defaulttitlelength

false
d:/project/rup50/applet/
tree.zip
d:/project/rup/
sitemap/sitemap.htm
../
#C0C0C0
#336699
sitepreamble.txt
sitepostamble.txt
10
*
false
defaultstyle
headlinestyle
1
defaultfont
headlinefont
30

indexlevel2
indexlevel1
indexlevel2
Arial Plain -1
Arial Bold +2

Name of the parameter	Example value	Description
wwwroot	d:/project/rup50/applet/	This parameter defines the directory where the datafile is located. This parameter is mandatory.
datafile	tree.zip	This parameter defines name of the WinZip-file that contains the data file (tree.dat) defining the tree structure. This parameter together with the parameter "wwwroot" shall define a valid URL to the datafile. The default value is "tree.dat". This parameter is optional.
includesubtree	false	A tree structure may contain subtrees defined in separate dat-files. This parameter defines if all subtrees shall be included in the Site Map or not. Possible values are "true" and "false". Default is "false". This parameter is optional.
resultfile	sitemap/overview.htm sitemap/artifacts.htm sitemap/worker.htm sitemap/workflow.htm sitemap/toolmentors.htm	The name of the file in which the Site Map is to be written. The value of this parameter together with the value of the parameter "startDir" shall be a valid path for a file. This parameter is mandatory.
relativepath	../	Defines the relative path from where the result of this application is written to the files it refers to. If the result is written to a directory one level below the top of the site this parameters shall have the value "..". This parameter is mandatory.
synonymfile	synonyms.txt	This parameter will make the application behave in a quite different way if it is used. If this parameter is specified the application will traverse the directory structure specified by the parameter "startDir". It will create a temporary dat-file named "sitemap.dat" located in the directory defined by the parameter "wwwroot". In the synonymfile each direct name is mapped to a more readable name, the name that shall be visible in the Site Map. If a directory is not specified in the synonym file that directory will not be included in the dat-file and therefore not in the Site Map. The dat-file will contain every html document in the directory structure.
removedatfile	true	If the parameter "synonymfile" is set then a temporary dat-file is created. If you want this file can be used as input to a TreeBrowser. If that is the case this parameter should be set to false. The default value is true, i.e. the file is removed. If the generated dat-file shall be used without modification it have to be placed at the same level from the top of the directory structure as the Site Map document generated by this program. This parameter is optional.
target	ory_doc	The name of the target in which the html documents is to be shown. This parameter is optional.
maxlevels	10	If the tree structure that serves as base for the Site Map is very deep you may want to exclude the deepest parts if the structure. This parameter defines how many levels of the structure that at most will be included in the Site Map. The default value is "10". This parameter is optional.
delimeters	*	This parameter defines the delimeter character in the datafile. The default value is "". This parameter is optional and only needs to be set if the operating system does not support the "" sign.
convertampersand	true	This parameter defines if the system shall convert all "special" characters, for example the Swedish ä to ä. The default value is "true". This parameter is optional.
bgcolor	#C0C0C0	If a node is marked as a headline the cell in which the node is written will have this background color. This parameter is mandatory.
fgcolor	#336699	If a node is marked as a headline the node text will have this color. This parameter is mandatory if stylesheets are not used. If stylesheets are used this parameter is left without notice.
headerfile	sitepreamble.txt	To make it possible for the user to customize this application as much as possible this parameter exists. This parameter is the name of a file that will serve as the header for the file SiteMap. The value of this parameter is either a relative path from where this program is executed or an absolute path. This parameter is mandatory.
footerfile	sitepostamble.txt	To make it possible for the user to customize this application as much as possible this parameter exists. This parameter is the name of a file that will serve as the footer for the Site Map. The value of this parameter is either a relative path from where this program is executed or an absolute path. This parameter is mandatory.
levelstyle	defaultstyle defaultsitemapstyle 1 levelonestyle	This parameter defines which style, in the referenced stylesheet, that shall be used for each node level. The SiteMap application assumes the <P>-tag, which means the stylesheet must define styles for the <P> tag. For example, p.headinglevel2. If stylesheets are not used the parameter "levelfont" controls the layout. The syntax of this attribute is [paramname][nodelevel/reservedname][stylename]. [paramname] is "levelstyle". [nodelevel/reservedname] is either the level of the node or one of the reserved names, ("defaultstyle" or "headlinestyle"). [stylename] is the name of the style. The attribute is optional but if you intend to use stylesheets you have to specify at least a "defaultstyle". Use the file defined by the parameter "headerfile" to import the styles.
levelfont	defaulfont Arial Bold +2 1 Times Italic -1	This parameter defines which font that shall be used to generate the different nodes. If you have defined any stylesheets this parameter will be left unnoticed. If you have not specified any stylesheets this parameter have to be used. The syntax of this attribute is [paramname][nodelevel/reservedname][fontname][fontstyle][fontsize]. [paramname] is "levelfont". [nodelevel/reservedname] is either the level of the node or one of the reserved names, ("defaultfont" or "headlinefont"). [fontname] is mapped to the "FACE" attribute of the HTML FONT attribute. [fontstyle] is mapped to the "<B>" or "<I>" tags. Possible values are Bold, Italic and Plain. [fontsize] is mapped to the "SIZE" attribute of the HTML FONT attribute. The attribute is optional but if you intend to use Font definition you have to specify at least a "defaultfont".
startDir	d:/project/rup50	This parameter defines the top directory of the structure to describe and/or the top of the directory structure in which the resultfile is to be written. The reason to have both a wwwroot and a startDir parameters are as follows. You may want to create a Site Map with a data-file as input parameter where the data-file is located on a server somewhere, but the Site Map is supposed to be located on a totally different place. This parameter is mandatory.
defaulttitlelength	3	This parameter the max length of a title of a document. If the length exceeds this value it is truncated and "..." are apended to the string. This parameter is only valid if there is no definition of the parameter "titlelength" for the current cell. If this parameter is not set the length of a title can be in definite. This parameter is optional.

The layout of the Site Map

The Site Map that will be generated is an ordinary HTML table. In the definition file you will define how the table will look. To specify the definition file think that you will cut the tree structure into smaller parts. Each top node in one of these structures shall be defined in the definition file. The application will insert the node and all nodes that are children and siblings to that node until it finds the next node defined in the definition file. This will make it possible to create the table in the way you want to. For each node there are a number of parameters described below. The order among the parameters are not of any interest and the names of the parameters are not case sensitive.

<--
label
level
row
col
colspan
rowspan
colwidth
cellcolor
links
visitonce
onlythis
mode
titlelength
-->

Introduction to the Rational Unified Process / rup
0
1
1
1
1
20%
false
true
true
true
headline
20

<--		Each definition of a node starts with "<--". This parameter is mandatory.
label	Introduction to the Rational Unified Process / rup	The visible label of a node, ("Introduction to the Rational Unified Process") or the synonym for a directory/file ("rup"). The synonym case is only applicable if you use a synonymfile. This parameter is mandatory.
level	0	The level of the node in the tree structure. The first level is 0. The unique definition of a node in the tree structure is the label of the node and the level the node is located at. There can exist more than one node in the tree structure that have the same label and level as long as no one of them are not included in the definition file. This parameter is mandatory.
row	1	The row in the table where this node is to be inserted. If the value is "0" then the node will be inserted above the table. This parameter is mandatory.
col	1	The column in the current row this node is to be inserted into. If the node is to be inserted into the cell specified by the previous node definition, let this node have the same values of the parameters ""row" and "col". This parameter is mandatory.
rowspan	1	Defines the number of rows in the table this cell shall occupy. Default is "1". This parameter is optional.
colspan	1	Defines the number of columns in the current row this cell shall occupy. Default is "1". This parameter is optional.
colwidth	20%	Defines the width of the column in pixels or in percentage. This parameter is optional.
cellcolor	false	Defines if this cell shall have a background color or not. Possible values are "true" and "false". The default value is "false". This parameter is optional.
links	true	Defines if the hypertext links of the nodes in this subtree shall be generated. Possible values are "true" and "false". The default value is "true". This parameter is optional.
visitonce	true	Defines if this node can be defined just one time in the definition file. Possible values are "true" and "false". The default value is "true". The reason for setting this parameter to false is if you first want to have the node label as the headline in a cell without any hypertext link and then want the node in a cell with the hypertext link generated. This parameter is optional.
onlythis	true	The default behavior is that the program starts width the node defined and continues as far as possible of until another node defined in this file. But if only this node is to be inserted and no more then this parameter is set to true. The default value is "false". This parameter is optional.
titlelength	20	This parameter the max length of a title of a document. If the length exceeds this value it is truncated and "..." are appended to the string. This parameter defines the max length of the title for the subtree defined by this node definition. If neither of the parameters "titlelength" and the parameter "defaulttitlelength" not set the length of a title can be in definite. This parameter is optional.
mode	headline	This parameter is only applicable if you use a synonym file. Possible values of this parameter are "headline", "first", "half" and "define". If you use a synonymfile the value of the parameter "label" is a synonym for the real label. The value of that parameter is typically the name of a directory. This parameter together with the label parameter will instruct the program how to calculate the label. "headline", The label will get the text this node is associated with in the synonymfile. "first", The label will get the text of the first child of the node pointed out by the synonym. Even if you shall point out a child node the value of the label and level parameters shall be as if you did point out the parent node. The program will den use that node to calculate the actual value of the parameter label and level. This will make the definition of nodes in the definition file independent of if you add or remove files from a directory. "half", The label will get the text of the middle child of the node pointed out by the synonym. The child nodes are sorted in alphabetical order. "define", The program will create a as many cells needed to display this node and all its children. Each row will have four columns. The nodes that have children will be marked as headline. This parameter is optional.
-->		Each definition of a node ends with "-->". This parameter is mandatory.

Synonym file

The purpose of the synonymfile is to define a mapping between non HTML documents or directories and a label visible in the Site Map. The Site Map will use the title attribute of all HTML documents. Items that are not HTML documents have to be defined in the synonym file. Such items are directories, data files and PDF documents. Each item consists of the directory/filename and the user defined label/title separated with a tab character (\t). All directory/filenames are relative from the directory structure top.

Below is an example of how a synonym file may look. It shows how to map a directory, a PDF document and a dat-file into a readable label.

process
process/summary.pdf
process/process.dat

Process overview
Process summary
External process description

How to execute the application

Read the System Requirements to understand what is needed to execute this application.

Execute Java application

To execute the SiteMap as a Java application type:

java -classpath ../../ruptools/RUP.jar ruptools.SiteMap -r configfile.txt -c ASCII - h helpfile.txt

The parameters can be entered in any order.
-r	The file defining the behavior of the application, i.e. the 'configuration file'.
-c	The character set to use when reading input. Default is local character set. Parameter is optional.
-h	File containing text to make the output from the application language dependent. Parameter is optional.