Custom elements

Individual element customization

The following section uses the Start tab as an example to describe how to add and delete buttons.

• Demonstration

  • Add: A custom element named Button is added to the right of the Start tab toolbar.

  • Delete: The custom element is deleted, and the right side of the toolbar is now empty.

• Syntax

  expression.CommandBars(CommandBarId).Controls.Item(Index)

  Expression: An Application object.

• Parameters

  Parameter	Type	Required	Description
  Index	Number	Yes	The index of the custom element.

• Example

  async function example() {
    await instance.ready();
  
    const app = instance.Application;
  
    // Get the controls for the Start tab.
    const controls = await app.CommandBars('StartTab').Controls;
    
    // Add a button as a custom element.
    const controlButton = await controls.Add(1);
    controlButton.Caption = 'Button';
  
    // Delete the custom element after 6,000 ms.
    setTimeout(() => {
      controlButton.Delete();
    }, 6000);
  }

Set caption

You can use the Caption property to set the caption for a custom element.

• Demonstration: Two custom elements with the captions Button and Drop-down list appear on the right side of the toolbar.

• Syntax

  expression.CommandBars(CommandBarId).Controls.Add(Type).Caption

  Expression: An Application object.

• Example

  async function example() {
    await instance.ready();
  
    const app = instance.Application;
  
    // Get the controls for the Start tab.
    const controls = await app.CommandBars('StartTab').Controls;
    
    // Add a button and set its caption.
    const controlButton = await controls.Add(1);
    controlButton.Caption = 'Button';
    
    // Add a drop-down list and set its caption.
    const controlPopup = await controls.Add(10);
    controlPopup.Caption = 'Drop-down list';
  }

Delete a custom element

You can use the Delete() property to delete custom elements.

• Demonstration

  • Before deletion: The Button and Drop-down list elements are visible on the toolbar.

  • After deletion: The right side of the toolbar is empty.

• Syntax

  expression.CommandBars(CommandBarId).Controls.Add(Type).Delete()

  Expression: An Application object.

• Example

  async function example() {
    await instance.ready();
  
    const app = instance.Application;
  
    // Get the controls for the Start tab.
    const controls = await app.CommandBars('StartTab').Controls;
    
    // Add a button and set its caption.
    const controlButton = await controls.Add(1);
    controlButton.Caption = 'Button';
    
    // Add a drop-down list and set its caption.
    const controlPopup = await controls.Add(10);
    controlPopup.Caption = 'Drop-down list';
  
    // Delete the two custom elements after 6,000 ms.
    setTimeout(() => {
      controlButton.Delete();
      controlPopup.Delete();
    }, 6000);
  }

Disable a custom element

You can use the Enabled property to disable custom elements.

• Demonstration (grayed out): The Button and Drop-down list custom elements are grayed out and cannot be clicked.

• Syntax

  expression.CommandBars(CommandBarId).Controls.Add(Type).Enabled

  Expression: An Application object.

• Example

  async function example() {
    await instance.ready();
  
    const app = instance.Application;
  
    // Get the controls for the Start tab.
    const controls = await app.CommandBars('StartTab').Controls;
    
    // Add a button and disable it.
    const controlButton = await controls.Add(1);
    controlButton.Caption = 'Button';
    controlButton.Enabled = false;
    
    // Add a drop-down list and disable it.
    const controlPopup = await controls.Add(10);
    controlPopup.Caption = 'Drop-down list';
    controlPopup.Enabled = false;
  }

Click a custom element

You can click a custom element by using the Execute() property. By listening for custom element click events, you can determine whether the button was clicked.

• Syntax

  expression.CommandBars(CommandBarId).Controls.Add(Type).Execute()

  Expression: An Application object.

• Example

  async function example() {
    await instance.ready();
  
    const app = instance.Application;
  
    // Get the controls for the Start tab.
    const controls = await app.CommandBars('StartTab').Controls;
    
    // Add a button and set up a click listener.
    const controlButton = await controls.Add(1);
    controlButton.Caption = 'Button';
    controlButton.OnAction = () => console.log('Button was clicked');
    
    // Add a drop-down list and set up a click listener.
    const controlPopup = await controls.Add(10);
    controlPopup.Caption = 'Drop-down list';
    controlPopup.OnAction = () => console.log('Drop-down list was clicked');
  
    // Execute the click action after 6,000 ms.
    setTimeout( async () => {
      await controlButton.Execute();
      await controlPopup.Execute();
    }, 6000);
  }

