Together’s template-based document generation engine stores its templates as plain text files. Normally created by the Together Documentation Template Designer, these plain text files usually have a file extension of tpl. For this reason many people refer to them as tpl files. The template designer is included as standard with the Together 2006-2008 products.

To create a new document generation template file, select File|New|Other… from Together’s main menu bar. This displays the New wizard (see Figure 1).

Figure 1: The New | Other…menu

When the New wizard appears, expand the Modeling node if necessary and select the Documentation Template entry. Then press the Next >  button (see Figure 2).

On pressing the Next > button, the second page of the wizard (see Figure 3) is displayed. Enter the full name and path for  the new template (tpl) file.  You can also choose whether the new template is going to be used to generate HTML frameset files or straight forward document files (Document Template). Usually we choose the straight forward document files. Instructions for creating  HTML frameset templates is an advanced topic and is not covered it in this document.

The second page of the wizard also contains a Model Type field. The only value available for the Model Type field is UML Meta-model. This is confusing. This field ought to be removed long ago. In much older versions of Together, gendoc supported templates that worked against ‘models’ formed from a graphical user interface design tool. That GUI design tool was not popular and not widely used. Support for it was dropped when Together moved to the Eclipse platform. However, only the relevant value for this field was removed, not the whole field. In addition, the single value does not restrict the generated documents to UML models only; BPMN and ERD model content may also be included.

Figure 3: Specifying the name and type of a new document template

Reusing the Templates that Ship with Together

The document generation templates that ship with Together provide a good source of examples. You find them in a particular plug-in directory of the Together installation. This can be painful to locate on a frequent basis but there is a way to make these templates easier to open in the template designer. What we do is create a general purpose Eclipse project that uses the plug-in directory as a non-default location.

To do this:

1. Select the File | New | Project… menu item from Together’s main menu bar. This displays the New Project dialog.
2. Select the General |  Project item in the New Project dialog. Then press the Next > button.
3. Name the project. I typically call it something like Together Gendoc Templates
4. Then, very importantly, uncheck the Use default location checkbox
5. Specify the plugins/com.borland.gendoc.core_8.1.3.v20080305-1200/templates directory as the location for the project.
6. Finally, press the Finish button.

The templates can now be opened and browsed within this new project, but remember to use the Eclipse Navigator view not the Model Navigator view because template files are not model files. In the Navigator view, double click on any of the *.tpl files to open that template in the template designer.

Notes:

• The version of the plug-in may be slightly different in different versions of Together and the plug-ins directory is located under an eclipse directory in later versions.
  
  
• Although it is tempting to edit and change the templates that ship with Together, this is not recommended. The templates should be considered only as a source of examples to learn and copy from.