Using the Documentation Template Designer

Introduction
Creating and opening projects

How to open a project


How to create a project

Setting Resource options

Setting page margins, page orientation, report headers and footers

Report Designing Basics

Structure of report


Page header, report header, details, report footer, page footer

Inserting Data

Label


Image


Panel


Formula


Data control

Formatting Data

Fonts


Colors


Borders

Zones
Sections
Areas
Stock Sections
Designing your own documentation template
Tips and Tricks

Introduction

The Main Template Designer Window is divided into 2 main regions or panes. They allow to create templates used then by GenDoc in creating documentation reports.

Scope pane (left pane) - represents the scope of template's objects;
Area pane (right pane) - represents sections (hereinafter "areas") definitions connected with the appropriate template's objects;

Each report which has been created using Together's Document Template Designer, is divided into 5 main sections (hereinafter "Zones"):

  - Report Header
  - Page Header
  - Details
  - Page Footer
  - Report Footer

Both panes including all five zones are shown below.

How does it work?

GenDoc needs to know how to generate a report: how to traverse the model, which elements to collect, in which order to represent and group them within the report and so on. First, it will look at Scope pane, where are all zones the report will be created from. Next, GenDoc needs to know which data should be put in the particular report's area and how they should appear. In order to do that, GenDoc will analyze each existing report zone area. Some of them are grouped in sections, some do not. Actually, each area represents some kind of procedure the GenDoc should execute while generating the report.

Terminology

Zone: a distinct part of a report (Ex. Report Header).
For more information, see Zones topic.
Sections: logical grouped (based on grouping criteria) informational parts (areas) within a zone (Ex. Folder Section). There are five main sections:

  1). "Element Iteration" section
  2). "Static" section
  3). "Property Iteration" section
  4). "Folder" section
  5). "Stock" section

Sections may contain one area (for example Static section) or other sub-sections (for example Element Iteration section) with corresponding them areas.
For more information, see Sections topic.
Area: the smallest piece of information of the report. It describes which data must be inserted into particular report area field. (Ex. any Static Section). For more information, see Areas topic.

This tutorial will cover the creation of reports in Together using Documentation Template Designer.

Creating and opening projects

Opening existing projects

To open an existing Documentation Template Designer file:

• From the Main menu, choose File | Open to display the file selection dialog.
  

• Navigate to the directory containing the file.
  

• Select the file (e.g. myFile.dtf) and click Open.
  

• Note: Each opened template project displays in its own tab page in the Area pane.

Creating a new file (e.g. NoName.dtf)

To create a new file:

• From the Main menu choose File | New to display the a new empty project.

Setting Resource options

To set options for a template, first you must open/create it and then modify any or all of the following:

• Page Header - check if you want to use a page header in your report file
  

• Page Footer -check if you want to use page footer in your report file
  

• Report Header - check if you want to use headers in your report file
  

• Report Footer - check if you want to use footers in your report file
  

• Page Type - choose the paper size or select use to define your own size. Numbers are treated in mm.
  

• Page margins

Left - the left margin offset in mm


Right -the right margin offset in mm


Top - the top margin offset in mm


Bottom - the bottom margin offset in mm

• Page orientation - defines orientation of the page.

Report Designing Basics

A report can be divided into five major zones, which are:

Page Header

Elements of this zone will be seen once per page in the upper half of the report.

Report Header

Placing elements here will allow them to only be seen on the very first page of the final report.

Details

The Details zone represents all report's data, and it is divided into sequence of areas (sometime grouped by sections), each of them representing a piece of information of the report. This zone contains at least one Element Iteration section (by default, only one).

Report Footer

Placing elements here will allow them to only be seen on the very last page of the final report. It is often used to print summary data for the report.

Page Footer

Elements of this zone will be seen once per page in the upper half of the report.

Note:

- if you don't want to define in your report all zones, Documentation Template Designer supports the ability to hide them. See Tips and Tricks for more information.
- the "Details" zone is divided into sequence of areas. Page header/footer and report header/footer contain only one area each.

Inserting Data

Click with the right mouse button on one area background and choose Insert control.

This command lets you create a blank element exactly at that position in the template area, where the box appears.

• Label

Label text

The text entered in this box will appear in the created label field. On the bottom of that box there is another box to preview all changes (font, color, border) you make to the typed text. See below the

• Image

In a Report header you can also insert an image. Just navigate to the directory containing the file, select the file and click Open. A preview of the image will appear on the bottom of the control panel.

• Panel

A panel is an element, within you can insert all elements which are available for inserting into that zone, including new panels too. After creating, you have the possibility to set the alignment parameter for coming inside elements. Use panels to show areas in a more compact way.

• Formula

Formulas provide an important mechanism to manipulate and display data inside the report that could otherwise not be available directly from the data source. Sometimes data can be missing from data sources even though you have to put them on your report therefore is it necessary to use formulas in reports. Each Formula control is connected with an expression which calculates a value printed in the report (for the first time it may be a value returned by some predefined function). For example, it may be the function which returns a property value by the property name. Example of using formulas: To display a property name and value, two predefined function may be used: "thisPropertyName()" and "thisProipertyValue()". This functions should be set as expressions in Formula controls which should be put in detail zone of the Property Iteration section.

•   Data Control

This is the most important control type because it contains that information you need to see in a report: documentation, name, stereotype, version, package, author and more. There may be two different types of data source for this control:

• an Element property - In this case, a name of a specific element property should be set for the control. When GenDoc executes this control it requests the "current" model element for the value of property with the specified name.
  

• a GenDoc variable - Each a such variable represents some particular kind of GenDoc's internal information available at the given moment and having a specific name. To connect the data control with a specific GenDoc's variable the "variable" data source should be selected and the appropriate variable name should be chosen from the list of the variables available in this place.

Note: The information you can insert into Data Control, always depends on Element Iteration area you are working in e.g. you can't have in a Page Header's data field stereotypes.

Note: You can come back to each control panel by right-clicking on element and choosing "Properties".

Formatting Data

• Font

Here you can set the family, style and size of the font and also text alignment. All settings are applied to the all typed text in the field.
Note: After you finished, click Ok to apply formatting to the field

• Color

Pick the needed color and using the left/right mouse button, change the text color/fill the label with selected color. Note: If the background color is with cross hash in the text window, that means that background color of this field is transparent. To specifiy a color, first uncheck the Transparent option.

• Border

Here you can set the border color and thickness of the label border lines one-by-one or all together. This features will help you when you want to highlight an element which is important for you.

Note: Use the "Preview box", which reflects your selections, to synchronize all changes you make with the typed text.

Zones, sections, areas

Documentation Template Designer divides a report into sections called "zones". For example Page Footer is a zone.

Operations with Zones

• Hide/Show: If you don't want to show a zone (maybe you want to hide it from some users or don't want to include it in the report) select File | Options and uncheck zones you want to hide/show. See Tips and Trick for more information.

   

• Resizing zones: To re-size a zone, position the cursor over its split bar. After the cursor takes the shape of a <img.gif>, click the left button and drag and drop the split bar to its desired position.

Sections are logical groups containing informational report parts (areas). There are 5 types of sections used in the template:

  1). "Element Iteration" section
  2). "Static" section - the smallest section of a template, represented by only one area.
  3). "Property Iteration" section - contains properties of a iteration element. By default each "Property Iteration" section iterates through all properties of the object.
  4). "Folder" section - usually, this section is used to keep compact a short description of the whole iteration element
  5). "Stock" section

Operations with Sections

• Hide/Show: Right click on the section in the Scope pane and check "Hidden" to make this section invisible. Note: any hidden section will be shown in Template, but it will be not printed in the report.

   

• Resizing sections: See Operations with zones.
  

• Insert other sections: Within one section may be inserted other sections. Right-click on Details Zone and choose one from the next two options: Insert Nested/Sibling Sections (See image below).

• Properties:

Enabling Condition: This field is for entering conditions, which can influence the report generating process. This options is used when the user wants to hide a section (it may be done by checking "Hidden" box), but during one session only. As you remember, the "Hidden" option will hide the element it is checked for, in the whole report. See Tips and Tricks for more information of how to use this option.

 

