correlated-objects-pattern.yaml

order: 3
id: word-scenarios-correlated-objects-pattern
name: Correlated objects pattern
description: Shows the performance benefits of avoiding `context.sync` calls in a loop.
author: OfficeDev
host: WORD
api_set:
    WordApi: '1.4'
script:
    content: |
        $("#replace-placeholders").on("click", () => tryCatch(replacePlaceholders));  $("#replace-placeholders-slow").on("click", () => tryCatch(replacePlaceholdersSlow)); $("#setup").on("click", () => tryCatch(setup)); $("#add-lots-of-text").on("click", () => tryCatch(addLotsOfText));
        const jobMapping = [
          { job: "{Coordinator}", person: "Sally" },
          { job: "{Deputy}", person: "Bob" },
          { job: "{Manager}", person: "Kim" }
        ];
        async function replacePlaceholders() {
          Word.run(async (context) => {
            const startTime = Date.now();
            let count = 0;

            // Find the locations of all the placeholder strings.
            const allSearchResults = [];
            for (let i = 0; i < jobMapping.length; i++) {
              let options = Word.SearchOptions.newObject(context);
              options.matchWildcards = false;
              let searchResults = context.document.body.search(jobMapping[i].job, options);
              searchResults.load('items');
              let correlatedSearchResult = {
                rangesMatchingJob: searchResults,
                personAssignedToJob: jobMapping[i].person
              }
              allSearchResults.push(correlatedSearchResult);
            }

            // Sync to load those locations in the add-in.
            await context.sync()

            // Replace the placeholder text at the known locations.
            for (let i = 0; i < allSearchResults.length; i++) {
              let correlatedObject = allSearchResults[i];

              for (let j = 0; j < correlatedObject.rangesMatchingJob.items.length; j++) {
                let targetRange = correlatedObject.rangesMatchingJob.items[j];
                let name = correlatedObject.personAssignedToJob;
                targetRange.insertText(name, Word.InsertLocation.replace);
                count++;
              }
            }

            await context.sync();
            console.log(`Replacing ${count} placeholders with the correlated objects pattern took ${Date.now() - startTime} milliseconds.`);
            console.log()
          });
        }
        async function replacePlaceholdersSlow() {
          Word.run(async (context) => {
            const startTime = Date.now();
            let count = 0;

            // The context.sync calls in the loops will degrade performance.
            for (let i = 0; i < jobMapping.length; i++) {
              let options = Word.SearchOptions.newObject(context);
              options.matchWildcards = false;
              let searchResults = context.document.body.search(jobMapping[i].job, options);
              searchResults.load('items');

              await context.sync();

              for (let j = 0; j < searchResults.items.length; j++) {
                searchResults.items[j].insertText(jobMapping[i].person, Word.InsertLocation.replace);
                count++;
                await context.sync();
              }
            }
            console.log(`Replacing ${count} placeholders with in-loop sync statements took ${Date.now() - startTime} milliseconds.`);
          });
        }
        async function setup(timesToAddText: number = 1) {
          await Word.run(async (context) => {
            console.log("Setup beginning...");
            const body: Word.Body = context.document.body;
            body.clear();
            while (timesToAddText > 0) {
              body.insertParagraph(
                "This defines the roles of {Coordinator}, {Deputy}, {Manager}.",
                Word.InsertLocation.end
              );
              body.insertParagraph(
                "{Coordinator}: Oversees daily operations and ensures projects run smoothly by coordinating between different teams and resources.",
                Word.InsertLocation.end
              );
              body.insertParagraph(
                "{Deputy}: Assists and supports senior management, often stepping in to make decisions or manage tasks in {Manager}'s absence.",
                Word.InsertLocation.end
              );
              body.insertParagraph(
                "{Manager}: Leads the team, setting goals, planning strategies, and making decisions to achieve organizational objectives.",
                Word.InsertLocation.end
              );
              timesToAddText--;
            }
            await context.sync();
            console.log("Setup complete.");
          });
        }
        async function addLotsOfText() {
          // Add the setup text 100 times.
          setup(100);
        }
        // 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);
          }
        }
    language: typescript
template:
    content: |-
        <section class="ms-Fabric ms-font-m">
          <p>This sample demonstrates the performance optimization gained from the correlated objects pattern. For more information, see <a href="https://learn.microsoft.com/en-us/office/dev/add-ins/concepts/correlated-objects-pattern">Avoid using the context.sync method in loops</a>.</p>
        </section>

        <section class="ms-Fabric samples ms-font-m">
          <h3>Setup</h3>
          <p>Use <b>Setup</b> to create a basic text block with some placeholders. Use <b>More text</b> to create a longer text block to better see performance distinctions.</p>
          <button id="setup" class="ms-Button">
              <span class="ms-Button-label">Setup</span>
          </button><button id="add-lots-of-text" class="ms-Button">
              <span class="ms-Button-label">More text</span>
          </button>
        </section>

        <section class="ms-Fabric samples ms-font-m">
          <h3>Replace placeholder text</h3>
          <button id="replace-placeholders" class="ms-Button">
              <span class="ms-Button-label">Replace all</span>
          </button>
          <button id="replace-placeholders-slow" class="ms-Button">
              <span class="ms-Button-label">Replace all (slow)</span>
          </button>
        </section>
    language: html
style:
    content: |-
        section.samples {
            margin-top: 20px;
        }

        section.samples .ms-Button, section.setup .ms-Button {
            display: block;
            margin-bottom: 5px;
            margin-left: 20px;
            min-width: 80px;
        }
    language: css
libraries: |
    https://appsforoffice.microsoft.com/lib/1/hosted/office.js
    @types/office-js

    office-ui-fabric-core@11.1.0/dist/css/fabric.min.css
    office-ui-fabric-js@1.5.0/dist/css/fabric.components.min.css

    core-js@2.4.1/client/core.min.js
    @types/core-js

    jquery@3.1.1
    @types/jquery@3.3.1