Introduction

A shape placeholder is defined in a diagram to present undefined objects of a model. These objects, which can be considered as parameters of a model, are connected to other objects.

Having a placeholder is the only way to define relationships between objects before defining these objects in a diagram.

Usage

A diagram is needed to graphically display a complex model and to help the end user to understand it. Relationships play a key role in a diagram, not the objects: a diagram is not needed to display a set of objects without relationships.

That’s why a diagram with placeholders is usually defined by an expert or defined programmatically to set the relationships even if some objects are not known yet.

An end user then completes it by dropping an object’s shape into each placeholder. The action corresponds to setting a value to a parameter of the model.

Use a placeholder if:

Don’t use a placeholder if:

Anatomy

Note: the construction of the placeholder uses “viewport coordinates” and “world coordinates”.

Size and Corners

The placeholder is made of two-segment rounded lines positioned at each corner of the shape that can be inserted in. The placeholder defines an area which follows the size of the shape and the zoom factor, but the corner dimensions are independent from the zoom to be clearly visible.

The shape of the placeholder area is calculated by taking the shape’s dimension and adding a 4px margin in viewport coordinates around it (D). That corresponds to 4px*Z in world coordinates where Z is the zoom factor.

Each corner is a two-segment rounded line with 3px width. Each segment is 16px length viewport coordinates (E). That corresponds to 16px*Z in world coordinates. The radius of a placeholder angle (RA) depends on the radius of the shape angle (SA) and the zoom factor (Z) by:

RA = 4px+ SA/Z (in viewport coordinates)

Example:

If the shape doesn’t have corners, the 4 limits are positioned in the 4 diagonal directions. If this calculation is too complex or if the exact shape form isn’t predictable, a boxing rectangle is used instead.

States and style

The placeholder has the following interaction states:

The placeholder also has content states:

Connectors and Ports

The connectors (E) and the ports (D) of the placeholder (C) are displayed at the same location and with the same style and behave similarly as if the shape was there (B) or if there was only the shape without any placeholder (A).

Ports are not displayed when the placeholder is in a ghost state.

Role Name

The name of the placeholder is the role of the object in the diagram.

When the placeholder is not filled, the name is displayed in the center of the placeholder (A).

When the placeholder is filled, the shape normally hides it.

It's possible, when needed, to display the name over the placeholder when it's filled (B).

Behavior and Interaction

There are two ways to set a value to the placeholder’s variable:

Once the value is set, the placeholder cannot be selected. Only the shape inside it can be selected. When the shape is moved, the placeholder follows it.

To replace a shape in a filled placeholder, it's possible to:

Dragging and Dropping a Shape into a Shape Placeholder

When a user drags a shape (A), the shape is under the mouse cursor, centered under it.

At any moment the use can drop it:

When the mouse is over the shape (B), the placeholder is in the targeted state but if the shape is not compatible with the placeholder, the placeholder stays in the normal state.

Once dropped, the shape moves directly to its final position (C), the shape is selected, and the placeholder state is filled. No animation is needed.

Dragging and Dropping a Shape into a Magnetized Shape Placeholder

According to the design of the end-to-end workflow chosen to create a valid diagram, we may want to force the user to drag and drop onto mandatory placeholders before dragging and dropping onto other places.

For that, we defined “magnetized” placeholders. The nearest unfilled magnetized placeholder attracts the shape.

When no shape is dragged over the diagram, all magnetized placeholders are in the normal state (A).

When a shape is dragged over the diagram (B), it's attracted by a placeholder by the center of the nearest placeholder (G). The shape is not cented under the mouse cursor (E), but has moved towards the placeholder (F).

The distance from (F) to (E) depends on the shape dimensions: d = Ka*(Ws+Hs). Ws and Hs are the width and the height of the shape in world coordinate. Ka is an attraction factor set to 0.25. This factor may be tuned after usability tests.

The nearest unfilled, compatible, magnetized shape is the targeted state. During the mouse drag, another magnetized placeholder can become the targeted one (C). In that case, it becomes the targeted placeholder and the position (F) of the dragged shape is recalculated with the new placeholder position (G).

At any time, the user can interrupt the dragging action (as usual with ESC key or move outside the diagram area) or drop it to valid it (D). In that case, the dragged shape moves rapidly (around 0.2 seconds) between F and G to fit onto the placeholder. The user can also move the mouse cursor over the placeholder and drop the shape. In that case, the move is immediate.

Selecting Empty Placeholders and Choosing Objects in the Dialog Box

To pass accessibility standards, this feature should be able to be performed without any dragging and dropping: by simple clicks or with the keyboard only.

When selecting the placeholder, the contextual toolbar of the placeholder (magnetized or not) appears and must contain an “Add” command (B).

When selecting the add command (C), it displays a dialog box to choose an object (not presented here).

