Customize the Navigation Bar

One key part of customizing the UI is the customization of the navigation bar. There are several ways you may want to customize the navigation bar. To name a few:

• Add a custom save button.
• Remove existing tools from the navigation bar.
• Rearrange the feature area.
• Hide the text field tool in the sub-menus of the forms feature and move them to the right side of the navigation bar.

ComPDF for Web's WebViewer UI provides flexible APIs for easy customization of the navigation bar.

To understand the structure of the navigation bar and the different types of tools, you can read The Composition of the Navigation Bar and Navigation Bar Tools. You can also jump directly to the UI Customization Samples to see examples of customizing the navigation bar.

The Composition of the Navigation Bar

The navigation bar is mainly divided into three parts: Navigation Tools, Feature Area, and the sub-menus of corresponding features (including sub-toolbars).

• Navigation Tools: The icon buttons on the left and right sides of the image below (Navigation Bar) are the Navigation Tools.

  

• Feature Area： The part inside the feature box in the middle of the navigation bar is called the Feature Area (as shown in the image below). Each feature has a different Sub-Menus. Buttons in both the Feature Area and the Sub-Menus can be modified individually.

• Sub-Menus： Under different Feature Areas, there are corresponding Sub-Menus showing a group of tools for that feature. ComPDF for Web provides various APIs to customize the tools within this Sub-Menus. Below, the Sub-Menus for annotations and forms are shown:

  

  

Hide/Show Navigation Bar Elements

Find the Data Element Attribute of the Navigation Bar

To hide or show navigation bar elements, you first need to find the element’s data-element attribute in the DOM inspector.

For Example, the image below is the DOM of the Toolbar of the Feature Area.

We can see that their data-element value. Now we can use this value to hide or show it.

Hiding/Showing Navigation Bar Elements

• Hide/Show the annotation button in the Feature Area:

// Hide the annotation button in the feature area.
instance.UI.disableElements('toolbarGroup-Annotation');
// Show the annotation button in the feature area.
instance.UI.enableElements('toolbarGroup-Annotation');

• Hide/Show multiple navigation bar elements:

// Hide the left panel button and the search button.
instance.UI.disableElements(['leftPanelButton', 'searchButton']);
// Show the left panel button and the search button.
instance.UI.enableElements(['leftPanelButton', 'searchButton']);

Switching Feature Areas

You can call setToolbarGroup to switch between the different feature modes in the Feature Area.

ComPDFKitViewer.init(...)
  .then(instance => {
    // Set the current toolbar group.
    instance.UI.setToolbarGroup('toolbarGroup-Annotation');
  });

Properties and Types of Navigation Tools

Navigation Tools are objects with certain properties. You can add, remove, or move Navigation Tool buttons by calling setHeaderItems. If you would like to add custom tools to the navigation bar, it is crucial to understand what types of custom tools you need to add and which attributes to use. Below are the properties and types for Navigation Tools.

instance.UI.setHeaderItems(header => {
  header.update([
    {
      type: 'toolButton',
      dataElement: 'handToolButton',
      toolName: 'pan',
      icon: 'Pantool',
    },
    {
      type: 'toggleElementButton',
      dataElement: 'searchButton',
      element: 'searchPanel',
      icon: 'Search'
    },
    { type: 'divider' },
    {
      type: 'actionButton',
      dataElement: 'downloadButton',
      icon: 'Download',
      onClick: download
    }
  ]);
});

1. Set the Header

Parameters for the setHeaderItems callback function: header object, can invoke get, getItems, shift, unshift, push, pop, delete, and update to perform corresponding operations on navigation tools and the toolbar.

instance.UI.setHeaderItems(header => {
  // Get all feature area.
  const items = header.getHeader('default').getItems();
  console.log(items);
});

2. Action Button

An action button can trigger an action. This kind of button has no active state. Its properties include:

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

const newActionButton = {
  type: 'actionButton',
  img: 'path/to/image',
  text: 'Alert',
  onClick: () => {
    alert('Hello world!');
  },
  dataElement: 'alertButton'
};

3. State Button

The state button is a customizable button. You can decide how many states it has, what state is active, and when to update the state. Its properties include：

• type (string) - Must be set to statefulButton.
• initialState (string) - String that is one of states object's keys.
• states (object) - The shape of the object looks like： { nameOfState1: state1, nameOfState2: state2, ... }
• The properties of states include:
  • img (string, optional): Path to an image or base64 data.
  • getContent (function, optional): Function to be called when you update the state. Define this property if you don't use the img property for this button getContent has a parameter activeState. activeState is an object that corresponds to the value of initialState in states.
  • onClick (function): A function that is triggered when clicked. onClick has a parameter activeState. activeState is an object that corresponds to the value of initialState in states.
  • More properties you need.
• mount (function) - Function to be called after the button is mounted into DOM.
• unmount (function, optional) - Function to be called before the button is unmounted from DOM.
• title (string, optional) - Tooltip of the button.
• dataElement (string, optional) - String to set data-element value of the button element.
• hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet, mobile and small-mobile.