Filter expression: this is a expression which determines for all objects in the iteration whether the object belongs to the metatype or not. A metatype, is a type of object presented in any model. Examples of metatypes: packages, classes, operations, diagrams etc. The list of allowed metatypes depends on the place where the section is located in. Example of filter expression: For example, filter for "Interface" metatype: " hasPropertyValue("$shapeType", "Class") && hasProperty("$interface") ".


"Hidden" check box: Check or uncheck this box to include / not include a current section into the report.


"Recursive" check box: Check or uncheck this box to if you want / don't want to have the currents settings active over the whole iteration section. .

• Recommendation: Add Static sections whenever you need to delimit zones, complex Folder sections, Element iteration sections from others sections. Add them at the end of the current section.

An area is the smallest piece of information of the report. For example, Report Header contains just one area so it can be called area too. Each area in the report always have some prototype definition in the report which shows how data should be put in the particular report's area and how should they appear.

Operations with Areas

• Start from new page: the area starts from a new page;
  

• Break page after this area: next area after currently will be printed on the next page;
  

• Don't break between pages: this will prevent breaking the areas between pages;
  

• Keep on the same page with the next area: this will keep area with the next zone on the same page;

Element Iteration Section

This section consists of the following objects:

  - the header section
  - nested sections
  - the footer section

Header and footer sections are represented by only one area each. Their meanings are similar to headers/footers zones meanings.

Nested sections are used by GenDoc while a report is created. When GenDoc meets an Element Iteration section, it looks at its properties in order to know for which type of model elements this section was designed. For example, if the Iteration element is "package", then GenDoc will ask the model all packages it has, will take the "root package" and generate a report for it using existing sections. Some of those sections may contain incompatible (nonexistent) information for the "root packages", so they will be skipped. If there are packages in the "root package", then GenDoc will process all Element Iteration section list for each of them. Suppose, your template has only two Folder sections: first - a list of packages, the second one - a list of diagrams. Now, let's take a "root package" containing only packages containing diagrams. First time when the list is passed, the second folder will be skipped. Then, for each of packages, the first folder will be skipped.

Stock Sections

Stock sections are sections that may be called and inserted as modules. If a fragment of your template is repeated, you can create a stock sections from this fragment, delete it from the template and call it there by using only one row of design. In this way, you don't need to describe iterations you already inserted, twice.

Operations with Stock Sections

• Creating: Choose Stock | New from the Main menu to display the New Stock dialog (see below).

• Calling: After a stock section was created, you may insert it into report by selecting "Call to Stock Section" in the Scope pane.
  

• Showing: If a template containing calls to Stock sections was opened, you can see them by right-clicking in the Scope pane on each of them and selecting "Show Stock Section" option. Each section will be shown in separate tab.
  

• Deleting: Follow the same steps for showing but select Delete option.
  

• Changing one called section to another: If you decided to change the called stock section to another section or you inserted a call to a stock section before to create it, right-click on section and choose "Call to" option. A list with all created stock sections will appear in a pop-up window. Pick one of them and click Ok. Note: The same operation could be done if select Properties.
  

• Editing: Stock sections may be edited in two ways: by right-clicking on it and selecting "Show Stock section" from the pop-up menu or by selecting Stock | Edit from the Main menu. Note: selecting Stock | Edit from Main menu, reveals a pop-up menu containing all created stock sections, available for editing.
  

• Properties: Through Properties pop-up menu dialog, you may choose/change the section, the current stock section will/is designed for. For that, just right-click on the section name (you may do it in both Scope pane and Area pane) and select "Properties" from the pop-up menu.
  

• Copy/Paste stock sections: For increasing speed, you can copy stock section and paste them into another places. Very often, some stock sections are needed in more than one place so these two commands will be very useful in such situations.

First, you have to open the needed stock section (See above). Then, just right-click on Folder section in the Scope tab and select "Copy to clipboard". From this moment, your selected stock section is in the clipboard.


If you want to create a new, similar Stock section, select Stock | New | Paste from clipboard. As far as you already have a Stock section with such a name, a dialog window will ask you to enter a new name. The new, similar Stock section, will be created having the name you entered.


A stock section (always represented by a Folder section or Property iteration section) also may be inserted into another sections, of course, if it's possible. Since it was copied into clipboard, the stock section may be inserted like when you add sibling or nested sections. Just select from the pop-up menu, "Paste from clipboard".

