12. Print & Templates

NkapBooks includes a powerful print template system that lets you design, customize, and generate professional documents — invoices, receipts, quotes, payment vouchers, and more. The system combines a visual Template Builder with a code editor, pre-built templates, and full PDF export and direct printing capabilities.

12.0 Print System Overview

The NkapBooks print system works through three layers:

┌──────────────────────────────────────────────────────────┐
│  1. Print Template (Vue HTML Template)                    │
│     Defines the layout using HTML, CSS, and Vue syntax    │
├──────────────────────────────────────────────────────────┤
│  2. Template Variables (doc + print)                      │
│     Document data and print settings injected at render   │
├──────────────────────────────────────────────────────────┤
│  3. Rendering Engine                                      │
│     Vue compiler → HTML → PDF (via Tauri) or Print       │
└──────────────────────────────────────────────────────────┘

How It Works

1. A PrintTemplate record stores the Vue HTML template code, the target document type, and the page dimensions
2. When you click Print or Save as PDF on a document, NkapBooks:
   • Loads the appropriate template (default or custom)
   • Fetches the document data and print settings
   • Compiles the template using the Vue compiler
   • Renders the template with the document data injected as props
   • Generates the final HTML with all CSS styles
   • Sends the HTML to the Tauri backend for PDF generation or printing

Accessing Print Templates

12.1 Print Templates

A Print Template (PrintTemplate) is a document that stores the HTML/CSS layout used to render printable versions of business documents.

PrintTemplate Schema

Template Types

Each template is associated with a specific document type. The available types are:

Built-in vs Custom Templates

Creating a Custom Template

There are three ways to create a custom template:

1. Duplicate an Existing Template

1. Open an existing template in the Template Builder
2. Click the ⋮ Actions menu → Duplicate
3. The duplicate is created with isCustom: true and opens for editing
4. Rename the template and customize the layout

2. Create from Scratch

1. Navigate to Setup → Print Templates
2. Click + New Print Template
3. Enter a Template Name
4. Select the Template Type (document type)
5. The editor opens with a base starter template
6. Write your custom HTML/CSS/Vue code

3. Import a Template File

1. Open the Template Builder for any custom template
2. Click ⋮ Actions → Select Template File
3. Choose an .html file from your computer
4. The file contents are loaded into the editor

List View

The Print Template list view shows:

Clicking a template navigates to the Template Builder at /template-builder/:name.

12.2 Template Builder

The Template Builder is a full-featured template editing environment that combines a live preview, code editor, and variable reference panel in a single page.

Layout

The Template Builder page is divided into three main sections:

┌──────────────────────────────────────────────────────────┐
│  Header: Template Name | Save | Print | PDF | Actions ▼  │
├──────────────────────┬───────────────────────────────────┤
│                      │                                    │
│   Live Preview       │   Code Editor                     │
│   (Scaled paper)     │   (Vue/HTML/CSS)                  │
│                      │                                    │
│   Display Doc        │   ─────────────────────────────── │
│   Selector           │   Keyboard Shortcuts              │
│                      │   ─────────────────────────────── │
│   Scale Slider       │   Key Hints Panel                 │
│                      │   (Collapsible)                   │
│                      │                                    │
└──────────────────────┴───────────────────────────────────┘

Header Actions

Actions Menu

Live Preview Panel (Left)

The left panel shows a scaled paper preview that renders the template in real-time as you edit the code:

The preview automatically picks the most recent non-cancelled document of the template's type as the initial display document. You can change this to any document using the Link selector.

Code Editor (Right)

The code editor is built on CodeMirror 6 and provides:

The autocomplete system knows all available template variables and provides suggestions as you type inside Vue template expressions ({{ }} and v-bind attributes).

Edit Mode

The Template Builder has two display modes:

Toggle between modes using the Edit Mode button. When entering edit mode:

• The sidebar is hidden to maximize screen space
• The scale is automatically adjusted to fit the preview optimally
• A toast notification confirms the mode change

Apply changes with Ctrl+Enter to see the preview update.

Key Hints Panel

The Key Hints panel (toggle with the hints button) shows all available template variables organized hierarchically:

Each variable is displayed with its key path and current value type (string, object, or array). Click on collapsible items to expand nested objects and arrays.

Page Size Configuration

The Set Print Size dialog supports pre-defined and custom page sizes:

Template Syntax

Templates use Vue 3 template syntax with three injected props:

Example template structure:

<main class="h-full w-full bg-white">
  <header class="p-4 flex justify-between border-b">
    <h2 class="font-semibold text-2xl" :style="{ color: print.color }">
      {{ print.companyName }}
    </h2>
    <h2 class="font-semibold text-2xl">
      {{ doc.name }}
    </h2>
  </header>

  <div class="p-4">
    <!-- Your template content here -->
  </div>
