Some test text!

Search
Hamburger Icon

Web / Guides / Items

Items

Overview

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.

items

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.

button-configurations

Custom Buttons

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]);
Using Icons
When incorporating icons into your project, you have two options: utilize custom icons by providing a local path, or select from the extensive collection included with WebViewer by specifying the icon's file name. To explore the available icons and their corresponding file names, refer to the comprehensive list here.

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

Stateful Buttons

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: items-stateful-button

Toggle Element Buttons

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: items-toggle-element-button

Tool Buttons

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

items tool button

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.

Using multiple instances of a tool
In the above list of tools you will find some tools have multiple instances, and use names such as RECTANGLE2, RECTANGLE3, etc. These are different instances of a tool that have different pre-set styles. If your UI requires multiple instances of the same tool as separate tool buttons, with different styles for each you can leverage these.

Ribbon Items

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.

items-ribbon-item

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

Prebuilt Items

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

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

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.

items-page-controls

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]);
Adding a Page Controls item to a vertical container like a left-placed Modular Header, will set the Page Controls to be vertical as well.

View Controls

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.

items view controls

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]);

Zoom

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).

items zoom

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]);

Trial setup questions? Ask experts on Discord
Need other help? Contact Support
Pricing or product questions? Contact Sales