View source for Documentation:Diagrams in Diagrams

You can place diagrams inside other diagrams in MDriven Designer to create an overview and navigation map for anyone working through a model.

Here is an example of a diagram placed within another diagram:
[[File:Diagram -1.png|frameless|346x346px]]
== Use diagrams as an overview ==
A diagram is a visual representation of model information. You can create as many diagrams as you need, show the same class on multiple diagrams, and use a diagram to organize related [[Documentation:Class diagrams|class diagrams]], [[Documentation:State Diagrams|state diagrams]], and process diagrams.

A placed diagram appears as a small thumbnail on the containing diagram. It is a navigation item, not an editable copy of the placed diagram.

For example, an ''Order overview'' class diagram can contain:
* Classes such as <code>Order</code> and <code>OrderLine</code>.
* A placed state diagram that describes the states of <code>Order</code>.
* A placed process diagram that documents the workflow for handling an order.

This lets you start with one overview and open the detailed diagram when you need it.

Diagrams provide a visual way to organize and navigate your model:
[[File:Diagram -2.png|frameless|436x436px]]
== Diagram types you can place ==
In AppComplete, you can place these diagram types inside another diagram:

{| class="wikitable"
! Diagram type
! What it shows
! Example use in an overview diagram
|-
| [[Documentation:Class diagrams|Class diagram]]
| Classes, attributes, methods, and associations.
| Place a detailed ''Order fulfillment'' class diagram on an overall domain diagram.
|-
| [[Documentation:State Diagrams|State diagram]]
| The states and transitions for a state attribute.
| Place the <code>Order.State</code> state diagram beside the <code>Order</code> class.
|-
| Process diagram
| A workflow: the order in which activities are performed.
| Place a ''Fetching Mail'' process diagram that documents steps such as <code>GoToPostOffice</code>, <code>TalkToLady</code>, and <code>GoHome</code>.
|}

For an introduction to creating and organizing diagrams, see [[Documentation:MDriven designer overview Part 1]]. For guidance on deciding which classes and details to show in each diagram, see [[MDrivenStart:MDrivenStart Diagrams]].

Here are examples of the diagram types available:
[[File:Diagram -3.png|frameless|448x448px]]
== Place a diagram on another diagram ==
# Create or locate the diagram that you want to use as the overview diagram.
# In the repository tree, locate the diagram you want to place.
# Drag that diagram from the repository tree onto the overview diagram.
# Position the resulting thumbnail where it makes the overview easiest to read.

The original diagram remains where it is in the repository. Placing it on another diagram adds another representation for navigation; it does not move, duplicate, or change the underlying model.

For example, you can drag ''DiagramMyNewDiagram'' onto ''DiagramMyFirstDiagram''. The first diagram then shows a thumbnail for the second diagram, while both diagrams remain available in the repository tree.

This illustration shows how a diagram appears when placed:
[[File:Diagram -4.png|frameless|387x387px]]
== Open a placed diagram ==
You cannot edit the contents of a diagram through its thumbnail on the containing diagram.

To work in the placed diagram:
# Double-click its thumbnail.
# Edit the diagram in its own diagram view.
# Use the back navigation arrow to return to the diagram you came from.

You can also navigate directly through the repository tree.

This separation is intentional: the containing diagram is an overview, while each placed diagram keeps its own layout and editing surface.
== Build a useful navigation hierarchy ==
Use placed diagrams to keep a large model readable without removing detail from the model.

A practical structure is:
* A top-level domain overview diagram that contains the most important classes and placed detail diagrams.
* One class diagram for each area of the domain, such as orders, customers, or mail handling.
* A state diagram placed near the class whose state it describes.
* A process diagram placed near the domain area whose workflow it documents.

For example, a mail-handling overview can show a <code>MailItem</code> class, a placed state diagram for its state attribute, and a placed ''Fetching Mail'' process diagram. A reader can see that these artifacts are related, then double-click the appropriate thumbnail to inspect the detail.
== Nested diagrams and recursion ==
A placed diagram can itself contain another placed diagram. This makes it possible to build recursive navigation structures.

For example:
# Place a state diagram and a process diagram on a class diagram.
# Place that class diagram on the process diagram.
# Open either diagram and follow the placed-diagram thumbnails to navigate between the related views.

MDriven Designer limits recursive display to '''two levels'''. This prevents a recursive structure from expanding indefinitely on the screen.

Treat this as an overview feature, not a way to embed editable diagram content. If a diagram appears within another diagram, double-click it to edit the original diagram.
== Keep diagram views focused ==
A class can appear on any number of diagrams, and removing a class from one diagram does not remove the class from the model. Use this to create focused views for different audiences.

For example, a detailed implementation-oriented class diagram may show attributes and associations, while an overview diagram shows only the classes and placed diagrams needed for navigation. The same <code>Order</code> class can appear in both views.

Do not use a nested diagram thumbnail as a substitute for showing the relationships that readers need to understand in the current view. Show the key classes and associations on the overview; use placed diagrams to lead readers to deeper detail.
=== Recurse Diagrams ===

Here is an example of a recursive diagram structure:
[[File:Diagram -6.png|frameless|429x429px]]

Another example of nested diagram organization:
[[File:Diagram -7.png|frameless|419x419px]]

== See also ==
* [[Documentation:MDriven designer overview Part 1]]
* [[MDrivenStart:MDrivenStart Diagrams]]
* [[Documentation:Class diagrams]]
* [[Documentation:State Diagrams]]
* [[Documentation:Autodiagram]]

[[Category:Class diagrams: layout and readability]]
[[Category:Diagrams and Documentation]]
[[Category:Intermediate-Friendly]]
[[Category:Priority 50]]
[[Category:State diagrams: modeling lifecycle]]