Dock Manager Overview

The Dock Manager is a WebComponent that provides means to manage the layout of your application through panes, allowing your end-users to customize it further by pinning, resizing, moving and hiding panes.

Demo

Dependencies

To install the Dock Manager package execute the following command:

npm install --save igniteui-dockmanager

Then it is necessary to import and call the defineCustomElements() function:

import { defineCustomElements } from 'igniteui-dockmanager/loader';

defineCustomElements();

Usage

Once the Dock Manager is imported, you can add it on the page:

<igc-dockmanager id="dockManager">
</igc-dockmanager>
Note

Since the Dock Manager component uses ShadowDOM and slots it is not supported on older browsers like Internet Explorer 11 and Edge 18 and below (non-Chromium versions).

The Dock Manager has a layout property, which describes the layout of the panes. To start defining a layout, you should set the rootPane property and add child panes. Here is how you can define a layout with a single content pane:

import { IgcDockManagerPaneType, IgcSplitPaneOrientation, IgcDockManagerComponent } from 'igniteui-dockmanager';

// ...

this.dockManager = document.getElementById("dockManager") as IgcDockManagerComponent;
this.dockManager.layout = {
    rootPane: {
        type: IgcDockManagerPaneType.splitPane,
        orientation: IgcSplitPaneOrientation.horizontal,
        panes: [
            {
                type: IgcDockManagerPaneType.contentPane,
                contentId: 'content1',
                header: 'Pane 1'
            }
        ]
    }
};

To load the content of the panes, the Dock Manager uses slots. The slot attribute of the content element should match the contentId of the content pane in the layout configuration. It is highly recommended to set width and height of the content elements to 100% for predictable response when the end-user is resizing panes.

<igc-dockmanager id="dockManager">
    <div slot="content1" style="width: 100%; height: 100%;">Content 1</div>
</igc-dockmanager>

The Dock Manager defines several pane types:

Each type of pane has a size property. Depending on the parent orientation the size may affect either the width or the height of the pane. The size of a pane is relative to the sizes of its sibling panes and defaults to 100. If you have two sibling panes, where the first one has size set to 200 and the second one - size set to 100, the first will be twice the size of the second one. If the absolute size of their parent is 900px, they will be sized to 600px and 300px respectively.

The end-user can perform the following actions to customize the layout at runtime:

  • Pin/unpin a pane
  • Resize a pane
  • Close a pane
  • Drag a pane to make it float
  • Move a floating pane
  • Dock a floating pane

All of these are reflected in the layout property of the Dock Manager.

Content Pane

The content pane represents a pane with header and content. It can be hosted inside a Split Pane or a Tab Group Pane. Here is how a content pane is defined:

const contentPane: IgcContentPane = {
    type: IgcDockManagerPaneType.contentPane,
    contentId: 'content1',
    header: 'Pane 1'
}

When a pane is unpinned, it appears as a tab header at one of the edges of the Dock Manager. If the end-user selects it, its content appears over the docked pinned panes. To unpin a content pane, set its isPinned property to false.

const contentPane = {
    type: IgcDockManagerPaneType.contentPane,
    contentId: 'content1',
    header: 'Pane 1',
    isPinned: false
}

The isPinned property affects only content panes that are docked outside a document host. Also, content panes hosted in a floating pane cannot be unpinned.

By default, the unpin destination for a content pane is calculated automatically based on the location of the pane relative to the document host. When more than one document host is defined, the nearest one in the parent hierarchy of the unpinned content pane will be used. If there is no document host defined, the default location is used - left. It is also possible to set the desired destination of the unpinned pane by using the unpinnedLocation property.

Split Pane

The split pane is a container pane which stacks all of its child panes horizontally or vertically based on its orientation property. Here is how a horizontal split pane with two child content panes is defined:

const splitPane: IgcSplitPane = {
    type: IgcDockManagerPaneType.splitPane,
    orientation: IgcSplitPaneOrientation.horizontal,
    panes: [
        {
            type: IgcDockManagerPaneType.contentPane,
            contentId: 'content1',
            header: 'Pane 1'
        },
        {
            type: IgcDockManagerPaneType.contentPane,
            contentId: 'content2',
            header: 'Pane 2'
        }
    ]
}

The split pane may contain child panes of all pane types including other split panes.

Tab Group Pane

The tab group pane displays its child content panes as the tabs of a tab component. Here is how a tab group pane with a content pane for each of its two tabs is defined:

const tabGroupPane: IgcTabGroupPane = {
    type: IgcDockManagerPaneType.tabGroupPane,
    panes: [
        {
            type: IgcDockManagerPaneType.contentPane,
            contentId: 'content1',
            header: 'Pane 1'
        },
        {
            type: IgcDockManagerPaneType.contentPane,
            contentId: 'content2',
            header: 'Pane 2'
        }
    ]
}

Document Host

The document host is an area of tabs for documents, similar to the one in Visual Studio for code editing and design view. Here is how to define a document host with two document tabs:

const docHost: IgcDocumentHost = {
    type: IgcDockManagerPaneType.documentHost,
    rootPane: {
        type: IgcDockManagerPaneType.splitPane,
        orientation: IgcSplitPaneOrientation.horizontal,
        panes: [
            {
                type: IgcDockManagerPaneType.tabGroupPane,
                panes: [
                    {
                        type: IgcDockManagerPaneType.contentPane,
                        contentId: 'content1',
                        header: 'Grid'
                    },
                    {
                        type: IgcDockManagerPaneType.contentPane,
                        contentId: 'content4',
                        header: 'List'
                    }
                ]
            }
        ]
    }
}

Floating Pane

The floating pane is a split pane rendered above all other ones in a floating window. The floating pane definitions are stored in the floatingPanes property of the layout. Here is how to add a floating pane with a single content pane inside:

const layout: IgcDockManagerLayout = {
    rootPane: {
        // ...
    },
    floatingPanes: [
        {
            type: IgcDockManagerPaneType.splitPane,
            orientation: IgcSplitPaneOrientation.horizontal,
            floatingLocation: { x: 80, y: 80 },
            floatingWidth: 200,
            floatingHeight: 150,
            panes: [
                {
                    type: IgcDockManagerPaneType.contentPane,
                    contentId: 'content1',
                    header: 'Floating Pane 1'
                }
            ]
        }
    ]
};

The floatingLocation, floatingWidth and floatingHeight properties represent absolute dimensions in pixels. Please note that these properties are applied only for the split panes in the floatingPanes array.

Save/Load Layout

To restore or persist a layout, you simply have to get/set the value of the layout property. Here is how to save the layout as a stringified JSON:

private savedLayout: string;

private saveLayout() {
    this.savedLayout = JSON.stringify(this.dockManager.layout);
}

private loadLayout() {
    this.dockManager.layout = JSON.parse(this.savedLayout);
}

Please note that modifying any of the properties of the layout object will not trigger an update of the Dock Manager. If that is your goal, you should replace the whole layout object like so:

const layout = this.dockManager.layout;
layout.rootPane.orientation = IgcSplitPaneOrientation.vertical;
this.dockManager.layout = { ...layout };

Themes

The Dock Manager comes with a light and a dark theme. The light theme is the default one. To change it to dark, you only need to import the igc.themes.css file in your css and add the dark-theme class to the Dock Manager or any of its parents:

@import '~igniteui-dockmanager/dist/collection/styles/igc.themes';
<igc-dockmanager class="dark-theme">