ForgeDoc 2.2.0

ForgeDoc - Word Template Processor

ForgeDoc is a library for processing Word templates with placeholders and generating dynamic Word documents.

Features

• Replace text placeholders in Word documents
• Add images to Word documents using {% imageKey %} syntax
• Render tables in Word documents
• Support for rich text formatting
• Works with headers, footers, and tables

Image Placeholders

ForgeDoc supports inserting images into Word documents using a special placeholder syntax:

{% imageKey %}

Where imageKey is a key that references an image path you've added to the template data.

Adding Images to Template Data

// Create template data
var data = new WordTemplateData();

// Add image (path must be accessible at runtime)
data.AddImage("Logo", @"C:\path\to\logo.png");
data.AddImage("Signature", @"C:\path\to\signature.jpg");

// Process the template
var template = new WordTemplate("template.docx", data);
template.Process("output.docx");

Images in Tables

You can also include images in tables by using the same placeholder syntax:

var tableData = new List<Dictionary<string, string>>
{
    new Dictionary<string, string> { { "Name", "John Doe" }, { "SignatureKey", "Signature1" } },
    new Dictionary<string, string> { { "Name", "Jane Smith" }, { "SignatureKey", "Signature2" } }
};

// Add the table data
data.AddTable("Employees", tableData);

// Add the images
data.AddImage("Signature1", @"C:\path\to\john_signature.png");
data.AddImage("Signature2", @"C:\path\to\jane_signature.png");

In your Word template, use:

{{#docTable Employees}}
Name: {{ item.Name }}
Signature: {% {{ item.SignatureKey }} %}
{{/docTable}}

Working with Database Images

When working with images from a database, save them to temporary files first:

// Save database image to a temporary file
string tempPath = Path.Combine(Path.GetTempPath(), $"signature_{Guid.NewGuid()}.png");
File.WriteAllBytes(tempPath, databaseImageBytes);

// Add the image to the template data
data.AddImage("Signature", tempPath);

// Remember to clean up temporary files after processing
try {
    if (File.Exists(tempPath)) {
        File.Delete(tempPath);
    }
} catch {
    // Handle cleanup errors
}

Supported Image Formats

The processor supports common image formats:

• PNG • JPEG/JPG • GIF • BMP • TIFF

Images are inserted at their original size.

Table Rendering

ForgeDoc supports three ways to render tables in Word documents:

1. Standard Table Syntax

Use the following syntax in your Word template to define where a table should be rendered:

{{#docTable tableName}}
{{item.column1}} {{item.column2}}
{{/docTable}}

This will create a new table at the location of the placeholder, with one row for each item in the table data.

2. Existing Table with Placeholders

You can also use placeholders directly in an existing table in your Word document:

| Header 1   | Header 2   | Header 3   |
|------------|------------|------------|
| {{column1}} | {{column2}} | {{column3}} |

The processor will replace the placeholders with values from the first row of data and duplicate the row for each additional data item.

3. Mixed Syntax in Existing Tables

ForgeDoc also supports a mixed syntax approach where you can have both table placeholders and regular placeholders in the same table:

| Header 1   | Header 2   | Header 3   |
|------------|------------|------------|

| {{#docTable tableName}}{{column1}} | {{column2}} | {{column3}}{{/docTable}} |

In this case, the processor will:

1. Identify the table that contains the {{#docTable}} tag
2. Replace all placeholders in the row with values from the data
3. Duplicate the row for each data item in the table data
4. Remove any remaining table tags

This is particularly useful for complex tables with headers in different languages or when working with existing template documents.

Usage

Basic Usage

// Create a new WordTemplateData object
var data = new WordTemplateData
{
    Placeholders = new Dictionary<string, string>
    {
        { "Title", "My Document" },
        { "Author", "John Doe" },
        { "Date", DateTime.Now.ToString("yyyy-MM-dd") }
    }
};

// Create a new WordTemplate object
var template = new WordTemplate("path/to/template.docx", data);

// Get the generated document as a byte array
byte[] document = template.GetFile();

Adding Images

var data = new WordTemplateData
{
    Placeholders = new Dictionary<string, string>
    {
        { "Title", "My Document with Images" }
    },
    Images = new Dictionary<string, string>
    {
        { "Logo", "path/to/logo.png" },
        { "Signature", "path/to/signature.jpg" }
    }
};

In your Word template, use {% Logo %} and {% Signature %} to place the images.

Adding Tables

Tables can be added to your Word template using the following syntax:

{{#docTable tableName}}
{{item.column1}} {{item.column2}} {{item.column3}}
{{/docTable}}

In your code, add the table data like this:

var tableData = new List<Dictionary<string, string>>
{
    new Dictionary<string, string>
    {
        { "column1", "Row 1, Column 1" },
        { "column2", "Row 1, Column 2" },
        { "column3", "Row 1, Column 3" }
    },
    new Dictionary<string, string>
    {
        { "column1", "Row 2, Column 1" },
        { "column2", "Row 2, Column 2" },
        { "column3", "Row 2, Column 3" }
    }
};

data.AddTable("tableName", tableData);

The table will be rendered with one row for each item in the list, and one column for each placeholder in the template.

Example

Here's a complete example of using all features:

var data = new WordTemplateData
{
    Placeholders = new Dictionary<string, string>
    {
        { "Title", "Inventory Report" },
        { "Date", DateTime.Now.ToString("yyyy-MM-dd") },
        { "PreparedBy", "John Doe" }
    },
    Images = new Dictionary<string, string>
    {
        { "CompanyLogo", "path/to/logo.png" },
        { "Signature", "path/to/signature.jpg" }
    }
};

// Add inventory items table
var inventoryItems = new List<Dictionary<string, string>>
{
    new Dictionary<string, string>
    {
        { "itemName", "Laptop" },
        { "quantity", "10" },
        { "price", "1200.00" }
    },
    new Dictionary<string, string>
    {
        { "itemName", "Monitor" },
        { "quantity", "15" },
        { "price", "300.00" }
    },
    new Dictionary<string, string>
    {
        { "itemName", "Keyboard" },
        { "quantity", "20" },
        { "price", "50.00" }
    }
};

data.AddTable("inventory", inventoryItems);

var template = new WordTemplate("inventory_template.docx", data);
byte[] document = template.GetFile();

In your Word template, you would have:

Title: {{Title}}
Date: {{Date}}
Prepared By: {{PreparedBy}}

Company Logo: {% CompanyLogo %}

Inventory Items:
{{#docTable inventory}}
{{item.itemName}} {{item.quantity}} {{item.price}}
{{/docTable}}

Signature: {% Signature %}

License

This project is licensed under the MIT License - see the LICENSE file for details.