Template Generation Engine (.docx Parsing)

The idea: smart find-and-replace

At its core the template engine is a very sophisticated “fill in the blanks” system. A barangay staff member creates a normal Word document (a clearance, a certificate, whatever) and drops in placeholder tags where the variable data should go. When a request is approved, the engine reads those tags and swaps each one for the real value: the resident’s name, the date, the address, and so on.

Think of it like a mail-merge you might have used in a word processor, except it happens automatically, at scale, without anyone opening the file manually. The staff member who designed the template never needs to touch code (they just type{{fullName}} where the name should appear and the engine handles the rest.

To Whom It May Concern:

This is to certify that {{fullName}}, born on {{dateOfBirth}}, and
currently residing at {{address}}, is a bonafide resident of Barangay
{{barangayName}}, City of {{city}}.

This certification is issued upon the request of the above-named
individual for whatever legal purpose it may serve.

Issued this {{dateIssued}} at Barangay {{barangayName}}.

_________________________
{{captainName}}
Barangay Captain

The template above is a plain .docx file. The placeholders inside double curly braces are the only “code” in the entire document. Every other piece of formatting (fonts, margins, letterhead, signatures) stays exactly as the designer set it up.

How .docx templates work behind the scenes

A .docx file is not a single opaque blob. It is a ZIP archive containing a collection of XML files. The text you see in Word lives inside word/document.xml, along with every formatting instruction, image reference, and style. Fonts, headers, footers, and even the spell-check dictionary each get their own XML file inside the archive.

The template engine exploits this structure directly. When a template is uploaded, it is unzipped in memory. The engine parsesword/document.xml with an XML parser, walks every text node, and collects every run of text that matches the{{...}} pattern. Because it operates at the XML level rather than at the display level, it can handle placeholders that span multiple Word “runs” (Word sometimes splits a single word into several runs due to formatting changes). The engine reassembles these fragments before replacing them.

This also means the engine is format-agnostic. Bold, italics, tables, and images are all preserved exactly, because the engine never rewrites formatting. It only modifies the text content of the nodes that contain a placeholder.

How placeholders map to form fields

Each placeholder tag corresponds to a field in the request form. Some fields are filled automatically by the system (for example, the resident’s name and address come from the profile they already created during registration). Other fields are filled by the staff member when they encode a walk-in request, or by the resident when they submit an online request.

The mapping is defined in the document type’s configuration. Here is a simplified version of what that looks like:

{
  "documentType": "Barangay Clearance",
  "templateFile": "templates/barangay-clearance.docx",
  "placeholders": {
    "fullName":       { "source": "resident", "field": "fullName" },
    "dateOfBirth":    { "source": "resident", "field": "dateOfBirth" },
    "address":        { "source": "resident", "field": "address" },
    "barangayName":   { "source": "system",  "field": "barangayName" },
    "city":           { "source": "system",  "field": "city" },
    "captainName":    { "source": "system",  "field": "captainName" },
    "dateIssued":     { "source": "auto",    "field": "currentDate" },
    "purpose":        { "source": "request", "field": "purpose" }
  }
}

The source key tells the engine where to pull the value from:

• resident (read from the resident’s profile). The system already has their name, birth date, and address on file.
• system (pulled from the barangay’s own settings: barangay name, city, the captain’s name). These rarely change but can be updated in the admin panel.
• auto (generated at runtime). The current date, a tracking number, or a hash can be injected without any human input.
• request (comes from the specific request being processed). The purpose of the clearance, the business name on a permit, or any custom detail the staff or resident entered when filing the request.

Auto-filled tags like {{dateIssued}} and{{barangayName}} are invisible to the end user (they never see a form field for them). User-filled tags like{{purpose}} appear as editable fields in the request form. This split is what makes the system both flexible and safe: staff only need to type what is unique to each request.

From template to finished PDF

Once all placeholders are resolved, the engine has a completed XML document sitting in memory. But a Word XML document is not what residents or staff need (they need a universally readable PDF). The pipeline that produces the final file has four stages:

• 1. Parse the .docx (the ZIP archive is unzipped, word/document.xml is loaded, and every placeholder node is identified).
• 2. Inject values (each placeholder is replaced with its resolved value). The engine handles type coercion: dates are formatted to locale, numbers are formatted with commas, and empty strings produce a visible dash so the document never has blank gaps.
• 3. Render to PDF (the modified XML is converted to a PDF using a LibreOffice-based renderer). The renderer respects all formatting (fonts, spacing, tables, and images) so the PDF looks identical to what the designer intended.
• 4. Embed QR code (a unique QR code is generated from the document’s tracking number and a signed hash). The QR is placed at a designated position in the PDF (usually the bottom-right corner). Scanning the code verifies the document against the database.

Why this matters for barangay staff

The template engine is not just a technical convenience. It solves real, daily pain points in a barangay office:

• Consistency. Every document produced from a template has the same layout, same wording, and same formatting. No more differences between what Secretary Maria writes on Monday and what Encoder Juan writes on Friday.
• Fewer mistakes. Because the system auto-fills names, addresses, and dates from the database, the most error-prone part of document creation is eliminated. Staff only need to verify that the auto-filled data is correct.
• Speed. A clearance that once took five minutes to type from scratch now takes seconds. The engine generates the entire document in under a second, and staff only need to review it before approving.
• Easy template edits. If a document’s wording needs to change (a new law requires a different clause, or the barangay captain wants a revised header), the admin simply uploads a new .docx template. No developer involvement, no downtime, no restart.

Template management in the admin panel

Barangay admins manage templates through the admin panel. The workflow is designed to be as simple as possible so that non-technical staff can handle it end to end:

1. Upload. The admin opens the Document Types page and selects a document type (e.g., “Barangay Clearance”). They upload a .docx file that has been prepared with the correct placeholders.
2. Map placeholders. The system automatically detects every {{...}} tag in the uploaded document and presents a mapping form. The admin assigns each placeholder to a source (resident profile, system setting, auto-generated value, or request field).
3. Preview. Before saving, the admin can generate a test PDF using sample data. This lets them verify that every placeholder resolves correctly, that the layout looks right, and that the QR code appears in the expected position.
4. Publish. Once satisfied, the admin saves the template. From that moment on, every approved request for that document type will use the new template. Older documents retain the version that was active when they were generated.

Version history is maintained automatically. If an admin uploads a new template, the old one is archived. This means the system can still re-generate a PDF for a past request using the original template it was filed under, even if a newer version exists.