Support for nested fields and IF fields


From Julian:

Following on from the talk about the If conditionals and the nested Ifs, here is an explanation of the sort of thing I need:-

1. Processing of If statements where I can check the value of one field and then enter the value of another.
2. Nested Ifs
3. Conditional If statements where I can check the value of fields and even do some mathematical calculations like ‘if x is > y’ or ‘if b between d and e’ handling numbers as well as dates.

I have attached a sample template as an example - it is only a made up sample, but should illustrate the sort of things.

I need to roll out the beta of the application by the end of May so really need to know if you will be able to add this by then.




Hi Julian,

Thank you for your interest in Aspose.Word.

As we agreed, I will look into feasibility and complexity of implementing support for nested and calculated fields in Aspose.Word. I need 2-3 days before I reply.

In the meantime I still suggest you consider taking conditional logic out of the document and placing it into the code as it helps to achieve a clean separation between report logic and report presentation. This is applicable, of course, only if your users don’t need the ability to modify logic in the report themselves.

The ways to implement conditional report logic in the code are as follows:

1. Respond to MailMerge.MergeField event. In the event handler you can perform any logic you want and return result that is to be inserted into the document.

2. Build your DataTable either from a query and/or programmatically. You can have all or some of your calculations performed in the SQL query and load the DataTable from it. You can also create calculated columns in the DataTable programmatically.

3. To include or remove bigger parts of the document conditionally, split the document into sections using section breaks (you can have section breaks that do not start a new page). At runtime use Document.Sections collection to remove unneeded sections or insert required sections from other documents.


Hi Roman,

Thanks for the response.

Whilst the idea of taking the conditional logic out of the document is the logical way to go, it creates too many maintenance headaches.

The main merge template is over 200 pages long when viewed with all the MS Word mail merge codes being visible. Depending on the data entered, the average document that is produced can range from 12pages through to 50 pages.

The conditional if statements we need can end up adding just a single word to the document or several pages of info that themselves contain further merge codes and nested conditional if statements.

This main template will be tweaked and changed every couple of months to reflect changes in the law and we need to be able to allow the users to download updated templates at will without having to download a completely recompiled program.

If you want I could send you a copy of the template so you can get an idea of what we are trying to achieve.


Julian Voelcker


Hi Julian,

This is not my final answer, but I just want to let you know that nested fields and expression evalution are complex things. It is very likely we cannot have them by the end of May.

What do you think your options are if Aspose.Word does not support nested and IF fields? As far as I know none of the competing products can help you to achieve this in the way you want.

I understand putting logic into compiled code prevents users from tweaking it for every change in the law, but maybe you can reach some compromise by identifying things that are most likely to change and working them around.

Users still can edit the templates and maybe not every change requires change of logic in the fields. If you let them download the templates, maybe you can let them download the dll with the business logic as well.


Hi Roman,

Many thanks for the response.

The problem we have is that we cannot predict the changes in the law, sometimes it might be a minor tweak due to changes in tax regulations and other times it can be a major change due to changes in the trust laws.

One of our original trains of thought was actually to use XSLT and XML to do a transform as opposed to doing a mail merge, which would give us the flexibility that we need, but it would be harder for the people managing the templates to update than if we were using word.

The main problem is that the logic is so tightly tied into the content of the document that it is almost impossible to split them apart without either some logic remaining in the template or some of the template content remaining in the logic.

I think that I need to go back to considering the XSLT/XML route.

Thanks for all your help.


I see you where you heading. You still can try to retain MS Word as your report designer.

1. Split the document into sections where each section represents a piece that you want to conditionally insert or remove from the document.

2. You can store these sections in multiple documents or in one big document. In either case they form a set of building blocks from which you can build your final document.

3. Use only simple mail merge fields that insert values in those sections.

4. Express rules that govern what information to insert and what sections to select using your own simple XML format.

5. Write code that inteprets the rules from the XML file and uses Aspose.Word to combine sections and insert data into fields as specified by the rules.

This way you allow users to design their reports in Word and yet put the logic into an XML file.



I see what you are saying, but still suspect that the logic is still too complicated to be split up.

For example, if the user is married, we need to add a section of text and merge fields, and then within that section we need to determine if they have children and add a listing of the children and then for each one include another sectionwith further conditional merge codes.

Overall there are about 8000 if statements with many of them being nested. They range from simple statements checking the value of a data field and then adding a section of text to checking several data valuse and then adding one to the document.

OK, I have managed to trim them down a bit by shifting the logic to the data retrieval side of things, but I don’t think I can do it any more.


I agree, for 8000 IF statements it is probably not worth the effort to separate logic from the document.

Can you send me a bigger sample that shows how you include portions of the document using the IF fields.


Thanks, I’ve got the document.

Sorry if I’m giving too much advice here, but I think you’ve got a very difficult task.

Those IFs are almost impossible to comprehend. If it was my project, I would rip them away into some sort of “expert system”, secure with unit tests and never let the end users touch them yet alone edit freely in the document.

They can be easily broken. Who is going to make sure that after someone editing some of the 8000 rules the document still correctly does what it supposed to do.

You’ve got no version control, no testing environment as long as these rules are in the document.

In the meantime we are still considering how to implement nested and evaluated fields in Aspose.Word.


Hi Roman,

I hear what you are saying, however the end users won’t actually be able to access the merge codes.

We have a team of legal eagles who will be making sure the templates are kept up to date. They are familar with MS Word mail merge codes and the relevant systems will be in place to test everything before releasing a new version.

Updates would then be distributed to users using the .Net update application block provided by MS.

I hope that you can do something with the conditional statements and then nested ones.


Hi Julian,

We are now working to support nested fields. Although this feature will be available within a week, it will not include support for IF fields that require expression evaluation, so I’m afraid we cannot have a full solution for you by the end of May.

Please let us know how you get on with your project and whether you are still interested in support for IF fields. In this case we will schedule it for delivery sometime in June.


Does this also mean that you can do mailmerge with several records on the first level.

for example:
multiple orders and each order has multiple orderlines.

Support for nested fields will be available by the end of may? (it’s almost the end of may :slight_smile:





Even when nested fields are supported they will never be used for this purpose: to represent parent-child relationship between merge data. Nested fields are for other applications, such as TOC (table of contents) field. It has hyperlinks to something like pageof(bookmark) structure with two levels of nesting.

To represent parent-child relationships in your data, repeatable merge regions should be used. The repeatable merge regions is Aspose.Word’s “extension” to the flat world of MS Word mail merge.

The merge regions cannot be nested yet, but it will be possible in some future release. This does not mean you cannot do parent-child data however.

The order example with multiple order lines is resolved without using nested fields or nested regions. It uses three non nested regions: one for the order header, one for order details and one for totals.

Please see the Invoice demo for more details.

There are some scenarios that require what we call “true parent-child model” for the document and we cannot do these using mail merge yet. An example would be a sales report grouped by regions. But you still can create any document programmatically using the DocumentBuilder builder without relying on MailMerge.


Hi Roman,

Thanks for the response.

Unfortunately it doesn’t look like your development will fit in with our current schedule.

However, all plans change, so do please keep us informed with your progress.


Hi Roman,

How are you progressing with handling nested fields?


Hi Julian,

Aspose.Word supports nested fields now. But we don’t support expression evaluation in IF fields. At this stage I’m not sure we are going to support them soon. It seems this is not a typical approach to use lots of IF fields in documents.