APE Word Add-in

Damstra Forms' APE Word Add-in makes it easy to insert merge fields into Microsoft Word DOCX files (Windows only).

When forms and actions have been filled-out, they can be output as a PDF file. The appearance of those PDFs is configured (in advance) by using a Microsoft Word file in the template. Word makes it easy to control the document’s appearance by using formatting, headers/footers, tables, logos, etc.

There is a need to direct where pieces of information will appear in the PDF. That is done by getting the fields from the template editor as ‘merge fields’ and inserting them inside the Word document. Previously that was done using Word’s mail merge manager but the Word Add-in makes it easier, as that is specifically for the purpose. It saves time in many ways including:

• Keeping the list of fields open
• Doing smart table updating
• Linking to a Damstra Forms server directly instead of using CSV files
• Automatically putting Image: into signature and image fields
• By-passing Word's limit on the number of merge fields

Requirements

Microsoft™ Word version 2010 or higher, running on Windows™.

If your computer has a different operating system then you’ll need to either use a Windows emulator (like Parallels on Macs) or use Word’s Mail Merge functionality instead of the Add-in.

Download and Installation

Download

If you have admin permission then download the EXE installer from here 

If you don't have admin permission then download the MSI installer from here

Installation

If you have an existing installation that is older than version 1.2 then uninstall that first.

1. Unzip the downloaded file
2. Close Microsoft™ Word
3. If you have an existing installation then uninstall it using Add/Remove Programs, if possible.
4. Run APEWordAddInInstall (EXE or MSI) and follow the installation wizard*
5. Check inside Word** that the Add-in is installed correctly

*When doing step 4, if you get a Windows SmartScreen message as shown below ten click "More info" and "Run anyway".

** When restarting Word, if you get the following dialog then click "Install".

Using the Add-in

Open your template fields list

1. Open your template’s DOCX Word File
2. Optional: Save a new copy of your DOCX with Merged in the filename.
3. On Word’s Insert tab, click APE Template Fields.

4. Log into your server, like below. Don’t put http:// or https:// at the start of the server name.

5. Select your template.

6. The Add-in shows the template’s Sections and the Display Name for each field.

7. To expand (see inside) a group of fields, such as Project fields and fields in tables, click the > button. You can also use that to expand tables’ rows.

8. If you have a question field that links to a form or action then its list of merge fields will include a Form or Action section like that shown below, which you can expand to access the other template's fields.

If you don't see the expandable section then ask Damstra Forms support.

Insert fields into the document

Left-click drag fields from the list to the desired location in your Word file.

Alternatively, if you prefer you can double-click the Display Name and then its field will be inserted at the current text cursor location.

Smart Table Handling

If you have a table in your template then the add-in makes it easy to insert its merge fields into a table in your Word DOCX. After you have inserted fields into the first row of the DOCX, the add-in can automatically complete all of the other rows, so that they are like the first row but with appropriate row numbers (R2, R3, etc).

The steps are:

1.  Ensure that you have a table in Word with the matching number of rows and columns.
2. Using the add-in, insert merge fields as desired into the first row. Tip: if desired, you can put multiple fields into a cell.
3. Insert a field into one of the cells in the 2nd The add-in will ask "Would you like to automatically fill in the rest of this table using the first row as a template?"

That is also triggered if you copy-and-paste the first row’s cells to other rows. If you don’t want that prompt to appear at that time, then have the add-in closed while copy-and-pasting.

4. Choose Yes, and then the add-in will complete the rows. Progress is displayed at the bottom of Word.

More about the Add-in

Previewing

It is important to check how the final result will look as a PDF with data inside it. To view a PDF preview, containing sample data from the template, click the green preview button.

The PDF will open in the default PDF viewer on your computer, for example Adobe Acrobat Reader.

You can specify to include a sample signature image and/or attached photo by clicking "Preview Template".

Refreshing the fields list

If you create a new template or change a template that you're working on (using the template editor in the web app) then you’ll want to see the change in the add-in. Do that by clicking the refresh link at the bottom of the Add-in. That triggers it to re-read template information from the server.

Image and Signature Fields

When you insert an Image or Signature field then the add-in automatically inserts "Image:" inside the merge field - which is necessary in order to display that correctly image in the PDF. You can see that by right-clicking on the signature merge field and selecting "Toggle Field Codes".

You can control the size that the Image or Signature will be displayed, as follows:

1.Insert the Image or Signature field using the Add-in
2. Click on the inserted merge field (to select it)
3. Near the bottom of the Add-in, a dropdown list will appear, initially saying "None"
4. From the dropdown list choose "Scale to Fit" or "Specify Size"

"Scale to Fit" is suitable when the merge field is within a table cell or a text box. It maximizes the size of the image to fit the cell/box, while maintaining its aspect ratio

"Specify Size" allows you to specify a height and/or width. If you specify both then that may change its aspect ratio (by necessity).

When controlling the size of signatures, specifying a height between 12 and 30 typically works well. Use the Preview function to see how that will look.

Matching Merge Fields to Display Names

If you click on a Merge Field in the DOCX then the add-in’s fields list will highlight the matching Display Name.

Insert Section as a Table

You can make the Add-in create a table in the Word document containing every field in a section, by right-clicking the section and choosing "Insert As Table"

to produce a result like shown below.