Examples:

A stateful button that shows the count. When you click it, it will increment the counter by 1.

const countButton = {
  type: 'statefulButton',
  initialState: 'Count',
  states: {
    Count: {
      number: 1,
      getContent: activeState => {
        return activeState.number;
      },
      onClick: activeState => {
        activeState.number += 1;
      }
    }
  },
  dataElement: 'countButton'
};

A state button showing the current page number. When you click it, the document will go to the next page. If you are on the last page, the document will turn to the first page.

const nextPageButton = {
  type: 'statefulButton',
  initialState: 'Page',
  states: {
    Page: {
      getContent: Core.getCurrentPage,
      onClick: activeState => {
        const currentPage = Core.getCurrentPage();
        const totalPages = Core.getPagesCount();
        const atLastPage = currentPage === totalPages;

        if (atLastPage) {
          Core.previousPage();
        } else {
          Core.nextPage();
        }
        activeState.getContent = Core.getCurrentPage();
      }
    }
  },
  mount: () => {
    // Execute after mounting.
    console.log('Mounted.');
  },
  unmount: () => {
    // Execute before destruction.
    console.log('Destroyed.');
  },
  dataElement: 'nextPageButton'
};

4. Toggle Element Button

The toggle element button is used to open/close a specified UI element. When the UI element is open, the button is in an active state.

Its properties include：

• type (string) - Must be set to toggleElementButton.
• img (string) - The path to an image or base64 data.
• element (string) - The property value of the data-element UI element to be opened/closed.
• title (string, optional) - Tooltip text for the button.
• dataElement (string, optional) - Set the option for the data-element button element value. It can be used for showing/hiding that element.
• text (string, optional)- Set the text displayed for the button.
• hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet, mobile and small-mobile.

const newToggleButton = {
  type: 'toggleElementButton',
  img: `path/to/image`,
  element: 'pageModePanel',
  dataElement: 'pageModePanelButton',
  hidden: [ 'mobile' ]
};

5. Tool Button

The tool button is the button in the sub-menus under the feature module. For example, in the Form feature mode, you can create a button for a text field function by customizing a tool button and specifying its element value as textfield. You can place the tool buttons you need to customize anywhere. When the tool is activated, the button is in an active state.

Its properties include：

• type (string) - Must be set to toolButton.
• toolName (string) - The data-element button element value of the target tool.
• title (string, optional) - Tooltip of the button.
• text (string, optional)- Set the text displayed for the button.
• dataElement (string, optional) - Set the option for the data-element button element value. It can be used for showing/hiding that element.
• hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet, mobile and small-mobile.

const newToolButton = {
  type: 'toolButton',
  toolName: 'textfield',
  dataElement: 'textfieldButton'
};

6. Spacer

The spacer is just a div with a CSS attribute of flex: 1, used to occupy any remaining space in the tool. It is used to push buttons to each side of the default title.

Its properties include：

• type (string) - Must be set to spacer.
• hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet, mobile and small-mobile.

const newSpacer = {
  type: 'spacer',
  hidden: [ 'mobile', 'small-mobile' ]
};

7. Divider

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

Its properties include：

• type (string) - Must be set to divider.
• hidden (array of strings, optional) - Option to hide the element at certain screen sizes. Accepted strings are desktop, tablet, mobile and small-mobile.

const newDivider = {
  type: 'divider',
  hidden: [ 'mobile', 'small-mobile' ]
};

Examples of Custom UI

Add a custom save button:

instance.UI.setHeaderItems(header => {
  const mySaveButton = {
    type: 'actionButton',
    dataElement: 'mySaveButton',
    img: `<svg width="14" height="14" viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
            <path d="M13 1L1 13" stroke="#BABABA" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
            <path d="M1 1L13 13" stroke="#BABABA" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
          </svg>`,
    onClick: function() {
      Core.download();
    }
  }
  header.push(mySaveButton);
});

Hide the text field tool in the form function area and put it on the right side of the navigation bar:

instance.UI.setHeaderItems(header => {
  // get the freetext tool.
  const freetext = header.getHeader('toolbarGroup-Annotation').get('freetextButton');
  header.getHeader('toolbarGroup-Annotation').delete('freetextButton');
  // add the line tool to the top header.
  header.getHeader('default').push({
    type: 'toolButton',
    toolName: 'line',
    dataElement: 'lineButton'
  });
  // add the freetext tool to the top header.
  header.push(freetext);
});

Remove existing buttons from the top header, leaving only the ribbon:

instance.UI.setHeaderItems(header => {
  const items = header.getItems().slice(9, -3);
  header.update(items);
});

Display and hide of bottom page box:

// Show bottom page box.
instance.UI.disableElements('pageNavOverlay');
// Hide bottom page box.
instance.UI.enableElements('pageNavOverlay');