ComPDF Generation User Guide

Overview

This guide helps you quickly learn the core workflow of the ComPDF Generation Template Editor, from creating an HTML template and importing a JSON data source to inserting placeholders and exporting the final PDF. Whether you are using the editor for the first time or preparing templates for team reuse, you can follow this guide to complete the full setup and output process.

After deployment, you will enter the main interface of the ComPDF Generation Template Editor. To get started quickly, we recommend reading the “Quick Start” section first and generating your first PDF before exploring advanced table handling, data formatting, and troubleshooting.

Terms:

• HTML template: A template file used to define PDF content, styling, and layout.
• Data source: JSON data used to populate the template.
• Placeholder: A variable tag in the template that receives values from the JSON data source.
• Export PDF: The process of merging the template and data source to generate the final PDF file.

Quick Start

If you want to complete the shortest end-to-end flow first, follow these steps:

1. Create a new HTML template.
2. Import a JSON data source.
3. Insert placeholders into the editor.
4. Save the template.
5. Export the PDF.

Use the following minimal JSON sample for testing:

{
  "customer_name": "ACME Corp",
  "invoice_no": "INV-20260802",
  "amount": 1280.5,
  "date": "2026-08-02"
}

You can start with the following sample content in the rich-text template editor:

Customer Name: {{customer_name}}
Invoice No.: {{invoice_no}}
Amount: {{amount}}
Date: {{date}}

After exporting the PDF, you can quickly confirm that the template, data source, and placeholders are configured correctly.

Create and Manage HTML Templates

This section explains how to create a new HTML template and manage it later from the template management center.

Steps

1. Click the New Template button on the home page.
2. Enter the Template Name and Template Description in the dialog box.
3. Submit the form. The new template will appear in the template management center.
4. From the template list, you can continue with actions such as Import, Download, Edit, Delete, and Design.

Common Use Cases

• Separate templates by business scenario, such as invoices, contracts, quotations, or reports
• Maintain different template versions for different customers or regions
• Build a standardized template library for batch document generation

Import Templates

Click Import Template from the template list, then select a file to create the corresponding template. The following file formats are supported:

• .zip, .dito: Import a template package and create the corresponding template.

After importing, open the template from the template list to continue editing, configure its data source, or export a PDF.

Design HTML Templates

Once the template is created, you can open the editor to design its content, layout structure, and basic styling.

How It Works

You can edit the template much like a document, adding text, images, paragraphs, tables, and layout styles directly in the editor.

Two Common Approaches

1. Start from scratch This is useful when you are designing a new document layout for the first time.

2. Modify an existing template This is useful when you want to reuse and refine a previously saved HTML template.

Recommendations

• Confirm the overall document structure before refining visual details
• For formal business documents, place the content first and fine-tune formatting afterward
• If the template contains images, verify that image paths or URLs are accessible in advance

Import a Data Source

Before inserting dynamic content, you need to import a JSON data source so the editor can recognize the fields available for mapping.

Steps

1. Open the Design Template page.
2. Click the entry point for importing a data source.

3. Choose one of the following methods:

• Upload a JSON file

• Paste or type JSON code directly

4. After a successful import, the recognized fields will appear in the Data Source panel on the right.

Important Notes

• The JSON must be valid, otherwise the system cannot recognize or import it
• Every placeholder used in the template must exist in the JSON data source
• Field names in the data source and HTML template must match exactly, including letter case
• If you plan to generate images, dates, or boolean values later, define field types clearly in advance

Configure Data Formatting

If you need specific display rules for field values, you can configure data formatting in this section to match different business document requirements.

Typical Use Cases

• Numeric calculations, rounding, and comparisons
• Standardized date formats
• Text concatenation or case conversion
• Image width and height control
• Converting boolean values into business-friendly labels

How It Works

If you want to adjust how placeholder values are displayed in the final output, click the button shown below and configure the field as needed. Common options include calculations, conditional logic, and date formatting.

Supported Types

Type	Supported Processing
Text	Concatenate strings, convert to uppercase, convert to lowercase
Number	Addition, subtraction, multiplication, division, exponentiation, modulo, rounding, multiply two values, divisibility checks, odd/even checks, size comparison, equality comparison, currency symbols, and symbol-position settings
Date	MM/DD/YYYY, DD/MM/YYYY, YYYY-MM-DD, YYYY-MM-DD HH:mm:ss
Image	Width (px), height (px)
Boolean	Display text for true, display text for false

