Section:

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.

Prebuilt Panels

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.

List of Prebuilt Panels

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

Integrating Prebuilt Panels

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.

Prebuilt Panels Enum

The namespace with all the identifiers for the prebuilt panels can be found at instance.UI.Panels

JavaScript

1// Bookmark Panel
2instance.UI.addPanel({
3  dataElement: 'bookmarkPanel',
4  location: 'left',
5  render: instance.UI.Panels.BOOKMARKS,
6});
7
8// Thumbnail Panel
9instance.UI.addPanel({
10  dataElement: 'thumbnailPanel',
11  location: 'right',
12  render: instance.UI.Panels.THUMBNAIL,
13});

Related Links

Visual representation of the panels:

Apryse Docs Image

Bookmarks Panel

Apryse Docs Image

Thumbnails Panel

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.

JavaScript

1// Using the openElements API to open the Bookmark panel
2instance.UI.openElements(['bookmarkPanel']);
3
4// Using the toggle button to open the Thumbnail panel
5const thumbnailPanelToggle = new instance.UI.Components.ToggleElementButton({
6 dataElement: 'thumbnailPanelToggle',
7 toggleElement: 'thumbnailPanel',
8 img: 'icon-header-sidebar-line',
9 title: 'Thumbnail Toggle Panel',
10});
11
12// Then this button should be added to a container's item using the setItems API.
13// This container can be a modular header or a grouped items container.
14const defaultHeader = instance.UI.getModularHeader('default-top-header')
15defaultHeader.setItems([thumbnailPanelToggle]);

Related Links

Adding Custom Panels

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.

JavaScript

1// Adding a panel built with JS and DOM elements
2instance.UI.addPanel({
3    dataElement: 'customPanel',
4    location: 'left',
5    icon: '/path/to/icon.svg',
6    render: () => {
7      const div = document.createElement('div');
8      div.innerHTML = 'My custom panel';
9      return div;
10    }
11  });
12
13// Adding a panel built with React
14instance.UI.addPanel({
15    dataElement: 'customPanel',
16    location: 'right',
17    icon: '/path/to/icon.svg',
18    render: () => <MyCustomReactComponent />
19  });
20
21  // You can then add a toggleElement button for this panel
22  // Using the toggle button to open the Thumbnail panel
23const customPanelToggle = new instance.UI.Components.ToggleElementButton({
24  dataElement: 'customPanelToggle',
25  toggleElement: 'customPanel',
26  img: 'icon-header-sidebar-line',
27  title: 'Custom Panel',
28});
29
30// Then this button should be added to a container's item using the setItems API.
31// This container can be a modular header or a grouped items container.
32const defaultHeader = instance.UI.getModularHeader('default-top-header')
33defaultHeader.setItems([customPanelToggle]);

Related Links

Tabbed Panels

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.

Adding prebuilt panels to a tab panel

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

JavaScript

1const tabPanel = new instance.UI.Components.TabPanel({
2  dataElement: 'myTabPanel',
3  panelsList: [
4    {
5      render: instance.UI.Panels.THUMBNAIL // or 'thumbnailsPanel'
6    },
7    {
8      render: instance.UI.Panels.OUTLINE  // or 'genericOutlinesPanel'
9    },
10    {
11      render: instance.UI.Panels.BOOKMARKS // or 'bookmarkPanel'
12    },
13    {
14      render: instance.UI.Panels.LAYERS // or 'layersPanel'
15    },
16    {
17      render: instance.UI.Panels.FILE_ATTACHMENT // or 'fileAttachmentPanel'
18    },
19  ],
20  location: 'right'
21});
22
23// Add the tab panel to the UI
24instance.UI.addPanel(tabPanel);
25
26// You can then add a toggleElement button for this panel
27const tabPanelToggle = new instance.UI.Components.ToggleElementButton({
28  dataElement: 'tabPanelToggle',
29  toggleElement: 'myTabPanel',
30  img: 'icon-header-sidebar-line',
31  title: 'Tab Panel',
32});
33
34// Then this button should be added to a container's item using the setItems API.
35// This container can be a modular header or a grouped items container.
36const defaultHeader = instance.UI.getModularHeader('default-top-header')
37defaultHeader.setItems([tabPanelToggle]);

Related Links

This is the result:

Apryse Docs Image

Adding custom panels to a tab panel

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.

JavaScript

1const tabPanel = new instance.UI.Components.TabPanel({
2    dataElement: 'customLeftPanel',
3    panelsList: [
4      {
5        dataElement: 'firstPanel',
6        icon: '/path/to/icon.svg',
7        render: () => {
8          const panelDiv = document.createElement('div');
9          const paragraph = document.createElement('p');
10          paragraph.textContent = 'My panel';
11          const button = document.createElement('button');
12          button.textContent = 'Add';
13          button.style.backgroundColor = 'blue';
14          button.style.color = 'white';
15          panelDiv.appendChild(paragraph);
16          panelDiv.appendChild(button);
17          return panelDiv;
18        }
19      },
20      {
21        dataElement: 'secondPanel',
22        icon: '/path/to/icon.svg',
23        render: () => <MyCustomReactComponent />
24      },
25    ],
26    location: 'left'
27  });

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.

Register custom panels before using them in a Tab Panel

By registering the panel with the viewer, you can use the panel's dataElement in the panelsList property of the Tab Panel. Otherwise you will have to define the panel's render function directly in the panelsList property.

JavaScript

1instance.UI.addPanel({
2    dataElement: 'customPanel',
3    location: 'left',
4    icon: '/path/to/icon.svg',
5    render: () => {
6      const div = document.createElement('div');
7      div.innerHTML = 'My custom panel';
8      return div;
9    }
10  });
11
12instance.UI.addPanel({
13    dataElement: 'customPanel2',
14    location: 'left',
15    icon: '/path/to/icon.svg',
16    render: () => {
17      const div = document.createElement('div');
18      div.innerHTML = 'My custom panel 2';
19      return div;
20    }
21  });
22
23const tabPanel = new instance.UI.Components.TabPanel({
24    dataElement: 'TabPanel',
25    location: 'right',
26    panelsList: [
27      {
28        render: 'customPanel' // The dataElement can now be used as the panel is registered with the UI
29      },
30      {
31        render: 'customPanel2'
32      },
33    ],
34  });

Related Links

Working with Panels

addPanel

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:

JavaScript

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

Related Links

getPanels

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:

JavaScript

1const panelsList = instance.UI.getPanels();

Related Links

setPanels

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:

JavaScript

1const panelsList = instance.UI.getPanels();
2
3panelsList.pop();
4
5instance.UI.setPanels(panelsList);

Related Links

delete

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.

JavaScript

1const panelsList = instance.UI.getPanels();
2
3// deleting the first panel from the UI
4panelsList[0].delete();

Related Links

setLocation

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:

JavaScript

1const panelsList = instance.UI.getPanels();
2
3// Find the panel you want to change the location of ie. searchPanel
4const panel = panelsList.find(panel => panel.dataElement === 'searchPanel');
5
6// setting its location to the left
7panel.setLocation('left');
8
9// You can also set the location via the property
10panel.location = 'left';

Related Links

Changing items in a Tab Panel

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.

JavaScript

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

Did you find this helpful?

Trial setup questions?

Ask experts on Discord

Need other help?

Contact Support

Pricing or product questions?

Contact Sales