• Important note: When you create a new Element iteration Stock section (Stock | New | Element iteration), don't forget to enter the title of selected Stock sections from the pop-up menu.
  

• Note: When adding new sections within Stock sections, before you right-clicked on a section, be careful where is positioned your cursor. This is very important as far as depending on it you'll see different pop-menus.

Designing you own documentation template

• Start Template Designer according to the instructions.
  

•  Create a new file and save it as 'ecm.dtf'. It's name will appear at the top of the left toolbox.

Page Header (first zone)

• Now click with the right mouse button on the white background of the first zone area to add elements. Select Insert Control | Label, then enter "Page". This will add a field named "Page". which will appear within first zone area. Select Insert Control | Data Control . Make sure that Data Source is set to Variable. Select Page Number to have on each page a page number. Repeat the steps above to add one more Label called "of" and a Data Control field containing "Number of page" within. Note: You can insert a Page Number field in either the Page Header or the Page Footer zone, but not in any other zone. If you wish, click and drag the element's border to the preferred size.

Save Changes

Remember to click on the button "File | Save" when you are finished making any adjustments to the text in your template.

Note: If you don't use this button after making changes to your template all changes will be lost.

Report Header (second zone)

• Add a Label containing a Project Name. In the Color box choose one color to fill by clicking with the right mouse button. Click 'ok'. You have to make the same operations you made to insert a page number into Page Header, but now select Insert Control | Data Control, then choose "Current date/time" and click Ok.

Element Iteration (third zone)

• In the Scope pane, click with the right mouse button on this section and select Package in the Properties | MetaType. That means that all documentation will be built by packages; the number of iterations will be equal to number of existing packages Note: when creating a new template, "Iteration by Package" will be set by default.
  

• In the Static Section's field, first create a panel by selecting Insert Control | Panel. After you re-sized the panel window and set the background color, click with the right mouse button within that panel and add a Label. Enter "Package" in the Label text field. Re-size Label. Until this moment, your report will write the word "package" for every package founded. Let's add a name for that package. For this, add Data Control choosing Full Name in Data Source | Element Property field. You can also specify a Default text, in case a package will be founded without name or leave empty this field. Click Ok, re-size, then choose the position within panel when you want the data will appear. The report will write a full name for each package. Note: You will not see the root package, so this will be the first shown and without name.

• Creating "Property iteration" section

Now insert a Sibling Section for the Static Section, by clicking on it in the Scope pane and selecting Insert Sibling Section | Element Property Iterator. Let's put in this field the package's Documentation. To do that, change the Property iteration name from <null> to Documentation by selecting it from the "Properties". We've just set the name which will appear at the beginning of this section. For adding data, click with the right mouse button on Static section field and select Insert Control | Data Control | Source | Documentation.

• Next, we recommend to use a special section called Folder Section. Use this section to insert in your report a brief content of project diagrams.

• Creating "Folder section" section

To create a Folder Section, select Insert Sibling Section | Folder Section by clicking on Property Iteration. In this way, this section will follow Property Iteration section. Note: If you decide to create the Folder Section through Element Iteration, the section will be created behind all other sections.


Now you must insert all those sections, you want to have a brief information for. Because all next iterations should be within Folder Section, you can add each element iteration in two ways: inserting a sibling section for the static one or inserting a nested section relatively Folder Section. Then select from the pop-up box an element. Recommendation: Put diagrams first, then all other elements.


Suppose you created a Class Diagram first. First of all, insert a Header to delimit one element iteration from another. Click on Element Iteration in the Scope pane and select Add Header. In Header's field, insert a Label called "Class Diagram". Next, click with the right button on the Static section's field in the Area pane and insert an image. Note: Make sure that Image type is static.


After that, add one Label called "Diagram" and a Data Control with a Name in Data Source | Element Property (by default). For a better design, arrange element positions in this field.


Continue repeating above steps, with State, Interaction, Activity, Component, Deployment, Use Case, Business Process diagrams, and also with Subpackages, Classes, Interfaces. Note: For subpackage, class and interface, use Full Name instead Name in Data Control settings.


