Exercise - Create content controls and replace content

Completed

In this exercise, you'll learn how to create rich text content controls in the document, and then how to insert and replace content in the controls.

Important

This exercise assumes you have created the Word add-in in the previous exercise in this module.

Note

There are several types of content controls that can be added to a Word document through the UI, but currently only rich text content controls are supported by Word.js.

Create a content control

  1. Open the file ./src/taskpane/taskpane.html.

  2. Locate the <button> element for the insert-table button, and add the following markup after that line:

    <button class="ms-Button" id="create-content-control">Create Content Control</button><br/><br/>
    
  3. Open the file ./src/taskpane/taskpane.js.

  4. Within the Office.onReady() method call, locate the following line in the Office.onReady() method:

    document.getElementById("insert-table").onclick = insertTable;
    

    Add the following code immediately after it:

    document.getElementById("create-content-control").onclick = createContentControl;
    
  5. Add the following function to the end of the file:

    async function createContentControl() {
      await Word.run(async (context) => {
        // TODO1: Queue commands to create a content control.
    
        await context.sync();
      })
      .catch(function (error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
          console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
      });
    }
    
  6. Within the createContentControl() function, replace TODO1 with the following code:

    const serviceNameRange = context.document.getSelection();
    const serviceNameContentControl = serviceNameRange.insertContentControl();
    serviceNameContentControl.title = "Service Name";
    serviceNameContentControl.tag = "serviceName";
    serviceNameContentControl.appearance = "Tags";
    serviceNameContentControl.color = "blue";
    

    Note

    • This code is intended to wrap the phrase "Microsoft 365" in a content control. It makes a simplifying assumption that the string is present and the user has selected it.
    • The ContentControl.title property specifies the visible title of the content control.
    • The ContentControl.tag property specifies a tag that can be used to get a reference to a content control using the ContentControlCollection.getByTag() method, which you'll use in a later function.
    • The ContentControl.appearance property specifies the visual look of the control. Using the value "Tags" means that the control will be wrapped in opening and closing tags, and the opening tag will have the content control's title. Other possible values are "BoundingBox" and "None".
    • The ContentControl.color property specifies the color of the tags or the border of the bounding box.

Replace the content of the content control

  1. Open the file ./src/taskpane/taskpane.html.

  2. Locate the <button> element for the create-content-control button, and add the following markup after that line:

    <button class="ms-Button" id="replace-content-in-control">Rename Service</button><br/><br/>
    
  3. Open the file ./src/taskpane/taskpane.js.

  4. Within the Office.onReady() method call, locate the following line in the Office.onReady() method:

    document.getElementById("create-content-control").onclick = createContentControl;
    

    Add the following code immediately after it:

    document.getElementById("replace-content-in-control").onclick = replaceContentInControl;
    
  5. Add the following function to the end of the file:

    async function replaceContentInControl() {
      await Word.run(async (context) => {
        // TODO1: Queue commands to replace the text in the Service Name
        //        content control.
    
        await context.sync();
      })
      .catch(function (error) {
        console.log("Error: " + error);
        if (error instanceof OfficeExtension.Error) {
          console.log("Debug info: " + JSON.stringify(error.debugInfo));
        }
      });
    }
    
  6. Within the replaceContentInControl() function, replace TODO1 with the following code. Note:

    • The ContentControlCollection.getByTag() method returns a ContentControlCollection of all content controls of the specified tag. We use getFirst to get a reference to the desired control.

      const serviceNameContentControl = context.document.contentControls.getByTag("serviceName").getFirst();
      serviceNameContentControl.insertText("Fabrikam Online Productivity Suite", "Replace");
      
  7. Verify that you've saved all of the changes you've made to the project.

Test the add-in

  1. Repeat the steps from the previous exercise to sideload the add-in.
  2. If the add-in task pane isn't already open, from the Home tab, select Show Taskpane.
  3. In the task pane, select the Insert Paragraph button to ensure that there's a paragraph with "Microsoft 365" at the top of the document.
  4. In the document, select the text "Microsoft 365" and then select the Create Content Control button. The phrase is wrapped in tags labeled "Service Name".
  5. Select the Rename Service button and note that the text of the content control changes to "Fabrikam Online Productivity Suite".

Screenshot of content control created and changed by tutorial in Word.

Summary

In this exercise, you learned how to create rich text content controls in the document, and then you learned how to insert and replace content in the controls.

Test your knowledge

1.

How can a Word add-in get a reference to a content control in the current document?

2.

Which of the following options is used to update the contents of a content control?