Containers

Overview

Containers are the top-level components that hold all the other components. They are responsible for the layout of the UI and can be nested to create complex layouts.

Some commonly used containers include Modular Headers, Grouped Items, and Ribbon Groups.

Modular headers are the highest level of containers and can contain other containers and items. Grouped items are containers that can hold any kind of item, including other grouped items. Ribbon groups are containers that can only hold ribbon items.

Modular Header

Modular headers are the containers at the highest level. These are the containers that many other components will be placed in. The default UI only has top-aligned headers, but they are able to be placed on the top, left, right, and bottom.

This means that by switching a property on the header, you can quickly move its position. In the example below, the tools header is set to be on the left.

There are restrictions on modular headers:

• Top headers allow up to two headers stacked on each other

• The remaining positions only allow one header

DataElements are unique keys

In these guides you will see the usage of dataElements; these should be thought of as unique identifiers for each visual component. These dataElements can be used to enable or disable elements, as well as toggle their visibility. For more information on these APIs, please refer to the documentation .

Starting in WebViewer version 11.10, you can reuse a component with the same dataElement multiple times within a header or across different headers using the setItems() method. Note that_ _any changes made to, or functions called on, an item with a given dataElement will affect all instances of that item throughout the UI. For ease of maintenance, we still recommend assigning a unique dataElement to each item, even if they are similar.

The example below shows how to create a top header similar to the one used in the default UI. It also shows some of the options it accepts, such as grow and style. For more details on these options, please refer to the API documentation for ModularHeader

JavaScript

Webviewer.WebComponent({
  path: '/lib',
}, viewerElement).then((instance) => {
  const { UI, Core } = instance;
  const { Tools } = Core;

  // First we define four items that will be placed in the header.
  // Please refer to the Items page for more info on the
  // items that can live inside headers.

  // Menu Flyout Button
  const mainMenu = new UI.Components.MainMenu();
  // View Controls
  const viewControlsToggle = new UI.Components.ViewControls();
  // Zoom Controls
  const zoomControls = new UI.Components.Zoom();
  // Pan Tool Button
  const panToolButton = new UI.Components.ToolButton({
    dataElement: 'panToolButton',
    toolName: Tools.ToolNames.PAN,
  });


  // Creater a top header where we will add the above items
  const topHeader = new instance.UI.Components.ModularHeader({
    dataElement: 'default-top-header',
    placement: 'top',
    grow: 0,
    gap: 12,
    position: 'start',
    stroke: true,
    style: {},
    items: [
      mainMenu,
      viewControlsToggle,
      zoomControls,
      panToolButton,
    ]
  });

  // Set the modular header in the UI
  instance.UI.setModularHeaders([topHeader]);
});

UI.Components.ModularHeader UI.setModularHeaders

addModularHeaders

This API allows you to add headers to the existing UI; it is an additive operation. This means that if you call this API multiple times, it will add the headers to the UI, not replace them. In the example above, if we used this API instead of setModularHeaders, the top header would have been added to the existing UI. This API is useful when you want to add a header to the default UI.

Example usage:

JavaScript

const { Tools } = instance.Core;
// Pan Tool Button
const panToolButton = new instance.UI.Components.ToolButton({
  dataElement: 'panToolButton',
  toolName: Tools.ToolNames.PAN,
});

const topHeader = new instance.UI.Components.ModularHeader({
  dataElement: 'default-top-header',
  placement: 'top',
  grow: 0,
  gap: 12,
  position: 'start',
  stroke: true,
  style: {},
  // As an example we add the pan tool button to the top header
  items: [panToolButton]
});

instance.UI.addModularHeaders([topHeader]);

UI.addModularHeaders

setModularHeaders

This API sets the headers for the UI, replacing any existing headers. This is useful when you want to replace the default headers with your own.

Example usage:

JavaScript

const { Tools } = instance.Core;
// Pan Tool Button
const panToolButton = new instance.UI.Components.ToolButton({
  dataElement: 'panToolButton',
  toolName: Tools.ToolNames.PAN,
});

const topHeader = new instance.UI.Components.ModularHeader({
  dataElement: 'default-top-header',
  placement: 'top',
  grow: 0,
  gap: 12,
  position: 'start',
  stroke: true,
  style: {},
  // As an example we add the pan tool button to the top header
  items: [panToolButton]
});

instance.UI.setModularHeaders([topHeader]);

UI.setModularHeaders

getModularHeaderList