Delete the first Static Section within Folder Section since it's empty. For this, click on it in the Scope pane and select Delete.


Add more Element Iterations in the Folder Section. See Tips and Tricks/Cut, Copy and Paste for increasing speed.

• Within first Element Iteration (Iteration by "Package"), after Folder Section, you have to create Element Iteration sections for each diagram and diagram element. In these fields will be inserted information about classes, attributes, interfaces, depending of the diagram type. Our example will contain only the class diagram.

Iteration by "Class Diagram"

• Relative last created section (Folder Section), create (click on it in the Scope pane and select Insert Sibling Section | Element Iteration) a new Element Iteration section. In the appeared pop-up box, choose Class Diagram. First, add a Header section with a Label within, called "Class Diagrams". For a better design, select a color to fill in, and then re-size.
  

• As you had done for the Class Diagram in Folder Section, insert a static image, a Label called "Class Diagram" and a Data Control called "Name". To do that, you can use the 'copy/paste' options.
  

• Next, you have to describe the diagram e.g. to parse it. For that, you can write a Stock section, actually the best way to insert data into template. A stock is used when you have some diagrams with similar configuration, so you don't have to design them twice. It's enough to call a Stock section containing the description.

• Creating "Diagram description" stock section

  Select Stock | New | Folder Section from the Main menu. Enter "Diagram description" in the pop-up dialog which was appeared. In the Area pane right-click on Folder Section and select Properties. You'll see a pick-list of all possible elements used in Together where you should choose Diagram (generic), as the most common description of a diagram.
  

  In the first Stock static section, insert an image with "Diagram" as Type. That will add the class diagram image into this section. The use format is Windows MetaFile (wmf).

  Relative first Static section, add a sibling section, called Element Property Iterator. Right-click on the split bar and choose Properties | Documentation to select a name for this area. For data, click with the right mouse button on this area, and select Insert Control | Data Control | Documentation. Re-size.
  

  To obtain more information about parsed diagram, you have to insert another Element Property Iterator section, which will contain your specified data. Suppose your area name will be "Stereotype, Alias". Note: To select more than one element in Element Property Iterator pop-up dialog, make sure that Scope option is set to "Set of properties". The multi-select is activated by pressing "Ctrl".
  

  For data, you have to add two corresponding fields. First, make sure that in Data Label pop-up window, Data Source option is set to "Variable". Click on "Full name of current property" to select first field, and "Value for current property" for the second. Re-size.
  

  Add an empty Footer for a better stock section delimitation.

• Since the Stock Section was created, right-click on last Static Section from the Scope pane and insert a sibling section by choosing "Call to Stock Section". In the pop-up window you'll see a complete pick-list of all available Stock sections. Select the last created one and click Ok.

• Creating "Diagram Contents Summary" folder section

  Now you may want to insert a brief content of the class diagram. To add a new Folder section within this diagram, follow the same steps as for the whole project. For example, let's create the first element iteration. Name it "Iteration by package reference". First, create a Header, and insert into it a Label, named "Package nodes". Then, create a Static section and as Data control, select "Full name" of the element property.
  

  Continue with Class, Interface, Object, Actor and Use Case. Now you have a brief description of all elements of the Class diagram so you can describe each of them, one-by-one. How it may be done?

• Creating "Iteration by "Package reference""

  Create a new Element iteration section. For that, right-click on last created Folder section (in the Scope pane) and choose Insert sibling section | Element iterator | Package reference. In this section, you'll be able to describe every founded package in a Class diagram.
  

  First, add a Header for this new created section containing one Label Control named: "Package Node Detail". Recommendation: For a better design, choose a color and fill it. Re-size.
  

  In the Static section, insert a Label Control (right-click on its area and select Insert control | Label control). Call it: "package". Then, add the corresponding Data control by selecting "Full name" in the Element Property box. Recommendation: for a better design, insert a small image at the beginning of the area.
  

  In the Scope pane, click on Static section and insert one Property iteration section. This will be used for describe all package documentation so in this section area, click on Property iteration, select "Properties" and choose "Documentation". Then, insert a Data control (). Set Data source option to "Variable" and choose "Value of current property".
  

  Create one more Property iteration section. In the Element properties pop-up window, select all items except Documentation, Name and Full name. Note: Make sure that Scope option is set to "Set of properties".
  

  Then, add two Data control: "Full name of current property", and the second one: "Value of current property". Note: Make sure that Data Source option is set to "Variable".

