Format Contract - Form Entry

Function Description

Form entry functionality aims to improve efficiency and accuracy in standard contract drafting, avoiding manual editing errors.

Usage Instructions: Select a document with bookmarks set, business system automatically generates a form, users can enter content in the form.

Common Requirements

1. Preset Bookmarks: Open document for initialization, fill prepared data (from database, etc.) into corresponding bookmark areas in the document.
2. Restrict Editing (Optional): During contract form entry phase, users are not allowed to manually edit the document.
3. Fill Form:
   • Click an item in the business system form, document automatically locates to the corresponding bookmark position.
   • Fill content in the business system form, content automatically fills into the corresponding bookmark area in the document.
4. User Behavior Listening:
   • When user clicks into a bookmark area in the document, the corresponding form item in the business system enters selected state.
   • When user modifies content in a bookmark area in the document, the modified bookmark area content automatically syncs to the corresponding form item in the business system.
5. Special Requirements (Optional):
   • During document bookmark area content initialization phase, API calls should not trigger document scrolling and focusing.
   • During form filling phase, calling API to locate bookmarks and modify bookmark area content, document should not focus (to prevent grabbing form cursor, causing issues).

---

Code Examples

1. Preset Bookmarks

const bookmarkValues = {
  "Bookmark1": "Bookmark1 content",
  "Bookmark2": "Bookmark2 content",
  "Bookmark3": "Bookmark3 content",
  "Bookmark4": "Bookmark4 content",
  "Bookmark5": "Bookmark5 content"
}

const app = await ZOfficeSDK.mount(docUrl, selector, true);
await app.ready();

// Use initial values in bookmarkValues to fill document during initialization
await initializeBookmarkValues();

// Fill bookmarks with initial values
async function initializeBookmarkValues() {
  for (const [bookmarkName, initialValue] of Object.entries(bookmarkValues)) {
    try {
      // Check if bookmark exists
      const bookmark = await app.ActiveDocument.Bookmarks.item(bookmarkName);
      if (bookmark) {
        // Set content in bookmark area in document
        await bookmark.setText(initialValue);
        console.log(`Initialized bookmark "${bookmarkName}" with value: "${initialValue}"`);
      } else {
        console.warn(`Bookmark "${bookmarkName}" does not exist in document`);
      }
    } catch (error) {
      console.error(`Failed to initialize bookmark "${bookmarkName}":`, error);
    }
  }
}

2. Restrict Editing (Optional)

const app = await ZOfficeSDK.mount(docUrl, selector, true);
await app.ready();

// Enable form protection immediately after mounting document
await app.ActiveDocument.protect(Word.ProtectionType.FormEntry);

3. Fill Form

// Store mapping of bookmark names and input boxes
const bookmarkInputs = {};

// Initialize business system form
async function initBookmarkForm() {
  try {
    // 1. Get all bookmark names in document
    const bookmarks = await app.ActiveDocument.Bookmarks.toJson();
    console.log(bookmarks);

    const formContainer = document.getElementById('bookmarkForm');
    formContainer.innerHTML = '';

    // 2. Add an input box in the form area for each bookmark name
    bookmarks.forEach(bookmarkName => {
      const formItem = document.createElement('div');
      formItem.className = 'form-item';

      const label = document.createElement('label');
      label.textContent = bookmarkName;

      const input = document.createElement('input');
      input.type = 'text';
      input.dataset.bookmarkName = bookmarkName;

      // 3. Listen to input box focus event
      input.addEventListener('focus', async (e) => {
        const bookmarkName = e.target.dataset.bookmarkName;
        try {
          const bookmark = await app.ActiveDocument.Bookmarks.item(bookmarkName);
          await bookmark.focus(); // Locate corresponding bookmark in document
        } catch (error) {
          console.error('Failed to locate bookmark:', error);
        }
      });

      // 4. Listen to input box input event
      input.addEventListener('input', async (e) => {
        const bookmarkName = e.target.dataset.bookmarkName;
        const value = e.target.value;
        try {
          const bookmark = await app.ActiveDocument.Bookmarks.item(bookmarkName);
          await bookmark.setText(value); // Assign input box content to corresponding bookmark area in document
        } catch (error) {
          console.error('Failed to set bookmark content:', error);
        }
      });

      formItem.appendChild(label);
      formItem.appendChild(input);
      formContainer.appendChild(formItem);

      // Store mapping of bookmark name and input box
      bookmarkInputs[bookmarkName] = input;
    });
  } catch (error) {
    console.error('Failed to initialize form:', error);
  }
}

4. User Behavior Listening

// Set up event listeners
async function setupEventListeners() {
  // Listen to IDOCS.EVENT.selectionChange event
  app.addListener('IDOCS.EVENT.selectionChange', async () => {
    try {
      // Clear selected state of all form input boxes
      Object.values(bookmarkInputs).forEach(input => {
        input.classList.remove('selected');
      });

      // Get current selection
      const range = await app.ActiveDocument.getSelection();
      if (!range) return;

      // Get bookmark in current selection
      const bookmark = await range.Bookmarks.item(1);
      if (!bookmark) {
        // Compare relationship between current selection and each bookmark area
        for (const [bookmarkName, input] of Object.entries(bookmarkInputs)) {
          try {
            const bookmark = await app.ActiveDocument.Bookmarks.item(bookmarkName);
            const bookmarkRange = await bookmark.range;
            const relation = await range.compare(bookmarkRange);
            // Check if selection overlaps with bookmark area
            if (relation === Word.LocationRelation.equal || relation === Word.LocationRelation.inside) {
              input.classList.add('selected');
              break;
            }
          } catch (error) {
            console.error('Failed to check bookmark area:', error);
          }
        }
      }
    } catch (error) {
      console.error('Failed to handle selection change event:', error);
    }
  });

  // Listen to IDocs.Event.ContentChange event
  app.addListener('IDocs.Event.ContentChange', async (content) => {
    try {
      if (content.type === 'bookmark' && content.data) {
        content.data.forEach(change => {
          const { id, newData } = change;
          const input = bookmarkInputs[id];
          if (input) {
            // Assign latest content in bookmark area to corresponding input box in form
            input.value = newData || '';
          }
        });
      }
    } catch (error) {
      console.error('Failed to handle content change event:', error);
    }
  });
}

5. Special Requirements (Optional)

const app = await ZOfficeSDK.mount(docUrl, selector, true);
await app.ready();

// Wait for application to load completely before initializing form
// During initialization phase, API calls should not focus document, should not scroll view
await app.setUIState({ cursorContext: { focus: false, scroll: false }});
await initBookmarkForm();

// After initialization, subsequent API calls allow scrolling view, do not allow focusing document
await app.setUIState({ cursorContext: { focus: false, scroll: true }});
await setupEventListeners();