I did read the Mail Merge with Regions explained when I first started using the product. I am trying to stay in the context of what is supported so I don’t have future migration problems. I definitely understand, based on the threads I’ve read, the dot notation should be avoided.
With that being said, are there separate considerations for a data source that is XML? XML can be defined many ways and typically has many more children than a typical data source such as a database. I still go back to the reference to Mustache Syntax for Mail Merge (https://blog.aspose.com/2012/04/03/support-for-new-mail-merge-syntax-in-.net-and-java-word-processing-api/) which is the only reference I could find regarding the syntax. Looking at the example, this indicates the dot notation is supported with an XML data source. The example there shows Street is a child element of Address but appears to also be acceptable as an attribute for the object.attribute syntax (Nelson Street…). For that XML, the example shows a defined field for “MERGEFIELD Address.Street”. This is how I am using the syntax now and would like to continue and be a supported configuration. The problem is that that usage appears to be contradictory to what you are telling me “Please do not use dot in mail merge field name.” I would guess that if street was an actual element attribute (), which is not how XML should be used, the object.attribute should work also. At least I would hope so.
If I go by the rules you are stating in your last post, this should be defined as a merge region of TableStart:Address and a merge field of Street. I could buy off on that except for the fact that the TableStart and TableEnd markers must be inside of the same section. I have some use cases in which the definition would cross a section boundary. The use case will not work using the Table markers due to crossing section boundaries, but will work using the dot notation. What options are available for a use case such as this if we can’t use the dot notation and have to cross sections? None of the documentation indicates how to solve this problem. In the case of a database as a source, I see where there could be problems. It would be nice to have the ability to cross section boundaries either way.
Hi James,
Thanks for your inquiry. Please note that the issue discussed in this thread is ‘IMailMergeDataSource.GetChildDataSource is called when mail merge filed contains dot (.)’.
If you are using IMailMergeDataSource.GetChildDataSource then do not use dot (.) in mail merge fields. Implement IMailMergeDataSource interface to allow mail merge from a custom data source, such as a list of objects. Master-detail data is also supported.
However, you can use dot (.) in mail merge fields either you are using “Mustache” Template Syntax or not. Please check the following mail merge templates and XML example.
«TableStart:Order»
«Number»
«Address.Street»
«Address.Suburb»
«Address.City»
«TableEnd:Order»
----------------------------------------------------------------------
{{#foreach Order}}
{{Number}}
{{Address.Suburb}} {{ Address.City}} {{Address.Street}}
{{/foreach Order}}
----------------------------------------------------------------------
XML :
<Order>
<Number>23</Number>
<Address>
<Street>Nelson Street</Street>
<Suburb>Howick</Suburb>
<City>Auckland</City>
</Address>
</Order>
The above template works with XML (data source). Please use the following code example to check these templates. Please use MailMerge.UseNonMergeFields value as true, if you are using “Mustache” Template Syntax. I have attached the input and XML files with this post for your kind reference.
Hope this answers your query. Please let us know if you have any more queries.
DataSet ds = new DataSet();
ds.ReadXml(MyDir + "Orders.xml");
// Open a template document.
Document doc = new Document(MyDir + "Invoice Template.docx");
doc.MailMerge.UseNonMergeFields = true;
// doc.MailMerge.UseNonMergeFields = false;
// Execute mail merge to fill the template with data from XML using DataSet.
doc.MailMerge.ExecuteWithRegions(ds);
// Save the output document.
doc.Save(MyDir + "Out.docx");
I guess I have been having difficulty undertanding the difference between the two scenarios that you are trying to explain. It seems to me that the same terminology is being used on both scenarios. Based on how you describe both scenarios, I believe I am matching both scenarios. For the second example and the attachements you have given, I am using XML similar to the example. I am also defining the template just as the attachment templates indicate with dot notation. Sometimes I’ve defined my templates like the first template and others have been defined like the second template or a combination of both. However, going back to the first scenario (for not using dot), you state “If you are using IMailMergeDataSource.GetChildDataSource then do not use dot (.) in mail merge fields. Implement IMailMergeDataSource interface to allow mail merge from a custom data source, such as a list of objects. Master-detail data is also supported.” It turns out I am implementing an IMailMergeDataSource interface and implementing the GetChildDataSource method. This matches what you are indicating I should not do. For your statement, in what context are we talking about not using dot in the mail merge fields? Inside a code block? Inside the Word document? Or some other context?
Am I to understand that the differentiation you are trying to identify is using the dot notation in the context of an actual code block of the GetChildDataSource method (e.g. Using dot notation as a test for an if statement such as if(Address.Street == “abc”))? If this is the case, it would be helpful to indicate in documentation “then do not use dot notation in the code to reference a mail merge field.” The second scenario is using dot notation in a mail merge field, but within the context of a Word document. If your explanation is to indicate the fact that I created any implementation of the GetChildDataSource method that I should not be using dot notation, then I am not using the IMailMergeDataSource correctly? However, if that’s a problem, the examples in the programmers guide are incorrect.
I definitely want to be clear on what is supported and what is not supported. If this is as significant of an issue as it appears to be, more documentation would be helpful. Maybe your documentation can show an example of what’s not supported. I have yet to see a clear example of what shouldn’t be done in the documentation.
~~~~
As I wrote all of this, I looked back on the thread once again. I believe I have figured out the scenario you are trying to prevent may be in the getValue method, not the getChildDataSource. Is that where the dot notation should not be used? Is there anywhere else? It seems that quite a bit more information should be given in the programmers guide to help people be compliant with the Aspose usage and what should or shouldn’t be done. I left the text above in case I have not interpreted correctly.v
Hi James,
Thanks for your inquiry.
*jrsaspose:For your statement, in what context are we talking about not using dot in the mail merge fields? Inside a code block? Inside the Word document? Or some other context?*
As I shared earlier, please do not use dot (.) in mail merge field in your template document (e.g Word document) if you are using custom data source, such as a list of objects. If you are implementing IMailMergeDataSource interface, dot (.) is not recommended in mail merge fields and data source object as well.
*jrsaspose:Am I to understand that the differentiation you are trying to identify is using the dot notation in the context of an actual code block of the GetChildDataSource method (e.g. Using dot notation as a test for an if statement such as if(Address.Street == “abc”))? If this is the case, it would be helpful to indicate in documentation “then do not use dot notation in the code to reference a mail merge field.” The second scenario is using dot notation in a mail merge field, but within the context of a Word document. If your explanation is to indicate the fact that I created any implementation of the GetChildDataSource method that I should not be using dot notation, then I am not using the IMailMergeDataSource correctly? However, if that’s a problem, the examples in the programmers guide are incorrect.*
Please check the following code example for the issue using dot (.) in mail merge fields.
If your template has mail merge filed e.g Item.Name, Aspose.Words can not determine at the time of field “Item.Name” mailmerge - is this field name “Item.Name” or is this related object “Item” with property “Name”.
I have attached the input template document with this post. I suggest you please check the code example shared at following documentation link.
https://reference.aspose.com/words/net/aspose.words.mailmerging/imailmergedatasource/getchilddatasource/
class TestDataSource : IMailMergeDataSource
{
private int _index;
public bool MoveNext()
{
return _index++ < 5;
}
public bool GetValue(string fieldName, out object fieldValue)
{
switch (fieldName)
{
case "SimpleName":
fieldValue = "Simple item name";
return true;
case "Item.Name":
fieldValue = "Dotted item name";
return true;
default:
throw new Exception("Unexpected fieldName " + fieldName);
}
}
public IMailMergeDataSource GetChildDataSource(string tableName)
{
switch (tableName)
{
case "Item":
throw new Exception("This is not a collection. It is part of my field name.");
default:
throw new Exception("Unexpected tableName " + tableName);
}
}
public string TableName
{
get { return "Collection"; }
}
}
var document = new Document(MyDir + "TestMergeTemplate.docx");
document.MailMerge.ExecuteWithRegions(new TestDataSource());
*jrsaspose:I definitely want to be clear on what is supported and what is not supported. If this is as significant of an issue as it appears to be, more documentation would be helpful. Maybe your documentation can show an example of what’s not supported. I have yet to see a clear example of what shouldn’t be done in the documentation.*
As I shared earlier, Aspose.Words fully support the mail merge features. The issue using dot (.) in mail merge fields is described in above code example. The usage of simple mail merge and mail merge with regions are well explained in documentation. Please read following documentation articles.
https://docs.aspose.com/words/net/mail-merge-and-reporting/
https://docs.aspose.com/words/net/types-of-mail-merge-operations/
*jrsaspose:As I wrote all of this, I looked back on the thread once again. I believe I have figured out the scenario you are trying to prevent may be in the getValue method, not the getChildDataSource. Is that where the dot notation should not be used? Is there anywhere else? It seems that quite a bit more information should be given in the programmers guide to help people be compliant with the Aspose usage and what should or shouldn’t be done. I left the text above in case I have not interpreted correctly.*
I have explained this issue in above code example. We will update our documentation about this issue detail that the dot should not be used in the mail merge field names.
Please check the code example at following
forum link about using dot (.) in mail merge field name. The code
example at following forum link use DataSet object in
MailMerge.ExecuteWithRegions method.
https://forum.aspose.com/t/49899
You can merge attributes of a field using the syntax Object.Attribute e.g Address.Street. However, implementation of IMailMergeDataSource does not allow dot (.) in mail merge field name (in template document and data source).
Hope this clear the detail of issue ‘IMailMergeDataSource.GetChildDataSource is called when mail merge filed contains dot (.)’. Please let us know if you have any more queries, we will be happy to help you.
>>You can merge attributes of a field using the syntax Object.Attribute
>>e.g Address.Street. However, implementation of IMailMergeDataSource
>>does not allow dot (.) in mail merge field name (in template document
>>and data source).
>>You can merge attributes of a field using the syntax Object.Attribute
>>e.g Address.Street. However, implementation of IMailMergeDataSource
>>does not allow dot (.) in mail merge field name (in template document
>>and data source).
Ok, based on this information, my original concern on usage was correct. What you are telling me is that how I am using this is in fact incorrect by using dot notation in a document template AND using a “custom” data source that is an implementation of the IMailMergeDataSource even though it follows the examples in Aspose documentation.
In reference to the only document I could find on mustache syntax usage (which is not in the programmers guide), the example was defined using XML which shows that dot notation is supported in the document template with an XML data source. The document Mail Merge from XML using IMailMergeDataSource indicates that an implementor should use the IMailMergeDataSource to use XML as a datasource. These two documents indicate that I should be able to use dot notation in the document template and use an XML data source by implementing IMailMergeDataSource by just putting both concepts together as most software engineers do (using the simple isolated cases from documentation together to create a more complex implementation). However, you are telling me that I shouldn’t use it. The documentation and what you are telling me is contradictory.
Respectfully, I wouldn’t consider mail merge well documented or fully supported features when the two basic pages you reference (Simple mail Merge and Mail Merge Regions) and a release note page I found all include limited and isolated simple cases. I read every page of the programmers guide that dealt with mail merge and, while a helpful start, found that I had to look in the forum threads for answers to additional questions and put together a more complex solution. With the document describing mustache syntax in a release note and not the programmers guide indicates that documentation could be more complete than it is. But that’s my opinion. The additional documentation that will be updated should indicate the exact case that is not supported.
Simple, isolated cases are required to help deliver a solid understanding on usage, but the real world complex implementations that many of us are creating require more than just these simple isolated cases when what is supported is so similar to what is not supported. In this case, there appears to be a very fine line as to what is supported with dot notation and what is not. I realize that XML is complex and can be more complex from a tool perspective since you have no knowledge of the schema. I’m dealing with the same issue on my end with software I am building.
If the implementation I’m using is not supported as you suggest, I’m not quite sure where to go from here. My implentation mimics the Mail Merge from XML using IMailMergeDataSource. I have a getValue method and getChildDataSource method that has very similar code so I am not using dot notation in the code, but I am using dot notation in the document template with the IMailMergeDataSource implementation. I’m hoping that this implementation would be considered a supported configuration considering I’m not referencing the dot notation in the code or even trying to reference a collection as you describe in the code example. If you can tell me that what I am trying to accomplish is “a supported implementation” then I am done here.
Hi James,
Thanks for your inquiry. I am in communication with the development team about 1) usage of dot (.) in mail merge field name and 2) Object.Attribute. I will update you as soon as I have information on this.
Thanks for your patience.
Thank you for the update. Thank you for talking with development as well.
Hi James,
Thanks for your patience. I have received response from our development team about using dot (.) in mail merge field names.
Please check my following post about using dot (.) in mail merge field name.
https://forum.aspose.com/t/49899
You can use dot (.) in mail merge field name. However, there is only one following exception.
IMailMergeDataSource.GetChildDataSource is called when mail merge filed contains dot (.)
For example,
- a master table named “master”
- its field named “details”
- a related detail table named “details”
- and a reference to “master.details” in a template.
This makes the topmost “detail” table’s item to be used instead of “details” field which may be undesired. So, if such conflicts exist in your data sources then you should avoid using of a dot in their field names (or alternatively avoid such conflicts). This refers to data sources and templates of all types.
Hope this clear the detail of using dot (.) in mail merge field name.
Moreover, below are the rules that the implementation of GetChildDataSource must follow.
- If the table that is represented by this data source object has a related child (detail) table with the specified name, then your implementation needs to return a new IMailMergeDataSource object that will provide access to the child records of the current record. An example of this is Orders / OrderDetails relationship. Let’s assume that the current IMailMergeDataSource object represents the Orders table and it has a current order record. Next, Aspose.Words encounters “MERGEFIELD TableStart:OrderDetails” in the document and invokes GetChildDataSource. You need to create and return a IMailMergeDataSource object that will allow Aspose.Words to access the OrderDetails record for the current order.
- If this data source object does not have a relation to the table with the specified name, then you need to return a IMailMergeDataSource object that will provide access to all records of the specified table.
- If a table with the specified name does not exist, your implementation should return null.
Thank you for clarifying with development. I believe I have the understanding now. The key to using the mail merge field with dot notation is that the parent (master) CANNOT have a field that has the same name as the child (details) data source name. This is where a conflict can occur because there is no way to differentiate between the parent.field and the child data source. So, as long as I know my data and do not attempt to name a field the same as a table name, I can use the dot notation without any problems and this IS a supported configuration of the Aspose product.
Please add this information to your programmers guide so that future implementers of Aspose can benefit from this information. Because this configuration is so close to what is not supported, it should be written so that an example such as this can be explained. Too many of the threads refer strongly to not using dot notation at all when implementing IMailMergeDataSource.GetChildDataSource. In addition, an example of what is supported with respect to the key point of parent.field and child data source names (as explained above) not being named the same.
Thanks again.
As I think about this further, my next question is how is the XML document processed? Is the full DOM document processed for each merge field defined in the template? If that’s the case, what gets processed first? The getValue or the getChildDataSource? From what I can tell, an XML document is processed at the child level of the root element unless wrapped with a TableStart. So depending on where these methods get called in the MailMerge would determine whether or not an XML defined data source would be a problem with the dot notation. Can you give some understanding regarding the order and conditions of calling those methods during a MailMerge?
Honestly, I plan to avoid that scenario altogether. However, using the examples (release note on mustache syntax) defined for dot notation from an XML data source (not another data source). Depending on how the MailMerge is processed, if I define an XML document where a different City element is at the same level as Address, would Address.City be equal to Auckland? Or would the MailMerge short circuit and give me Kumeu? Or some other variation? See below. I can see how there could be a conflict with a field that had the same name as a child element if the full DOM document is processed for each merge field or due to the processing order of MailMerge.executeWithRegions. This processing would be nice to have documented to help those of us using the libraries to know how to define the data.
<Order>
<Number>23</Number>
<Address>
<Street>Nelson Street</Street>
<Suburb>Howick</Suburb>
<City>Auckland</City>
</Address>
<City>Kumeu</City>
</Order>
{{#foreach Order}}
{{Number}}
{{Address.Suburb}} {{ Address.City}} {{Address.Street}}
{{City}}
{{/foreach Order}}
I say this from the perspective that the City element could have just as easily been a field with the name “id” under the Order element and a child.id (child being Address or some other element name) element and both would have different values.
Hi James,
Thanks for your inquiry.
jrsaspose:
Please add this information to your programmers guide so that future implementers…
We have logged a task as WORDSNET-9069 to add this detail in our documentation. You will be notified via this forum thread once this detail is available in documentation.
jrsaspose:
As I think about this further, my next question is how is the XML document processed? Is the full DOM document processed for each merge field defined in the template? If that’s the case, what gets processed first? The getValue or the getChildDataSource?
Aspose.Words calls IMailMergeDataSource.getValue method to get a value for every data field.
The Aspose.Words mail merge engine invokes IMailMergeDataSource.GetChildDataSource method when it encounters a beginning of a nested mail merge region.
*jrsaspose:
From what I can tell, an XML document is processed at the child level of the root element unless wrapped with a TableStart. So depending on where these methods get called in the MailMerge would determine whether or not an XML defined data source would be a problem with the dot notation. Can you give some understanding regarding the order and conditions of calling those methods during a MailMerge?Honestly, I plan to avoid that scenario altogether. However, using the examples (release note on mustache syntax) defined for dot notation from an XML data source (not another data source). Depending on how the MailMerge is processed, if I define an XML document where a different City element is at the same level as Address, would Address.City be equal to Auckland? Or would the MailMerge short circuit and give me Kumeu? Or some other variation? See below. I can see how there could be a conflict with a field that had the same name as a child element if the full DOM document is processed for each merge field or due to the processing order of MailMerge.executeWithRegions. This processing would be nice to have documented to help those of us using the libraries to know how to define the data.
I say this from the perspective that the City element could have just as easily been a field with the name “id” under the Order element and a child.id (child being Address or some other element name) element and both would have different values.*
Firstly, I like to share with you that the usage of dot (.) in mail merge field name has already explained in following forum link.
https://forum.aspose.com/t/49899
In your case, I suggest you please use ResultSet, com.aspose.words.DataSet or com.aspose.words.DataTable as data source. Please read following documentation links for your kind reference.
https://docs.aspose.com/words/java/mail-merge-and-reporting/
https://docs.aspose.com/words/java/types-of-mail-merge-operations/
In case, you are using XML as data source, please note that IMailMergeDataSource corresponds to one “table”. If you want data from more than one table in your document (e.g Customer and CustomerDetail) you need to have two IMailMergeDataSource objects and need to execute mail merge twice. Please check this forum link for your kind reference.
https://forum.aspose.com/t/122437
Note that Java (and Aspose.Words for Java too) does not support loading of DataSets from XML. It is yet another .Net-specific feature. You may use com.aspose.words.DataSet or com.aspose.words.DataTable as data source to achive your requirements. E.g for Address.City and City mail merge fields, you will get the correct results using com.aspose.words.DataSet.
Hope this answers your query. Please let us know if you have any more queries.
You mention logging a task to WORDSNET for added documentation. That’s a great idea. This should also be done on the Java side as well.
Your suggestion of using a ResultSet with a DataSet and DataTable is NOT an option. XML is being delivered to me from an external source. I have read the two mail merge references. I do understand that an IMailMergeDataSource represents one table.
You say that Aspose.Words for Java does not support loading of DataSets from XML. It took me a while to understand what you were saying. I confused it with the fact that I am loading data from XML, however with IMailMergeDataSource. It might have been more clear to have referenced loading a DataSet directly from XML by a call to DataSet.readXml (which, as you say, does not exist for Java). Originally, I had looked for a way to load XML directly, but using the IMailMergeDataSource is actually better for me. While most of what I am doing is similar to the XML example implementation, I do have some additional things I’ve done in that code which I would not be able to do within a readXml method anyway.
So what your saying regarding the getValue method, the XML document is potentially read completely every time a merge field is encountered in a template. This information helps me understand more of why Aspose has problems differentiating between fields. The MailMerge is not processing the XML document, it’s processing the template and searching the XML document for elements matching the field name at only the top level of the XML document below the root element. When in the context of a merge region, that element is found first in the XML and the getChildDataSource method is called to create a new IMailMergeDataSource object, then the child elements are searched within that XML element for which each value is called with getValue.
Some of this information regarding the process should be documented in all of your documentation. Understanding the mechanics of how your product works and where there are pitfalls would help those of us implementing. The simplistic examples are helpful, but do not help us understand where things can go wrong. As a result there are more questions in the forum that might have been answered if there was more documentation about the process. Personally, I may not have asked the last questions about an id field had I known how Aspose was processing.
At this point, given that I must use XML and without knowing more of how the product processes a mail merge, when it comes to dot notation, I will try to avoid naming XML elements the same in different parts of the document in favor of the standard merge regions. If I have an XML document that does have the same name, I will avoid dot notation. I believe this scenario will allow me to continue using the IMailMergeDataSource the way I have been. That being said, I would hope this usage will continue to be supported.
Hi James,
Thanks for your inquiry.
We will update the documentation for both Aspose.Words for Java and .NET.
Following two issues are discussed in this forum thread.
1) Usage of dot (.) in mail merge field name
The answer of this issue is well explained in following forum thread.
https://forum.aspose.com/t/49899
What is the possiblity of using dot (.) in mail merge fields if you implement IMailMergeDataSource?
I have logged this query in our issue tracking system as WORDSNET-9669. I will update you via this forum thread once there is any information is available about this query. Thanks for your patience.
2) Mail Merge from XML using IMailMergeDataSource
You can load the shared XML in DataSet by using DataSet.readXML and use MailMerge.ExecuteWithRegions Method (DataSet) to perform mail merge process. However, there is no implementation, same as DataSet.readXml in Java and Aspose.Words for Java.
However, I have logged a feature request as WORDSJAVA-845 in our issue tracking system. Our development team will look into the possibility of implementation of this feature. Once we have any information about this feature, we will update you via this thread.
<Order>
<Number>23</Number>
<Address>
<Street>Nelson Street</Street>
<Suburb>Howick</Suburb>
<City>Auckland</City>
</Address>
<City>Kumeu</City>
</Order>
{{#foreach Order}}
{{Number}}
{{Address.Suburb}} {{ Address.City}} {{Address.Street}}
{{City}}
{{/foreach Order}}
I appreciate you sending on these items to your issue tracking. I’m hoping that these items will continue to work as they do today. Or more importantly, not stop working due to an update.
My situation requires an XML source and I would like to continue using the callback implementation of the IMailMergeDataSource to have some additional control over the data coming in. Knowing the MailMerge processes the template and then searches the DOM document, I wonder if the MailMerge could have additional execute methods that process the DOM and search the template for the associated fields. Additional methods like this could reduce the problem of the Aspose code not being able to determine the correct object.attribute item the way you expect. Not knowing the internals, I’m not sure if something like this can be accomplished or whether it’s even worth it.
Considering I’m not sure how long things take to get through your issue tracking, when you reply here, I would appreciate it if you sent an email to me with the link indicating the thread has been updated. I will try to check every once in a while but I know that as time goes on, I will check it less and less.
Hi James,
Thanks for your inquiry. Currently, your issues are pending for analysis and are in the queue. We will update you via this forum thread once there is any update available on your issues.
Thank you for your patience and understanding.
Hi James,
*tahir.manzoor:
- Mail Merge from XML using IMailMergeDataSource
You can load the shared XML in DataSet by using DataSet.readXML and use MailMerge.ExecuteWithRegions Method (DataSet) to perform mail merge process. However, there is no implementation, same as DataSet.readXml in Java and Aspose.Words for Java.However, I have logged a feature request as WORDSJAVA-845 in our issue tracking system. Our development team will look into the possibility of implementation of this feature. Once we have any information about this feature, we will update you via this thread.
23
Nelson Street
Howick
Auckland
Kumeu{{#foreach Order}}
{{Number}}
{{Address.Suburb}} {{ Address.City}} {{Address.Street}}{{City}}
{{/foreach Order}}*
Regarding WORDSJAVA-845, please use the attached code example of XmlMailMergeDataSet. In your case, this will solve your issue. I have attached the input/output documents with this post for your kind reference. Please modify the XML as shown below (see the bold tag).
<Order>
<Number>23</Number>
<Address>
<Street>Nelson Street</Street>
<Suburb>Howick</Suburb>
<City>Auckland</City>
</Address>
<City>Kumeu</City>
</Order>
// Use DocumentBuilder from the javax.xml.parsers package and Document class from the org.w3c.dom package to read
// the XML data file and store it in memory.
DocumentBuilder db = DocumentBuilderFactory.newInstance().newDocumentBuilder();
// Parse the XML data.
org.w3c.dom.Document xmlData = db.parse(MyDir + "Orders.xml");
// Open a template document.
Document doc = new Document(MyDir + "Invoice+Template.doc");
// Note that this class also works with a single repeatable region (and any nested regions).
// To merge multiple regions at the same time from a single XML data source, use the XmlMailMergeDataSet class.
// e.g doc.getMailMerge().executeWithRegions(new XmlMailMergeDataSet(xmlData));
doc.getMailMerge().executeWithRegions(new XmlMailMergeDataSet(xmlData));
// Save the output document.
doc.save(MyDir + "Out.docx");
*tahir.manzoor:I have logged this query in our issue tracking system as WORDSNET-9669. I will update you via this forum thread once there is any information is available about this query. Thanks for your patience.*
The XmlMailMergeDataSet code example will solve this issue as well. Please try this code sample at your end and let us know if you still face any issue. The only exception of using dot (.) in mail merge field name already explained here:
https://forum.aspose.com/t/49899
For both items, I believe you have misunderstood. My mistake for specifying the Order XML without a parent and then showing the looping of a list of orders using foreach. I was just trying to create a scenario to describe the problem I thought I might have based on the other threads I have seen about NOT using dot notation with IMailMergeDataSource implementation. I did not have a problem with specifying the foreach command and producing a document. The scenario I was trying to describe was for using dot notation when two fields exist or when a field and attribute have the same name. I used City as an example to extend your example, but realistically, I see it more of an issue with some other element named the same such as an id as a child of some other element while having an id field at the parent level. The change you made only solves the mistake in my example. It does not address the issue I have been trying to describe.
The main issue that I have been trying to resolve here is the usage of dot notation while implementing IMailMergeDataSource and the fact that several threads have indicated NOT to mix the two for ANY implementation though it DOES work under certain circumstances. As I have mentioned before, I have implemented IMailMergeDataSource. I also want to use dot notation in some situations (but not all situations). I understand that the way you process using the MailMerge, there can be issues in finding data inside XML. I understand there is no way for you to differentiate between an attribute and a child field when they are at the appropriate level where there could be a conflict. I understand that my implementation may not work in some circumstances due to the processing of the MailMerge if I define an attribute of an element and then have an element name named the same at the same level. The XML I have defined includes very few XML attributes, so processing a parent.child (such as Address.Street where Street is a child element) would not be confused for my current implementation. I understand there might be a short circuit to the wrong field if I define an attribute the same name as an element at the same level, but at the end of the day I have to know my data within the constraints of the MailMerge process so there are no conflicts as opposed to just not using the dot notation as has been indicated in multiple threads. XML can be defined so many ways with different schemas. The customers example you have sent that has all the data in attributes is a valid schema, but placing data in attributes is discouraged by the community. Attributes should describe/alter/enhnance the contents of an element.
With all this being said, what I want to know is whether or not my implmentation, which IS working, will continue to work and that I won’t discover a couple Aspose revisions later that the implementation is invalid due to assumptions/opinions from Aspose about how a schema should be defined. What I would like to see is added documentation that describes some of the potential conflicts and possibly a warning indicating a short circuit might happen depending on how the XML source is defined. I know Aspose is trying to support several sources and there are potential conflicts as a result but don’t want changes to break my implentation. I believe my implementation may be different from some of those others defined in other threads in which the answer was to NOT use dot notation.
I appreciate that you have continued to send me solutions, but nearly all of them are the simplistic examples that have already been documented which I have already read. Please have someone in the development group look at this thread so we can see if changes on the product road map might occur that could break my implementation. I am truly attempting to stay within the rules of what is supported, but XML as a source is definitly a large variable that can have many implications. Stating some warnings in documentation seems more appropriate than to send out a blanket statement to NOT use dot notation.
Hi James,
Thanks for your inquiry. The only exception of using dot (.) in mail merge field name has already explained in this therad. I tested the scenario shared by you in this thread and have not found any issue while using ‘Mail Merge from XML using IMailMergeDataSource’.
It would be great if you please share the scenario for which you are getting any issue. Please share the runnable Java application that demonstrates the issue which you are facing.
I have requested the development team to share the exceptions while using dot (.) in mail merge field name. As soon as any information is shared by them, I will be more than happy to share that with you.
As I mentioned before, my implementation IS working. I am not having any problem at this time. When I was searching for some additional information regarding the mustache notation, I found very limited documentation. The only reference to it was not in the programmers guide, but instead in a release note several versions old. I then went to the forum and spent quite some time searching for information on it. What I found were multiple threads explicitly indicating do NOT use dot notation with an implementation of IMailMergeDataSource. I searched for more documentation to figure out what the limitations were or why I could not use the implementation. I found no explanation, just continuing statements indicating do NOT use it. Many of the threads stated that an upgrade to Aspose occurred and what was working is no longer working followed by responses from Aspose staff continuing to make a blanket statement that it was BY DESIGN, the IMailMergeDataSource implementation and dot notation should NOT be used together. As a result, I added on to the original question of this thread which appeared to have a problem that had similarities to my concern going forward.
With so much being said about it in the forum and my implementation having a lot riding on it, I need to know if there is any possibility of other upgrades on the product roadmap that attempt to block my usage of what is working today in order to keep the library safe for most implementors. If plans exist to block the usage of these two together, indicated by the repeated statements to NOT use the two together, then I have a major problem. I’m trying to stay within the “rules” but the rules are not very well defined as described above. What I would rather see, since the world is using XML for everything, is for Aspose to document any known issues and caution implementors on the dilema of the conflict in finding a child element or attribute with the same name in XML due to the MailMerge processing the template to find field names. Obviously, this is not as much of an issue if the data source is a table and the implementor can use the DataSet and DataTable classes. I believe the implentor must know their data and decide for themselves whether there is an issue since XML can be defined so many ways. When we create a template, for example, we have to be aware of the limitation for a merge region being wrapped around section breaks. I have had to redesign templates to accomodate this rule. I would prefer that the rule wasn’t there, but I don’t know what the issue is because your source is closed and there is very little documentation on why we can’t cross section breaks.
Mainly, I don’t want to see the library limited to keep the library simple. I like to have libraries that offer the simple interface as well as the advanced interface with documented caveats and limitations. While the IMailMergeDataSource could be considered the advanced interface, more documentation should be created on mustache syntax, limitations and cautions on using it with dot notation, etc. to allow many of us to find the answer. Maybe an additional set of methods in the MailMerge to process the XML and then search the template for fields of a given element name for replacement could give some alternatives to the conflict. Though I don’t know the full impact of an additional set of methods like this. I fully understand the challenges of a tool vendor for making things generic, working with multiple data sources, and trying to keep a common interface. There are times where the effort is not easy. The product overall does a great job.
Hi James,
Thanks for your inquiry.
Regarding your query about documentation, we have already logged a task in our issue tracking system as WORDSNET-9599 to add an article in documentation for Mustache mail merge features. You will be notified via this forum thread once this article is available.
As I shared earlier, Aspose.Words fully support the mail merge features. There is only one exception which was mentioned here.
There are no plans to change the existing behaviour of mail merge features. You can upgrade to the latest versions of Aspose.Words without any hesitation. I have already requested the development team to share the exceptions while using dot (.) in mail merge field name. As soon as any information is shared by them, I will be more than happy to share that with you.
Moreover, we had already logged a feature request as WORDSJAVA-720. This feature will include the implementation of .Net DOM Xml features including reading from XML. We will update you via this forum thread once this feature is available.