Items

Items are the building blocks of WebViewer Modular UI. They are components that are placed inside containers. They include buttons and prebuilt components such as the page controls and zoom controls. All items inherit properties from the same base class and can be modified in similar ways. They can also be placed in different containers to make them easier to manage and reuse.

There are many different items in the default UI which include Toggle Buttons, Tool Buttons, Ribbon Items, View Controls, Zoom Controls, and Page Controls among others.

Items are also highly customizable. For example, a button can have a label or an icon or even both depending on the properties set.

Custom buttons, also referred to as Action Buttons, allow you to specify the icon, title, and onClick behaviour. These can include any kind of function call, such as posting data to a server.

const testButton = new instance.UI.Components.CustomButton({
  dataElement: 'customButton',
  label: 'test',
  title: 'this is a test button',
  onClick: () => console.log('button clicked!'),
  img: 'icon-save',
});

// This can now be added to a modular header
const defaultHeader = instance.UI.getModularHeader('default-top-header')
defaultHeader.setItems([...defaultHeader.items, testButton]);

The code above creates a custom button which will look like this:

Stateful buttons are buttons that can have state within them. These are generally used for tools or viewing modes, where we want to change the style of the button depending on the state (e.g. active tool vs not active).

const statefulButton = new instance.UI.Components.StatefulButton({
  initialState: 'SinglePage',
  states: {
    SinglePage: {
      img: 'icon-header-page-manipulation-page-layout-single-page-line',
      onClick: (update) => {
        update('DoublePage');
      },
      title: 'Single Page',
    },
    DoublePage: {
      img: 'icon-header-page-manipulation-page-layout-double-page-line',
      onClick: (update) => {
        update('SinglePage');
      },
      title: 'Double Page',
    },
  },
  // Mount is a function that gets called when the button is mounted
  // use it to set the initial state or do other setup
  mount: () => {},
  // Unmount is a function that gets called when the button is unmounted
  // use it to clean up any resources
  unmount: () => {},
});

// This can now be added to a modular header
const defaultHeader = instance.UI.getModularHeader('default-top-header')
defaultHeader.setItems([statefulButton]);

The code above creates a stateful button which toggles between Single Page and Double Page states and will look like this:

Toggle Element Buttons, also known as Toggle Buttons, are buttons that can be used toggle specified elements on and off in the UI. These are generally used for opening panels, such as the Notes Panel or the Thumbnails Panel, or for activating special modes such as Form Field Editing Mode or Content Editing Mode.

const toggleButton = new instance.UI.Components.ToggleElementButton({
  label: 'Toggle',
  title: 'Toggle the visibility of the element',
  toggleElement: 'dataElementToToggle',
});

// This can now be added to a modular header
const defaultHeader = instance.UI.getModularHeader('default-top-header')
defaultHeader.setItems([toggleButton]);

One of the most common use cases for this type of button is to toggle the visibility of the Style Panel like so:

Tool Buttons are buttons that are used to activate a specific tool.

In the Modular UI they are abstractions that can be used to easily add a tool button anywhere in the UI as shown in the example below:

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

// This can now be added to a modular header
const defaultHeader = instance.UI.getModularHeader('default-top-header')
defaultHeader.setItems([rectangleToolButton]);

Tool buttons can also be customized by passing in a custom img, label, or title.

See api guide for list of available tool names that can be used with Tool Buttons.

Ribbon Items are a special type of item that are used within a Ribbon Group to create a ribbon. They are used to set which Grouped Items should appear in the secondary header in the default UI.

For a full code samples of adding ribbon items to the UI, see the Ribbon Group documentation.

The Modular UI features a variety of prebuilt items designed to streamline the integration of commonly used viewer functionalities. These components allow for easy placement anywhere within the viewer, eliminating the need to recreate their internal logic. Among these are the Preset Items, which are buttons engineered to handle frequent actions such as downloading documents and initiating print options. Additionally, the prebuilt items include Page Controls, Zoom Controls, and View Controls. These render components that manage the viewer's state, enabling settings adjustments for the current page, zoom level, and page orientation.

Preset buttons are buttons that are already defined in the default UI. These include buttons such as the Save Button, Print Button, and Download Button . These buttons are generally used to perform actions on the document or toggle different modes like Content Edit Mode or Form Field Creation Mode.

You can find a full list of the available preset buttons in the PresetButton class documentation.

The following code creates a new Preset Save Button:

const saveAsButton = new instance.UI.Components.PresetButton({
  buttonType: 'saveAsButton',
  dataElement: 'presetButton-save'
});

// This can now be added to a modular header
const defaultHeader = instance.UI.getModularHeader('default-top-header')
defaultHeader.setItems([saveAsButton]);

Page Controls are used to navigate through the pages of a document. They include a page number input which shows the current page along with the total pages and buttons to move to the previous page and the next page in the document.

Page controls can be placed inside of containers and can be customized to fit the needs of your application.

The following code creates a new Page Controls item:

const pageControls = new instance.UI.Components.PageControls();

// This can now be added to a modular header
const defaultHeader = instance.UI.getModularHeader('default-top-header')
defaultHeader.setItems([pageControls]);

View Controls in WebViewer let you adjust the display settings of a document. These settings include options to change how you navigate through the document (like scrolling continuously or flipping page by page), rotate the document, choose the document layout (such as viewing one page at a time or two pages side-by-side), and a button to view the document in full screen.

This component gets added to the UI as a toggle button which can be used to show or hide the View Controls Flyout Menu.

The following code creates a new View Controls item:

const viewControls = new instance.UI.Components.ViewControls();

// This can now be added to a modular header
const defaultHeader = instance.UI.getModularHeader('default-top-header')
defaultHeader.setItems([viewControls]);

The Zoom component is used to change the zoom level of the document. It includes buttons to zoom in and zoom out, and an input field to manually change the zoom level. There is also a dropdown button which opens a Zoom Flyout Menu which contains a list of preset zoom levels as well as Fit To Width and Fit To Page buttons and a button to activate marquee zooming (changing the zoom level by clicking or cmd/ctrl+clicking).

The following code creates a new Zoom item:

const zoom = new instance.UI.Components.Zoom();

// This can now be added to a modular header
const defaultHeader = instance.UI.getModularHeader('default-top-header')
defaultHeader.setItems([zoom]);