• In the Class diagram, packages may be connected with other elements through relationships. So, you need to describe all possible links (related to packages) too. Very often, those links you'll have to use in other diagrams, that's why it makes sense to create for them Stock sections. This is the optimal method, though you can choose the slowly one: Click on one Property iteration section, select Insert sibling section | Element iterator and one from those three links will appear. Note: You have to pass these steps every time when you'll need to add a link description. Below, we'll continue with the first method.
  

• First, you have to create a Link description stock section which describes the basic features of a link: destination and source. Using that, you'll be able to create another stock section, for all links just by adding theirs particular characteristics to the basic ones.

  Creating "Link description" stock section

• Select Stock | New | Folder section. Enter "Link description" in the pop-up dialog.
  

• In the Area pane, right-click on Folder section and select "Properties". From the pop-up list, choose "Link (generic)". Note: "generic" means, that this is the basic description for a link.
  

• Right-click on section area and insert two Data controls: "Shape type of link destination" and "Name of link destination"; Note: make sure that Data source option is set to Element property.

• Creating "Generalization links" stock section

Select Stock | New | Element iterator | Generalization link.


Add a Header and within it a Label. Name it : "Generalization link".


Insert a Call to stock section. Choose "Link description" from the pop-up box.


Add a Property iteration section. Select "Documentation" from the pop-up box. Then, add two Data controls: "Full name of current property", and the second one: "Value of current property". Note: Make sure that Data Source option is set to "Variable".

• Creating "Association links" stock section

Select Stock | New | Element iterator | Association link.


Add a Header and within it a Label. Name it : "Association link".


Insert a "Call to the stock section". Choose "Link description" from the pop-up box.


Add a Property iteration section. Select all items from the pop-up dialog except these ones: "FullName of link destination/source", "Name of link destination/source", "Shape Type of link destination/source". Note: Make sure that Scope option is set to "Set of properties".


Add two Data controls: "Full name of current property", and the second one: "Value of current property". Note: Make sure that Data Source option is set to "Variable".

• Creating "Dependency links" stock section

Select Stock | New | Element iterator | Dependency link.


Add a Header and within it a Label. Name it : "Dependency link".


Insert a "Call to stock section". Choose "Link description" from the pop-up box.


Add a Property iteration section. Select next all items from the pop-up: "Client Role", "Documentation", "Stereotype", "Supplier Role". Note: Make sure that Scope option is set to "Set of properties".


Add two Data controls: "Full name of current property", and the second one: "Value of current property". Note: Make sure that Data Source option is set to "Variable".

• Creating "Iteration by "Class""

  This section will be used for describing any founded class in a Class diagram. There are only three sub-sections used here:
  

  A Header: within it, insert a Label Control and name it: "Class Node Detail";
  

  A Static section: first, add a Label Control, named "Class". Then, insert a Data control. Select "Full name" from pop-up window. Note: make sure that Data Source option is set to "Element property".

  Creating "Class Node Description" stock section

• Select Stock | New | Folder section. Enter "Class node Description" in the pop-up dialog.
  

• In the Area pane, right-click on Folder section and select "Properties". From the pop-up list, choose "Class".
  

• Right-click on Folder section in the left pane and select Insert Nested Section | Element property iterator. Then right-click in the Area pane on the created Property iteration and select Properties | Documentation. Next, right-click on this section area, and add a Data Control named "Value of current property". Note: Make sure that Data Source option is set to "Variable".
  

• Add one more Property iteration section. Click on it in the Area pane, and choose next items from "Properties": "Author", "Author's URL", "Deprecated", "Note", "See Also", "Since" and "Version". Note: Make sure that Scope option is set to "Set of properties".
  

• Add two Data controls: first - "Full name of current property", and the second one - "Value of current property". Note: Make sure that Data Source option is set to "Variable".
  

• In the Scope pane, delete the empty Static section, created by default by the Stock section.
  

