Supporting \f and \b instructions field codes.

[sjoerdjob]

Expected Behavior

See also https://support.office.com/en-us/article/Field-codes-MergeField-field-7a6d24a1-68a6-4b05-8359-1dc087daf4e6?ui=en-US&rs=en-US&ad=US

When the merge instruction contains a \b or \f flag, the contents after that flag should only be rendered when the value of the merge instruction is present and non-empty. In that case, the content of \b should be rendered before the value, and the content of \f should be rendered after the value.

Example:

MERGEFIELD  number \b ( \f )  \* MERGEFORMAT

should render as

(12)

when number is 12, and as

when number is the empty string.

Another example:

MERGEFIELD email \b "Email: " \f "
" \* MERGEFORMAT MERGEFIELD fax \b "Fax: " \* MERGEFIELD

Should be able to render

Email: bla@bla.com
Fax: +31 123 456789

or

Fax: +31 123 456789

But not

Email: 
Fax: +31 123 456789

Current Behavior

Currently, the values after \b and \f are ignored.

If the content of either contains a paragraph break, mergefields after this merge-field do not get rendered, and do not get returned in get_merge_fields(). This has to do with the instrText being broken in several parts [MERGEFIELD number \f "][" \* MERGEFORMAT], with a paragraph-close/open between the first and second instrText. In particular, the "begin" end "end" portion occurs in different paragraphs, and the indices in https://github.com/Bouke/docx-mailmerge/blob/master/mailmerge.py#L58 are "broken":

The begin/end for the node containing the start (in the proprietary document I'm currently working with) are:

[1]/[]

While in the case with the "closing" node (which also contains a second mergefield), the values are

[7]/[6, 11]

Possible Solution

For the simple case where neither \b or \f contain a line-break or formatting commands, the contents are mostly entered as plain-text, directly into the instrText fields. It should be possible to deal with this in a semi-elegant way.

For the more complex case where the command contains formatting, the instrText is spread over several nodes, each containing its own formatting instructions. However, the begin/end pair still share the same parent, and it should not be impossible to make it work, even though it would be hacky.

For the most complex case (which I am currently running into), \f contains a line-break. I think the only elegant way to deal with this would be to rewrite the merging to be sax-based, and storing the "events" from the \f " to " \* MERGEFORMAT, and only emitting them on merging when the field is non-empty.

Context

We use docx-mailmerge to provide templating functionality for documents that our customers send to their customers. We want them to be able to provide mergefields containing instructions (including newlines!) that will only be rendered when the field contains text.

I would be willing to add support for these cases and send them back upstream. However, considering that a rewrite to a sax-based algorithm would be quite involved, I would first like to know if there's a chance of it being merged before starting to work on it.

Your Environment

• Python version: 2.7
• docx-mailmerge version: 0.4.0 (and master).

[Bouke]

Hi @sjoerdjob, that looks like a nice feature. I didn't know about this, and must admit I haven't used mailmerge in quite a while. If there's a nice/clean way to support such a feature, I'd welcome it. Whether it would continue to work with the current parser or needs a sax-based parser, I don't know. I would suggest keeping as much with the current solution if possible, as that involves less changes overall and that improves the possibility of it getting merged.