sprotty-vscode

VS Code Integration for Sprotty

This library contains glue code for Sprotty diagrams in VS Code. The diagrams can optionally be backed by a language server.

A complete example with a Langium language server is available here.

Getting Started

As first step, you need to implement a webview that renders your diagrams using sprotty-vscode-webview. The webview package should bundle its code into a single JavaScript file (e.g. with Webpack) and put it into your VS Code extension package. The default implementation assumes that the webview code is available at the path pack/webview.js relative to the extension folder.

Then you can instantiate a WebviewPanelManager in the activate hook of your extension:

export function activate(context: vscode.ExtensionContext) {
    const webviewPanelManager = new WebviewPanelManager({
        extensionUri: context.extensionUri,
        defaultDiagramType: 'mydiagram',
        supportedFileExtensions: ['.mydiagram']
    });
}

This service manages webviews created as webview panels in the main editor area of VS Code. Alternatively, you can use SprottyEditorProvider to get a custom editor provider that can be directly associated with a file type, or SprottyViewProvider to get a webview view provider that can render diagrams in the view areas of VS Code, i.e. the bottom or side panels.

In case you are backing your diagrams with a language server, you should use LspWebviewPanelManager as superclass, or respectively LspSprottyEditorProvider or LspSprottyViewProvider. In this case you need to provide a language client configured to communicate with your language server.

Adding Commands

This library registers a few default commands that you can either execute programmatically or expose in the user interface with package.json entries as shown below. The registration happens by calling this function:

registerDefaultCommands(webviewPanelManager, context, { extensionPrefix: 'example' });

The first segment of each command id corresponds to the extensionPrefix option. The when clauses ending with -focused start with the Sprotty diagram type, which is usually determined by the defaultDiagramType option for WebviewPanelManager or the viewType option for SprottyEditorProvider and SprottyViewProvider.

{
  "contributes": {
    "commands": [
      {
        "command": "example.diagram.open",
        "title": "Open in Diagram",
        "category": "Example Diagram"
      },
      {
        "command": "example.diagram.fit",
        "title": "Fit to Screen",
        "category": "Example Diagram"
      },
      {
        "command": "example.diagram.center",
        "title": "Center selection",
        "category": "Example Diagram"
      },
      {
        "command": "example.diagram.export",
        "title": "Export diagram to SVG",
        "category": "Example Diagram"
      }
    ],
    "menus": {
      "commandPalette": [
        {
          "command": "example.diagram.open",
          "when": "editorLangId == 'example'"
        },
        {
          "command": "example.diagram.fit",
          "when": "example-diagram-focused"
        },
        {
          "command": "example.diagram.center",
          "when": "example-diagram-focused"
        },
        {
          "command": "example.diagram.export",
          "when": "example-diagram-focused"
        }
      ]
    }
  }
}

In addition to these command palette items, you can expose the commands in menus and keybindings.