It is good practice to develop and store custom templates separate from the templates that are supplied with SoDA. We recommend that, like supplied templates, you organize custom templates by product domain. For example:
C:\MyTemplates\rose
C:\MyTemplates\reqpro
(To enable tight integration, you must organize templates in product-specific folders such as these.)
Custom locations must have read/write privileges. They can be on a local or network drive.
You use the SoDA Options dialog box to identify these custom paths for SoDA to search.
To customize a SoDA template:
1. Master the key concepts for template customization.
2. Identify the domain that contains the information you need to document.
3. Do one of the following:
§ Choose a Template as a starting point, normally one of the supplied templates for that domain.
§ Create a new template based on soda.dot.
4. Use the Template View to add, modify, and/or delete SoDA commands as needed:
Note: If you work in the document, show the existing SoDA commands so you can be sure the cursor position is correct.
5. Save the template in a user-defined, product-specific folder.
6. Test the template to be sure it works as you want it to.
7. Repeat steps 4-6 until complete.
A good understanding of your information as it exists within each domain and a detailed document plan will ensure that the placement of SoDA commands within a template will yield the results you want after generation.
Note: To read about the annotation differences between the Word versions, see Word 2000 and Word 2002 Comparison.
To make custom templates available to other users, you store them in a location that is globally available. This can be one of these locations:
§ (Recommended) A user-defined location that you make known to SoDA as a user template path in the SoDA Options dialog box.
Additionally, we recommend that user-defined locations include the product domain, such as C:\MyTemplates\rose.
§ The default template directory for the appropriate product, such as:
…Program Files\Rational\SoDAWord\template\rose
You can make custom templates available for tight integration, which means they are included in the list of the reports that you can select for SoDA reporting from within other Rational tools.
To make a custom template available for tight integration, perform each of these steps:
Step |
Do this |
Details |
Make the template generic. |
Remove the arguments from the OPEN command. |
Modify the OPEN command and delete the values for all arguments by selecting each value and pressing Backspace. A prompt to complete the OPEN command appears each time a user runs the template. At that time, the user supplies the arguments that are appropriate for the current use. |
Provide a name to identify the template in the list of reports. |
Add a title to the document properties. |
Choose File > Properties, click the Summary tab, and enter a unique name for the template in the Title field. This name is displayed when you execute the SoDA Report generation utility in products such as Rose and Requisite Pro |
Save the template in a globally available, product-specific folder |
Create a folder structure for custom templates, and identify that location for SoDA. |
1. Create the folder structure for custom templates in your file system. 2. Create a folder for each product domain in that structure. 3. Add the paths to the list of user template paths in the SoDA Options dialog box. |
(Optional for Rose templates) Associate the template with a particular object. |
Add a keyword for the object to the document properties. |
Choose File > Properties, click the Summary tab, and enter the name of the object in Keyword field, with no spaces or punctuation and using the same capitalization. You can enter any object that is available for an OPEN command, such as Package, Class, UseCase, and Component. Model is implied, so it is not necessary to use it as a keyword. When an object in the model is selected, either in the Browser or in a diagram, and you click Reports > SoDA Reports, a keyword affects the list of reports as follows: § Reports that are associated (by keyword) with this object appear at the top of the list for easy selection. § When you select one of these reports, all argument values are supplied based on the context of your selection. § Reports that are associated with a different object are excluded from the list. When no object in the model is selected, the presence or absence of a keyword has no effect on the list. In that case, all Rose templates set up for tight integration are included, and you are prompted to supply the argument values. |