React Dock Manager Overview

    The Infragistics React 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, maximizing and hiding panes.

    React Dock Manager Example

    This example shows most functionalities and docking options of the React Dock Manager.

    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:

    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:

    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.

    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
    • Maximize a 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:

    The header property is used to provide a text header for the content pane. This text is rendered at several places: the top content pane header, the tab header if the pane is in a tab group and the unpinned header if the pane is unpinned. You can provide a custom slot content for each of these places respectively using the headerId, tabHeaderId and unpinnedHeaderId properties. If any of these properties is not set, the header text is used. Here is how to provide a tab header slot content:

    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.

    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.

    You can configure which end-user operations are allowed for a content pane using its allowClose, allowPinning, allowDocking and allowFloating properties.

    By default, when you close a pane it gets removed from the layout object. However, in some cases you would want to temporary hide the pane and show it later again. In order to do that without changing the layout object you can use the hidden property of the content pane. Setting the property to true will hide it from the UI, but it will remain in the layout object. In order to override the default close behavior you can subscribe to the paneClose event like this:

    this.dockManager.addEventListener('paneClose', ev => {
        for (const pane of ev.detail.panes) {
            pane.hidden = true;
        }
        ev.preventDefault();
    });
    

    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:

    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:

    If there is not enough space to display all tab headers, the tab group shows More tabs menu, which contains the non-visible tabs. If you click a tab item in that menu, the tab gets selected and moved to the first position.

    The tabs also can be reordered without being detached from the tab group in which they are located. You can click on a tab of your choice and drag it left or right to the position you want it to be. If you drag the selected tab outside of the tabs area it will be detached into a floating pane.

    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:

    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:

    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.

    With the floatingResizable and allowFloatingPanesResize you can set whether resizing floating panes is allowed. The allowFloatingPanesResize is a IgcDockManagerComponent property, so if the value is set to false none of the floating panes can be resized. The floatingResizable property can be applied separately on each split pane in the floatingPanes array and if the property value is not set, it defaults to the value of the allowFloatingPanesResize property. If the floatingResizable property is set for a specific pane, its value takes precedence over the allowFloatingPanesResize property value.

    Active Pane

    The Dock Manager component highlights the content pane which contains the focus and exposes it in its activePane property. You can programmatically change the active pane by setting the property. You can also listen for changes of the activePane property by subscribing to the activePaneChanged event:

    this.dockManager.addEventListener('activePaneChanged', ev => {
        console.log(ev.detail.oldPane);
        console.log(ev.detail.newPane);
    });
    

    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:

    Events

    The Dock Manager component raises events when specific end-user interactions are performed for example closing, pinning, resizing and dragging a pane. You can find the full list of Dock Manager events here. Here is how to add an event listener for the paneClose event:

    this.dockManager.addEventListener('paneClose', ev => console.log(ev.detail));
    

    Keyboard Navigation

    Keyboard navigation enhances the accessibility of the Dock Manager and provides a rich variety of interactions to the end-user like navigating through all panes, splitting the view in multiple directions through docking the active pane, etc.

    The shortcuts are as follows:

    Docking

    • Cmd/Ctrl + Shift + Arrow up Docks to global top
    • Cmd/Ctrl + Shift + Arrow down Docks to global bottom
    • Cmd/Ctrl + Shift + Arrow right Docks to global right
    • Cmd/Ctrl + Shift + Arrow left Docks to global left
    • Shift + Arrow Up With multiple tabs in a tab group splits the view and docks the focused tab above
    • Shift + Arrow down With multiple tabs in a tab group splits the view and docks the focused tab below
    • Shift + Arrow right With multiple tabs in a tab group splits the view and docks the focused tab right
    • Shift + Arrow left With multiple tabs in a tab group splits the view and docks the focused tab left
    • Cmd/Ctrl + F6 / Cmd/Ctrl + Arrow right Focuses next tab in document host
    • Cmd/Ctrl + Shift + F6 / Cmd/Ctrl + Arrow left Focuses previous tab in document host
    • Alt + F6 Focuses next content pane
    • Alt + Shift + F6 Focuses previous content pane

    Pane Navigator

    Тhe following keyboard shortcuts show a navigator from which you can iterate through panes and documents.

    • Cmd/Ctrl + F7 / Cmd/Ctrl + F8 Starts from the first document forward
    • Alt + F7 / Alt + F8 Starts from the first pane forward
    • Cmd/Ctrl + Shift + F7 / Cmd/Ctrl + Shift + F8 Starts from the last document backwards
    • Alt + Shift + F7 / Alt + Shift + F8 Starts from the last pane backwards

    Other

    • Alt + F3 Closes the active pane

    Practice all of the above mentioned actions in the sample demo.

    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';
    

    Localization

    The Dock Manager component supports localizing the strings used in the context menus, tooltips and aria attributes. By default, the Dock Manager detects the language of the page by searching for a lang attribute on any of its parents. If the lang attribute is not set or is set to a value which the Dock Manager does not support, the default language used is English(en). The Dock Manager provides built-in localized strings for the following languages: English(en), Japanese(jp), Korean(ko) and Spanish(es). In order to provide resource strings for any other language use the addResourceStrings method:

    The Dock Manager exposes resourceStrings property which allows you to modify the strings. If you set the resourceStrings property, the Dock Manager will use your strings no matter what lang attribute is set.