Programming API

This page is for expert software developers who are creating or modifying Word documents using Word's VBA programming model. If this isn't you, please ignore this page. Note that OnMerge support cannot offer help with Word VBA programming questions.

Important warning

If you're running a mail merge from a macro (AutoOpen for example), use a .doc (compatibility mode) Word document -- not a newer-style .docx or .docm document. That will avoid a bug in Word that prevents OnMerge from merging properly.

An oft-overlooked trick... um, technique: Bookmarks

How to access some field or text already in the Word document for use in OnMerge: you can easily set that up in Word by highlighting the text or field in the document and wrapping it in a named Bookmark (Links, Bookmark on the Insert tab of the Ribbon).

In OnMerge, pull in the text covered by the Bookmark into a Name Part by setting the Name Part Type to Bookmark and selecting the Bookmark's name from the list.

A variation on this technique is to hide the bookmarked information by making the text white (invisible) after setting up the Bookmark.

The basic interface to OnMerge

All access to the OnMerge API is done through the OnMergeImages.API object, including for OnMerge Images and OnMerge Barcodes. It can only be used by VBA programs running within Word, not by external Automation.

To prepare the OnMerge.API object for use within VBA:

  1. Set a Reference to "OnMerge Addin" within the project
  2. In your code:

      Dim OnMerge as OnMergeImages.API
      Set OnMerge = New OnMergeImages.API


  3. Call the appropriate API functions below on the OnMerge object.

Sub UpdateAll(Optional doc As Word.Document = <currently active document>, Optional refreshFields As Boolean = False)

Forces OnMerge to refresh all images and barcodes in the specificed document if their linked data has changed. This operation can be quite time-consuming for large documents.

OnMerge normally refreshes its graphic objects when the linked data (e.g. bookmarks or database fields) change. It does this by tracking the users' GUI operations to detect the changes and trigger refreshes of the on-screen graphics. However, OnMerge will probably not be aware of any changes to linked data made by VBA programs since there are no GUI events to track.

In such situations, your program must force OnMerge to refresh its images by calling

  OnMerge.UpdateAll

after making a batch of changes.

Normally, you won't need to specify the doc parameter unless your VBA program is running in a document that's separate from the document with the actual OnMerge graphics in it. If you still are not getting the expected results, try calling UpdateAll with refreshFields = True, e.g.

  OnMerge.UpdateAll Application.ActiveDocument, True

Note that refreshFields = True should only be tried if you observe actual problems since it may cause problems beyond the scope of this discussion, especially if the document contains { NextRecord } fields.