Recommendations

• Test formatting results with sample data before formal export
• Date and amount fields are the most common sources of formatting issues, so check them first
• If you use conditional logic, prepare at least two sets of test data for validation

Currency Symbols

After setting a field type to Number, select a currency format, currency symbol, and whether the symbol appears before or after the amount. Supported symbols include US$, $, €, ¥, £, CN¥, CHF, A$, CA$, HK$, S$, ₹, ₩, NT$, R$, R, Rp, ₺, ฿, RM, د.إ, ر.س, ₽, and ₫.

Insert Placeholders

After importing the data source, you can insert fields into designated positions in the template as placeholders. During PDF generation, the system automatically replaces these placeholders with actual data.

If certain fields require specific formatting in the generated PDF as shown below, configure the field format first according to Configure JSON Field Formatting, then insert the fields into the HTML template.

• displaying currency symbols for amounts,

• converting text to uppercase,

• performing calculations based on JSON data,

Steps

Method 1: Place the cursor where you want to insert the field in the left editor. Select the target field from the data source panel on the right and click the Insert at Cursor button to add the field into the HTML template.

Method 2: Click the Copy button beside the data you want to insert, then paste it directly into the rich text editor on the left, and the system inserts the field as a placeholder at the current cursor position.

Once the template design is complete, the system automatically replaces placeholders with actual data during PDF export.

Table and Loop Blocks

If you need to populate list-based or line-item data in a template, use the following workflow to insert table data row by row into the HTML template.

Steps for Dynamic Tables

Prepare the relevant table data in the data source first, then insert placeholders into the data row of the template table. The system will populate the table based on the field mapping.

Step 1: Prepare list-type data in the data source, such as order details, product information, or expense records.

Step 2: Insert a table into the HTML template and keep one row as the detail data row. This row will be used as a loop block for automatically populating JSON data.

Step 3: Insert corresponding field placeholders into the first cell on the left side of the data row, such as product name, quantity, unit price, and total amount.

Step 4: Verify that placeholder names exactly match JSON field names.

When generating the document, the system automatically creates additional rows based on the number of items in the list and fills in the corresponding values.

Example Use Cases

• Insert customer names into headers or contract titles
• Insert order amounts, dates, and IDs into body content
• Insert image fields into ID cards, product displays, or brand areas

Important Notes

• Placeholder names must match JSON fields exactly
• It is best to import the data source before inserting placeholders
• If the template contains many fields, insert them by section to make review easier later

Save Templates

After editing the template, save your current work in time so it can be revised later, versioned properly, or reused across scenarios.

Two save options are available at the top of the editor:

• Save Changes: Overwrites the current template and is suitable for updating an existing version
• Save as New Template: Creates a new version based on the current template and is useful for branching or preserving history

Export Templates and PDFs

Download HTML Templates

Click Download HTML Template at the top to export a template package for local backup, team sharing, archiving, or later migration.

The package usually includes:

• HTML template file
• JSON source data file, if available
• Template metadata file

Generate and Export PDF

Before exporting from the target template page, confirm the following:

1. The HTML content on the left is complete
2. The JSON data on the right is valid
3. All placeholders are mapped correctly
4. The current template has been saved

Once everything is confirmed, click Export PDF to generate the file.

Troubleshooting

If export fails or the output is not as expected, check the following items in order:

1. Template Not Saved

If you edited the template but did not save it, the system may not export based on the latest content. Click Save Changes first, then try exporting again.

2. Invalid JSON Format

If the JSON structure is incorrect, missing brackets, or contains invalid field syntax, the system cannot recognize the data source correctly. Validate the JSON first and re-import it.

3. Placeholder and Field Name Mismatch

If variable names in the template do not exactly match JSON field names, the system cannot replace them correctly. Check spelling, letter case, and hierarchy carefully.

4. Page Layout Exceeds the Printable Area

If the template contains wide tables, oversized images, or complex layouts, the exported PDF may show page breaks, truncation, or layout issues. Optimize the layout and test with sample data first.

5. Table or Complex Style Issues

For multi-row tables, nested structures, or complex layouts, start with a minimal version first and add elements gradually so problems are easier to isolate.