Overview

A diagram builder is a floorplan dedicated to building a model with the use of a diagram.

A diagram is a representation of a model with graphical elements; shapes represent objects, and connectors between shapes represent relationships between objects.

For some models, a diagram represents a subpart of a whole model, and is a convenient visual way to understand it from a given point of view. Building this type of mod

Usage

Use a diagram builder:

When you need to edit a model that needs to be represented by a diagram.
To define a model that has a graph structure (by opposition of a tree or a list).

Don't use a diagram builder:

To define a list of objects or a hierarchy of objects.
When the structure of relationships is simple, or the number of objects is limited, you are better off using lists, trees, or tree tables. In certain cases, you could use a diagram component as an alternative way to display and navigate, but not to edit.
If you need only to display a diagram: Prefer to integrate the diagram component into another floorplan, like the object page floorplan.
Inside a Flexible Column Layout.

Structure

The diagram builder is organized around the diagram displayed in the main area.

The placement of the toolbars, left side panels, diagram, secondary view and right panels is given by the left to right reading convention. As a result, the interactions also follow the same rule: an interaction done in an area on the left or above will impact the content of an area on the right or below. The opposite is rare, will have less impact, and is used as a complementary behavior only.

The main toolbar
The diagram toolbar
The diagram
The object list panel
The properties panel
The auxiliary views bar
The auxiliary view

Existing objects are taken from the Object List panel to be inserted as a shape into the diagram. In that case, the model reference them.

New objects and connectors are created with commands in the toolbars or the contextual menu. They are instantiated into the diagram and embedded into the model.

The properties of objects and relationships are editable in the Properties pane.

Assembly results (e.g. validation errors, resulting data preview) are displayed in auxiliary views.

The main toolbar contains several generic sections and optionally a specific “Diagram” section. The organization of the commands into sections follows the guidelines of the main toolbar (guideline to be defined)

The commands that impact a diagram are:

File commands
Verifying the model, executing the model will create feedback on shapes or connectors if messages concerning objects or connectors have to be displayed.
Edition commands
Undo, Redo, Selection mode like cursor / lasso / area)
Removing a shape from a diagram will remove the object from the model and its relationships. In some cases, it will also delete the object.
Removing connectors between shapes to delete relationship between objects.
Insertion commands
Adding objects in the diagram with create a shape in the diagram.
Creating shapes in the diagram will create new objects in the model.
Connecting shapes with connectors will create relationships between objects inside the model
Elements display commands
Moving shapes and connectors in the diagram, as well as changing the shape of connectors, will improve the readability of the diagram resulting in a better understanding of the structure of the model.
Showing and hiding objects/shapes and links/connections.
Diagram viewpoint commands
Panning and zooming commands will modify the visible part of the diagram.
Commands concerning shape placement and shape modifications (i.e. moving shapes, resizing shapes, changing the shape of connectors) are optional in the main toolbar

false

Do put commands that modify the diagram and the model (objects and relationships) in the Edit or Insert sections.
Do put commands that modify the diagram (shapes and connectors) without altering the model (object’s and relationships) into the Diagram section.

The diagram toolbar is an additional and optional toolbar that contains commands that impact the diagram area only.

These commands are implicitly grouped by section with the same logic order as the main toolbar. Sections are separated by a vertical separator, but the name of the section is not indicated.

Most of the sections are justified on left but it is possible that some last sections are justified on the right.

false

Use a diagram toolbar when there is not enough space in the main toolbar when the width of the screen is 1440px

dont

false

Don't use a diagram toolbar to find efficiency. You are better off providing good contextual menu content to access to commands on selected objects and standard keyboard shortcuts.

Object List Panel

The Object List panel is a convenient way to quickly insert existing objects or instantiate templates by a drag and drop into the diagram.

The Object List panel structure is described in the contextual side panel guideline.

A diagram can be built with two kinds of entities, displayed in two different lists:

Objects that have their own lifecycle and exist independently of the diagram. In this case the diagram references these objects (aggregation). This list is compulsory.
Templates that are instantiated as objects in the diagram and cannot exist independently of the diagram (composition). This list is optional.

In addition to the drag and drop (this type of interaction does comply to accessibility standards), an insertion command must be displayed in the main toolbar and/or in each list item’s context menu.

dont

false

Don'ts

Don't mix in the same list/tree both the object to be used and the templates to be instantiated.
Don't use the object list panel to display objects of the diagram.

Diagram

The diagram is the main area of the builder. It is always visible and can take most of the floorplan space.

A diagram displays shapes and connectors to represent objects and relations of a model that have a structure of a graph.

A shape is a symbolic representation of a given type of object and connectors are links between shapes to represent relations between objects. Some shapes can be containers to represent relation of composition (e.g. Swim lanes contain activities in a BPMN diagram).

Modeling with a diagram requires that you firstly specify many characteristics:

The type of objects and relationships allowed in the model and how they are represented.
The composition/alignment rules: how elements can be visually disposed by default or interactively with assistance.
The behavioral rules: how an interaction in one element affects itself and the others.
The validation rules: how each object/relationship is considered as valid or not, and and whether the whole assembly is also valid.