• Now you have to add all possible links for a class. Since you have created Stock sections for all of them , it will be easy to insert them. Just right-click in the Scope pane on the Folder section, and select Insert Nested Section | Call to Stock Section. Follow these steps, when adding "Generalization links", "Association Links", "Dependency Links" and "Implementation Links" stock sections. Note: To create "Implementation Links" stock section see "Creating "Generalization links" stock section".

• Creating "Iteration by "Interface""

  This section is similar with "Iteration by Class" except the Label name from the Header. It must be called: "Interface Node Detail".

• Creating "Iteration by "Object (of Class Diagram)""

  In the Scope pane, right-click on the last created "Element Iterator" section, and select Insert Sibling Section | Element Iterator | Object (of Class diagram). Note: Notice that a Static section was created by default.
  

  Add a Header with a Label Control within it. Name this Label: "Object Detail".

  Creating "Object Description" stock section

• From the Main Menu choose Stock | New | Folder section. Enter "Object Description" in the pop-up dialog which will appear.
  

• Open Folder section properties, and from the pop-up list select "Object (generic)". Note: This is the most common description for a object.
  

• In the created Static section, add an "Object" Label Control and "Name" Data Control. Note: When inserting Data Control, make sure that Data Source option is set to Element Property.
  

• Right-click in the Scope pane and insert a Property Iteration section. From its Properties select "Documentation". Then, in its Static section, insert a Data Control. From the pop-up window, choose "Value of current property". Note: Make sure that Data Source option is set to "Variable".
  

• Create one more Property Iteration section. From its Properties pop-up window, select all items except "Documentation" and "Name". Note: Make sure that Scope option is set to "Set of properties".
  

• In the Static section, add two Data controls: "Full name of current property", and the second one: "Value of current property". Note: Make sure that Data Source option is set to "Variable".
  

• Add a Footer.

• Add a "Call to Stock Section". Choose "Object Description".

• Repeat this step to add two more calls for stock sections: "Association Links" and "Dependency Links". Note: they already have been created.

   

• Delete the empty Static section which was created by default (see above).

• Creating "Iteration by "Actor""

  In the Scope pane, right-click on the last created "Element Iterator" section, and select Insert Sibling Section | Element Iterator | Actor. Note: Notice that a Static section was created by default.

   

  Add a Header with a Label Control within it. Name this Label: "Actor Detail".

  Creating "Actor Description" stock section

• From the Main Menu choose Stock | New | Folder section. Enter "Actor Description" in the pop-up dialog which will appear.
  

• Open Folder section properties, and from the pop-up list select "Actor".
  

• In the created Static section, add an "Actor" Label Control and "Name" Data Control. Note: When inserting Data Control, make sure that Data Source option is set to Element Property.
  

• Right-click in the Scope pane and insert a Property Iteration section. From its "Properties" select "Documentation". Then, in its Static section, insert a Data Control. From the pop-up window, choose "Value of current property". Note: Make sure that Data Source option is set to "Variable".
  

• Create one more Property Iteration section. From its Properties pop-up window, select all items except "Documentation" and "Name". Note: Make sure that Scope option is set to "Set of properties".
  

• In the Static section, add two Data controls: "Full name of current property", and the second one: "Value of current property". Note: Make sure that Data Source option is set to "Variable".
  

• Add a Footer.
  

• Add two calls to Stock sections: "Generalization Links" and "Communicates Links".
  

• Add calls to next Stock section: "Extends Links" and "Includes Links".

• Creating "Extends Links" stock section

Select Stock | New | Element Iterator from the Main Menu. In Title field, enter "Extends Links", and choose "Extends Link" from the pop-up list.


Add a Header with one Label Control. Enter "Extends links" in the Label text field.


Add a call to the "Link Description" Stock section.


Add a Property Iteration section. Click on it in the Area pane and next two items: "Label" and "Documentation". Note: Make sure that Scope option is set to "Set of properties".


In the Property Iteration's static section, add two Data controls: "Full name of current property", and the second one: "Value of current property". Note: Make sure that Data Source option is set to "Variable".

• Creating "Includes Links" stock section

Follow the same steps as for creating "Extends Links" Stock section.

• Add a call to "Association Links" stock section.

• Add a "Call to Stock Section". Choose "Actor Description".
  

