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.

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 (Tools, References, select box next to OnMerge Addin)
2. In your code:
   
     Dim OnMerge as OnMergeImages.API
     Set OnMerge = New OnMergeImages.API
   
   
3. Call the appropriate API functions on the OnMerge object.

How to grab a field or some text in the Word document for use in OnMerge

Use an oft-overlooked trick... um, technique: Word's Bookmarks. 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.

Sub UpdateAll(Optional doc As Word.Document = <target 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 macro is in a different document than the document with the actual OnMerge graphics in it (i.e. macros in their own document that generate and/or manipulate a target document). For example:

  OnMerge.UpdateAll Application.Documents "MyReport.doc"

If you still are not getting the expected results, try calling UpdateAll with refreshFields = True, e.g.

  OnMerge.UpdateAll Application.ActiveDocument, True

Important: 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.

Function LoadCSVDatasource(Optional doc As Word.Document = <target document>, Optional defaultHeaders as Boolean = True) as Boolean

Pop up the CSV Loader dialog to load a new mail merge datasource from a CSV file (only).

Parameter doc: the Word document to load the datasource into, Application.ActiveDocument by default.

Parameter defaultHeaders: the first row of data files usually contains column header names, but not always. To deal with that, the CSV Loader dialog has a checkbox setting that lets the user indicate that the first row is actual data. This parameter sets the initial value of that setting when the dialog comes up. though the user may change the setting before loading the datasource.

Examples:
  OnMerge.LoadCSVDatasource  'Default to the currently-active document
or
  Dim ok as Boolean
  ok = OnMerge.LoadCSVDatasource(doc:=Application.ActiveDocument, defaultHeaders:=True)

NB Avoid calling this function from a modal VBA Userform. That could lead to LoadCSVDatasource's dialog becoming unresponsive.