</main>

Template Compilation Errors

If your template has syntax errors, the preview panel shows a red error screen with:

Common errors include:

• Missing closing tags
• Invalid Vue directive syntax
• Referencing undefined variables (shows as "Invalid Key Error" with hint to check Key Hints)

12.3 Print Settings

The Print Settings (PrintSettings) schema is a singleton document that controls the global appearance of all printed documents. It is configured from Settings → Print tab.

PrintSettings Schema

Default Section

Contacts Section

Customizations Section

Available Colors

The color picker provides these pre-defined options:

You can also enter any custom hex color value.

How Print Settings Are Used

Print settings values are injected into every template via the print prop. Templates access them as:

Additionally, key fields from AccountingSettings are merged into the print object:

12.4 Supported Print Documents

The following document types support printing and PDF export. Each type has its own set of template variables reflecting its schema fields.

Transactional Documents

Inventory Documents

POS Documents

Default Template Assignments

Each document type can have a default print template assigned in Settings → Defaults:

12.5 Template Variables

When a template is rendered, NkapBooks collects data from the document, print settings, and related records, then injects it as two top-level props: doc and print.

Document Variables (doc.*)

The exact variables available depend on the document type, but common fields include:

Common Document Fields

Financial Fields (Invoices, Payments)

Items Array (Invoices, Quotes)

Tax Summary Array

Party Information

Payment Details

POS Session Variables

POS Session templates receive additional specialized variables:

Print Variables (print.*)

Translation Function (t)

Templates can use the t function for internationalized strings:

<p>{{ t`Invoice` }}</p>
<p>{{ t`Amount Due` }}: {{ doc.outstandingAmount }}</p>

This ensures templates work correctly regardless of the user's language setting.

12.6 PDF Export & Printing

NkapBooks uses the Tauri backend to generate PDFs and send documents to the system printer. Both operations work by converting the rendered template HTML into a complete standalone document.

PDF Export

When you click Save as PDF (or trigger it programmatically):

1. The template is rendered with document data in the preview panel
2. The rendered innerHTML is extracted from the preview container
3. A complete HTML document is constructed with all CSS styles embedded
4. A save dialog prompts for the file path (default name: document name + .pdf)
5. The HTML is sent to the Tauri backend via the makePDF command
6. The backend generates the PDF using the specified width and height
7. A success toast is shown with an option to open the containing folder

Direct Printing

When you click Print:

1. The same rendering and HTML construction process occurs
2. Instead of saving a file, the HTML is sent to the Tauri printDocument command
3. The system print dialog appears for printer selection and settings
4. A success or failure toast is shown

HTML Document Construction

The print document includes:

The print CSS ensures clean output:

Timeout Protection

Both PDF generation and printing have timeout protection:

Loading Feedback

While generating a PDF or printing, a loading toast is displayed:

Printing from the Template Builder

The Template Builder provides both Print and PDF buttons in the header:

1. PDF Button — Exports the current preview as a PDF file
2. Print Button — Sends the current preview to the system printer

Both use the currently selected Display Doc for data and the current template code for layout.

12.7 Default Templates

NkapBooks ships with built-in default templates for the most common document types. These templates are automatically created and updated during the setup process.

Template File Naming Convention

Built-in template files follow this naming pattern:

TemplateName[.SchemaName].template.html

When no schema name is specified in the file name, the template is automatically created for three default types: Sales Invoice, Sales Quote, and Purchase Invoice.

Template Update Behavior

During application setup or upgrade, the updatePrintTemplates() function:

1. Fetches all template files from the application resources
2. Compares the file modification dates with the database records
3. Updates only templates where the file is newer than the database record
4. Never modifies custom templates (isCustom: true)

This means:

• Built-in templates are kept up-to-date automatically
• Your custom templates are never overwritten
• New templates added in updates appear automatically

Base Starter Template

When creating a new custom template, the editor starts with a base starter template:

<main class="h-full w-full bg-white">
  <header class="p-4 flex justify-between border-b">
    <h2
      class="font-semibold text-2xl"
      :style="{ color: print.color }"
    >
      {{ print.companyName }}
    </h2>
    <h2 class="font-semibold text-2xl">
      {{ doc.name }}
    </h2>
  </header>

  <div class="p-4 text-gray-600">
    Edit the code in the Template Editor on the right
    to create your own personalized custom template.
  </div>
</main>

This provides a minimal starting point that demonstrates the basic template structure with doc and print variable usage.

Template Resources

Built-in template files are bundled with the application in the templates/ resource directory (configured in tauri.conf.json). The POS print width from Print Settings is passed to the template loader so POS-specific templates can adapt their layout width.

12.8 Workflow & Best Practices

Recommended Workflow

Template Design Tips

Exporting and Sharing Templates

Troubleshooting