Generate documents with Word sub-templates in C#
Business documents reuse the same building blocks. Letters, quotes, and contracts share a letterhead, standard terms, and a signature block. When each template holds its own copy of these blocks, a new office address means editing every template.
Sub-templates keep each building block in a Word file of its own. The main template holds a placeholder where the block goes, and the JSON model names the file for that placeholder. Nutrient .NET SDK (formerly GdPicture.NET) inserts the file’s content when it generates the document. A sub-template is a template too, so the same JSON data fills its placeholders.
This guide generates a letter whose page header, terms, and signature come from three sub-templates, then converts the letter to PDF. It builds on the PDF from a Word template guide.
Download sampleHow sub-templates work
Nutrient replaces a placeholder with a sub-template when the placeholder’s value in the JSON model is an object with "_type": "docx". The object names the Word file with one of the following properties:
path: The path to the DOCX file. A relative path starts from the application’s working directory.data: The content of the DOCX file in base64, plain or as adata:URI.
"model": { "letterhead": { "_type": "docx", "path": "input_letterhead.docx" }, "terms": { "_type": "docx", "data": "UEsDBBQABgAIAAAAIQ..." }, "companyName": "Nutrient"}The content of the sub-template replaces the placeholder as follows:
- The paragraphs, tables, and pictures of the sub-template replace a placeholder that’s alone in its paragraph.
- A placeholder inside text splits the paragraph. The text before and after the placeholder stays in paragraphs of its own.
- Placeholders work in the body, in table cells, and in page headers and footers.
The inserted content keeps its formatting. Nutrient copies the styles, lists, pictures, links, footnotes, and bookmarks that the sub-template uses. When the main template already has a style with the same ID, the style of the main template applies, as when Word inserts a file. The headers, footers, page setup, and comments of the sub-template aren’t copied.
Prepare the templates
The sample uses four Word files and one JSON model:
input_letter_template.docx: The letter. Its page header holds{{letterhead}}. Its body holds the address of the customer, a table with one row per ordered item,{{terms}}, and{{signature}}.input_letterhead.docx: The company logo next to{{companyName}},{{companyStreet}},{{companyCity}}, and{{companyPhone}}.input_letter_terms.docx: A heading and a numbered list that uses{{deliveryDays}}and{{paymentDays}}, with a footnote.input_letter_signature.docx:{{senderName}}in bold and{{senderRole}}in a style of its own.input_letter_model.json: The data. It names the three sub-templates and holds the values of every placeholder.
The model holds the sub-templates next to the plain values:
{ "config": { "delimiter": { "start": "{{", "end": "}}" } }, "model": { "letterhead": { "_type": "docx", "path": "input_letterhead.docx" }, "terms": { "_type": "docx", "path": "input_letter_terms.docx" }, "signature": { "_type": "docx", "path": "input_letter_signature.docx" }, "companyName": "Nutrient", "companyStreet": "100 Main Street", "companyCity": "San Francisco, CA 94105", "companyPhone": "+1 415 555 0100", "date": "29 October 2026", "customerName": "Jane Smith", "customerStreet": "42 Oak Avenue", "customerCity": "Austin, TX 78701", "orderNumber": "SO-1042", "items": [ { "name": "Document SDK license", "qty": "1", "price": "$4,800" }, { "name": "Support plan", "qty": "1", "price": "$1,200" } ], "deliveryDays": "5", "paymentDays": "30", "senderName": "Alex Taylor", "senderRole": "Account Manager" }}{{companyName}} appears in the letterhead and in the footer of the letter. One value fills both.
Prepare the project
Register the license before you process templates or convert documents:
using GdPicture14;
LicenseManager license = new LicenseManager();license.RegisterKEY(""); // Set your license keyGenerate the letter
Create a GdPictureOfficeTemplater instance and load the JSON model. SetTemplate checks that the JSON holds a delimiter configuration and a model, and Process reads the sub-template files later:
using GdPictureOfficeTemplater templater = new GdPictureOfficeTemplater();
GdPictureStatus status = templater.SetTemplate(File.ReadAllText("input_letter_model.json"));ExitIfFailed(status, "Loading the template model");Load the letter template:
status = templater.LoadFromFile("input_letter_template.docx");ExitIfFailed(status, "Loading the letter template");Process the template. Process fills the placeholders of the letter, then opens each sub-template that a placeholder refers to, fills it from the same data, and inserts its content in place of its placeholder:
status = templater.Process();ExitIfFailed(status, "Processing the letter template");Save the generated letter as a Word document:
status = templater.SaveToFile("output.docx");ExitIfFailed(status, "Saving the letter");Convert the letter to PDF
Convert the generated letter to PDF with GdPictureDocumentConverter:
using GdPictureDocumentConverter converter = new GdPictureDocumentConverter();
status = converter.LoadFromFile("output.docx", GdPicture14.DocumentFormat.DocumentFormatDOCX);ExitIfFailed(status, "Loading the letter for conversion");
status = converter.SaveAsPDF("output.pdf");ExitIfFailed(status, "Saving the PDF");
Console.WriteLine("Successfully generated the letter from its sub-templates");Each step returns a GdPictureStatus. The following helper prints the step that failed and stops the program:
static void ExitIfFailed(GdPictureStatus status, string step){ if (status != GdPictureStatus.OK) { Console.Error.WriteLine($"{step} failed: {status}"); Environment.Exit(1); }}The page header of the PDF shows the letterhead with its logo and the company address. The body shows the terms with their numbered list and footnote, followed by the signature.
Build the model in code
The GdPictureOfficeTemplateBuilder class builds the model in code. AddSubTemplateFromFile names a sub-template by its path, and AddSubTemplateFromBytes passes its content. The following excerpt shows the three sub-templates and two of the plain values:
GdPictureOfficeTemplateConfiguration configuration = new GdPictureOfficeTemplateConfiguration{ Delimiter = new GdPictureOfficeTemplateDelimiter { Start = "{{", End = "}}" }};
GdPictureOfficeTemplate template = GdPictureOfficeDefaultTemplateBuilder.CreateTemplate() .AddSubTemplateFromFile("letterhead", "input_letterhead.docx") .AddSubTemplateFromBytes("terms", File.ReadAllBytes("input_letter_terms.docx")) .AddSubTemplateFromFile("signature", "input_letter_signature.docx") .AddPlaceholderReplacement("companyName", "Nutrient") .AddPlaceholderReplacement("senderName", "Alex Taylor");
GdPictureStatus status = templater.SetTemplate(template, configuration);Use sub-templates in loops
Inside a loop, a sub-template reads the values of the current record first, then the values around the loop. Each record can also name a sub-template of its own. For example, a template paragraph that holds {{#sections}}{{content}}{{/sections}} receives one document per record from the following model. warranty.docx fills {{years}}, and returns.docx fills {{days}}, from their own records:
"model": { "sections": [ { "content": { "_type": "docx", "path": "warranty.docx" }, "years": "2" }, { "content": { "_type": "docx", "path": "returns.docx" }, "days": "30" } ]}With the builder, call AddSubTemplateFromFile inside each record of AddSection:
GdPictureOfficeTemplate template = GdPictureOfficeDefaultTemplateBuilder.CreateTemplate() .AddSection<GdPictureOfficeTemplate>("sections", record => record .AddSubTemplateFromFile("content", "warranty.docx") .AddPlaceholderReplacement("years", "2"), record => record .AddSubTemplateFromFile("content", "returns.docx") .AddPlaceholderReplacement("days", "30"));Each copy of a sub-template gets lists of its own, so a numbered list starts at 1 in every copy.
Error handling
Process returns a status other than GdPictureStatus.OK when a sub-template can’t be used. The whole document fails, so Nutrient never generates a letter without its letterhead. The statuses are as follows:
FileNotFound: The file or its folder doesn’t exist.AccessDenied: The file can’t be read, for example because of its permissions.UnsupportedFormat: The file isn’t a Word document, or the template is a PowerPoint or Excel document.InvalidParameter: The value has neitherpathnordata,datais empty or isn’t valid base64, or a sub-template includes itself. Nutrient stops after 10 levels of nesting.
Limitations
- Sub-templates work in Word templates only. PowerPoint and Excel templates reject a
docxvalue. - Nutrient inserts only the body of a sub-template. Placeholders in its footnotes and endnotes aren’t filled.
- Page headers and footers can’t hold footnotes or endnotes. In a header or footer, Nutrient removes the note references of a sub-template.
- Image caption numbers restart in each sub-template.
- A placeholder inside an inline content control receives only the text of the sub-template, one line per paragraph.
pathreads any file that the application can access. Don’t build the path from untrusted input.
Conclusion
Sub-templates use the same steps as any Word template: load the model, load the template, process it, and save the result. The model names each sub-template, and Nutrient fills it from the same data before inserting it. To produce an accessible PDF, refer to the Word template to PDF/UA guide.
Download the sample package to run this example as-is.