See details in the Diagrams Component.

false

Have a homogeneous set of shapes and if possible, the same shape to represent a given type of object across all the diagrams.

dont

false

Don’t display the same type of object with the same level of detail/content as two different shapes.

Auxiliary View Bar

The auxiliary views bar allows clear separation of the diagram area from the auxiliary views area where one or several distinct views may be displayed.

This bar allows the following to happen:

Indicate the title of the active auxiliary view among all the auxiliary views that have been switched on.
To switch between auxiliary views (if several are switch on) because they use the same area.
Optionally, it can give access to the commands on the currently active view content.

Tabs are displayed on the left, commands on the right.

Order of the tabs:

The views are listed following the logic of how they are read. For example, the message view is displayed before a data preview view, because it is only when no errors show in the message view that data displays in the data preview view.

Auxiliary View

An auxiliary view displays information of the edited file that cannot be properly displayed in the diagram.

The builder can have one or several auxiliary views defined, each one having a specific and exclusive content.

The content of each auxiliary view can depend on the currently selected objects in the diagram or can ignore it.

dont

false

Don’t use an auxiliary view if the task needs the view content but does not need the diagram. These are cases when displaying the diagram and the view simultaneously is not necessary. Instead, use a workspace, or switch the main area content, or use a dialog box.

Properties Panel

The properties panel allows viewing and editing of file, object and relationship properties that are displayed in the diagram.

It can take two forms: contextual side panel or contextual side sub-panel. The visual difference between the two is in the header, so it allows information to be arranged in a hierarchy, and the user will be able to activate the properties of the file, or the properties of the currently selected object.

Properties of Internal and External Objects

The diagram may contain internal object and external objects: Internal objects have the same lifecycle as the diagram, external objects have their own lifecycle.

The user must understand what is saved within the diagram when executing the save command.

A property pane of an external object can display both properties of the object but also information related to it.

false

Do's

Do display the necessary information for the building task extracted from the external object page, while respecting the same structure of the information.

Do display the non-editable properties of the external object in read only.

Do display the object-related information after the properties (e.g. list of linked objects). Do make them editable.

Do provide a command in the panel to open the external object in another browser’s window.

dont

false

Don'ts

Don’t display the whole object page of the external object in the property pane.

Other Components

dont

false

Don'ts

Don’t use a navigation tab bar to switch from one diagram to another. Having a navigation tab bar would mean that several diagrams will have a common lifecycle. Due to the complexity of the diagram content and the multiple interactions both in it and with other areas, we prefer to save one diagram at a time and so have each diagram lifecycle is independent from others.

Don’t put an explorer pane to list all diagrams and don’t put a tab container to switch between opened diagrams either. Instead, give space to the diagram. To edit several diagrams simultaneously, use several diagram builders in different tab pages of the browser.

Behavior and Interaction

Interactions Between the Object List Panel and the Diagram

<div> <div>Interaction in the Object List Panel</div> <div>Consequence in the Diagram</div> </div> <div> <div>Select an object.</div> <div> <p>None.</p> <p>The currently selected objects in the object list are different set from the currently selected objects in the diagram.</p> </div> </div> <div> <div>Drag an object and drop it into the diagram.</div> <div>Add a new shape in the diagram.</div> </div> <div> <div>Drag an object and drop it over an element in the diagram.</div> <div> <p>Add a new shape and connect it to the shape on which it is dropped.</p> <p>If several links can be created, display a context menu to let the user choose or, if by design, impose a choice by default.</p> </div> </div> <div> <div>Select an object and then select the Insertion command in the toolbar.</div> <div>Add a new shape in the middle of the screen.</div> </div> <div> <div>Filter list, Search, Reorder list items, etc.</div> <div>N</div> </div>

<div> <div>Interaction in the Diagram</div> <div>Consequence in the Object List Panel</div> </div> <div> <div>Select an object.</div> <div>None.</div> </div> <div> <div>Drag an object from the diagram and drop it over the Object List panel.</div> <div>No consequence in the Object List Panel but, as it is the opposite gesture of adding, it removes the element from the diagram.</div> </div>

Interactions Between the Diagram and the Property Panel

<div> <div>Interaction in the Diagram</div> <div>Consequence on the Property Panel</div> </div> <div> <div>Unselect an element (No element selected).</div> <div>Display the properties of the file in the Contextual side panel.</div> </div> <div> <div>Mouse over an element.</div> <div>None</div> </div> <div> <div>Select the output shape.</div> <div> <p>If file properties and output shape properties are displayed in one panel, display them in a Contextual side panel,</p> <p>otherwise display output shape properties as a normal shape in a Contextual side sub-panel.</p> </div> </div> <div> <div> <p>Select a shape (except an output shape)</p> <p>or select a connector.</p> </div> <div>Display properties in a contextual side sub-panel.</div> </div> <div> <div>Insert a new element (the new element is selected).</div> <div>Display the properties of the element.</div> </div> <div> <div>Delete the selected element (No element remains selected).</div> <div>Display the properties of the file.</div> </div> <div> <div>Select another element to the currently selected objects (multi-selection case).</div> <div>Display the panel of the last selected object.</div> </div> <div> <div>Remove a element from the selected objects (multi-selection case).</div> <div> <p>If no element left selected, display the properties of the file</p> <p>otherwise do nothing special. (Keep the last content).</p> </div> </div>