This API will return a list of all the modular headers in the current UI. The modular headers are encapsulated in class instances that have handy methods that give you the capability to dynamically update headers. For the methods available for each class, please refer to the documentation of each class.

Example usage:

JavaScript

const modularHeaders = instance.UI.getModularHeaderList();

UI.getModularHeaderList

getModularHeader

If you already know the dataElement of the header you wish to manipulate, you can use this API. You can find the dataElements by inspecting the UI using your browser’s dev tools.

Example usage:

JavaScript

const defaultHeader = instance.UI.getModularHeader('default-top-header')

UI.getModularHeader

header.getGroupedItems

Returns the grouped items contained in the header. Note that it will only return the grouped items contained at the top level - it will not recursively find all grouped items contained within this header.

Example usage:

JavaScript

const topHeader = instance.UI.getModularHeader('default-top-header')
const topHeaderGroupedItems = topHeader.getGroupedItems()

UI.getModularHeader UI.Components.ModularHeader.getGroupedItems

Accessing Grouped Items by dataElement

If you know the dataElement of the grouped items you want to access, you can use instance.UI.getGroupedItems(<dataElement>) directly. Refer to the Grouped Items Container documentation for more details.

getItems

This method will return all the items contained in the header. It takes an optional parameter of itemType; if passed it will return the items contained in the header that match this type.

Example usage:

JavaScript

const topHeader = instance.UI.getModularHeader('default-top-header')
// Returns all items contained in the header
const topHeaderItems = topHeader.getItems()
// Returns all items of type toggleButton
const topHeaderToggleButtons = topHeader.getItems('toggleButton')

UI.getModularHeader UI.Components.ModularHeader.getItems

setGap

This method allows you to set the gap between header items. It takes an integer value in pixels.

Example usage:

JavaScript

const topHeader = instance.UI.getModularHeader('default-top-header')
topHeader.setGap(50)

UI.getModularHeader UI.Components.ModularHeader.setGap

header.setItems

Sets the child items of the modular header. This method will remove any invalid items.

Example usage:

JavaScript

const topHeader = instance.UI.getModularHeader('default-top-header')
const stylePanelToggle = new instance.UI.Components.ToggleElementButton({
    dataElement: 'stylePanelToggle',
    toggleElement: instance.UI.Panels.STYLE,
    img: 'icon-style-panel-toggle',
    title: 'Style Panel',
  });

// This replaces all items in the header
topHeader.setItems([stylePanelToggle])

UI.getModularHeader UI.Components.ModularHeader.setItems

setJustifyContent

Sets the content justification within a header. The header can be thought of as a flex container and this is the property to set the justification of the flex items. The value can be one of start, end, flex-start, flex-end, center, space-between, space-around, or space-evenly.

Example usage:

JavaScript

const toolsHeader = instance.UI.getModularHeader('tools-header')
toolsHeader.setJustifyContent('start')

UI.getModularHeader UI.Components.ModularHeader.setJustifyContent

setStyle

This method allows you to pass your own style object, overriding the default styles.

Example usage:

JavaScript

const topHeader = instance.UI.getModularHeader('default-top-header')
topHeader.setStyle({
    background: 'aliceblue',
    border: '8px dashed',
    padding: '8px 12px'
});

UI.getModularHeader UI.Components.ModularHeader.setStyle

Grouped Items

Grouped items are light-weight containers that are placed in other containers and can house any kind of item. In the WebViewer default modular UI, grouped items are used mainly for holding tool buttons and action buttons that interact with the document. They can also house other grouped items. They work similarly to flex-box containers and can be styled like them.

If there is not enough space for all grouped items to be displayed in their container, there will be a more button (...) that will show in the container which will allow the user to see the rest of the items.

In the default UI, grouped items are used to hold the buttons in the top header. The example below shows how to create a grouped item similar to one the default UI.

JavaScript

const { Tools } = instance.Core;

// Create some components that can go into a grouped items container
// Menu Flyout Button
const mainMenu = new instance.UI.Components.MainMenu();
// View Controls
const viewControlsToggle = new instance.UI.Components.ViewControls();
// Zoom Controls
const zoomControls = new instance.UI.Components.Zoom();
// Pan Tool Button
const panToolButton = new instance.UI.Components.ToolButton({
  dataElement: 'panToolButton',
  toolName: Tools.ToolNames.PAN,
});
// create the grouped items container
const groupedLeftHeaderButtons = new instance.UI.Components.GroupedItems({
  dataElement: 'groupedLeftHeaderButtons',
  grow: 0,
  gap: 12,
  position: 'start',
  style: {},
  items: [
    mainMenu,
    viewControlsToggle,
    zoomControls,
  ],
  // either make this visible all the time or only when active
  alwaysVisible: true,
});

