# New JavaScript API Calls for Typical MailMerge Tasks > This article shows how to use the improved JavaScript API for typical MailMerge tasks such as inserting merge blocks. - **Author:** Bjoern Meyer - **Published:** 2020-03-19 - **Modified:** 2025-11-16 - **Description:** This article shows how to use the improved JavaScript API for typical MailMerge tasks such as inserting merge blocks. - **3 min read** (521 words) - **Tags:** - Angular - ASP.NET - JavaScript - MailMerge - Release - **Web URL:** https://www.textcontrol.com/blog/2020/03/19/new-javascript-api-for-typical-mailmerge-tasks/ - **LLMs URL:** https://www.textcontrol.com/blog/2020/03/19/new-javascript-api-for-typical-mailmerge-tasks/llms.txt - **LLMs-Full URL:** https://www.textcontrol.com/blog/2020/03/19/new-javascript-api-for-typical-mailmerge-tasks/llms-full.txt --- Version X18 (28.0) comes with a complete [JavaScript API](https://docs.textcontrol.com/textcontrol/asp-dotnet/ref.javascript.api.htm) for the online document editor shipped with [TX Text Control .NET Server](https://www.textcontrol.com/product/tx-text-control-dotnet-server/). The complete JavaScript API documentation can be found in our online docs: [JavaScript API](https://docs.textcontrol.com/textcontrol/asp-dotnet/ref.javascript.api.htm) This article describes typical tasks for MailMerge and reporting applications such as inserting merge fields, merge blocks and how to loop through these MailMerge elements. ### Inserting Merge Fields In the new API, each element, like a *TextField*, is accessible through it's own collection. The following code snippet shows how to insert a merge field, that is compatible with MailMerge, using the ApplicationFieldCollection. The collection is accessible through the applicationFields property. The add method inserts a new field at the current input position. ``` TXTextControl.applicationFields.add( TXTextControl.ApplicationFieldFormat.MSWord, "MERGEFIELD", "FieldText", ["FieldName"], af => { var highlightColor = "rgba(9, 165, 2, 0.3)"; var highlightMode = TXTextControl.HighlightMode.Always; af.setHighlightColor(highlightColor); af.setHighlightMode(highlightMode); } ); ``` The last parameter in the above call of the *add* method returns the inserted field in a callback. In this code snippet, this returned object is used to add additional properties that are not available in the constructor of the add method. The above snippet shows how to insert merge fields (or any other supported type) into a document. The same can be achieved by using the addMergeField method to make things easier for the most typical fields. ``` var mergeField = new TXTextControl.MergeField(); mergeField.name = "company"; mergeField.text = "«company»"; mergeField.numericFormat = "$#,###.00" TXTextControl.addMergeField(mergeField); ``` ### Looping Through Fields The next code snippet is using the forEach method that is available for each collection in the JavaScript API. This method executes a callback for all elements in a collection. The code loops through all *ApplicationFields* and returns it's name. ``` TXTextControl.applicationFields.forEach(function(appField) { appField.getName(function(name) { console.log(name) }); }) ``` The below code snippet changes the text of each field in the document: ``` TXTextControl.applicationFields.forEach(function(appField) { appField.setText("new text"); }) ``` ### Inserting Merge Blocks A merge block that repeats content based on the hierarchical data using MailMerge, is a SubTextPart element. The name of the *SubTextPart* must have the specific prefix *txmb\_* followed by the name of the merge block. The following code inserts a merge block with the name *myMergeBlock* at the current input position: ``` TXTextControl.selection.getStart(function(curSelStart) { curSel.getLength(function(curSelLength) { TXTextControl.subTextParts.add( "txmb_myMergeBlock", 0, curSelStart + 1, curSelLength); }) }); ``` The Selection object is used to retrieve the start and length index of the current selection which is then used in the add method of the *SubTextPartCollection*. The next code snippet shows how to iterate through all *SubTextParts* in order to return valid merge block names: ``` TXTextControl.subTextParts.forEach(function(subTextPart) { subTextPart.getName(function(name) { var mergeBlockName; if (name.startsWith("txmb_")) { mergeBlockName = name.substring(5, name.length); console.log(mergeBlockName); } }); }); ``` Read more about the improved [JavaScript API](https://docs.textcontrol.com/textcontrol/asp-dotnet/ref.javascript.api.htm) in our documentation and download the [trial version](https://www.textcontrol.com/product/tx-text-control-dotnet-server/download/) of TX Text Control .NET Server to test this on your own. --- ## About Bjoern Meyer As CEO, Bjoern is the visionary behind our strategic direction and business development, bridging the gap between our customers and engineering teams. His deep passion for coding and web technologies drives the creation of innovative products. If you're at a tech conference, be sure to stop by our booth - you'll most likely meet Bjoern in person. With an advanced graduate degree (Dipl. Inf.) in Computer Science, specializing in AI, from the University of Bremen, Bjoern brings significant expertise to his role. In his spare time, Bjoern enjoys running, paragliding, mountain biking, and playing the piano. - [LinkedIn](https://www.linkedin.com/in/bjoernmeyer/) - [X](https://x.com/txbjoern) - [GitHub](https://github.com/bjoerntx) --- ## Related Posts - [Using the Document Editor in SPA Applications using the removeFromDom Method](https://www.textcontrol.com/blog/2024/09/02/using-the-document-editor-in-spa-applications-using-the-removefromdom-method/llms.txt) - [TXTextControl.Web: Creating a Custom ButtonBar using the InputFormat Class](https://www.textcontrol.com/blog/2020/03/20/creating-a-custom-buttonbar-using-the-inputformat-class/llms.txt) - [Creating Advanced Tables in PDF and DOCX Documents with C#](https://www.textcontrol.com/blog/2024/09/30/creating-advanced-tables-in-pdf-and-docx-documents-with-csharp/llms.txt) - [Video Tutorial: Creating a MailMerge Template and JSON Data Structure](https://www.textcontrol.com/blog/2024/08/16/video-tutorial-creating-a-mailmerge-template-and-json-data-structure/llms.txt) - [Observe When the Reporting Preview Tab is Active Using MutationObserver](https://www.textcontrol.com/blog/2024/07/23/observe-when-the-reporting-preview-tab-is-active-using-mutationobserver/llms.txt) - [Mail Merge: The Pre-Shaped Data Concept Explained](https://www.textcontrol.com/blog/2024/05/30/mail-merge-the-pre-shaped-data-concept-explained/llms.txt) - [Building an ASP.NET Core Backend Application to Host the Document Editor and Document Viewer](https://www.textcontrol.com/blog/2024/03/14/building-an-asp-net-core-backend-application-to-host-the-document-editor-and-document-viewer/llms.txt) - [Reuse Angular Document Editor Instances in Bootstrap Tabs](https://www.textcontrol.com/blog/2023/05/22/reuse-angular-document-editor-instances-in-bootstrap-tabs/llms.txt) - [MailMerge: Working with Image Placeholders](https://www.textcontrol.com/blog/2022/12/22/mailmerge-working-with-image-placeholders/llms.txt) - [Merging Signature Annotations into Documents](https://www.textcontrol.com/blog/2022/10/19/merging-signature-annotations-into-documents/llms.txt) - [Sneak Peek 31.0: Customizing the Context Menu of the ASP.NET Document Editor](https://www.textcontrol.com/blog/2022/08/25/sneak-peek-310-customizing-the-context-menu-of-the-aspnet-document-editor/llms.txt) - [Text Control Error Navigator Launched](https://www.textcontrol.com/blog/2022/08/15/text-control-error-navigator-launched/llms.txt) - [Restoring the Merge Field Default Behavior](https://www.textcontrol.com/blog/2022/08/15/restoring-the-merge-field-default-behavior/llms.txt) - [JavaScript: Avoid Flickering and Visual Updates by Grouping Undo Steps](https://www.textcontrol.com/blog/2022/07/25/javascript-avoid-flickering-and-visual-updates-by-grouping-undo-steps/llms.txt) - [Version 30.0 Live Preview](https://www.textcontrol.com/blog/2021/09/22/version-30-live-preview/llms.txt) - [TX Text Control 30.0 Preview: Improved Online Document Editor Ribbon Design](https://www.textcontrol.com/blog/2021/09/17/tx-text-control-30-preview-improved-online-document-editor-ribbon-design/llms.txt) - [TX Text Control Document Editor Deployment Strategies](https://www.textcontrol.com/blog/2021/08/10/document-editor-deployment-strategies/llms.txt) - [DocumentViewer 29.2 (29.0.302.500) Final Released](https://www.textcontrol.com/blog/2021/07/27/documentviewer-29-302-final-released/llms.txt) - [DocumentViewer: Deploying Forms](https://www.textcontrol.com/blog/2021/07/02/document-viewer-deploying-forms/llms.txt) - [Track Changes: Show 'Original' and 'No Markup'](https://www.textcontrol.com/blog/2021/02/18/track-changes-show-original-and-no-markup/llms.txt) - [Using the Document Viewer in Angular Routes](https://www.textcontrol.com/blog/2021/01/14/using-document-viewer-in-angular-routes/llms.txt) - [Announcing DS Server Public Beta: Your On-Premise Document Services Cloud](https://www.textcontrol.com/blog/2020/12/18/announcing-ds-server-public-beta/llms.txt) - [Client-Side Packages for X19 Available](https://www.textcontrol.com/blog/2020/12/09/client-side-packages-for-x19-available/llms.txt) - [X19 Sneak Peek: Manipulating MergeBlockInfo Objects](https://www.textcontrol.com/blog/2020/11/17/x19-sneak-peek-manipulating-mergeblockinfo-objects/llms.txt) - [Updated DocumentViewer Features: Zooming and Panning](https://www.textcontrol.com/blog/2020/08/24/new-documentviewer-features-zooming-and-panning/llms.txt)