<div> <div>Interaction in the Property Panel</div> <div>Consequence on the Diagram</div> </div> <div> <div>Mouse over an item that is represented in the diagram (e.g. linked objects).</div> <div>Highlight the element with a different feedback that the currently selected object.</div> </div> <div> <div>Select an item that have that is represented in the diagram.</div> <div>To provide navigation from objects to objects through the property panel, the element in the diagram is selected and the property panel is now referring the this new element.</div> </div> <div> <div></div> <div></div> </div>

Interaction Between the Diagram and the Auxiliary Views

<div> <div>Interaction in the Diagram</div> <div>Consequence in the Auxiliary View</div> </div> <div> <div>Add/remove/modify an element (i.e. modify the model through the diagram).</div> <div>The view is updated if it is possible to calculate the view content after each model changes (e.g.: validation of the diagram and display of errors in the view).</div> </div> <div> <div>The view is updated if it is possible to calculate the view content after each model changes (e.g.: validation of the diagram and display of errors in the view).</div> <div> <p>Several behaviors are possible:</p> <p>Case 1: update the content (e.g. execution of the dataflow until the selected shape and display the data).</p> <p>Case 2: filter the content that is linked to the currently selected items (e.g. errors).</p> <p>Case 3: keep the content but select in the auxiliary view the items linked with the currently selected items.</p> </div> </div> <div> <div>Mouse over an element.</div> <div> <p>According to the behavior chosen when selecting an element (see above):</p> <p>Case 1: Nothing.</p> <p>Case 2: Highlight what is linked to the currently selected items.</p> <p>Case 3: Highlight what is linked to the currently selected items.</p> </div> </div> <div> <div>Double click on a sub-element that is correlated with one auxiliary view content (e.g. a shape badge counts the messages).</div> <div>Selects the element and activates the auxiliary view (e.g. the messages view).</div> </div>

<div> <div>I <strong>nteraction in the Auxiliary View</strong></div> <div>C <strong>onsequence on the Diagram</strong></div> </div> <div> <div> <p>Select an item in the auxiliary view</p> <p>(</p> </div> <div>s</div> </div> <div> <div> <p>Select an item in the auxiliary view</p> <p>(</p> </div> <div>highlight the associated elements and/or or display a temporary representation.</div> </div> <div> <div></div> <div></div> </div>

dont

false

Don't switch views when selecting an element in the diagram. The selection of a specific symbol inside or over the shape can activate or switch a view (e.g. a badge on a shape can activate the Message Auxiliary View)

Interaction Between the Auxiliary View and the Properties Panel

The auxiliary view cannot interact with the property panel directly but, indirectly by the combination of behaviors: interaction in the auxiliary view impacting the diagram and the interaction in the diagram impacting the property panel.

Switching on/off Auxiliary Views

One or several commands in the main toolbar switches on and off the auxiliary views bar and displays one of the auxiliary views: the first tab by default, otherwise the last one active in the user session.

Other commands can activate an auxiliary view and, if necessary, also display the auxiliary views bar. (e.g. the command “Preview Data” in the contextual menu of a shape of a “Graphical View” will display the “Data Preview” Tab). In this case the command must be explicit and should concern one of the auxiliary views.

To hide the auxiliary views bar and the current bar, hide the current auxiliary view with the command in the main toolbar.

false

Do use an explicit and dedicated command to activate an auxiliary view.

dont

false

Don't activate automatically an auxiliary view when executing a command with a purpose that is different (e.g. “Validate”). Instead, let the user do it in two steps, for example a command for Validate, another to see the errors in the auxiliary view.

Examples

DWC - Data Builder - Graphical View Editor

DWC – Data Builder – Entity-Relationship Model

Resources

Diagram Component

Contextual Side Panel

Contextual Side Sub-Panel

Object List Panel

Support

If you have any questions or feedback about this page, please contact our team. For further information and questions in regards to the Design System, please visit the DNA Design SharePoint.

Overview

A diagram builder is a floorplan dedicated to building a model with the use of a diagram.

A diagram is a representation of a model with graphical elements; shapes represent objects, and connectors between shapes represent relationships between objects.

Usage

Use a diagram builder:

Don't use a diagram builder:

Structure

Main Toolbar

Diagram Toolbar

Object List Panel

Diagram

Auxiliary View Bar

Auxiliary View

Properties Panel

Properties of Internal and External Objects

Other Components

Behavior and Interaction

Interactions Between the Object List Panel and the Diagram

Interactions Between the Diagram and the Property Panel

Interaction Between the Diagram and the Auxiliary Views

Interaction Between the Auxiliary View and the Properties Panel

Switching on/off Auxiliary Views

Examples

Resources

Support