Listen for click events

After setting up a click event listener, check the console output when the element is clicked. You can then implement your business logic.

• Syntax

  expression.CommandBars(CommandBarId).Controls.Add(Type).OnAction = Function

  Expression: An Application object.

• Example

  async function example() {
    await instance.ready();
  
    const app = instance.Application;
  
    // Get the controls for the Start tab.
    const controls = await app.CommandBars('StartTab').Controls;
    
    // Add a button and set up a click listener.
    const controlButton = await controls.Add(1);
    controlButton.Caption = 'Button';
    controlButton.OnAction = () => console.log('Button was clicked');
    
    // Add a drop-down list and set up a click listener.
    const controlPopup = await controls.Add(10);
    controlPopup.Caption = 'Drop-down list';
    controlPopup.OnAction = () => console.log('Drop-down list was clicked');
  }

Customize element icons

You can customize an element's icon by using the Picture property. The following example shows how to set the icon by using Base64.

• Demonstration: The Button and Drop-down list custom elements display custom icons set by the Picture property.

• Syntax

  expression.CommandBars(CommandBarId).Controls.Add(Type).Picture

  Expression: An Application object.

• Example

  async function example() {
    await instance.ready();
  
    const app = instance.Application;
  
    // Get the controls for the Start tab.
    const controls = await app.CommandBars('StartTab').Controls;
    
    // Add a button and set its icon.
    const controlButton = await controls.Add(1);
    controlButton.Caption = 'Button';
    controlButton.Picture = 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48ZyBmaWxsPSIjM0Q0NzU3IiBmaWxsLXJ1bGU9ImV2ZW5vZGQiPjxwYXRoIGQ9Ik04LjIxMyAxM0g2LjhsNi42MzYtNi42MzYtNC4yNDMtNC4yNDMtNy4wNyA3LjA3MUw1LjkyOCAxM0g0LjUxNUwxLjA2IDkuNTQ2YS41LjUgMCAwIDEgMC0uNzA3TDguODM5IDEuMDZhLjUuNSAwIDAgMSAuNzA3IDBsNC45NSA0Ljk1YS41LjUgMCAwIDEgMCAuNzA3TDguMjEzIDEzeiIgZmlsbC1ydWxlPSJub256ZXJvIi8+PHBhdGggZD0iTTQuNTM2IDYuMzY0bDQuOTUgNC45NS0uNzA3LjcwNy00Ljk1LTQuOTV6TTQuNTIxIDEzaDEwLjAzdjFINS40OTZ6Ii8+PC9nPjwvc3ZnPg==';
    
    // Add a drop-down list and set its icon.
    const controlPopup = await controls.Add(10);
    controlPopup.Caption = 'Drop-down list';
    controlPopup.Picture = 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48ZyBmaWxsPSJub25lIiBmaWxsLXJ1bGU9ImV2ZW5vZGQiPjxwYXRoIGQ9Ik03LjUgMnYyLjVINGEuNS41IDAgMCAwLS41LjV2MmEuNS41IDAgMCAwIC41LjVoOWEuNS41IDAgMCAwIC41LS41VjVhLjUuNSAwIDAgMC0uNS0uNUg5LjVWMmEuNS41IDAgMCAwLS41LS41SDhhLjUuNSAwIDAgMC0uNS41eiIgc3Ryb2tlPSIjM0Q0NzU3Ii8+PHBhdGggZmlsbD0iIzNENDc1NyIgZD0iTTEzIDdoMXY0aC0xeiIvPjxwYXRoIGQ9Ik0xMSAxM2EyIDIgMCAwIDAgMi0yVjguNzY0QTMgMyAwIDEgMSA4Ljc2NCAxM0gxMXoiIGZpbGw9IiMzRDQ3NTciLz48cGF0aCBmaWxsPSIjM0Q0NzU3IiBkPSJNMSAxM2gxMHYxSDF6Ii8+PHBhdGggZD0iTTEgMTNhMiAyIDAgMCAwIDItMlY4Ljc2NEEzIDMgMCAwIDEgMSAxNHYtMXoiIGZpbGw9IiMzRDQ3NTciLz48cGF0aCBmaWxsPSIjM0Q0NzU3IiBkPSJNMyA3aDF2NEgzeiIvPjwvZz48L3N2Zz4=';
  }