// now we can add this grouped items container to a modular header
const defaultTopHeader = new instance.UI.Components.ModularHeader({
  dataElement: 'default-top-header',
  placement: 'top',
  grow: 0,
  gap: 12,
  position: 'start',
  stroke: true,
  style: {},
  items: [
    groupedLeftHeaderButtons,
  ]
});

instance.UI.setModularHeaders([defaultTopHeader]);

UI.Components.GroupedItems UI.setModularHeaders

If a grouped items container is set to 'alwaysVisible: true', it will always be visible, even if it is not active. If it is set to 'alwaysVisible: false', it will only be visible when it is active (i.e. set by a Ribbon Item). The default value is false.

You can also add a grouped items container to a modular header after it has been created. Let's reuse our example from above and add the grouped items container to the top header.

JavaScript

const { Tools } = instance.Core;

// Create some components that can go into a grouped items container
// Menu Flyout Button
const mainMenu = new instance.UI.Components.MainMenu();
// View Controls
const viewControlsToggle = new instance.UI.Components.ViewControls();
// Zoom Controls
const zoomControls = new instance.UI.Components.Zoom();
// Pan Tool Button
const panToolButton = new instance.UI.Components.ToolButton({
  dataElement: 'panToolButton',
  toolName: Tools.ToolNames.PAN,
});
// create the grouped items container
const groupedLeftHeaderButtons = new instance.UI.Components.GroupedItems({
  dataElement: 'groupedLeftHeaderButtons',
  grow: 0,
  gap: 12,
  position: 'start',
  style: {},
  items: [
    mainMenu,
    viewControlsToggle,
    zoomControls,
  ],
  // either make this visible all the time or only when active
  alwaysVisible: true,
});

const topHeader = instance.UI.getModularHeader('default-top-header')

// or you can add the grouped items to the header after it has been created
topHeader.setItems([groupedLeftHeaderButtons])

UI.Components.ModularHeader UI.Components.ModularHeader.setItems

Grouped items can be modified in two ways: by calling methods directly on the class instances, or by calling several generic APIs. The generic APIs can modify properties of specific grouped items, or all grouped items, depending on the options passed.

The following APIs have a requirement that the grouped items are already part of the UI - if they have not been added with as part of a header 'addModularHeaders' or 'setModularHeaders' the APIs will have no effect

getGroupedItems

Returns the grouped items with the specified dataElement. Note that it will only return the parent grouped items; it will not return any nested groups.

Example usage:

JavaScript

instance.UI.getGroupedItems('groupedLeftHeaderButtons')

UI.getGroupedItems

Accessing Grouped Items via Header Container

If you don’t know the dataElement of a grouped item—or if you want to retrieve all grouped items within a specific header—you can call getGroupedItems() from the header container itself. Refer to the Header Container documentation for more details.

setActiveGroupedItems

Sets a specified grouped items as active in the Modular UI. This method is useful in scenarios where your application displays only a subset of grouped items at a time. For example, when you want to hide certain ribbon items or perhaps not use ribbon items at all, but still have the flexibility of changing which grouped item is displayed.

If your ribbon items are placed in the Ribbon Group as the default configuration, you can use the setActiveRibbonItem API.

JavaScript

instance.UI.setActiveGroupedItems('annotateGroupedItems'); 

// You can also use 'shapesGroupedItems', 'insertGroupedItems', or any grouped items selector existing on the config file. 

UI.setActiveGroupedItems

setItems

Sets the items of a grouped item and will throw an error if there is any invalid item passed to this method.

Example usage:

JavaScript

const group = instance.UI.getGroupedItems("groupedLeftHeaderButtons");
const toolButton = new instance.UI.Components.ToolButton({
  dataElement: 'pan-tool-2',
  label: 'Pan',
  title: 'Pan the document',
  img: 'icon-header-pan',
  toolName: 'Pan',
});
group.setItems([...group.items, toolButton])

setGroupedItemsGap

Used to set the gap in pixels for items inside grouped items containers. This can set the property on all grouped items if the second parameter is not provided, or can set it on a specific container if the second parameter is provided with the dataElement of the container being updated.

JavaScript

// Setting the gap of all Grouped Items
instance.UI.setGroupedItemsGap(20);

