Creating Invoices from DOCX Templates in C# from Scratch

Generating invoices in business applications is a very typical scenario for digital document processing. In this tutorial, the required steps of generating an invoice in a C# ASP.NET Core application is shown:

• Template creation
• Data merging
• PDF generation

Resulting Template

First, let's have a look at a typical invoice template (later, we will create a more simplistic version of it). The following animation is alternating between the template with placeholders and with merged data:

Download Template

This template is discussed in another blog post that also provides links to download the template and JSON data.

Creating Templates: Typical Invoice Elements

JSON Data

JSON data is used as the data source that is merged into the template. This JSON data string is also beginning of the template creation process. The JSON file is loaded into the DocumentEditor to provide the user ("template designer") the available merge field names.

The following JSON data contains the typical elements that should be included on an invoice including invoice meta data, information about the payer, the sold products and payment information. In this sample, the total amount, tax and discount values are calculated using formulas in the template itself.

Creating the Template

Assuming that you created an ASP.NET Core web application according to our getting started tutorial, the following steps describe how to load the JSON data into the document editor to insert available merge fields.

1. In the Solution Explorer, select your project and insert a new folder by clicking Project -> New Folder from the main menu. Name this folder App_Data.

2. Create a new JSON file in that folder and name it data.json. Copy and paste the content of the JSON file above into the newly created file.

3. Find the Index.cshtml file in the Views -> Home folder. Replace the complete content with the following code to add the document editor to the view:

   	@using TXTextControl.Web.MVC
   	@{
   	var jsonData = File.ReadAllText("App_Data/data.json");
   	}
   	@Html.TXTextControl().TextControl().LoadDataFromJson(jsonData).Render()

   view raw test.cshtml hosted with ❤ by GitHub

After the document editor is initialized, all available merge fields and merge blocks are listed in the drop-down lists in the Reporting tab:

This way, users can focus on creating and designing the template and don't have to care about proper merge field names that can be added to a template. Let's start to design the template by adding merge fields.

1. Insert the string Invoice: and select invoice -> number from the Insert Merge Field drop-down list.

   

   Pro Tip

   By looking at the name of the inserted field (invoice.number), you can see that it uses the dot-notation to access fields from a child table. This way, you can access field columns of any level in the data hierarchy.

2. Repeat the same for the field invoice -> date. After adding the field, click the field with the mouse to set the input position into it and choose Field Properties from the ribbon bar.

   In the dialog, set the Date / time format to dddd, MM/dd/yyyy. This defines a custom string formatter for this field.

   

3. Click on Preview to see first results.

   

   You can close the preview by clicking the Exit button in the opened contextual ribbon tab.

4. Following the above steps, insert as many fields from the data source as required into the template.

Inserting Merge Blocks

A merge block (or repeating block) is a reporting element that repeats content based on data rows. A merge block can contain anything including tables, paragraphs or single words. Typically, a table row is repeated that represents an invoice line item in our scenario.

1. Click items in the list of available merge blocks from the Insert Merge Block drop-down list.

   

2. In the opened dialog, select all columns and move the item product to top as this should be our first table column.

   

3. After confirming with OK, a table is added that consists of a repeating table header and the actual merge block that is highlighted in red. Manually, you can change the column titles to reflect proper descriptions.

   

4. Click on Preview to see the first merge block results.

   

   You can close the preview by clicking the Exit button in the opened contextual ribbon tab.

5. Resize the table columns using the mouse interface to provide the inserted columns a better ratio:

   

6. Set the input position into the field unitprice and set the alignment to top/right in the Table Layout ribbon tab.

   

7. Back in the Reporting tab, select Field Properties to change the properties of the field unitprice. As it is a currency, set the value of the Numeric format to C or to your desired format such as $##.##,##.

   

8. In the Preview, the currency values are perfectly aligned and formatted in the desired format.

   

Using the document editor, there are various ways to save the document for example using the JavaScript API by sending it to a Web API controller method. This is shown in another blog article:

Loading and Saving Documents Through Controller HttpPost Methods

For TX Text Control, the template format can be any supported document format. You can save the template as an Office Open XML (DOCX) document, as RTF or in the internal TX Text Control format. In the next steps, we will use the internal TX Text Control format.

Merging the Data

In the next step, the template is merged with the actual data. Typically, this is done server-side in a non-UI process.

Pro Tip

The JSON data loaded into the Document Editor is not necessarily the actual data, but only dummy data with the correct structure or hierarchy. When merging the data into the template, you can use any form of data object (IEnumerable) with the same structure and naming.

Assuming that you created an ASP.NET Core web application according to our getting started tutorial, the following steps describe how to load the prepared template and to how to merge it with JSON data.

1. In the Solution Explorer, select your project and insert a new folder by clicking Project -> New Folder from the main menu. Name this folder App_Data.

2. Copy the created template into this folder and name it template.tx.

3. Create a new JSON file in that folder and name it data.json. Copy and paste the content of the JSON file above into the newly created file.

4. Find the HomeController.cs file in the Controllers folder. Replace the Index() method with the following code:

   	public IActionResult Index() {
   	// load the JSON data
   	string jsonData = System.IO.File.ReadAllText("App_Data/data.json");
   	using (TXTextControl.ServerTextControl tx = new TXTextControl.ServerTextControl()) {
   	tx.Create();
   	// load the template
   	tx.Load("App_Data/template.tx", TXTextControl.StreamType.InternalUnicodeFormat);
   	// use MailMerge to merge data
   	using (TXTextControl.DocumentServer.MailMerge mm =
   	new TXTextControl.DocumentServer.MailMerge()) {
   	mm.TextComponent = tx;
   	mm.MergeJsonData(jsonData);
   	}
   	// return result as HTML
   	string result = "";
   	tx.Save(out result, TXTextControl.StringStreamType.HTMLFormat);
   	ViewBag.Document = result;
   	}
   	return View();
   	}

   view raw test.cs hosted with ❤ by GitHub

In the above method, the template is merged automatically with data from the JSON string. The results are returned in form of an HTML document that is rendered in the view:

In order to create a PDF from the results, the document can be simply exported as an Adobe PDF using this code in the controller method:

Getting Started

You will find this tutorial and many more in our Getting Started tutorial collection:

Getting Started