LayoutOptions - how to use

[rsoika]

Hi,
I have a question about the LayoutOptions in a AbstractGNodeBuilder class. Where can I found information which options are defined and what they mean?

I only found this discussion which reveals a short glimpse of possibilities.

Thanks for help.

[tortmayr]

Hi @rsoika,
thank you for raising issues about missing or incomplete documentation. This is really helpful for us and gives an idea on what aspects we should focus when further extending/completing the GLSP documentation. I created an umbrella ticket to track all problems, issues etc. that concern the GLSP documentation (#545)

In the meantime I will try to give you a short summary on how to use the LayoutOptions:

In GLSP we distinguish between micro and macro layout. Usually, the server is responsible for the macro layout, that is the arrangement of the main model elements (i.e. nodes and edges). In turn, the client is responsible for the micro layout, that is the positioning and size computation of elements within a container element such as nodes. (For more details see also: https://www.eclipse.org/glsp/documentation/clientlayouting/)

The server just tells the client which layouter it should use and can provide additional configuration options. This information is stored in the graphical model. The layout property defines the layouter that should be used and additional configuration options are stored in the layoutOptions property.

Here are three built-in layout types that can be used: “hbox”,”vbox” and “freeform”.

For an example let's consider the following node builder:

new GNodeBuilder()
   .layout("vbox")
   .layoutOptions(new GLayoutOptions()
      .hAlign("center"))
     .add(new GLabelBuilder()
      .text("label1")
      .build())
   .build();

This builder creates a node whose content (i.e. children) should be layouted with the VBox layouter. In addition, we declare that the elements should be centered horizontally.

The set of available default options is defined in the GLayoutOptions class.

Unfortunately, as you already noticed, this concept is not well documented at all. Layouters may only use a subset of the available options and also the expected option value type is not documented. This information is currently scattered across GLSP client, sprotty and GLSP server code but I will try my best to give you a concise description:

The following options are commonly supported by all layouters:

• resizeContainer: a boolean value, that tells the layouter wether the size of the parent node (i.e. the layout container) should be resized if the layouted child elements do not fit within the bounds [default=true]
• Padding options: used to declare the desired padding of the child elements in pixels [default: 5]. Each padding side can be defined individually (paddingTop,paddingBottom, paddingLeft,paddingRight)
• paddingFactor: a double number that can be used to globally scale the defined padding. [default: 1]. The value for each padding side is multiplied with this factor to compute the final padding
• minWidth: Normally the parent container is resized to exactly fit its content (if resizeContainer is enabled). This option can be used to declare that the parent container should have at least a certain width (even if the content would fit in less). [default 0]
  -minHeight: Similar behavior as minWidth for the height property of the parent container

Vbox Layouter ("vbox")
If vbox is used the children of the container are layouted in a single vertical column. In addition to the common options, the following
additional options are available:

• 'vgap`: Defines the vertical gap between child elements in pixel. [default: 1],
• hAlign: Defines how the horizontal alignment of the child elements. Allowed values are "left","center" or "right".

HBox Layouter ("hbox")
If hbox is used the children of the container are layouted in a single horizontal column. In addition to the common options, the following
additional options are available:

• 'hGap`: Defines the horizontal gap between child elements in pixel. [default: 1],
• vAlign: Defines how the vertical alignment of the child elements. Allowed values are "top","center" or "bottom".

Free from ("freeform")
The free form layout allows the user to freely position child elements inside of a container with the client side tooling (i.e moving them around). There are no additional options on top of the common options.

Side note on the vbox layouter:
Previously we reused the builtin layouters from sprotty, however we noticed that these layouters are not well suited for advanced uses cases like nested (structured) node. @CamilleLetavernier has implemented a improved variant of sprotty's vbox layouter to support these use cases (eclipse-glsp/glsp-client#136). Some additional options have been added (prefWidth, prefHeight, hGrab, vGrab). I'm not that familiar with this new layouter so maybe @CamilleLetavernier can elaborate on this.

[CamilleLetavernier]

For the VBox layouter, the idea is that the serialized size only represents a minimum size, and the node is allowed to grow bigger if it contains additional child nodes (Which is the main point of structured nodes).

So, we distinguish "prefWidth/prefHeight", which is the size given by the user during resizing, and "width/height", which is the actual size currently used for displaying the node (It may be the same as or larger than the pref size).

hGrab and vGrab are used to indicate if an intermediate node should grow to match its parent size. This is especially useful for decorated compartments (Compartments with a visible border or background), as they can otherwise be smaller than their parent Node (By default, they are only as big as required by their children. But if the parent node is bigger, without these options, the compartment would not cover all the available surface of its parent).

So, you usually want:

• hGrab=true for labels (Especially when the main Node also contains children, that can be larger than the label)
• hGrab=true, vGrab=true for compartments (It's unnecessary for invisible compartments, but there is no harm in using them anyway).

Another important point: by default*, in Sprotty, all layout options are inherited by the children, recursively. While this makes sense for options such as Alignment, it doesn't work well for others (Such as size). This can cause some confusion (and weird bugs). As a consequence, it is not always clear if an option should be set on the parent, on the child node, or both (Since it's inherited, setting it on the parent will actually apply it on the child node as well; even though it doesn't always make sense).

In theory:

• layout applies to the parent
• Alignment is set on the parent, and applies to all children (But I guess it can also be applied to an individual child node? I'm not really sure how this is currently implemented)
• hGap/vGap is for the parent
• size and prefSize apply to the child node
• vGrab and hGrab apply to the child node

• For our GLSP layouting use cases, we currently distinguish "getLayoutOptions(element)", which returns all inherited options, and "getElementLayoutOptions(element)", which only returns the element direct options. It's up to each layout implementation to decide whether a property should be inherited.

[rsoika]

Thanks for this information - it helps a lot (Even if it will take me some time until I can safely apply this knowledge).
I think your text is already fine to be taken into the documentation.

One thing I would like to suggest in addition is to illustrate the things explained here by the Task Element in the Workflow Example 0.9.0. The Task contains a Label and an Icon. The Server part simply defines the vertical layout for the too compartments 'Icon' and 'Header'. I understand now that this is a macro layout information.
In the client code (version 0.9.0 ) in the workflow-view the client decides which kind of icon to display (based on the meta information 'type' given by the server) - This is what I now understand as a micro layout. (I hope I am right so far)

The whole concept is really impressive! It seems to be very well thought out and goes much further than anything else I have seen so far. For the BPMN modeling tool I am working on this is really the best fit.

[rsoika]

Sorry but I must come back to the topic. Even as you provide much information I am still not able to apply them to my different scenarios.

If I want to achieve the following element layout:

I try to do define a server side macro layout like this:

public class EventNodeBuilder extends AbstractGNodeBuilder<EventNode, EventNodeBuilder> {
  ....
   @Override
   public void setProperties(final EventNode node) {
      super.setProperties(node);
      node.setName(name);
      node.setNodeType(nodeType);

      node.setLayout(GConstants.Layout.VBOX);
      // Set min width/height
      node.getLayoutOptions().put("minWidth", 40);
      node.getLayoutOptions().put("minHeight", 40);

      node.getLayoutOptions().put(H_ALIGN, "center");
      // define icon and label
      node.getChildren().add(createCompartmentIcon(node));
      node.getChildren().add(createCompartmentHeader(node));
   }
.....
}

So I am extending the AbstractGNodeBuilder and not using a GNodeBuilder - I hope this is correct (I still try to follow the Workflow Example).

Client

Now on the client side (micro layout) I define my event element in the ContainerModule simply like this:

const bpmnDiagramModule = new ContainerModule((bind, unbind, isBound, rebind) => {
....
  configureModelElement(context, 'event:start', EventNode, CircularNodeView);
...

and my EventNode looks like this

export class EventNode extends CircularNode implements Nameable, WithEditableLabel {
    static readonly DEFAULT_FEATURES = [
        connectableFeature,
        deletableFeature,
        selectFeature,
        boundsFeature,
        moveFeature,
        layoutContainerFeature,
        fadeFeature,
        hoverFeedbackFeature,
        popupFeature,
        nameFeature,
        withEditLabelFeature
    ];
    eventType?: string;

    get editableLabel(): (SChildElement & EditableLabel) | undefined {
        const label = this.children.find(element => element.type === 'label:heading');
        if (label && isEditableLabel(label)) {
            return label;
        }
        return undefined;
    }
    get name(): string {
        const labelText = this.editableLabel?.text;
        return labelText ? labelText : '<unknown>';
    }
}

The result will look like this:

I fear this is the wrong approach to achieve the following:

• The element should show an circle, an icon and a lable
• The circle should include the icon
• The editable lable should be below the circle

So I guess that I need to define my own custom View to arrange the elements in the right order

@injectable()
export class EventView extends ShapeView {
.....
...??
}

puh... I am absolute unsure how to go ahead....
can you provide me hint if the way to define my own custom view is correct?
Should I design all in SVG ?

===
Ralph

[rsoika]

I figured out, that technical this is possible if I change the svg attributes with the Browser Debugger I can adjust the 'transform' attribute like

transform="translate(-5, 52) translate(0, 13)

The text position changed:

But can I do this from my GLSP Server code? Or my GLSP Client code?

[rsoika]

I came a little bit near to a solution by defining a custom EventNodeView:

@injectable()
export class EventNodeView extends ShapeView {
	render(element: EventNode, context: RenderingContext): VNode | undefined {
		if (!this.isVisible(element, context)) {
			return undefined;
		}
		const vnode = (
			<g transform={'scale(1) translate(74,52)'}>
					<circle r="23.5" cx="23.5" cy="23.5" class-sprotty-node={true}></circle>
					<text transform={'translate(15,52) translate(-40, 13)'} class-heading={true} class-sprotty-label={true}>{element.name}</text>
			</g>
		);
		const subType = getSubType(element);
		if (subType) {
			setAttr(vnode, 'class', subType);
		}
		return vnode;
	}
}

The result looks like:

but it's still a lot of guessing.....

[rsoika]

The Final Solution

After all I come to the following solution - supporting also editable label headers:

My setProperties method in the server side event node Builder looks like this:

......
   @Override
   public void setProperties(final EventNode node) {
      super.setProperties(node);
      node.setName(name);
      node.setNodeType(nodeType);
      node.setLayout(GConstants.Layout.VBOX);
      node.getLayoutOptions().put(H_ALIGN, "center");
      node.getLayoutOptions().put(H_GRAB, true);
      node.getLayoutOptions().put(V_GRAB, true);
      node.getChildren().add(createCompartmentHeader(node));
   }

   private GLabel createCompartmentHeader(final EventNode taskNode) {
      return new GLabelBuilder(ModelTypes.LABEL_HEADING) //
         .id(taskNode.getId() + "_classname") //
         .text(taskNode.getName())
         .build();
   }

My final view implementation looks like this:

@injectable()
export class EventNodeView extends ShapeView {
	render(element: EventNode, context: RenderingContext): VNode | undefined {
		if (!this.isVisible(element, context)) {
			return undefined;
		}

		// first we compute the event symbol based on the event type
		let eventSymbol = undefined;
		if (element.type === "event:start") {
			// eslint-disable-next-line max-len
			eventSymbol = 'M14 7v1H8v6H7V8H1V7h6V1h1v6h6z';
		} else {
			// default symbol
			eventSymbol = 'M7.116 8l-4.558 4.558.884.884L8 8.884l4.558 4.558.884-.884L8.884 8l4.558-4.558-.884-.884L8 7.116 3.442 2.558l-.884.884L7.116 8z';
		}
		// find the label:heading
		let header = undefined;
		for (const entry of element.children) {
			if (entry instanceof SLabel && entry.type === "label:heading") {
				header = entry;
				// adjust allignment and position
				header.alignment = { x: 0, y: 0 };
				header.position = { x: 0, y: 60 };
			}
		}

		let vnode = undefined;
		if (header) {
			vnode = (
				// render circle with a event symbol and the label:heading
				<g transform={'scale(1) translate(0,0)'}>
					<circle r="20" cx="20" cy="20" class-sprotty-node={true}></circle>
					<g class-icon={true}>
					  <path transform={'scale(2.0),translate(1.75,1.75)'}
						d={eventSymbol} />
					</g>	
					<g transform={'translate(0, 0) translate(0, 0)'}>
						{context.renderElement(header)}
					</g>
				</g>
			);
		} else {
			// we do not found a header so simply draw a circle...
			vnode = (
				<g transform={'scale(1) translate(0,0)'}>
					<circle r="20" cx="20" cy="20" class-sprotty-node={true}></circle>
				</g>
			);
		}
		const subType = getSubType(element);
		if (subType) {
			setAttr(vnode, 'class', subType);
		}
		return vnode;
	}
}

I know that my Serverside Layout information did not make much sense as it is mostly ignored by the client implementation. But hey! I have editable labels and a symbol within my circle!!!

Can you give me a short review? Maybe some of this code can become part of a documentation chapter "Draw your own element view"

[rsoika]

@tortmayr can you please have a short look on my last comments. Just to ensure that I am on the right track.

[tortmayr]

@rsoika Sorry I missed your last comment somehow. Do you still need feedback on this?

[rsoika]

No, thanks I think I figured it out somehow. But as I mentioned in #567 the server side layout options did not convince me. At the end I am using now FREEFORM and add simply the core compartments to my custom NodeBuilder - like symbols, ports or headers. And I do all the layout on the client site.

So my current question is more about if this is a way you would agree too or is this a bad practice?

[tortmayr]

It's definitly not bad practice and a completely valid approach. As also mentioned in #567 (comment) there is no recommended generic default approach. If you are feeling more comfortable with keeping the layout computation at client side that's perfectly fine.