Customizing header

In this document
chevron_rightHeader composition
chevron_rightHeader items
chevron_rightActionButton
chevron_rightToggleActionButton
chevron_rightToggleElementButton
chevron_rightToolButton
chevron_rightToolGroupButton
chevron_rightSpacer
chevron_rightDivider
chevron_rightRelevant APIs

There are a number of ways you may want to customize the header. To name a few:

  • Removing all annotation tool buttons
  • Reordering annotation tool buttons
  • Replacing the existing view controls buttons with custom buttons
  • Adding a custom annotation tool button
  • Replace the entire header with different items in smaller screens

The WebViewer UI provides a flexible API to easily handle each of these cases and more.

linkHeader composition

The header is represented by an array of header items and you can edit the array to add/remove/reorder them however you want. The API, setHeaderItems, will provide the array of header items as a function argument.

For cases where the user wants to replace the entire header items back and forth, the header items are grouped, and displayed only when the group is active:

linkHeader items

Header items are objects with certain parameters. If you wish to add a header item, it is important for you to understand what type it is and what properties should be used.

linkActionButton

ActionButton triggers an action. The button has no active state.

Properties

  • type (string) - Must be set to actionButton.
  • img (string) - Path to an image or base64 data.
  • onClick (function) - Function to be triggered on click.
  • name (string, optional) - Option to set data-element value of the button element. It can be used to disable/enable the element.
  • hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet and mobile.

Example

const newActionButton = {
  type: 'actionButton',
  img: 'path/to/image',
  onClick: () => alert('Hello world!'),
  name: 'alertButton',
  hidden: [ 'mobile' ]
};

linkToggleActionButton

ToggleActionButton is basically composed of two action buttons where the active button is toggled on each click.

Properties

  • type (string) - Must be set to toggleActionButton.
  • img (array of strings) - Paths to image or base64 data. The array must have 2 children.
  • onClick (array of functions) - Functions that will take turns to be triggered. The array must have 2 children.
  • name (string, optional) - Option to set data-element value of the button element. It can be used to disable/enable the element.
  • hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet and mobile.

Example

const newToggleActionButton = {
  type: 'toggleActionButton',
  img: [ 'path/to/image', 'path/to/image2' ],
  onClick: [
    () => alert('Hello world!'),
    () => alert('How are you?')
  ],
  name: 'alertButton',
  hidden: [ 'mobile' ]
};

linkToggleElementButton

ToggleElementButton opens/closes the UI element. The button is in an active state when the UI element is open.

Properties

  • type (string) - Must be set to toggleElementButton.
  • img (string) - Path to an image or base64 data.
  • element (string) - data-element attribute value of the UI element to be opened/closed.
  • name (string, optional) - Option to set data-element value of the button element. It can be used to disable/enable the element.
  • hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet and mobile.

Example

const newToggleElementButton = {
  type: 'toggleElementButton',
  img: 'path/to/image',
  element: 'leftPanel',
  name: 'leftPanelButton',
  hidden: [ 'mobile' ]
};

linkToolButton

ToolButton activates a WebViewer tool. The button is in an active state when the tool is activated.

Properties

  • type (string) - Must be set to toolButton.
  • toolName (string) - Name of the tool, which is either the key from toolModeMap or the name you registered your custom tool with. For custom tool registration, refer to registerTool.
  • hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet and mobile.

Example

const newToolButton = {
  type: 'toolButton',
  toolName: 'AnnotationCreateFreeText',
  hidden: [ 'mobile' ]
}

linkToolGroupButton

ToolGroupButton opens an overlay with the tools in the tool group. Unless the img option is set, the button displays the image of one of the group members. The button is in an active state when any tool in the group is active.

Properties

  • type (string) - Must be set to 'toolGroupButton'.
  • toolGroup (string) - Name of the tool group. In default viewer, there are freeHandTools, textTools, shapeTools and miscTools.
  • img (string, optional) - Path to an image or base64 data.
  • name (string, optional) - Option to set data-element value of the button element. It can be used to disable/enable the element.
  • hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet and mobile.

Example

const newToolGroupButton = {
  type: 'toolGroupButton',
  toolGroup: 'shapeTools',
  name: 'shapeToolGroupButton',
  hidden: [ 'mobile' ]
};

linkSpacer

Spacer is just a div with flex: 1 to occupy any remaining space. It is used to push the buttons to each side on the default header.

Properties

  • type (string) - Must be set to 'spacer'.
  • name (string, optional) - Option to set data-element value of the element. It can be used to disable/enable the element.
  • hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet and mobile.

Example

const newSpacer = {
  type: 'spacer',
  name: 'mySpacer',
  hidden: [ 'mobile' ]
};

linkDivider

Divider renders a vertical bar with some margin to separate item groups.

Properties

  • type (string) - Must be set to 'divider'.
  • name (string, optional) - Option to set data-element value of the element. It can be used to disable/enable the element.
  • hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet and mobile.

Example

const newDivider = {
  type: 'divider',
  name: 'myDivider',
  hidden: [ 'mobile' ]
};

linkRelevant APIs

To add/remove/re-order header items, you can use the following API:

For ToolButton, make sure you register/unregister the tool using:

To switch a header group, you can use the following API: