word-js-docs

On changing selection in content controls

Registers, triggers, and deregisters onSelectionChanged event that tracks when selections are changed in content controls.

This sample demonstrates how to use the onSelectionChanged 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();

    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].onSelectionChanged.add(contentControlSelectionChanged);
        contentControls.items[i].track();
      }

      await context.sync();

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

async function contentControlSelectionChanged(event: Word.ContentControlSelectionChangedEventArgs) {
  await Word.run(async (context) => {
    console.log(`${event.eventType} event detected. IDs of content controls where selection 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 selection 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);
  }
}