word-js-docs

On changing data in content controls

Registers, triggers, and deregisters onDataChanged event that tracks when data is changed in content controls.

This sample demonstrates how to use the onDataChanged event on content controls.

let eventContexts = [];

async function insertContentControls() {
  // Traverses each paragraph of the document and wraps a content control on each.
  await Word.run(async (context) => {
    const paragraphs: Word.ParagraphCollection = context.document.body.paragraphs;
    paragraphs.load("$none"); // Don't need any properties; just wrap each paragraph with a content control.

    await context.sync();

    for (let i = 0; i < paragraphs.items.length; i++) {
      let contentControl = paragraphs.items[i].insertContentControl();
      contentControl.tag = "forTesting";
    }

    console.log("Content controls inserted: " + paragraphs.items.length);

    await context.sync();
  });
}

async function registerEventHandlers() {
  await Word.run(async (context) => {
    const contentControls: Word.ContentControlCollection = context.document.contentControls;
    contentControls.load("items");
    await context.sync();

    // Register the onDataChanged event handler on each content control.
    if (contentControls.items.length === 0) {
      console.log("There aren't any content controls in this document so can't register event handlers.");
    } else {
      for (let i = 0; i < contentControls.items.length; i++) {
        eventContexts[i] = contentControls.items[i].onDataChanged.add(contentControlDataChanged);
        contentControls.items[i].track();
      }

      await context.sync();

      console.log("Added event handlers for when data is changed in content controls.");
    }
  });
}

async function contentControlDataChanged(event: Word.ContentControlDataChangedEventArgs) {
  await Word.run(async (context) => {
    console.log(`${event.eventType} event detected. IDs of content controls where data was changed:`, event.ids);
  });
}

async function deregisterEventHandlers() {
  await Word.run(async (context) => {
    for (let i = 0; i < eventContexts.length; i++) {
      await Word.run(eventContexts[i].context, async (context) => {
        eventContexts[i].remove();
      });
    }

    await context.sync();

    eventContexts = [];
    console.log("Removed event handlers that were tracking when data is changed in content controls.");
  });
}

async function setup() {
  await Word.run(async (context) => {
    const body: Word.Body = context.document.body;
    body.clear();
    body.insertParagraph("One more paragraph.", "Start");
    body.insertParagraph("Inserting another paragraph.", "Start");
    body.insertParagraph(
      "Do you want to create a solution that extends the functionality of Word? You can use the Office Add-ins platform to extend Word clients running on the web, on a Windows desktop, or on a Mac.",
      "Start"
    );
    body.paragraphs
      .getLast()
      .insertText(
        "Use add-in commands to extend the Word UI and launch task panes that run JavaScript that interacts with the content in a Word document. Any code that you can run in a browser can run in a Word add-in. Add-ins that interact with content in a Word document create requests to act on Word objects and synchronize object state.",
        "Replace"
      );
  });
}

// Default helper for invoking an action and handling errors.
async function tryCatch(callback) {
  try {
    await callback();
  } catch (error) {
    // Note: In a production add-in, you'd want to notify the user through your add-in's UI.
    console.error(error);
  }
}