Set focus

The SetFocus property sets the focus on a custom element by moving the cursor to its position.

• Demonstration: The drop-down list custom element is highlighted in blue when it receives focus.

• Syntax

  expression.CommandBars(CommandBarId).Controls.Add(Type).SetFocus()

  Expression: An Application object.

• Example

  async function example() {
    await instance.ready();
  
    const app = instance.Application;
  
    // Get the controls for the Start tab.
    const controls = await app.CommandBars('StartTab').Controls;
    
    // Add a button and set focus on it.
    const controlButton = await controls.Add(1);
    controlButton.Caption = 'Button';
    await controlButton.SetFocus();
    
    // Add a drop-down list and set focus on it.
    const controlPopup = await controls.Add(10);
    controlPopup.Caption = 'Drop-down list';
    await controlPopup.SetFocus();
  }

Hide a custom element

You can use the Visible property to hide or show elements.

• Demonstration

  • Show: The Button custom element is visible on the right side of the toolbar.

  • Hide: The custom element is hidden.

• Syntax

  expression.CommandBars(CommandBarId).Controls.Add(Type).Visible

  Expression: An Application object.

• Example

  async function example() {
    await instance.ready();
  
    const app = instance.Application;
  
    // Get the controls for the Start tab.
    const controls = await app.CommandBars('StartTab').Controls;
    
    // Add a button as a custom element.
    const controlButton = await controls.Add(1);
    controlButton.Caption = 'Button';
  
    // Add a drop-down list as a custom element.
    const controlPopup = await controls.Add(10);
    controlPopup.Caption = 'Drop-down list';
  
    // Hide the custom elements after 6,000 ms.
    setTimeout(() => {
      controlButton.Visible = false;
      controlPopup.Visible = false;
    }, 6000);
  }

Set a tooltip

You can use the TooltipText property to set the tooltip for a custom element.

• Demonstration

  • Button: When you hover over the button, the tooltip Tooltip: Button is displayed.

  • Drop-down list: When you hover over the drop-down list, the tooltip Tooltip: Drop-down list is displayed.

• Syntax

  expression.CommandBars(CommandBarId).Controls.Add(Type).TooltipText

  Expression: An Application object.

• Example

  async function example() {
    await instance.ready();
  
    const app = instance.Application;
  
    // Get the controls for the Start tab.
    const controls = await app.CommandBars('StartTab').Controls;
    
    // Add a button and set its tooltip.
    const controlButton = await controls.Add(1);
    controlButton.Caption = 'Button';
    controlButton.TooltipText = 'Tooltip: Button';
  
    // Add a drop-down list and set its tooltip.
    const controlPopup = await controls.Add(10);
    controlPopup.Caption = 'Drop-down list';
    controlPopup.TooltipText = 'Tooltip: Drop-down list';
  }

Individual mobile elements

You can use the Controls property to access the element and control its caption, image, click behavior, and more.

This section uses the button on the bottom toolbar (WriterHoverToolbars) to demonstrate how to add a new button.

• Add a custom element

  A custom Button entry is added to the mobile bottom toolbar, displayed alongside the default Edit, Comment, and Continuous Page options.

• Syntax

  expression.CommandBars(CommandBarId).Controls.Add(Index)

  Expression: An Application object.

• Parameters

• Example

  async function example() {
    await instance.ready();
  
    const app = instance.Application;
  
    const controls = window.instance.Application.CommandBars.Item('WriterHoverToolbars').Controls;
      // Add a custom button element.
    const controlButton = await controls.Add(20);
    // Set the caption.
    controlButton.Caption = 'Button';
    // Set the icon.
    controlButton.Picture = 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48ZyBmaWxsPSIjM0Q0NzU3IiBmaWxsLXJ1bGU9ImV2ZW5vZGQiPjxwYXRoIGQ9Ik04LjIxMyAxM0g2LjhsNi42MzYtNi42MzYtNC4yNDMtNC4yNDMtNy4wNyA3LjA3MUw1LjkyOCAxM0g0LjUxNUwxLjA2IDkuNTQ2YS41LjUgMCAwIDEgMC0uNzA3TDguODM5IDEuMDZhLjUuNSAwIDAgMSAuNzA3IDBsNC45NSA0Ljk1YS41LjUgMCAwIDEgMCAuNzA3TDguMjEzIDEzeiIgZmlsbC1ydWxlPSJub256ZXJvIi8+PHBhdGggZD0iTTQuNTM2IDYuMzY0bDQuOTUgNC45NS0uNzA3LjcwNy00Ljk1LTQuOTV6TTQuNTIxIDEzaDEwLjAzdjFINS40OTZ6Ii8+PC9nPjwvc3ZnPg==';
    
  }

