Worked example: extracting items through child roles and child types (Publisher)

This is one of five worked examples that relate to developing document structures:

The previous worked example extracted all classes in a model ( Worked example: extracting items through model item types

). This worked example develops that extraction of Classes further through the use of child roles and child types to extract items associated with those Classes. In addition, this example demonstrates how to define which item properties are extracted and how to generate items in a table. This example uses the Word output format.

In this worked example, we create a document definition that extracts the following information from a model:

• All the Classes in a model, including the Description property of each Class.

• For each Class: all the Operations it owns, including the Signature property of each Operation.

• For each Operation: all the parameters it owns in a tabular format that shows the Name, Data Type, Mechanism and Description properties of each Parameter.

This example uses the following model:

Each item in the model has its Description property set to 'Description of the <item name> <item type>'. For example, 'Description of the Dispenser Display class'.

In this example, we have the publication model open in Modeler, and a new blank Publisher Document Definition that is ready to be defined.

The extraction of Classes was covered in the Worked Example: Extracting Items Through Model Item Types topic ( Worked example extracting items through model item types (Publisher)

We will use the document structure created in the Worked Example: Extracting Items Through Model Item Types topic and develop it further in the following sections. The document structure created in that example and the generated text for the Classes in the model are as follows:

After the heading and description text that is generated for each Class, we want to generate a heading for each Operation that Class owns. For each Operation, we want to generate its Signature property prefixed by 'Signature:'.

To do this we extend the definition of the Class model item type that we created in the document structure, now called 'Classes in the Model'.

We want to extract Class owned Operations, and we do this by extracting Operations that are related to the owning Class through the automation interface role (association) that is named Operation.

Tip: The Modeler Help for the Modeler Automation Interface documents the relationships between model items types.

In the document structure, we select the 'Classes in the model' item, click the

Add Modeler Child Role Section, and then select the Operation role.

We now add the Operation child type to the Operation role by selecting the Operation role in the document structure, clicking the

Add Modeler Child Type Section button, and then selecting the Operation child type.

Note that the

icon indicates that we have added an Operation child type, rather than an Operation child role.

We select the Operation child type and can see that the Title Text property is set to Operation. We want the heading that appears before the Operations in the generated document to be named Operations of Class, so we change the Title Text property to 'Operations of Class'.

In the Properties pane, we can see that the standard properties of each Operation will be extracted, that is, Name, FullScopedName, Description and DynamicUmlClassName.

We want to extract only the Signature property, so we delete the four default properties by selecting each property and clicking the

Delete Item button in turn.

To add the Signature property, we select the Item Properties To Generate entry, and then click the

New Item button. By default, Publisher adds the Name property, so we change it to the Signature property.

We save the changes and then generate the document. The Word document includes the following text.

You can see that a heading has been created for each Operation of the Class, and in each case the Operation's Signature has been generated.

We have defined the extraction of Operations from the model, and now we want to define the extraction of the Parameters that each Operation owns.

Unlike the Class and Operation extraction, we do not want the Parameters to have headings in the generated document; instead, we want to present the Name, Mechanism, Type and Description properties of each Parameter in a table after the Operation signature.

We need to further develop the Class model item type we added to the document structure, which is now called Classes in the Model.

We select the Operations of Class child type, click the

Add Modeler Child Role Section button, and then select the Parameter role.

Unlike the definition of the Operation extraction, we are going to define the extraction of the Parameters through a child role, rather than through a child type (only Parameter child types can be extracted through the Parameter role).

Tip: Defining item extractions through a child role can be useful when the child role returns items of different types and you want all those items to be extracted in the same way.

We do not want to generate a heading for each Parameter, so we select the Parameter role, and then set the Generate Title property to Don't Generate.

We want to generate the Parameter properties in a table, so we set the Organize As Sections/Table property to In Table.

Note that when the Organize As Sections/Table property to In Table, you can include the title of the table in the List of Tables section by setting the Generate Title property to Generate (Word output format only).

Finally, rather than extracting the standard Name, FullScopedName, Description and DynamicUmlClassName properties; we want to extract the Name, Data Type, Mechanism and Description properties of each Parameter, so we change the extracted properties accordingly.

We save the changes and then generate the document. The Word document includes the following text.

You can see that no headings are generated for the Parameters and instead each Parameter is generated as a row of a table.

In this worked example, we have demonstrated how to extract items through their model item type, how to extract related items through child roles and child types, and how to present that information in a tabular format.