Sidebars

To help support deep integration into the IDE an extension may contribute a Sidebar with one or more sections. These sidebars can then be placed in any sidebar split within the IDE by the user.

When contributing a sidebar, an extension provides two pieces: A static definition of a sidebar and its sections in the extension.json manifest, and a TreeView object in its JavaScript code which provides data and dynamic access to a sidebar section.

Defining a Sidebar

The extension’s extension.json can include a sidebars key defining which sidebars are exposed by the extension. The value of this key contains an array of sidebar definition objects.

Example:

{
    "identifier": "com.mycompany.ColorSidebar",
    "name": "Colors",
    
    "main": "main.js",
    
    "sidebars": [
        {
            "id": "mysidebar",
            "name": "My Sidebar",
            "smallImage": "sidebar-small",
            "largeImage": "sidebar-large",
            "sections": [
                {
                    "id": "mysidebar-colors",
                    "name": "Colors",
                    "allowMultiple": false,
                    "headerCommands": [
                        {
                            "title": "Add",
                            "image": "__builtin.add",
                            "tooltip": "Add a new color",
                            "command": "mysidebar.add"
                        },
                        {
                            "title": "Remove",
                            "image": "__builtin.remove",
                            "tooltip": "Remove the selected color",
                            "command": "mysidebar.remove",
                            "when": "viewItem != null"
                        }
                    ],
                    "contextCommands": [
                        {
                            "title": "Remove",
                            "command": "mysidebar.remove",
                            "when": "viewItem != null"
                        }
                    ]
                }
            ]
        }
    ]
}

This defines a single sidebar, “My Sidebar”. It has a single section, named “Colors”.

Sidebar definitions support the following options:

Every sidebar must define at least one section defition in the sections property. While most sidebars likely will have only one section, a sidebar can optionally have more than one. They will be displayed as a set of splits in the sidebar, ordered from top to bottom.

Section definitions support the following options:

Providing a TreeView

Each section defined in a sidebar should be populated using a TreeView object. It is common to set up a TreeView object as a result of the activate function of the extension being invoked.

A TreeView is created with the identifier of the specific sidebar section for which it will be providing content. The second argument is a options object. The most important piece of this is the dataProvider value.

The data provider is an object conforming to the TreeDataProvider interface. This object will be consulted when the sidebar is made visible to populate its tree of items.

var treeView = null;
var dataProvider = null;

exports.activate = function() {
    // Provided by the extension code
    dataProvider = new ColorDataProvider();
    
    // Create the TreeView
    treeView = new TreeView("mysidebar", {
        dataProvider: dataProvider
    });
    
    treeView.onDidChangeSelection((selection) => {
        // console.log("New selection: " + selection.map((e) => e.name));
    });
    
    treeView.onDidExpandElement((element) => {
        // console.log("Expanded: " + element.name);
    });
    
    treeView.onDidCollapseElement((element) => {
        // console.log("Collapsed: " + element.name);
    });
    
    treeView.onDidChangeVisibility(() => {
        // console.log("Visibility Changed");
    });
    
    // TreeView implements the Disposable interface
    nova.subscriptions.add(treeView);
}

nova.commands.register("mysidebar.add", () => {
    // Invoked when the "add" header button is clicked
    
});

nova.commands.register("mysidebar.remove", () => {
    // Invoked when the "remove" header button is clicked
    
});