Mobile toolbar style

You can set a uniform style for the mobile bottom toolbar to display only text, only icons, or both text and icons.

• Show text only

  The mobile bottom toolbar displays only the text labels Edit, Comment, Continuous Page, and Button, without their icons.

• Show icons only

  The mobile bottom toolbar displays only the icons, without their text labels.

• Syntax

  expression.CommandBars.Item(CommandBarId).CommandBarMode(WdCommandBar)

  Expression: An Application object. For parameter information, see Enum.WdCommandBar.

• Example

  async function example() {
    await instance.ready();
  
    const app = instance.Application;
  
    const controls = window.instance.Application.CommandBars.Item('WriterHoverToolbars').Controls;
  
    await commandBar.CommandBarMode(1);
    
  }

Add items to revision settings

• Add a first-level item to Revision Settings

  In the Review tab's Revision Settings drop-down menu, a custom first-level item is added at the bottom, alongside default options like Accept Revisions, Reject Revisions, Revision Status, and Revision Pane.

• Add a second-level item to Revision Settings

  Hovering over the first-level item expands a submenu that displays the custom second-level item option.

• Syntax

  expression.CommandBars(CommandBarId).Controls.Add(10)

  Expression: An Application object.

• Examples

  • Add a first-level item

    async function example() {
        await instance.ready();
    
        const app = instance.Application;
    
        const controls = await app.CommandBars('RevisionSetting').Controls;
    
        const button = await controls.Add(10);
        // Set the caption.
        button.Caption = 'First-level Item';
        // Add a click event.
        button.OnAction = () => console.log('First-level item clicked');
        // Set the Enabled property.
        button.Enable = false;
    }

  • Add a second-level item

    async function example() {
        await instance.ready();
    
        const app = instance.Application;
    
        const controls = app.CommandBars('RevisionSetting').Controls;
        const button = await controls.Add(10);
        button.Caption = 'First-level Item';
        const popupControls = await button.Controls;
        // Add a second-level item.
        const button1 = await popupControls.Add(1);
        // Set the caption for the second-level item.
        button1.Caption = 'Second-level Item';
        // Set the click event for the second-level item.
        button1.OnAction = () => console.log('Second-level item clicked');
    }

Add an element to a drop-down list

You can use the Add() property to add new custom elements to the drop-down list.

• Syntax

  expression.CommandBars(CommandBarId).Controls.Add(10).Controls.Add()

  Expression: An Application object.

• Example

  async function example() {
    await instance.ready();
  
    const app = instance.Application;
    
    // Get the controls for the Start tab.
    const controls = await app.CommandBars('StartTab').Controls;
  
    // Add a drop-down list as a custom element.
    const control = await controls.Add(10);
    control.Caption = 'Drop-down list';
    
    // Get the controls of the drop-down list.
    const popupControls = await control.Controls;
  
    // Add a custom element inside the drop-down list.
    const button = await popupControls.Add(1);
    button.Caption = 'Drop-down button 1';
  }

Individual elements in a drop-down list

• Syntax

  expression.CommandBars(CommandBarId).Controls.Add(10).Controls.Item(Index)

  Expression: An Application object.

• Parameters

  Parameter	Type	Required	Description
  Index	Number	Yes	The index of the custom element within the drop-down list.

• Example

  //@file=base.docx
  async function example() {
    await instance.ready();
  
    const app = instance.Application;
    
    // Get the controls for the Start tab.
    const controls = await app.CommandBars('StartTab').Controls;
  
    // Add a drop-down list as a custom element.
    const control = await controls.Add(10);
    control.Caption = 'Drop-down list';
    
    // Get the controls of the new drop-down list.
    const popupControls = await control.Controls;
  
    // Add an individual element to the drop-down list.
    const button = await popupControls.Add(1);
    button.Caption = 'Drop-down button 1';
  
    // Get the first element in the drop-down list by its index and modify its caption.
    const item1 = await popupControls.Item(1);
    item1.Caption = 'Modified drop-down button';
  }