Introduction

Introduction

A diagram is a component that displays shapes and connectors in a 2D plane to represent a model that has a structure.

Shapes represent objects of the model (see Shapes guideline).
Connectors represent relationships between objects (see Connectors guidelines).

Each type of object and each type of relationship can have distinct representations. Their style, geometric shape, and content layout gives information to differentiate them. Nevertheless, their anatomy, interactivity and behavior share a common base describe in the Shapes guidelines and Connectors guidelines.

As a component, the diagram is a rectangular area that can be displayed in many places from being the main area, highly interactive, (e.g. in the Diagram Builder Floorplan) to being a simple visual component, static (e.g. a thumbnail in a card) : See the “Where to use a diagram” in Usage section and “Which level or interactivity to choose” in Best Practices section.

To view, explore, arrange, or edit this assembly of shapes and connectors (called also a diagram!), the diagram component is made of several tools displayed in 2 layers: the canvas and the overlay (see section Anatomy). Also, some commands may be accessible out of the component in a toolbar above the diagram or in the main toolbar. These toolbars are not described in this document.

On any tool in the overlay, on any shape or connector or on the background of the canvas, there is a context menu defined.

information

Disclaimer:

This guideline is aligned with the UX Consistency Product Standard for colors, theming, typography and iconography (Fiori 3 Quartz Light), which might not be implemented yet in the product on which you’re working.
For designers who work on modeling, this guideline describes how we want to unify modeling across our products. For developers of the Galilei library, this guideline acts as specifications for future developments.

What does this mean for you?

Usage

When to Use a Diagram

Diagrams are used to display models having a non-trivial structure of nodes and links:

Graphs are a type of structure in which each node can have zero to several links to other nodes (including himself).
Multi-parent hierarchies are graphs where each node can have one or several parent/child relationships.
Trees are graphs where each node has one parent (except the root node) and zero or several children.

Lists are not displayed by a diagram.

Trees that can be displayed in a Tree or a Tree Table component shouldn’t be represented by a diagram.

The diagram visualizes the structure of a model.

Depending on whether you’re referring to a diagram, a model, a structure or the display framework, different terms are used:

<div> <div>Diagram</div> <div>Model</div> <div>Structure</div> <div>Display Framework</div> </div> <div> <div>Shape</div> <div>Object</div> <div>Node</div> <div>Symbol</div> </div> <div> <div>Connectors</div> <div>Relationship</div> <div>Link</div> <div>Link Symbol</div> </div>

Where to Use a Diagram

The diagram component can be used in many floorplans. We recommend choosing the right floorplan from the list below for the tasks the user will perform with the diagram, and then, once chosen, providing the appropriate behavior of the diagram within this floorplan:

In a diagram builder floorplan
In a specific tab-page
In an object page, with other components
In a story as a story widget
In a card

Diagram in a Diagram Builder Floorplan

Use a builder floorplan diagram when the main purpose of the user is to edit the model.

The diagram is the main area of the diagram Builder Floorplan and can interact with the content of the other areas.

See the Diagram Builder floorplan for details

Diagram in a Specific Tab-Page

Use a diagram component inside a specific tab-page of an object page when the main purpose is, while viewing or editing the object, to view its relationships and its linked objects.

The diagram toolbar is at the top of the tab-page area and respects the tab page horizontal padding.

This diagram toolbar contains specific actions on the diagram. The components inside this toolbar should be arranged in a logic consistent with the one defined in the Table Bar (Fiori Design Guidelines).

The diagram takes all the rest of the area of the tab page without any margin or padding.

Diagram in an Object Page, with Other Components

Use the diagram in the page or a tab page with other components when the diagram is small or if the importance of the diagram information is not worth a specific tab page.

The diagram toolbar and the diagram respect the tab-page paddings like any other components.

The height of the diagram depends of the width. The ratio width / height is 4:3.

The size of the diagram can be limited in some case to avoid taking unnecessary space in the page.

A diagram toolbar is displayed above the diagram. The components inside this toolbar should be arranged in a logic consistent with the one defined in the Table Bar (Fiori Design Guidelines).

An inconvenience of this layout is that there can be some interactivity difficulties with the scroll of the page: According the method and the device used and the height of the diagram, the user may need to move the pointing device on the 2 rem margin in order to scroll the page otherwise the focus would be on the diagram and it would pan the diagram.

