Creating Custom Documents
Of the various ways in which you can extract and publish information from your model, the most versatile and yet simplest is to create a Custom Document. This is a Linked Document on a Document Artifact or other element, into which you drag objects from any part of the model, from the Browser window, as Dynamic Content. These objects include Packages, diagrams, elements, attributes and operations.
For each added object, you specify an RTF Template or Fragment to control how the data from that object is to be presented. You can also insert the object as:
- A hyperlink to the same object in another part of the document, or
- (For a diagram) a diagram image, to show just the diagram with no template text or report formatting applied to it
Depending on what you want to communicate in the document, you can type or insert text from any source, and format the text as you require. You can also generate a report just on the parent element, so that it contains only the objects you have added, or include one or more customized Linked Documents in a more extensive report that contains a custom section or sections.
You are therefore creating a unique document to present exactly the information you need, in the sequence you need, and in the format and layout appropriate to each individual item.
Having created the document, you can return to it at any time and automatically refresh it with the latest model changes to the objects within it, quickly add any new objects you require, or delete objects that are no longer relevant.
Whilst you are populating your document you have access to all the facilities of the Document-Edit ribbon, the context menu options and the 'Generate Documentation' dialog, which you can use to develop the document (see the Learn more section).
The model data you add to the document will be presented according to a template. If there is no appropriate system template to extract and display the information you require, you can develop a custom template for that purpose. For example, there is no system template to present details of an attribute or operation in isolation from its parent element, so if you want to, say, show a set of standard attributes from different elements for reference, you will need to develop a template that shows attribute properties. See the Design Custom Document Templates Help topic.
Set up the document
You have two options for setting up the document, depending on how closely you want to associate the document with an object in the model:
- Create or make use of a Package for administrative tasks, and drag onto a diagram in this Package the 'Document' icon from the 'Artifacts' page of the Diagram Toolbox
- Select the focal element for the document you want to create, and drag it onto an appropriate diagram for the purposes of your document
In either case, when the element is on the diagram, right-click on it and select the 'Linked Document' option (for a Document Artifact, you can also double-click on the element).
Alternatively, select the 'Publish > Model Reports > ' ribbon option and type in a name for the document element.
A prompt displays for you to select a template to apply to the whole document. For a custom document you might want only to select a template for each object as you add it to the document; in this case, click on the.
However, if it suits your purpose to apply a base template to the whole document, click on the 'Template' drop-down arrow, select a template name and click on the. The custom document templates will only be applied where the objects are inserted in the document.
Populate the Document
When you drag an object from the Browser window onto the Linked Document, the 'Document Drop Action' dialog displays.
Use this dialog to add the objects to your document in the appropriate format, as explained in this table.
If you are creating a number of links of the same type, create the first link and then press theas you drag each of the subsequent objects onto the document, to avoid displaying the dialog. The links are all of the first-selected type, until you drag an object without pressing the Ctrl key; the dialog displays again and you can change the 'Drop as' option.
You can also select more than one object at a time and drag them into the document together. They will be added to the document in the same sequence as they are listed in the Browser window.
Create Hyperlinks to Model Objects
Drag the object into the Linked Document to the position at which to create the hyperlink.
On the dialog click on the 'Drop as' drop-down arrow and select 'Insert as Hyperlink(s)'.
Click on the . The system creates the hyperlink(s), using the object name as the hyperlink text. You can edit this text if you prefer.
In the unpublished document, Browser window. In the generated document click on the hyperlink to expose the next instance of the object in the document. on the link to highlight the object in the
Insert Dynamic Content
Drag the object into the Linked Document to the position at which to insert the information from the object.
On the dialog, click on the 'Drop as' drop-down arrow and select 'Dynamic Content'.
Click on the appropriate radio button ('All', 'User', 'System' or 'Technology') to display the selection of RTF templates to choose from, and click on the required template.
Click on the . The system extracts information from the object, formats it according to the template, and inserts it from the cursor location.
At any later point, you or another user can refresh the dynamic content in the Linked Document by right-clicking in the document and selecting the 'Update Dynamic Report elements' menu option. Note that this option will reinstate any text you might have deleted from the inserted information.
Insert a Diagram Image
Drag the selected diagram into the Linked Document to the position at which to insert the diagram image.
On the dialog, click on the 'Drop as' drop-down arrow and select 'Insert as Diagram Image'.
Click on the . The system generates the diagram image and inserts it at the drop point.
At any later point, you or another user can refresh the image in the Linked Document by right-clicking in the document and selecting the 'Update Dynamic Report elements' menu option.
Manage Custom Document content
As you add objects to the Custom Document as Dynamic Content or a diagram image, a panel to the left of the content screen lists those objects in the same sequence as they are positioned in the document. You can click on a name in this list to immediately move to the start of that item in the document content.
You can also right-click on a name to select options to perform these operations on the object information:
- Change the Template - redisplays the 'Document Drop Action' dialog so that you can select a different template to act on the selected object
- Highlight section - select and highlight the entire content for the selected object
- Update Dynamic Section - to refresh the content for just the selected object
- Find in Project Browser - to locate the selected object in the Browser window
- Delete section - to remove the content for the selected object
If the list does not include an object you have added, consider if you might have added it as a hyperlink (which is not listed) or whether the selected template is suitable to display the object information.