We're sorry Aspose doesn't work properply without JavaScript enabled.

Free Support Forum - aspose.com

A few mail merge questions before purchase


Currently I'm evaluating Aspose.Words for use in a project I'm working on and I must say: I'm impressed with the powerful yet easy to use API.

I have a few questions about using mail merge:

1) I am aware that Range.UpdateFields() only updates DOCPROPERTY and DOCVARIABLE fields for the moment. Any news on when and what other fields will be supported (IF, ASK, COMPARE, ...)?

2) Is there a way to control the size of an image being inserted in the template (using MergeImageField-event)?

3) When I use merge regions (ExecuteWithRegions) I would sometimes like to repeat the records one after another instead of below each other. An example:

I have a DataTable "Items" which looks like this:

1 Item 1
2 Item 2
3 Item 3

I would like to display the following in my document:

Item 1 (ID 1) / Item 2 (ID 2) / Item 3 (ID 3) /

To achieve this, I put the following merge fields in my template:

<><> (<>) /<>

The result is the following:

Item 1 (ID 1) /
Item 2 (ID 2) /
Item 3 (ID 3) /

The mail merge engine seems to repeat the entire paragraph instead of only the document content between TableStart and TableEnd. If I add text before and after TableStart and TableEnd this text is repeated also:

Before table <><> (<>) /<> after table


Before table Item 1 (ID 1) / after table
Before table Item 2 (ID 2) / after table
Before table Item 3 (ID 3) / after table

Am I missing something when using repeatable regions?

4) Another merge with regions question: I have a data table with the following columns:

ITEM_ID typeof(int)
ITEM_DESCRIPTION typeof(string)
ITEM_PICTURE typeof(Image)

My template looks like this:

<> <> <> <>

The image in the DataTable is not merged into the document. Are data columns of type Image supported or do I have to solve this using the MergeImageField-event?

Thanks in advance for your reply.

Best regards,

Andy Thevelein

Dear Andy,

Thanks for the kind words on our product. I will try to answer your questions in order:

  1. Conditional fields support will be implemented in one of our future versions. I cannot provide exact timeline yet. I think somewhere around the end of the year is a good guess.

    It was not one of our priority features because with Aspose.Words you can pretty much shift the document logic to C# code which is a way better to develop and support data processing applications.

    We understand however that there is a wide user demand for possibilty to build-in the existing templates which rely heavily on conditional field logic and we will try to implement this feature as soon as our schedule permits.
  2. To scale image during insertion use DocumentBuilder.InsertImage Method (String, RelativeHorizontalPosition, Double, RelativeVerticalPosition, Double, Double, Double, WrapType, WrapSide, Boolean, PictureFormat) method overoad. It allows to control image width and height.
  3. Current implementation of ExecuteWithRegions was made to allow growing regions vertically on a row-by-row or line-by-line basis. We have not forseen the need to grow regions inside the same paragraph. I have logged this to our defect base as a feature request (issue #1074).
    We will consider it for implementation in the near future.

    I also think that a workaround is possible due to flexibility of our current mail merge API. If you provide me more details on a task and a template I will try to compose a code snippet solving this problem.
  4. Using fields with 'Image:' prefix is intended to trigger MergeImageField event where the actual insertion of the image is done using DocumentBuilder.InsertImage method. Any amount of custom image data processing can also be done there if necessary.

    There are several MergeImageField implementation examples in our programmer's guide and API reference. Use search on 'MergeImageField' in Aspose.Words help file to find them.

Do not hesitate to ask if you have more questions. I will be more than happy to answer them.

Best regards,

Hi Vladimir,

Thanks for the quick response. Merging images is clear now and regarding growing regions inside the same paragraph I can solve this easily using a different approach.

I understand that supporting conditional fields is not an easy task, because evaluating the (potentially very complex) condition would be up to your component instead of letting MS-Word do the job. I have no existing templates to build in but I thought about using IF-statements to hide certain content when a certain field (or fields) is empty.

An example: template looks like this:

Property 1: <>
Property 2: <>
Property 3: <>

Property 1 and 3 have a value but property 2 is empty. In that case, I don't want to see the label for property 2 and shift property 3 one line up. IF-statements can be used to achieve this:

Property 1: <>
{ IF <> <> "" "Property 2: <>
" "" }Property 3: <>


Property 1: a value
Property 3: a value

Do you know of another approach that could help me?

Another question: is there a list of Word fields available that are updated by Aspose.Words (NUMPAGES, SAVEDATE, ...) ? This way I can check what I can or can not use in my templates. Are there other limitations when using fields?

Beginning from the last question:

Apart from fields that participate in MailMerge Aspose.Words does not update any fields automatically except DOCPROPERTY and DOCVARIABLE fields. Most of the fields get updated immediately when you open the document in MS Word, such as PAGE, NUMPAGES, etc., so it does not matter. Some require explicit update action (pressing F9), for example TOC fields.

IF fields, although not evaluated by Aspose.Words, are preserved as is and can be later used when openning document in MS Word. Don't know if it helps in your task though.

To remove parts of template content from resulting document the best way is bookmarking parts of the document. Contents of bookmark can be removed using Aspose.Words. Bigger parts can also be put in separate sections or even separate documents and the resulting document can be assembled from them.

Hope that answers your questions.

Best regards,

Wow, you guys are really quick :-)

One scenario we have in mind is that the user will be able to choose the output format for the report (DOC or PDF). If the user chooses PDF, the software will generate the DOC file and immediately convert it to PDF (using Aspose.PDF). This way, the document is never opened in Word. Does this mean that fields like NUMPAGES will never get updated and will be wrong in the PDF?

Thanks for the advice on bookmarks, this approach might work if I allow a simple condition syntax in the bookmark name e.g. !FIELD.IsNull. Then I can parse the bookmark name and decide wether to remove the bookmark contents or not.

Best regards,

Andy Thevelein

When you do DOC2PDF using Aspose.Words + Aspose.Pdf conversion, the situation is better.

Aspose.Words converts NUMPAGES, PAGE and PAGEREF fields into commands that Aspose.Pdf understands, so the resulting PDF will have proper page numbers and references to page numbers.

The only issue is that if you have a TOC in your Word document, and you added some text that should appear in the TOC, it will not, because the TOC field is not updated.

Edited the above post.

Regarding mail merge region within one paragraph.

It has been logged as a possible feature for the future, but sorry we are not going to work on it right now.

If you want to grow text inside a paragraph, you should code your own loop to build a line of text and then insert into the document at a merge field or at a bookmark.