When the pan is not allowed, this problem does not exist.

Use a diagram as a Story widget when the diagram needs to be displayed with other widgets in a story.

As a story widget, the diagram widget follows all the rules and behavior of the widgets for resizing, contextual menu of the widget, etc...

The colors representing the states of the shapes follows the colors of the story and overrides the one defined by default in this diagram guidelines.

Diagram in a Card

When the user clicks on the card or the diagram in the card, he expects to open the object with the diagram in it.

Anatomy

The diagram component is made of two layers:

The canvas (A) on which the model is represented.
The overlay (B) on which some tools interfaces (C) are drawn in device coordinates (pixels)

Canvas

The canvas is the infinite area on which the shapes and connectors are drawn.

The is the visible part of the canvas (E). It is rendered on the viewport (D) through a translation and scaling transformation.

The world coordinate window is defined by:

Its center (in 2D world coordinates)
The viewport width and height (in pixels)
The zoom scale (factor)

When designing shapes, in world coordinates, we can choose any scale (centimeters, miles, or any unit). By convention, shapes are designed to have an optimal display when the zoom=100% and the unit taken is the pixel.

The background color is white.

Shapes and connectors are described in the Shapes guideline and Connectors guideline.

The canvas can also display artifacts. Artifacts are additional representations that are displayed in the diagram but are not representing objects of a model:

Currently Selected Objects rectangle area (see Selection in Behavior and Interactions chapter)
Groups of shapes (TBD)
Text annotations (TBD)

Overlay

The overlay is the layer that displays over the viewport some tools to work with the diagram such as:

The control pad (A)
The overview (B)

The overlay has exactly the same size as the viewport.

Components are positioned relative to a corner or a border of the overlay area.

Components background and stokes are 50% transparent to lighten the presence of these tools in the normal state and opaque when the mouse is over.

Components have usually a fixed size: it doesn’t react to the pan and the zoom of the diagram, nor the dimensions of the overlay area.

Control Pad

Currently, the control pad is displayed at the top right corner of the overlay. It gives the access to the commands that changes the translation and scaling: zoom in, zoom out, move left, right, up and down and Fit to screen.

If displayed, the control pad must be the same for all diagrams.

Don’t change the display or the behavior of the control pad for one type of diagram specifically.

The control pad has a context menu.

Overview

The overview is a window displaying the whole diagram as a map and the visible area of the diagram on that map.

It helps to user to understand where he is seeing but also to translate the diagram by moving the visible area rectangle.

More specifications will come in the future.

Behavior & Interactions

Orientation when Displaying a Diagram

When relationships carry a notion of sequence or a notion of hierarchy between objects, an orientation of the diagram must be defined:

Horizontal orientation: a child is at the right of the parent; a successor is at the right of its predecessor.
Vertical orientation: a child is below the parent; a successor is below the predecessor.

When a type of diagram needs an orientation, a user research is required to know what the common usages are and what available orientation may be proposed to the user

This type of diagram is mostly displayed horizontally.
This type of diagram is mostly displayed vertically.
Both horizontal and vertical orientation are used.

In this last case, the main usage will give also the default orientation when creating a new diagram. A command must be available to the user to change to orientation, available when the user edits the diagram, at any time even if it would be used once at most. This command should not be in the overlay because it will be rarely used.

When the user will change the orientation, the value can be stored per diagram type and per user to be used as the default orientation for the next new diagram.

The auto-layout must support both orientations if they are defined.

Shapes should support the same orientations as the diagrams they are included.

Auto-Layout

The auto-layout consist of calculating the position of a part or all shapes of a diagram.

This calculation can be automatically and implicitly done in some task:

Create a new object linked to the previous one (using a simple click)
Collapse and expand a shape

This calculation can also be explicitly called by a specific command. This command is a one-shot command. Don’t use a toggle command.

In some cases of low level of interactivity, where the user cannot interact with the shapes to move them, the auto-layout is permanent. Any modification of the model, any collapse/expand will launch the auto-layout.

The auto-layout depends on the orientation of the diagram, if it has been defined.

The auto-layout does not zoom or pan.

For more details, see Auto-layout guidelines

Selection

One or more objects are selected by clicking on the shape.

