Modular UI Panels

Modular panels serve as dynamic components within WebViewer, designed to enhance user interaction by displaying content either on the left or right side. This guide provides detailed instructions and examples for incorporating both prebuilt and custom panels into your UI, offering a seamless integration process.

The UI includes a comprehensive selection of preconfigured panels designed to address common functionality requirements, such as thumbnail manipulation and document outline navigation. Through the use of the provided APIs, you can seamlessly integrate these panels into your UI. Additionally, you have the flexibility to customize various aspects of their behavior, such as the side of the UI from which they open.

• Outline
• Signature
• Bookmarks
• File Attachment
• Thumbnail
• Layers
• Text Editing
• Change List
• Style
• Redaction
• Search
• Notes
• Tabs
• Signature List
• Rubber Stamp
• Portfolio

To incorporate a prebuilt panel, utilize the addPanel API, specifying necessary properties such as dataElement, location, label, and render. For prebuilt panels, render corresponds to a reserved identifier, while for custom panels, it involves a function returning the panel element.

// Bookmark Panel
instance.UI.addPanel({
  dataElement: 'bookmarkPanel',
  location: 'left',
  render: instance.UI.Panels.BOOKMARKS,
});

// Thumbnail Panel
instance.UI.addPanel({
  dataElement: 'thumbnailPanel',
  location: 'right',
  render: instance.UI.Panels.THUMBNAIL,
});

Visual representation of the panels:

To open the panels, you can use the API openElements with the dataElement of the panel. You can also add a toggle button to your UI and use the selector of the panel as the toggleElement of the button.

// Using the openElements API to open the Bookmark panel
instance.UI.openElements(['bookmarkPanel']);

// Using the toggle button to open the Thumbnail panel
const thumbnailPanelToggle = new instance.UI.Components.ToggleElementButton({
 dataElement: 'thumbnailPanelToggle',
 toggleElement: 'thumbnailPanel',
 img: 'icon-header-sidebar-line',
 title: 'Thumbnail Toggle Panel',
});

// Then this button should be added to a container's item using the setItems API.
// This container can be a modular header or a grouped items container.
const defaultHeader = instance.UI.getModularHeader('default-top-header')
defaultHeader.setItems([thumbnailPanelToggle]);

If you want to customize your UI even more, the Modular UI framework lets you build panels exactly the way you want. This means you can create special components that fit perfectly with what your app needs. You still use the same properties when creating panels with the prebuilt options. However, instead of passing a panel element identifier directly to the render property, you pass a function that returns the panel element. This element can be a React component or a DOM element built with JavaScript, giving you the flexibility to tailor your UI components to your specific requirements.

// Adding a panel built with JS and DOM elements
instance.UI.addPanel({
    dataElement: 'customPanel',
    location: 'left',
    icon: '/path/to/icon.svg',
    render: () => {
      const div = document.createElement('div');
      div.innerHTML = 'My custom panel';
      return div;
    }
  });

// Adding a panel built with React
instance.UI.addPanel({
    dataElement: 'customPanel',
    location: 'right',
    icon: '/path/to/icon.svg',
    render: () => <MyCustomReactComponent />
  });

  // You can then add a toggleElement button for this panel
  // Using the toggle button to open the Thumbnail panel
const customPanelToggle = new instance.UI.Components.ToggleElementButton({
  dataElement: 'customPanelToggle',
  toggleElement: 'customPanel',
  img: 'icon-header-sidebar-line',
  title: 'Custom Panel',
});

// Then this button should be added to a container's item using the setItems API.
// This container can be a modular header or a grouped items container.
const defaultHeader = instance.UI.getModularHeader('default-top-header')
defaultHeader.setItems([customPanelToggle]);

To efficiently manage space and organize content, the framework supports tabbed panels, allowing multiple panels to be housed within a single container. The TabPanel component facilitates this, accepting properties like dataElement, location, and panelsList, which is an array detailing each panel within the tabs.

The Tabbed panel is built using the component TabPanel that receives an object with the following properties:

• dataElement (string, required): A unique string that identifies the panel;
• location (string, 'left' or 'right', required): The location to place the panel;
• panelsList (Array): An array of objects that represent the panels for the tabs. Each object should have the following properties:
  • dataElement (string, optional): A unique string that identifies the inner panel.
  • icon (string, optional): Path to an image or base64 data. Can also be the filename of a .svg from the WebViewer icons folder found here: assets/icons/ (i.e. icon-save to use icon-save.svg).
  • render (string | function, required): When adding the prebuilt panels, it corresponds to the reserved identifier for the panels. For the custom panels, it is a function that returns the panel element.

You can have either prebuilt or custom panels added to your Tab Panel.

The following code snippet is adding only prebuilt panels to the tab panel.