Once the object is chosen and the dialog is validated, the object’s shape appears selected in the placeholder. The placeholder is not selected anymore. (D).

Moving Placeholders

When the placeholder is empty it behaves like any other shape. It can be dragged to be moved.

When the placeholder is filled, however, it cannot be selected, but it follows the shape when the shape is being dragged.

Emptying Placeholders

The simplest way to empty a placeholder is to select the shape and then to remove it. After that, the placeholder is automatically selected.

When the diagram’s level of interaction is low, for example, shapes and placeholders cannot be moved, it’s possible to drag the shape out of the placeholder and drop it out of the diagram. The placeholder is then empty.

But in high-level interaction diagrams, for example, when shapes can be moved, it’s not possible to drag the shape out of the placeholder to empty it, because the placeholder will follow the dragged shape.

Replacing a Placeholder’s Shape

The user can replace the shape by another one in two ways:

While the mouse is outside the placeholder (A, B), the dragging of the shape follows the normal behavior of a magnetized placeholder: The nearest empty, compatible, compulsory one is the targeted one. But when the mouse moves over a filled placeholder (C), this placeholder is emptied and becomes the targeted one. Then, if the user releases the mouse (D), the dragged shape fills the placeholder (D).

To make the interaction reversible (from C), if he moves out of the placeholder without releasing (B), the initial shape re-appears, and the targeted placeholder is the nearest magnetized one.

Creating a Placeholder

A placeholder can be created as any other shape: by drag and drop it onto a canvas. If the type of the shape the placeholder can receive is unknown when dragging, the size of the placeholder fits to an imaginary square shape of 60x60px. (A) The style is ghost.

If the object type is known while creating the placeholder, for example if the command is creating a specific object’s placeholder, the placeholder size will be based on the size of that object type (C).

When the placeholder is dropped onto the canvas (B), the placeholder is selected. Then the user can set the characteristics in the property pane

Another way to create a placeholder is to drop it on an existing shape. That’s the way to transform a diagram into a diagram template. When the mouse is over a shape, the shape is highlighted (D) when the placeholder can be dropped and the placeholder changes size and position to embrace the shape (E). This transformation is done by an 0.3 second animation.

If the placeholder cannot be dropped onto the shape, the shape remains unselected.

Once dropped, the placeholder is selected, the name is eventually displayed over the shape and the shape is not selected anymore.

Best Practices

When to Use Placeholders in a Diagram Template

A diagram template is a diagram used as a starting point to create another diagram. There are several methods available.

<div> <div>Case</div> <div>Advantages</div> <div>Disadvantages</div> </div> <div> <div> <p>The template is made from an ordinary diagram where placeholders replace some objects.</p> <p>Then another user completes it</p> <p>(method 1).</p> </div> <div> <p>The template can be built from a valid model.</p> <p>The end user can complete the model without caring about relationships.</p> </div> <div></div> </div> <div> <div> <p>The template diagram is an ordinary model the end user duplicates and then modifies</p> <p>(method 2).</p> </div> <div>Always possible on any diagram.</div> <div> <p>The relationships are “destroyed” when removing objects and inserting new ones to replace them (except if a “Replace By” action exists on objects to keep the relationships).</p> <p>The end user needs to know which objects must be changed and which ones must be kept.</p> </div> </div>

In the following examples, the model M (with objects “Object A”, “Object B”, “Object 1”) is the model template and the model N (with objects “Object C”, “Object D”, “Object 1”) is the model to create.

Method 1: Create a template from a diagram and then create diagram from the template

The expert creates the template. They will:

Then any end-user will use the template. They will:

Method 2: Create a diagram from a diagram

From an existing diagram, seen as a good example to follow (A), the user will:

As said above, the main issue here is that the user may not know how to reconnect the objects if the connections are complex.

When to Use Placeholders when Generating Diagrams

<div> <div>Case</div> <div>Advantages</div> <div>Disadvantages</div> </div> <div> <div> <p>The template model is generated with placeholders filled by the end user</p> <p>(method 3).</p> </div> <div>The end user is guided to complete the model without caring about relationships.</div> <div></div> </div> <div> <div> <p>A form is filled before generating the model</p> <p>(method 4).</p> </div> <div>The end user is guided to complete the model the first time only.</div> <div>Once the model has been generated, any change of the objects will need to remove the objects and also the relationships (same disadvantages as method 2).</div> </div>

Method 3: A diagram generated with placeholders

The user executes a command that generates the diagram with placeholders (A). Then the user fills the placeholders with objects and saves the model (B).

Method 4: A diagram generated after inputs in a dialog box

When the user executes a command to generate the model, a dialog box diagram asks to input the objects. Then the diagram is displayed (B).

Design System - Components - Shapes

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.