// Setting the gap on Grouped Items with a specific data element
instance.UI.setGroupedItemsGap(30, {
  groupedItemsDataElement: 'annotateGroupedItems'
});

UI.setGroupedItemsGap

setGroupedItemsGrow

Used to set the grow property of a grouped items container. The grow property is a number specifying how much the item wil grow relative to the rest of the items; it is equivalent to the grow property for flex boxes. This API can set the property on all grouped items if the second parameter is not provided, or can set it on a specific container if the second parameter is provided with the dataElement of the container being updated.

JavaScript

// Setting the grow property of all Grouped Items
instance.UI.setGroupedItemsGrow(1);

// Setting the grow property of all Grouped Items with a specific data element
instance.UI.setGroupedItemsGrow(1, {
  groupedItemsDataElement: 'group-1'
});

UI.setGroupedItemsGrow

setGroupedItemsJustifyContent

Used to set the justifyContent property of a grouped items container. This can set the property on all grouped items if the second parameter is not provided, or can set it on a specific container if the second parameter is provided with the dataElement of the container being updated.

JavaScript

// Setting the justifyContent property of all Grouped Items
instance.UI.setGroupedItemsJustifyContent('start');

// Setting the justifyContent property of all Grouped Items with a specific data element
instance.UI.setGroupedItemsJustifyContent('space-between', {
  groupedItemsDataElement: 'group-1'
});

UI.setGroupedItemsJustifyContent

Grouped Items Class Methods

These APIs apply to all objects of the Grouped Items class (including Ribbon Group):

setGap(int): Sets the gap between items. Takes a value in pixels.

JavaScript

const topHeader = instance.UI.getModularHeader('default-top-header')
const groupedLeftItems = topHeader.getGroupedItems()[0]
groupedLeftItems.setGap(20)

UI.getModularHeader UI.Components.ModularHeader.getGroupedItems UI.Components.GroupedItems.setGap

setGrow(number): Sets the flex-grow property of the items container. The grow property is a number specifying how much the item wil grow relative to the rest of the items; it is equivalent to the grow property for flex boxes.

JavaScript

const topHeader = instance.UI.getModularHeader('default-top-header')
const groupedLeftItems = topHeader.getGroupedItems()[0]
groupedLeftItems.setGrow(1)

UI.getModularHeader UI.Components.ModularHeader.getGroupedItems UI.Components.GroupedItems.setGrow

setItems(Array): Sets the items in the group, replacing the existing items.

JavaScript

const topHeader = instance.UI.getModularHeader('default-top-header')
const groupedLeftItems = topHeader.getGroupedItems()[0];
const stylePanelToggle = new instance.UI.Components.ToggleElementButton({
    dataElement: 'stylePanelToggle',
    toggleElement: instance.UI.Panels.STYLE,
    img: 'icon-style-panel-toggle',
    title: 'component.notesPanel',
  });
const notesPanelToggle = new instance.UI.Components.ToggleElementButton({
    dataElement: 'notesPanelToggle',
    toggleElement: 'notesPanel',
    img: 'icon-header-chat-line',
    title: 'component.notesPanel',
  });

// Replace all items with these two toggle buttons
groupedLeftItems.setItems([notesPanelToggle, stylePanelToggle])

UI.getModularHeader UI.Components.ModularHeader.getGroupedItems UI.Components.GroupedItems.setItems

setJustifyContent(string): Sets the content of the grouped items container. You can think of the container as a flex container, and this is the property to set the justification of the flex items.

JavaScript

const topHeader = instance.UI.getModularHeader('default-top-header')
const groupedLeftItems = topHeader.getGroupedItems()[0]
groupedLeftItems.setJustifyContent('end')

UI.getModularHeader UI.Components.ModularHeader.getGroupedItems UI.Components.GroupedItems.setJustifyContent

setStyle(Object): Sets the CSS style of the grouped items. This method allows you to pass your own style object, overriding the default styles.

JavaScript

const topHeader = instance.UI.getModularHeader('default-top-header')
const groupedLeftItems = topHeader.getGroupedItems()[0]
groupedLeftItems.setStyle({
  background: 'aliceblue',
  border: '8px dashed',
  padding: '8px 12px'
});

UI.getModularHeader UI.Components.ModularHeader.getGroupedItems UI.Components.GroupedItems.setStyle

Ribbon Group

Ribbon Groups are just like grouped items with one exception: they can only house Ribbon Items. This is to ensure consistent styling throughout the UI for things such as the currently active ribbon.