const tabPanel = new instance.UI.Components.TabPanel({
  dataElement: 'myTabPanel',
  panelsList: [
    {
      render: instance.UI.Panels.THUMBNAIL // or 'thumbnailsPanel'
    },
    {
      render: instance.UI.Panels.OUTLINE  // or 'genericOutlinesPanel'
    },
    {
      render: instance.UI.Panels.BOOKMARKS // or 'bookmarkPanel'
    },
    {
      render: instance.UI.Panels.LAYERS // or 'layersPanel'
    },
    {
      render: instance.UI.Panels.FILE_ATTACHMENT // or 'fileAttachmentPanel'
    },
  ],
  location: 'right'
});

// Add the tab panel to the UI
instance.UI.addPanel(tabPanel);

// You can then add a toggleElement button for this panel
const tabPanelToggle = new instance.UI.Components.ToggleElementButton({
  dataElement: 'tabPanelToggle',
  toggleElement: 'myTabPanel',
  img: 'icon-header-sidebar-line',
  title: 'Tab Panel',
});

// Then this button should be added to a container's item using the setItems API.
// This container can be a modular header or a grouped items container.
const defaultHeader = instance.UI.getModularHeader('default-top-header')
defaultHeader.setItems([tabPanelToggle]);

This is the result:

For custom panels within a TabPanel, the render property receives a function returning the panel element. This can be a React component or a DOM element built with JavaScript.

const tabPanel = new instance.UI.Components.TabPanel({
    dataElement: 'customLeftPanel',
    panelsList: [
      {
        dataElement: 'firstPanel',
        icon: '/path/to/icon.svg',
        render: () => {
          const panelDiv = document.createElement('div');
          const paragraph = document.createElement('p');
          paragraph.textContent = 'My panel';
          const button = document.createElement('button');
          button.textContent = 'Add';
          button.style.backgroundColor = 'blue';
          button.style.color = 'white';
          panelDiv.appendChild(paragraph);
          panelDiv.appendChild(button);
          return panelDiv;
        }
      },
      {
        dataElement: 'secondPanel',
        icon: '/path/to/icon.svg',
        render: () => <MyCustomReactComponent />
      },
    ],
    location: 'left'
  });

Another option for adding custom panels in the TabPanel is to first register the panel with the viewer using the addPanel API and then using the panel's dataElement in the panelsList property.

instance.UI.addPanel({
    dataElement: 'customPanel',
    location: 'left',
    icon: '/path/to/icon.svg',
    render: () => {
      const div = document.createElement('div');
      div.innerHTML = 'My custom panel';
      return div;
    }
  });

instance.UI.addPanel({
    dataElement: 'customPanel2',
    location: 'left',
    icon: '/path/to/icon.svg',
    render: () => {
      const div = document.createElement('div');
      div.innerHTML = 'My custom panel 2';
      return div;
    }
  });

const tabPanel = new instance.UI.Components.TabPanel({
    dataElement: 'TabPanel',
    location: 'right',
    panelsList: [
      {
        render: 'customPanel' // The dataElement can now be used as the panel is registered with the UI
      },
      {
        render: 'customPanel2'
      },
    ],
  });

To incorporate panels into your UI, begin by registering them with the addPanel method. This step makes the panels ready for use within your interface. For detailed guidance on utilizing this method, including all available options, refer to the earlier sections of this documentation.

Example usage:

instance.UI.addPanel({
    dataElement: 'customPanel',
    location: 'right',
    icon: '/path/to/icon.svg',
    render: () => <MyCustomReactComponent />
  });

This API fetches a comprehensive list of all the modular panels that can be utilized in the current UI. Once you have this list, you can select any specific panel and modify its properties using the APIs described below.

Example usage:

const panelsList = instance.UI.getPanels();

If you want to modify the list of panels, you can make the changes in the list using JavaScript methods to modify arrays and then you should call the setPanels API with the modified list as a parameter to update the panels list.

Example usage:

const panelsList = instance.UI.getPanels();

panelsList.pop();

instance.UI.setPanels(panelsList);

This API deletes a panel from the UI, rendering it inaccessible for future usage. The deleted panel will remain in the panels' list but it will not be rendered in the UI.

const panelsList = instance.UI.getPanels();

// deleting the first panel from the UI
panelsList[0].delete();

This method allows you to change the location of a panel within the Modular UI. It receives a string indicating the new location where the panel should be positioned. The available values for the location property are right and left.

Example usage:

const panelsList = instance.UI.getPanels();

// Find the panel you want to change the location of ie. searchPanel
const panel = panelsList.find(panel => panel.dataElement === 'searchPanel');

// setting its location to the left
panel.setLocation('left');

// You can also set the location via the property
panel.location = 'left';

To change the items in a Tab Panel, you can use the UI.getPanels() API to get the list of panels and then find the Tab Panel you want to modify. You can then use the panelsList property to modify the sub-panels in the Tab Panel.

// Get the list of panels
const panels = instance.UI.getPanels();
// Find the Tab Panel you want to modify
const tabPanel = panels.find((panel) => panel.dataElement === 'customLeftPanel');
// create a new panel to add to the tab panel
const newPanel = { render: 'searchPanel', dataElement: 'searchPanel' };
// Add the new panel to the tab panel
const newTabPanels = tabPanel.panelsList;
newTabPanels.push(newPanel);
tabPanel.panelsList = newTabPanels;