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:

• id: The unique identifier of the sidebar. This must be unique within the scope of the extension (two sidebars may have the same identifier if they are in different extensions).
• name: The user readable name of the sidebar. This value is automatically localized when shown.
• smallImage: The name of an image to use when the sidebar dock is in Small mode. These icons should use a 16px base size (32px for 2x resources)
• smallSelectedImage: The name of an image to use when the sidebar dock is in Small mode and the sidebar is selected. If not specified, the smallImage value will be used. These icons should use a 16px base size (32px for 2x resources)
• largeImage: The name of an image to use when the sidebar dock is in Large mode. These icons should use a 24px base size (48px for 2x resources)
• largeSelectedImage: The name of an image to use when the sidebar dock is in Large mode. If not specified, the largeImage value will be used. These icons should use a 24px base size (48px for 2x resources)
• sections: An array of section definitions defining the content of the sidebar

Every sidebar must define at least one section definition 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:

• id: The unique identifier of the section. This must be unique within the sidebar, but does not need to be unique otherwise.
• name: The user readable name of the section, shown in its header. If not specified, the section header may be omitted if no headerCommands are also specified. This value is automatically localized when shown.
• allowMultiple: Whether the tree shown within the section allows multiple selection.
• placeholderImage: The name of an image to display if the section has no content. These icons should use a 24px base size (48px for 2x resources).
• placeholderText: A label to display if the section has no content. This value is automatically localized when shown.
• headerCommands: An array of Command definitions that will be shown as buttons in the header of the section. These buttons may be enabled and disabled using the when clause of the command.
• contextualCommands: An array of Command definitions that will be shown in the contextual menu of the sidebar. These buttons may be enabled and disabled using the when clause of the command.

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
    
});