If a non-ribbon item is included in the set of items for a ribbon group, it will be ignored.

If there is not enough space for all ribbon items to be displayed in their container, there will be a more button (...) that will show in the container which will allow the user to see the rest of the items.

If there is only enough space for one ribbon item, the ribbon group turns into a dropdown to take up less space.

The following code sample shows how to create a ribbon group with two ribbon items, each mapping to different grouped items container with certain tools.

JavaScript

const { Tools } = instance.Core;
// First let's define some tools that we can place in the grouped items containers
const highlightToolButton = new instance.UI.Components.ToolButton({
  dataElement: 'my-highlightToolButton',
  toolName: Tools.ToolNames.HIGHLIGHT,
});

const freeTextToolButton = new instance.UI.Components.ToolButton({
  dataElement: 'my-freeTextToolButton',
  toolName: Tools.ToolNames.FREETEXT,
});

const rectangleToolButton = new instance.UI.Components.ToolButton({
  dataElement: 'my-rectangleToolButton',
  toolName: Tools.ToolNames.RECTANGLE,
});

const polylineToolButton = new instance.UI.Components.ToolButton({
    dataElement: 'my-polylineToolButton',
    toolName: Tools.ToolNames.POLYLINE,
});

// Now we can create two grouped items containers to hold the tools
const textToolsGroupedItems = new instance.UI.Components.GroupedItems({
  dataElement: 'textToolsGroupedItems',
  items: [
    freeTextToolButton,
    highlightToolButton,
  ],
});

const shapeToolsGroupedItems = new instance.UI.Components.GroupedItems({
  dataElement: 'shapeToolsGroupedItems',
  style: {},
  items: [
    rectangleToolButton,
    polylineToolButton,
  ],
});

// Now we can create the ribbon items that will map to the grouped items containers
const textRibbonItem = new instance.UI.Components.RibbonItem({
  dataElement: 'textRibbonItem',
  label: 'Text Tools',
  // Ribbon items can support Icons
  img: 'icon-tool-text-free-text',
  groupedItems: ['textToolsGroupedItems'],
});

const shapeRibbonItem = new instance.UI.Components.RibbonItem({
  dataElement: 'shapeRibbonItem',
  label: 'Shape Tools',
  img: 'icon-tool-shape-rectangle',
  // This maps to the grouped items container - a ribbon item can map to one or more grouped items containers
  groupedItems: ['shapeToolsGroupedItems'],
});

// Now we can create the ribbon group that will hold the ribbon items
const ribbonGroup = new instance.UI.Components.RibbonGroup({
  dataElement: 'my-ribbon-group',
  items: [
    textRibbonItem,
    shapeRibbonItem,
  ],
});

// Now let's bring it home by adding the ribbon group to the UI
const topHeader = instance.UI.getModularHeader('default-top-header')
topHeader.setItems([ribbonGroup])
// We can also modify the justification in the header so it's centered
topHeader.setJustifyContent('center')

// And let's also add the tools grouped items to the tools header
const toolsHeader = instance.UI.getModularHeader('tools-header')
toolsHeader.setItems([textToolsGroupedItems, shapeToolsGroupedItems])

UI.Components.RibbonGroup UI.Components.RibbonItem

Running the above code will create the following UI:

Alternatively, you can create a new header and add your ribbon.

JavaScript

// create the modular header with the ribbon group set in items
const defaultTopHeader = new instance.UI.Components.ModularHeader({
  ...
  items: [
    ribbonGroup,
    ...
  ]
});

UI.Components.ModularHeader

Ribbon Group Methods

Since Ribbon Groups are a subclass of Grouped Items, they have all the same methods as Grouped Items. See the Grouped Items Class Methods for more information. This means that you can modify the ribbon that is shipped by default using these APIs, instead of creating your own from scratch.

getRibbonGroup

This method returns the Ribbon Group that corresponds to the provided dataElement.

JavaScript

const ribbonGroup = instance.UI.getRibbonGroup('default-ribbon-group');

setActiveRibbonItem

Sets the active Ribbon Item in the Ribbon Group using the provided dataElement. This method is useful when you want to programmatically switch the active ribbon item.

If your application has customized the ribbon layout—for example, by moving ribbon items into a flyout or a different container—you may also want to use setActiveGroupedItems to update the visible grouped items accordingly.

JavaScript

instance.UI.setActiveRibbonItem('toolbarGroup-Insert');

UI.setActiveRibbonItem