Communication and Protocols

Actions are plain JSON serializable objects so that they can easily be passed through all kinds of APIs. They can be distinguished through their KIND string property. In this section, the most important actions for understanding the basic communication protocols are described. For more info on existing actions see actions.ts

Sent from the client to the model source to transmit the result of bounds computation for micro-layout. This is sent as a response to a RequestBoundsAction

Sent from the model source to the client to request bounds for the given model. This triggers the micro-layout computation.

Sent from client to model source to request a new model. Usually, this is the first action sent to initiate the communication. Optionally this can contain an options object containing configuration for the DiagramServer, like properties for needsClientLayout and needsServerLayout.

Sent from the model source to the client to set the model. It contains the schema for the new graph. Should a model already exist in the client, it is overwritten.

Sent from model source to client to update the current model. Allows animating the transition from the old to the new model and contains properties for the transition.

Based on where layouting should be done there are 3 different protocols through which the DiagramServer and client can communicate. On the client-side, this can be configured through the configureViewerOptions in the dependency injection container.

configureViewerOptions(context, {
    needsClientLayout: false,
    needServerLayout: true,
    baseDiv: containerId
});

On the server-side layout options need to be set in the DiagramServer

diagramServer.setNeedsClientLayout(false);
diagramServer.setNeedsServerLayout(true);

In this scenario, the server needs to provide a model with complete layout information, so that no further processing by the client is required.

sequenceDiagram
participant C as Client
participant S as Server
Note over C,S: Client requests model
C->>S: RequestModelAction
S->>C: SetModelAction
Note over C,S: Server updates model
loop when model changes
    S->>C: UpdateModelAction
end

The server sends RequestBoundsAction (highlighted in yellow) to the client instead of updating the model directly. The client does not forward the resulting ComputedBoundsAction to the server because that would be an unnecessary round-trip. The updated bounds are applied locally in the client instead.

sequenceDiagram
participant C as Client
participant S as Server
Note over C,S: Client requests model
C->>S: RequestModelAction
rect rgb(240, 240, 180, .4)
    S->>C: RequestBoundsAction
end
Note over C,S: Server updates model
loop when model changes
    rect rgb(240, 240, 180, .4)
        S->>C: RequestBoundsAction
    end
end

This is similar to the second scenario above, but here the ComputedBoundsAction is processed on the server so it can apply its own layout engine to the updated model.

sequenceDiagram
participant C as Client
participant S as Server
Note over C,S: Client requests model
C ->> S: RequestModelAction
S ->> C: RequestBoundsAction
C ->> S: ComputedBoundsAction
S ->> C: UpdateModelAction
Note over C,S: Server updates model
loop when model changes
    S ->> C: RequestBoundsAction
    C ->> S: ComputedBoundsAction
    S ->> C: UpdateModelAction
end