Some sub-parts of the shape can be selected directly (such as input fields in shapes when the diagram is in view mode) or indirectly (such as a row in a list of table columns in a table shape). In that case, the user needs to first select the shape, then the row.

Once selected, the shape has a “selected” representation. (See Shapes guidelines and Connectors guidelines)

Multi-Selection

The combination of a mouse click and the Ctrl key adds or removes an object from the currently selected objects (CSO), that is the set of zero to many objects that are selected at a given moment.

The CSO is reset by clicking on the canvas background.When there are several objects selected,

A rectangle area containing all CSO is displayed.
Each shape has a “selected” representation.

Zoom and Pan

When displaying an existing diagram, the previously saved center and zoom is used.

If it is a new diagram, the zoom is 100%. The default value of the center does not impact the user experience. But by convention, the center or the top left can be the (0,0).

The user can pan the diagram by:

Dragging the canvas (not a shape) with the mouse
Dragging the visible area in the overview tool
Using the arrows of the control pad for a step by step movement
Using arrow keys

When the user drags a shape or the extremity of a connector to a place that is not visible, there can be an animation to pan diagram in order to make visible to place to drop. Don’t mistake this with the drag and drop out of the diagram area which is another gesture.

The user can zoom the diagram by:

Using the mouse scroll wheel (continuous variation). In that case the zoom center is the mouse cursor.
Interacting with a zoom slider (continuous variation while moving the slider)
Clicking on the zoom-in, zoom-out command
Step by step zoom is done with actions on the control pad, toolbars or keyboard shortcuts.

The range of the zoom depends on the type of diagram. (Best practices to define the min and max TBD).

The Zoom Center

The zoom center is the point in the world coordinate window that does not moves on the viewport when zooming.

The default position of this center is the center of the world coordinate window.

There are cases where the zoom center is given by the position of the mouse cursor:

When using the mouse wheel
When using the up and down keys while panning

Step-by-Step Zoom

The step by step zoom must take a finite number of values. (List of steps values TBD) One of this value is zoom=100%.

The “Zoom in” or “Zoom Out” command change the zoom scale by taking the previous or the next scale among a list of zoom values.

The zoom-in and zoom-out can’t be a multiplication or a division of a factor because when the zoom is modified by a continuous variation method (mouse wheel, zoom slider) or a “Zoom to Fit” command, the value is no longer a step value. The user cannot return to 100% by using zoom-in and zoom-out commands. To avoid this, these commands must round the value to the nearest scale step value before going to the next scale step.

The following algorithm set which value that should take the zoom from a list of {z(i)} steps.

Consider the value zoom z between the zoom step zi and the zoom step z(i+1).

We calculate the “middle” zm(i) of z(i) and z(i+1). Such as zm(i) /z(i) = z(i+1) / zm(i).

So zm(i) = sqrt ( z(i+1) * z(i) )

If z <= zm(i) then a “Zoom In” command sets the zoom to z(i+1) otherwise to z(i+2)

If z <= zm(i) then a “Zoom Out” command sets the zoom to z(i-1) otherwise to z(i)

With that the user can easily reach again the 100% zoom value with a step by step zoom.

Resize

In most of the cases, when the diagram component is resized, the zoom and the center of the world coordinate window don’t change.

The zoom and the center can change due to some design constraints like for example:

The diagram has a low level of interactivity (without manual zoom and pan) and all the diagram must be visible. So, the zoom is automatically adjusted to see all the diagram.
The diagram has input fields that must keep the same size, so the zoom cannot change.

Zoom to Fit

This command (sometimes called “Fit to Window” or “Fit to Viewport”) displays all the shapes in the viewport with a padding of 1rem in order to have the biggest zoom.

One of the vertical or the horizontal dimension define the constraint of zoom and positioning. In the other dimension, the diagram is centered.

Because the best representation of shapes is at zoom 100%, the maximum zoom is 100%. So, if the diagram is small enough to be displayed entirely on the viewpoint, the “Zoom to Fit” displays the diagram at zoom 100% and center it.

There is a 1-second animation to go from the first world coordinate window to the second.

This command has two behaviors:

As a push button: When the diagram is the main area of edit, where the user can zoom and pan, this command adjusts the zoom level and re-centers the diagram to show all symbols.
As a toggle: When the diagram is an auxiliary area of edit or view, when the pan is locked for example, this command is on by default. So, the zoom is adjusted, and the diagram stays centered when the component area is resized. But it also gives to the user, when temporarily off, the possibility to focus on a part of the diagram.

The choice of behavior is done during the design according to the context of the floorplan for a given type of diagram. It’s not a choice given in the UI to the user.

Full Screen

The behavior of the diagram in full screen (hide of the overlay, command access, context menu, etc.) will be specified in the future.

Searching, Finding Impacts, Bookmarking...

Some commands may have an impact on the objects representation (see states of shapes and connectors) but also on the diagram:

The zoom and the pan can be triggered by these commands to better see the objects involved.
The keyboard navigation can be restricted to the objects concerned by the result.
The “Zoom to fit” can not display all the diagram but can center on concerned objects
...

Note: All these cases will be studied for future guidelines.

Best Practices

Which Level of Interactivity to Choose

After deciding where a diagram is needed, there are many interactions that could be allowed or not to the user. It depends on his task on the diagram

<div> <div>Task</div> <div>Static View-only</div> <div>Basic View-only</div> <div>Interactive View-Only</div> <div>Edit</div> </div> <div> <div>View the diagram</div> <div>X</div> <div>X</div> <div>X</div> <div>X</div> </div> <div> <div>Explore the diagram</div> <div></div> <div>X</div> <div>X</div> <div>X</div> </div> <div> <div>Arrange the diagram</div> <div></div> <div></div> <div>X</div> <div>X</div> </div> <div> <div>Edit the diagram</div> <div></div> <div></div> <div></div> <div>X</div> </div>

"Static View-Only" Diagram

The diagram is like a fixed image without any manual zoom, nor pan interaction.

The zoom is adjusted to display all shapes and connectors of the diagram when it is displayed the first time but also when diagram is resized.

The zoom value is between 0.01 and 1.

Shapes can be selectable to navigate only

Navigate to another object page
Display detailed information in a pop-over

Shapes and connectors don’t have a contextual actions or context menu.

Nevertheless, the diagram must have a context menu.

Shapes can contain input fields and control if needed. In that case, the diagram is used as a form.

If a diagram is used to display a thumbnail, shapes and connectors cannot be selected.

"Basic View-Only" Diagram

This level of interactivity allows the user to explore the diagram and find the information he needs even if he cannot move shapes or edit.

It can be used to edit a model as a secondary view which is not compulsory to edit it.

In addition to "Static View-only" interactivity level:

The viewpoint can be modified (Pan & Zoom or Zoom only).
Shapes can be expanded and collapsed to display or hide their content.
Shapes’ connectors can be expanded and collapsed to display or hide linked objects.
The user cannot move the shapes but when he expands or collapses them, the auto-layout arranges them automatically.
The configuration (zoom value, pan position, list of expanded shapes) is saved for the user or shared between all users depending of the context need.

If the edited object is represented in the diagram, the corresponding shape is at the center.

Zoom default value is 1 (even if all the diagram is not visible on screen)

Some commands may be accessible in a toolbar to help the user to explore the diagram: expand all/collapse all, zoom commands, search, impact.

The “Zoom to Fit” command is a toggle button. When on, the zoom is adjusted when the diagram component is resized and when the diagram content changes.

"Interactive View-Only" Diagram

This level of interactivity allows the diagram consumers to define and refine themselves the best way to represent things by arranging shapes instead of leaving it only to diagram producer that has the right to edit.

In addition to the "Basic View-only" level:

Shapes can be moved, and the diagram structure can be arranged.
Linked shapes can be shown or hidden.

With these actions, the model is not considered as modified. Only the representation of it is modified.

This configuration (zoom value, pan position, expanded shapes, expanded relations, shape presence and shape positions) is saved automatically, for all users for the next displays. This save is not part of the lifecycle of the object that is currently viewed or edited.

A diagram toolbar must be displayed over the diagram.

"Edit" Diagram

The purpose of this level of interactivity is to edit the model by interacting with a diagram.

The user is editing the model and doing all the actions done in the “Interactive View-only" level of interactivity in the same task.

The configuration (zoom value, pan position, expanded shapes) is saved in the diagram, for all users. It is done when the user is saving the model only.