Certificate Builder and PDF Engine

Updated for version 0.9.80+

This document explains the current certificate architecture: why the system now has multiple template modes, how the PDF Builder stores documents, how preview and public display work, and where to extend the feature safely.

Why the Architecture Changed

The original certificates feature assumed a Bricks template rendered to HTML and then exported to PDF. That remains available, but it is not the right foundation for exact, background-based downloadable certificates. The new architecture keeps the shared certificate domain model and adds a separate rendering engine for reliable fixed-canvas PDFs, plus a combined mode that uses both paths together.

High-Level Architecture

One certificate domain model — same post type, same issued-certificate table, same rules, same snapshot flow
Three template modes — bricks, pdf_builder, and both
Two PDF paths:
- Bricks template → render HTML → DOMPDF
- PDF Builder document → direct TCPDF composition

Template Storage Model

Shared Template Settings

Stored in _brm_certificate_settings.

Key fields:

render_engine
layout_type
page_size
orientation
public_view_mode
display_page_id
number_format

PDF Builder Document

Stored in _brm_certificate_designer_document.

Root keys:

version
page
background
guides
blocks

Supported blocks:

text
image
icon
qr
shape

Builder Runtime

The PDF Builder admin UI is intentionally not modeled visually after the quiz builder. It reuses only the controller/save architecture.

Runtime split:

CertificateDesignerAdmin — controller, asset loading, localized config
CertificateDesignerTemplate — admin markup shell
certificate-designer.js — state, canvas interaction, snapping, inline text editing, icon picker, save flow
certificate-designer.css — visual builder layout and canvas styles

The builder state is owned client-side and persisted through brm_certificate_save_designer_document. Server-side normalization always runs before saving.

Preview Architecture

The builder preview system does not invent a parallel dataset. It uses a synthetic certificate context generated by CertificateService::build_template_preview_context().

Preview flow:

admin clicks preview
signed preview URL is built by CertificateUrlService
CertificateSystem validates the nonce and edit_post capability
preview certificate + snapshot are generated
preview PDF or preview QR are served from the same certificate pipeline

Public Display Modes

PDF Builder-only templates support two public display modes:

direct_pdf — display_url = pdf_url
bricks_page — display_url = selected Bricks page + brm_cert_hash

Bricks templates always use the template page itself with brm_cert_hash.

both templates always use the Bricks template page for digital viewing and the PDF Builder composer for downloads. Internally that means:

display_url = Bricks template permalink with brm_cert_hash
download_url = certificate download route using the PDF Builder composer
pdf_url = inline PDF route using the PDF Builder composer

Why PDF Builder Uses TCPDF

PDF Builder does not convert HTML into PDF. It writes the PDF directly. That avoids the layout mismatch problems inherent in modern browser-style HTML/CSS rendering with server-side PDF libraries.

Benefits:

predictable placement
text remains text
background images behave as expected
icons, QR codes, shapes, and links can be composed deterministically

Icon and Font Handling

PDF Builder uses two separate registries:

CertificatePdfFontRegistry for text fonts
CertificateDesignerIconLibrary for Bricks icon libraries and TCPDF icon font registration

The icon registry:

loads Bricks icon CSS and icon bridge data for the admin UI
normalizes icon library IDs and glyph classes
creates TCPDF font definitions for icon fonts on demand
returns both the TCPDF family name and the generated font definition file path so SetFont() can load them correctly

Shared Data Layer

CertificatePlaceholderRegistry is the single source of truth for:

Bricks dynamic tags
PDF Builder placeholders
builder preview values
image fields vs text fields vs URL fields

This keeps the builder, public display, and dynamic-tag system aligned.

Bricks Integration

Certificates now keep the Bricks surface intentionally small:

BRM Certificate PDF

The PDF element matters for the new display model because it lets a normal Bricks page act as the public certificate page for a PDF Builder template.

Download buttons, verification links, QR images, and metadata output now use native Bricks elements together with certificate dynamic tags.

Combined Mode and Bricks Export

The both mode exists for teams that want:

free-form digital certificate pages in Bricks
reliable print/download output from the PDF Builder

Creation flow:

user selects Both Builders in the create-template modal
user chooses a PDF Builder preset
the PDF Builder document is stored normally
a Bricks starter document is generated from that PDF preset and saved into the template post meta

The PDF Builder also exposes a Copy for Bricks action. That uses CertificateDesignerBricksExportService to convert the current normalized builder document into Bricks-compatible JSON that users can paste into Bricks Builder as a starting point.

Extension Guidance

If you extend the certificates feature, keep these rules in mind:

add new certificate-facing URLs through CertificateUrlService
add new placeholders through CertificatePlaceholderRegistry
add new PDF Builder block types through CertificateDesignerBlockRegistry and CertificateDesignerService
keep rendering logic out of admin templates
keep request validation and capability checks in services/AJAX handlers, not in JS