add code to handle image merge

[TNGPS]

Description

To handle image merges prefix your field by IMAGE: and add the binary image (use .png) as a value.

In stead of using normal mailmerge fields in the template docx, you should add a placeholder image and add the field name as the image ALT TEXT.

In this way you can get a correct preview in you template, and add image layout markup to the placeholder image, that will be inherited by the inserted images.

you can call it like this:

f1 = open('test_img1.png')
img_data_1 = fp.read()
f1.close()

f2 = open('test_img2.png')
img_data_2 = fp.read()
f2.close()

document.merge_templates([
    {'field1': "Foo", 'field2: "Copy #1", 'IMAGE:merge_img1': img_data_1 },
    {'field1': "Bar", 'field2: "Copy #2", 'IMAGE:merge_img1': img_data_2 },
], separator='page_break')

Motivation and Context

This resolved #12 and it is listed as TODO in the readme.

How Has This Been Tested?

It works in my application (currenty running on MacOS)

If there are plans to accept this PR I wil spend some more time adding unit tests.

Types of changes

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• [x] My code follows the code style of this project.
• [x] My change requires a change to the documentation.
• [ ] I have updated the documentation accordingly.
• [ ] I have added tests to cover my changes.
• [ ] All new and existing tests passed.

[Bouke]

Nice idea and great to see that it helps with your use case! However as the implementation isn't using merge fields, I don't think I can merge this. I don't want this library to turn into a general purpose Word library, but keep it focused around merge fields.

I don't know if merging images with merge fields is even be possible in the Word format. So if that's not possible, I should probably just remove that goal from the TODO.

[TNGPS]

This PR can easily adapted to the use of merge fields. However as far as my (limited) knowledge of merge fields goes, there are designed for inserting text only. I decided for the use af a sample image as "merge field" here so the designer of the word doc has more freedom about the image properties (like the size, the text flow around the image etc.)

If we are to use merge field, we would replace it by complete embed xml code for the image using some reasonable default image settings.

It may be good to know what other users in the community would like to see here.

[sliverc]

I would love to see such a feature a well. I agree with @Bouke though that this library should focus on mailmerge field features Microsoft Word also supports. This is a unique advantage of this library over e.g. docx-template where everything is possible but is not safe for user as syntax can be messed up.

Microsoft Word seems to have mail merge picture support though. Best post I have found how this works is at https://onmerge.com/articleIncludePicture.html . Maybe an implementation would best follow this.

[deanmadoo]

I definitely would like to see this feature accepted in the library. Replacing images would be very useful.

[lukaszkacprzynski]

Could you please share some complete example of code you are using? Im getting syntax error and can't make it work: there is no function name 'document.merge_teplates' and with 'document.merge' sytax is not like:

document.merge_templates([
    {'field1': "Foo", 'field2: "Copy #1", 'IMAGE:merge_img1': img_data_1 },
    {'field1': "Bar", 'field2: "Copy #2", 'IMAGE:merge_img1': img_data_2 },
], separator='page_break')

Thank you, Lukasz

[vdsbenoit]

That's a great feature! However, it does not work on my side. It keeps hanging on document.merge_templates() forever. I'm running python 3.7.2 on Win10.