• Delete the empty Static section which was created by default (see above).

• Creating "Iteration by "UseCase""

  In the Scope pane, right-click on the last created "Element Iterator" section, and select Insert Sibling Section | Element Iterator | UseCase. Note: Notice that a static section was created by default.
  

  Add a Header with a Label Control within it. Name this Label: "Usecase Detail".

  Creating "UseCase Description" stock section

• See "Creating "Actor Description" stock section". Replace "Actor" with "UseCase" where this is necessary.

• Add a "Call to Stock Section". Choose "UseCase Description".

Page footer

• Hide this zone by unchecking it in Setting Resource options box.

Report footer

• Hide this zone by unchecking it in Setting Resource options box.

Tips and Tricks

Launching Documentation Template Designer

Documentation Template Designer can be launched in two ways: direct launch selecting Tools | Design Documentation and through Tools | Generate Documentation selecting Design from the pop-up dialog box. Note: In the last case a project must be already opened. Template Designer will automatically the project which has been specified as default in the Template name line.

Hide/show zones and sections

At times it is needed to hide certain fields or zones of a report. This may be necessary when you are concentrating on a particular zone or section and don't want other zones/sections created. DTD provides the ability to hide zones or sections within them.

To hide a zone, uncheck it in Setting Resource options box.

To hide a section within a zone, click on that section in the left pane and check Hidden from Properties.

Move an element (or group of elements) within sections areas

Moving and scaling of elements is done using the left mouse button. To move an element or a collection of elements to a new place, first select it (them) so that it is highlighted, using Ctrl + the left mouse button. Next press the left mouse button inside the element and move him (them) to its new position.

Moving sections up/down

Every section is being inserted according to the place of your clicks and right-clicks in the Scope pane. If a current order of sections doesn't fit your requirements you may delete the section and insert it again into another place or use "Move up/down" options. These actions can be reached from a pop-up menu, by right-clicking on the needed section

Setting attributes

To set attributes like type, color, label, etc., of an element first select it (using the right mouse button) and next select "Properties". Even if you select more than one element you'll be able to set the properties of only one element.

Cut, Copy and Paste

You can remove elements from the zone by first selecting them, right-clicking the right mouse button and next selecting "Cut" or "Delete". If you choose "Cut", the elements will disappear but are in fact saved in a buffer. You can put them back in the field, or in another zone, by pasting them using Properties | Paste.

For pasting, you can also select the Copy option from Properties and then "Paste". This will have the same effect.

Also, for increasing speed, you can copy whole section into clipboard and paste them in needed places. Just right-click in the Scope pane on a section you need to copy and select "Copy to clipboard". Then, to paste that section, right-click in the Scope pane, select "Insert sibling/nested section", and choose "Paste from clipboard" from the pop-up menu.

Closing tabs

Sometime you need to have all sections tabs opened, sometime you don't. If you want to close one of them, right-click on it in Main pane and click on ''Close".

Aligning elements

Sometimes you have a number of elements and you want to align them in some way, e.g. centered or all starting at the same left position, etc. Select the elements you want to align, then choose one of the alignment options: Left Side, Right Side, Top Side, Bottom Side. There are three more options in that menu: Make same width, Make same height and Make same size. Use them for a more compact form of the zone.

Enabling Conditions

This options is used when the user wants to hide a section (it may be done by checking "Hidden" box), but during one session only. For example: in your created template, right-click on the first Static section of the Element Iteration section, and select Properties. In the Enabling Condition field you'll see next value: < ! $fullName='' >. It means, that the root package name (in this situation) will be not printed, though for all other packages (except "root"), this option will be ignored.

Resizing fields

To re-size a zone/area, position the cursor over its split bar. After the cursor takes the shape of an arrow, click the left button and drag and drop the split bar to its desired position.

Collapse/Extend zones and sections

After you finished working with a zone, for a better navigation in the left pane, Collapse (click on sign "+") or Extend (click on sign "-") located in the upper-left cornet of each zone or section.

Multiple items selection

To select more than one item (labels, data controls, images) from pop-up lists or sections, keep "Ctrl" key pressed. Note: Sometime, you'll need to have Scope option set to "Set of properties".