7/10/2025 Pug Template

Development
Guidelines for
Forms
Detailed Documents with
Examples

Forms Development Team

DIONA
Index
1. Introduction

 1.1 Purpose of This Document

 1.2 Prerequisites

 1.3 Configure Manager Setup

o 1.3.1 Accessing Configure Manager

o 1.3.2 Form Configuration Steps

 1.4 Document Scope

 1.5 Key Principles

 1.6 Development Workflow Overview

2. Project Structure and File Organization

 2.1 Directory Structure

 2.2 File Naming Conventions

o 2.2.1 Template Files

o 2.2.2 Naming Rules

 2.3 File Purpose and Content

o 2.3.1 Core Files Required for Every Form

o 2.3.2 Optional Files

 2.4 When to Use Common Files

o 2.4.1 Common Files Usage Guidelines

o 2.4.2 Benefits of Individual Form Files

 2.5 File Dependencies and Relationships

o 2.5.1 Required Dependencies

o 2.5.2 Dependency Chain

 2.6 File Upload and Management in Configure Manager

o 2.6.1 Upload Sequence

o 2.6.2 File Validation in Configure Manager

  2.7 File Content Organization

o 2.7.1 Main Template Structure

o 2.7.2 Form Mixins Structure

o 2.7.3 Translation File Structure

o 2.7.4 HTML to PDF Options Structure

 2.8 Best Practices for File Organization

o 2.8.1 Keep Forms Self-Contained

o 2.8.2 Use Descriptive File Names

o 2.8.3 Documentation Within Files

3. Understanding ODK Forms and Data Binding

 3.1 What is ODK and Why It Matters

o 3.1.1 ODK Overview

o 3.1.2 The Connection Between ODK and Pug

 3.2 ODK Form Structure Deep Dive

o 3.2.1 Basic ODK Form Anatomy

o 3.2.2 Real-World Example

o 3.2.3 How This Translates to Pug Data Access

 3.3 Data Types and Their Handling

o 3.3.1 Text Fields

o 3.3.2 Date Fields

o 3.3.3 Boolean/Choice Fields

o 3.3.4 Calculated Fields

 3.4 Working with Repeating Groups (Arrays)

o 3.4.1 Understanding Repeating Groups

o 3.4.2 The Challenge with Repeating Groups

o 3.4.3 Proper Handling Pattern

o 3.4.4 Why This Pattern Is Essential

 3.5 Critical Data Binding Rules

 o 3.5.1 Rule #1: Exact Name Matching

o 3.5.2 Rule #2: Follow Group Structure

o 3.5.3 Rule #3: Handle Missing Data Gracefully

 3.6 Common ODK Form Patterns

o 3.6.1 User Information Pattern

o 3.6.2 Claim Information Pattern

o 3.6.3 Declaration Pattern

 3.7 Debugging Data Binding Issues

o 3.7.1 Common Debugging Techniques

o 3.7.2 Common Error Messages and Solutions

 3.8 Best Practices for Data Binding

o 3.8.1 Always Use Defensive Programming

o 3.8.2 Use Meaningful Variable Names

o 3.8.3 Document Complex Data Structures

o 3.8.4 Test with Various Data Scenarios

4. Common Mixins Reference

 4.1 What Are Mixins and Why Use Them

o 4.1.1 Understanding Mixins

o 4.1.2 Basic Mixin Syntax

o 4.1.3 Mixins vs Functions

 4.2 Essential Utility Functions

o 4.2.1 getText Function

o 4.2.2 formatDate Function

o 4.2.3 phone Function

o 4.2.4 money Function

 4.3 Essential Layout Mixins

o 4.3.1 Header Mixin

o 4.3.2 Privacy Mixin

  4.4 Checkbox Mixins

o 4.4.1 Simple Checkbox Mixin

o 4.4.2 Advanced Checkbox Mixin

 4.5 Table Rendering Mixins

o 4.5.1 Generic Table Row Mixin

o 4.5.2 Blank Row Mixin

 4.6 Specialized Form Mixins

o 4.6.1 Signature Block Mixin

o 4.6.2 Address Display Mixin

 4.7 Conditional Content Mixins

o 4.7.1 Section Header Mixin

o 4.7.2 Conditional Text Mixin

 4.8 Best Practices for Mixin Development

o 4.8.1 Mixin Design Principles

o 4.8.2 Error Handling in Mixins

o 4.8.3 Documentation Standards

 4.9 Common Mixin Patterns

o 4.9.1 Repeating Group Pattern

o 4.9.2 Form Section Pattern

5. Header and Footer Implementation

 5.1 Understanding Header and Footer Architecture

o 5.1.1 Purpose and Importance

o 5.1.2 Types of Header/Footer Implementation

 5.2 Mixin-Based Header Implementation

o 5.2.1 Complete Header Mixin Structure

o 5.2.2 Header Usage Examples

o 5.2.3 Header Responsive Design Considerations

 5.3 Mixin-Based Footer Implementation

 o 5.3.1 Complete Footer Mixin Structure

o 5.3.2 Footer with JavaScript Enhancement

 5.4 External HTML Header Implementation

o 5.4.1 When to Use External Headers

o 5.4.2 Referencing External Headers in PDF Options

 5.5 Header and Footer Best Practices

o 5.5.1 Content Guidelines

o 5.5.2 Design Principles

o 5.5.3 Accessibility Considerations

 5.6 Troubleshooting Header and Footer Issues

o 5.6.1 Common Problems and Solutions

o 5.6.2 Testing Headers and Footers

6. Styling Guidelines and CSS Standards

 6.1 CSS Architecture and Organization

o 6.1.1 CSS Structure in Pug Templates

o 6.1.2 CSS Organization Principles

 6.2 Typography Standards

o 6.2.1 Font Family Hierarchy

o 6.2.2 Font Size Guidelines

o 6.2.3 Line Height and Spacing

 6.3 Color Scheme and Usage

o 6.3.1 Standard Color Palette

o 6.3.2 Color Usage Rules

 6.4 Layout and Spacing Standards

o 6.4.1 Container and Section Spacing

o 6.4.2 Page Break Management

o 6.4.3 Responsive Width Management

 6.5 Table Styling Standards

 o 6.5.1 Standard Table Styles

o 6.5.2 Specialized Table Types

o 6.5.3 Table Responsive Behavior

 6.6 Form Element Styling

o 6.6.1 Checkbox and Input Styling

o 6.6.2 Signature and Declaration Blocks

 6.7 Specialized Component Styles

o 6.7.1 Header Component Styles

o 6.7.2 Footer Component Styles

 6.8 Utility Classes

o 6.8.1 Text Utility Classes

o 6.8.2 Spacing Utility Classes

o 6.8.3 Layout Utility Classes

 6.9 Responsive Design Considerations

o 6.9.1 Flexible Layouts

 6.10 CSS Best Practices and Standards

o 6.10.1 Code Organization Standards

o 6.10.2 Performance Considerations

o 6.10.3 Maintenance Guidelines

7. Data Rendering Patterns

 7.1 Understanding Data Rendering Fundamentals

o 7.1.1 What is Data Rendering?

o 7.1.2 Core Rendering Principles

 7.2 Text Data Rendering Patterns

 7.3 Date Rendering Patterns

 7.4 Monetary Value Rendering Patterns

 7.5 Boolean and Choice Data Rendering

 7.6 Array and Repeating Group Patterns

  7.7 Complex Data Rendering Patterns

 7.8 Error Handling and Data Validation Patterns

 7.9 Performance Optimization Patterns

8. Internationalization and Translation

 8.1 Understanding Internationalization in Forms

o 8.1.1 What is Internationalization (i18n)?

o 8.1.2 Key Components of Internationalization

 8.2 Translation File Structure and Management

o 8.2.1 Translation File Format

 8.3 The getText Function Implementation

9. Common Patterns and Examples

 9.1 Quick Reference Template Structure

 9.2 Data Display Patterns

 9.3 Table Patterns

 9.4 Form Section Patterns

 9.5 Validation Patterns

 9.6 Layout Patterns

 9.7 Conditional Content Patterns

 9.8 Error Handling Patterns

 9.9 Performance Patterns

 9.10 Accessibility Patterns

 9.11 Quick Reference Checklist

 9.12 Common Mistakes to Avoid

1. Introduction
1.1 Purpose of This Document

This comprehensive guide provides developers with the necessary knowledge and standards for creating
Pug templates for organizational forms. The document covers everything from basic Pug syntax to
advanced form rendering techniques specific to form-based applications.

1.2 Prerequisites

Before using this guide, developers should have:

 Basic understanding of HTML, CSS, and JavaScript

 Familiarity with template engines

 Knowledge of XLS form structures

 Understanding of PDF generation concepts

 Access to the Configure Manager system

1.3 Configure Manager Setup

Before beginning Pug template development, developers must properly configure the form in the
Configure Manager:

1.3.1 Accessing Configure Manager

1. Log into the Configure Manager system

2. Navigate to the Forms tab in the main interface

3. Locate your target form in the forms list

1.3.2 Form Configuration Steps

1. View Form Details: Click the "View" button under the Actions column for your specific form

2. Set PDF Configuration: In the form view page, locate the Details section and click on “Set PDF”
option to set the pdf then upload the Main pug template file there naming ‘[Link]’

3. Upload Required Files: In the Files section of the view page, upload all necessary template files:

o Translation file ([Link])

o PDF options file ([Link])

o Any additional assets (images, stylesheets)

Important: All template files must be properly uploaded and configured in the Configure Manager before
the form can generate PDFs correctly. The system will not function without this initial setup.

1.4 Document Scope

This guide covers:

 Manual Pug template development (not automated generation)

 Organization-specific form requirements

 Data binding from ODK forms

 Styling and layout standards

 Internationalization requirements

 PDF generation optimization

 Configure Manager integration workflows

1.5 Key Principles

 Consistency: All forms must follow the same visual and structural patterns

 Accessibility: Templates must be screen-reader-friendly and WCAG compliant

 Maintainability: Code should be modular, well-documented, and reusable

 Performance: Templates should generate PDFs e iciently

 Multilingual Support: All forms must support multiple languages as required

 System Integration: Templates must be properly configured in the Configure Manager

1.6 Development Workflow Overview

1. Analysis: Study the ODK form structure and requirements

2. Configuration: Set up form in Configure Manager

3. Development: Create Pug templates following guidelines

4. Testing: Validate templates with sample data

5. Deployment: Upload files through Configure Manager

6. Validation: Confirm PDF generation works correctly

2. Project Structure and File Organization
2.1 Directory Structure

Understanding the proper file organization is crucial for maintaining consistency and enabling e icient
development workflows.

2.2 File Naming Conventions

2.2.1 Template Files

Consistent naming ensures easy identification and prevents conflicts:

 Main Template: {form-name}.pug (lowercase with hyphens)

o Example: [Link]

o Example: [Link]

o Example: [Link]

 Form Mixins: {form-name}-[Link]

o Example: [Link]

o Example: [Link]

 PDF Options: {form-name}-[Link]

o Example: [Link]

o Example: [Link]

 Translation File: {form-name}-[Link] (if applicable)

o Example: [Link]

o Example: [Link]

 Assets: [Link] (or appropriate image format)

2.2.2 Naming Rules

 Use Pascal Case letters for all file names

 Use hyphens to separate words in form names

  Use hyphens to separate the form name from the file type su ix

 Avoid special characters, spaces, or non-ASCII characters

 Keep names descriptive but concise

2.3 File Purpose and Content

2.3.1 Core Files Required for Every Form

1. Main Template ([Link])

 Contains the complete form layout and structure

 Includes data binding from ODK forms

 Implements styling and page layout

 Must include mixins from the corresponding mixins file

2. Form Mixins ([Link])

 Contains reusable components specific to this form

 Includes utility functions (phone formatting, date formatting, etc.)

 Houses custom mixins for repetitive content blocks

 Contains common functions like getText() for translations

3. PDF Options ([Link])

 Controls PDF generation parameters

 Defines page margins, size, and layout

 Configures dynamic variable replacement

 Sets encoding and rendering options

4. Logo ([Link])

 Organization logo for form headers

 Should be optimized for PDF rendering

 Maintain consistent dimensions across forms

2.3.2 Optional Files

Translation File ([Link])

 Required only for multilingual forms

 Contains text translations for di erent languages

 Uses JSON structure for language mapping

  Include only when form needs translation support

2.4 When to Use Common Files

2.4.1 Common Files Usage Guidelines

Use common files ([Link], [Link], [Link]) ONLY when:

 You have multiple forms that share identical components

 The same mixins or functions are used across di erent forms

 Header/footer layouts are the same across forms

 You want to maintain consistency across many forms

Use individual form files when:

 Each form has unique requirements

 Forms have di erent layouts or styling needs

 You want to keep forms completely independent

 Development team prefers isolated, self-contained forms

2.4.2 Benefits of Individual Form Files

 Self-contained: Each form is completely independent

 Easier maintenance: Changes to one form don't a ect others

 Simpler deployment: Upload only the files needed for each form

 Reduced complexity: No need to track dependencies across forms

 Clearer debugging: All code for a form is in its specific files

2.5 File Dependencies and Relationships

2.5.1 Required Dependencies

Every form template must follow this structure:

1. Form mixins at the top

2. Document structure
3. Header implementation
4. Main body
5. Footer or Privacy notice (if Applicable)

Note: While referencing any file {{base}} should be used otherwise that file will not be referred to
the pug file.
❌ "footerHtml": "./[Link]"

✅ "footerHtml": "{{base}}/[Link]"
2.5.2 Dependency Chain

Understanding the relationship between files:

1. Main Template ([Link])

o Includes: [Link]

o References: Translation keys (if translations are used)

o Uses: Data from ODK forms

o References: [Link] for header

2. Form Mixins ([Link])

o Contains: All reusable components for this form

o Includes: Utility functions and custom mixins

o Provides: getText() function for translations

3. Translation File ([Link]) - if applicable

o Provides: Multilingual text content

o Format: JSON structure

o Used by: getText() function in mixins

4. PDF Options ([Link])

 o Controls: PDF generation parameters

o Configures: Page layout and margins

o May reference: Footer template if needed

2.6 File Upload and Management in Configure Manager

2.6.1 Upload Sequence

Follow this specific order when uploading files to Configure Manager:

1. Upload Assets First:

o [Link]

2. Upload Configuration Files:

o [Link] (if applicable)

o [Link]

3. Upload Template Files:

o [Link]

o [Link] (upload last to ensure all dependencies are available)

2.6.2 File Validation in Configure Manager

Before uploading, ensure:

 All file names follow the naming conventions

 File sizes are within system limits

 File encoding is UTF-8 (especially for translation files)

 No syntax errors in Pug templates

 JSON structure is valid in translation files (if applicable)

2.7 File Content Organization

2.7.1 Main Template Structure ([Link])

2.7.2 Form Mixins Structure ([Link])

2.7.3 Translation File Structure (if applicable)

2.7.4 HTML to PDF Options Structure ([Link])

2.7.1

2.7.2
2.7.3

2.7.4
Key Configuration Options Explained:

 Margins: Control space around page content (in millimeters)

 pageSize: Paper size (LETTER, A4, LEGAL, etc.)

 orientation: Portrait or Landscape

 disable-smart-shrinking: Prevents automatic content scaling

 encoding: Character encoding (UTF-8 recommended)

 image-quality: Image compression quality (0-100)

 image-dpi: Image resolution for printing

 minimum-font-size: Smallest readable font size

 replace: Dynamic variable replacement in templates

 footerHtml/headerHtml: External header/footer templates (optional)

Common Configuration Variations:

For forms with complex footers:

"marginBottom": "30mm",

"footerHtml": "{{base}}/[Link]"

For forms requiring high-quality images:

"image-quality": 100,

"image-dpi": 600

For landscape forms:

"pageSize": "LETTER",

"orientation": "Landscape",

"marginTop": "15mm",

"marginBottom": "15mm"

}
2.8 Best Practices for File Organization

2.8.1 Keep Forms Self-Contained

 Each form should be completely independent

 Include all necessary functions in the form's mixins file

 Avoid dependencies on external files unless necessary

2.8.2 Use Descriptive File Names

 Form names should clearly indicate the form's purpose

 Avoid abbreviations that might be unclear to other developers

 Use consistent naming patterns across all forms in your project

2.8.3 Documentation Within Files

 Include header comments in all files explaining their purpose

 Document any complex functions or unusual implementations

 Note any dependencies or special requirements

3. Understanding ODK Forms and Data Binding
3.1 What is ODK and Why It Matters

3.1.1 ODK Overview

ODK (Open Data Kit) is a framework for building data collection applications. In our context, ODK forms
define the structure and validation rules for the data that users fill out in web or mobile applications.
Understanding this structure is critical for Pug template development because:

 Data Source: All the information displayed in your PDF comes from ODK forms

 Field Names: You must use exact field names from the ODK form to access data

 Data Types: Di erent field types require di erent handling in templates

 Validation: ODK defines what data is required, optional, or calculated

3.1.2 The Connection Between ODK and Pug

Think of it this way:

 ODK Form: Defines what data is collected (like a database schema)

 User Input: Actual data entered by users

 Pug Template: Takes that data and formats it into a readable PDF

[User fills form] → [ODK processes data] → [Pug template renders PDF]

3.2 ODK Form Structure Deep Dive

3.2.1 Basic ODK Form Anatomy

Every ODK form has this XML structure:

3.2.2 Real-World Example

Let's examine a contact form structure:

3.2.3 How This Translates to Pug Data Access

In your Pug template, you access this data using the exact same structure:

3.3 Data Types and Their Handling

3.3.1 Text Fields

ODK Definition:
<firstName/>
<lastName/>
<comments/>
Pug Usage:

Important Notes:

 Always provide fallbacks for empty values

 Use || '' for table cells to avoid undefined values

 Consider text length for PDF layout

3.3.2 Date Fields

ODK Definition:

<incidentDate/>

<formatted_incidentDate/>

Pug Usage:

Why Formatted Dates Matter:

 ODK often provides both raw dates (incidentDate) and formatted dates (formatted_incidentDate)

 Formatted dates are already in the correct format for display

 Always prefer formatted dates over raw dates

3.3.3 Boolean/Choice Fields

ODK Definition:

<requestCallback>yes</requestCallback>

<termsAccepted>no</termsAccepted>

Pug Usage:

Important Notes:

 ODK boolean values are typically stored as strings ('yes'/'no')

 Always use strict equality (===) for comparisons

 Use getText() for translatable yes/no values

3.3.4 Calculated Fields

ODK Definition:

<fullName calculate="concat(firstName, ' ', lastName)"/>

<totalAmount calculate="sum(expense1, expense2)"/>

Pug Usage:
3.4 Working with Repeating Groups (Arrays)

3.4.1 Understanding Repeating Groups

Repeating groups allow users to enter multiple instances of the same data structure (like multiple
expenses, multiple addresses, etc.).

ODK Definition:

3.4.2 The Challenge with Repeating Groups

Repeating groups can exist in three states:

1. No data: User didn't add any entries

2. Single entry: User added exactly one entry

3. Multiple entries: User added multiple entries

This is crucial because:

 Single entries are objects: [Link]

 Multiple entries are arrays: [Link][0].[Link]

3.4.3 Proper Handling Pattern

Always use this pattern for repeating groups:

3.4.4 Why This Pattern Is Essential

Wrong approach (will break):

Right approach (handles all cases):

3.5 Critical Data Binding Rules

3.5.1 Rule #1: Exact Name Matching

This is the most important rule: Field names in your Pug template must exactly match the ODK form
field names.

Example from ODK:

<claimNumberGroup>
<claimNumber/>
<pdfClaimNumber/>
</claimNumberGroup>

Correct Pug usage:

[Link]= [Link]
[Link]= [Link]

Wrong (will not work):

[Link]= [Link] // Wrong group name

[Link]= [Link] // Wrong field name
[Link]= [Link] // Wrong field name

3.5.2 Rule #2: Follow Group Structure

ODK groups must be respected in Pug:

If ODK has:

<workerDeclarationGroup>
<workerSignature/>
<workerSignDate/>
</workerDeclarationGroup>

Pug must use:

[Link]
[Link]

Not:

[Link] // Missing group

[Link] // Wrong group name

3.5.3 Rule #3: Handle Missing Data Gracefully

Always assume data might be missing:

3.6 Common ODK Form Patterns

3.6.1 User Information Pattern

Almost every form has this structure:

Standard Pug usage:

[Link]= data.firstName + ' ' + [Link]

Or
[Link]= [Link]
3.6.2 Claim Information Pattern

Common in organizational forms:

Pug usage:

[Link]= [Link] || [Link]

3.6.3 Declaration Pattern

Standard for forms requiring user confirmation:

Pug usage:

3.7 Debugging Data Binding Issues

3.7.1 Common Debugging Techniques

1. Output Raw Data (Development Only):

if debugMode
pre= [Link](data, null, 2)

2. Check Individual Fields:

if debugMode
div Debug:
div Field exists: #{[Link].firstName ? 'Yes' : 'No'}
div Field value: #{[Link].firstName}
div Field type: #{typeof [Link].firstName}
3. Test Data Paths:

if debugMode
div personalInfo exists: #{[Link] ? 'Yes' : 'No'}
div firstName exists: #{[Link] && [Link].firstName ? 'Yes' : 'No'}

3.7.2 Common Error Messages and Solutions

Error: "Cannot read property 'fieldName' of undefined"

 Cause: Trying to access a field in a group that doesn't exist

 Solution: Check group existence first

Error: "Cannot read property '0' of undefined"

 Cause: Treating a single repeating group entry as an array

 Solution: Use the proper repeating group pattern shown earlier

Error: Field shows as blank in PDF

 Cause: Field name doesn't match ODK form exactly

 Solution: Compare field names character by character with ODK form

3.8 Best Practices for Data Binding

3.8.1 Always Use Defensive Programming

if [Link] && [Link].field

[Link]= [Link].field
else
[Link]= 'Not provided'

3.8.2 Use Meaningful Variable Names

3.8.3 Document Complex Data Structures

3.8.4 Test with Various Data Scenarios

Always test your templates with:

 Completely filled forms

 Forms with repeating groups (single and multiple entries)

 Forms with special characters or long text

4. Common Mixins Reference
4.1 What Are Mixins and Why Use Them

4.1.1 Understanding Mixins

Mixins in Pug are reusable blocks of code that can be called multiple times throughout your template.
Think of them as functions that generate HTML content. They will help you:

 Avoid repetition: Write once, use many times

 Maintain consistency: Same structure across all instances

 Simplify updates: Change in one place a ects all users

 Improve readability: Complex HTML becomes simple mixin calls

4.1.2 Basic Mixin Syntax

This generates:

<p>Hello, John!</p>
<p>Hello, Jane!</p>

4.1.3 Mixins vs Functions

Mixins generate HTML, while functions return values:

4.2 Essential Utility Functions

4.2.1 getText Function (Translation Support)

Purpose: Retrieves translated text based on user Location: Always in mixins file

Usage Examples:

4.2.2 formatDate Function

Purpose: Formats dates according to user locale Location: Always in mixins file
Usage Examples:

4.2.3 phone Function

Purpose: Formats phone numbers consistently Location: Always in mixins file

Usage Examples:

4.2.4 money Function

Purpose: Formats monetary values consistently Location: Always in mixins file

Usage Examples:

4.3 Essential Layout Mixins

4.3.1 Header Mixin

Purpose: Creates consistent header across all forms Usage: Required on every form

Usage Examples:
4.3.2 Privacy Mixin

Purpose: Creates consistent privacy notice and consent checkbox Usage: Required on forms that
collect personal information

Usage Examples:

4.4 Checkbox Mixins

4.4.1 Simple Checkbox Mixin

Purpose: Creates basic checkbox with text Usage: For simple yes/no questions
Usage Examples:

4.4.2 Advanced Checkbox Mixin

Purpose: Creates checkbox with enhanced formatting and styling options Usage: For complex
statements or checkboxes requiring special formatting

Usage Examples:
4.5 Table Rendering Mixins

4.5.1 Generic Table Row Mixin

Purpose: Creates consistent table rows for data display Usage: For displaying structured data in tables

Usage Examples:

4.5.2 Blank Row Mixin

Purpose: Creates empty table rows for consistent spacing Usage: When no data exists but table
structure must be maintained
Usage Examples:

4.6 Specialized Form Mixins

4.6.1 Signature Block Mixin

Purpose: Creates consistent signature and date sections Usage: For declaration and signature areas

Usage Examples:

4.6.2 Address Display Mixin

Purpose: Formats address consistently

Usage: For displaying addresses in forms

Usage Examples:

4.7 Conditional Content Mixins

4.7.1 Section Header Mixin

Purpose: Creates consistent section headers with optional styling

Usage: For organizing form content into sections

Usage Examples:

4.7.2 Conditional Text Mixin

Purpose: Displays text based on conditions

Usage: For showing di erent content based on data values

Usage Examples:

4.8 Best Practices for Mixin Development

4.8.1 Mixin Design Principles

1. Single Responsibility: Each mixin should have one clear purpose

2. Flexible Parameters: Use options objects for flexibility

3. Default Values: Always provide sensible defaults

4.8.2 Error Handling in Mixins

Always handle missing data gracefully:

4.8.3 Documentation Standards

Document complex mixins with comments:

PARAMETERS:

 data: Array of objects or single object

 columns: Array of column definitions
 options: Optional configuration object

EXAMPLE: +renderDataTable(expenses, expenseColumns, {showHeaders: true})

mixin renderDataTable(data, columns, options = {})

// Implementation here

4.9 Common Mixin Patterns

4.9.1 Repeating Group Pattern

Use this pattern consistently for repeating data:

4.9.2 Form Section Pattern

Use this pattern for consistent form sections:

5. Header and Footer Implementation
5.1 Understanding Header and Footer Architecture

5.1.1 Purpose and Importance

Headers and footers provide essential branding, navigation, and document information across all forms.
They ensure:

 Brand Consistency: Every form displays the same organizational branding

 Legal Compliance: Required disclaimers and contact information

 Document Tracking: Page numbers, submission dates, and reference numbers

 Professional Appearance: Polished, o icial document presentation

5.1.2 Types of Header/Footer Implementation

You can implement headers and footers in two ways:

Method 1: Mixin-Based (Recommended for individual forms)

 Header and footer are mixins in your form's mixins file

 Complete control over styling and content

 Self-contained within each form

 Easier to customize per form

Method 2: External HTML Files

 Separate HTML files for header and footer

 Referenced in PDF generation options

 Shared across multiple forms

 Better for large-scale consistency

5.2 Mixin-Based Header Implementation

5.2.1 Complete Header Mixin Structure (Example)

Location: In your [Link] file

5.2.2 Header Usage Examples

1. Basic Header:

+header
2. Header Without Claim Number:

+header({hideClaimNumber: true})

3. Incident Report Header:

+header({incidentReportStyle: true})

4. Header with Custom Title:

+header({customTitle: 'Special Investigation Report'})

5. Header with Multiple Options:

+header({

hideClaimNumber: true,

incidentReportStyle: true,

customTitle: 'Emergency Response Form'

})

5.2.3 Header Responsive Design Considerations

Flexible Logo Sizing:

Text Wrapping for Contact Information:

Note – Do not forget to initialize the getText() function otherwise it might lead to a runtime error.

5.3 Mixin-Based Footer Implementation

5.3.1 Complete Footer Mixin Structure

Location: In your [Link] file

5.3.2 Footer with JavaScript Enhancement

For dynamic content like timestamps and page numbers:

5.4 External HTML Header Implementation

5.4.1 When to Use External Headers

Use external HTML headers when:

 Multiple forms share identical headers

 You need advanced JavaScript functionality

 Headers are managed centrally by a di erent team

 PDF generation system requires external references

5.4.2 Referencing External Headers in PDF Options

File: [Link]
5.5 Header and Footer Best Practices

5.5.1 Content Guidelines

Header Content Should include:

 Organization logo and branding (When applicable)

 Contact information (address, phone, website)

 Document title/name

 Claim or reference numbers (when applicable)

 Form prefix or code (when applicable)

Footer Content Should Include:

 Worker/user identification (When required)

 Submission timestamp (When required)

 Page numbering

 Legal disclaimers (if required)

5.5.2 Design Principles

Consistency:

Responsive Design:

Professional Appearance:

5.5.3 Accessibility Considerations

Alt Text for Images:

Semantic HTML Structure:

5.6 Troubleshooting Header and Footer Issues

5.6.1 Common Problems and Solutions

Logo Not Displaying:

 Check file path: {{base}}/[Link]

 Verify logo file is uploaded to Configure Manager

 Ensure image format is supported (PNG, JPG recommended)

 Check image file size (keep under 500KB for performance)

Text Overlapping:

Page Numbers Not Working:

 Ensure PDF generation system supports page number variables

 Check that footer is properly referenced in PDF options

 Verify JavaScript is enabled in PDF generation

Multilingual Text Issues:

5.6.2 Testing Headers and Footers

Visual Testing:

1. Generate PDF with minimal data

2. Generate PDF with maximum data

3. Test with di erent page counts

4. Verify multilingual content

5. Check on di erent paper sizes

Content Testing:

1. Verify all dynamic content populates correctly

2. Test with missing claim numbers

3. Test with long document titles

4. Verify date formatting in di erent locales

6. Styling Guidelines and CSS Standards
6.1 CSS Architecture and Organization

6.1.1 CSS Structure in Pug Templates

All CSS styling in Pug templates should be contained within the style. block in the document head. This
ensures:

 Self-contained forms: No external CSS dependencies

 PDF compatibility: All styles embedded for proper rendering

 Easy maintenance: All styles visible in one place

 Performance: No additional HTTP requests for stylesheets

Basic CSS Structure:

6.1.2 CSS Organization Principles

Group Related Styles:

For increasing readability of the code and future debugging follow the organized group in order to
maintain consistency over the file.
Use Consistent Naming:

6.2 Typography Standards

6.2.1 Font Family Hierarchy

Establish a clear font hierarchy for di erent content types:

6.2.2 Font Size Guidelines

Establish a clear size hierarchy:

6.2.3 Line Height and Spacing

Proper spacing improves readability:

6.3 Color Scheme and Usage

6.3.1 Standard Color Palette

Define a consistent color palette:

6.3.2 Color Usage Rules

User Data (Answers):

.answer {

color: #1f497d; /* Blue for all user-entered data */

Static Labels and Text:

.label, .static-text {

color: #000000; /* Black for labels and static content */

Borders and Lines:

Status and Emphasis:

6.4 Layout and Spacing Standards

6.4.1 Container and Section Spacing

Establish consistent spacing patterns:

6.4.2 Page Break Management

Control page breaks for better PDF layout:

6.4.2 Page Break Management

Control page breaks for better PDF layout:

6.4.3 Responsive Width Management

Flexible layouts that work across page sizes:

6.5 Table Styling Standards

6.5.1 Standard Table Styles

Consistent table appearance across all forms:

6.5.2 Specialized Table Types

Data tables with specific requirements:

6.5.3 Table Responsive Behavior

Tables that work across di erent page sizes:

6.6 Form Element Styling

6.6.1 Checkbox and Input Styling

Consistent form element appearance:

6.6.2 Signature and Declaration Blocks

Professional signature area styling:

6.7 Specialized Component Styles

6.7.1 Header Component Styles

Consistent header styling:

6.7.2 Footer Component Styles

Professional footer styling:

6.8 Utility Classes

6.8.1 Text Utility Classes

Common text formatting utilities:

6.8.2 Spacing Utility Classes

Consistent spacing utilities:

6.8.3 Layout Utility Classes

Common layout helpers:

6.9 Responsive Design Considerations

6.9.1 Flexible Layouts

Layouts that adapt to di erent page sizes:

6.10 CSS Best Practices and Standards

6.10.1 Code Organization Standards

Consistent CSS structure:

6.10.2 Performance Considerations

E icient CSS for PDF generation:

6.10.3 Maintenance Guidelines

Code that's easy to maintain:

Use consistent naming conventions

.form-section { } Good: descriptive

.fs { } Bad: abbreviated

7. Data Rendering Patterns
7.1 Understanding Data Rendering Fundamentals

7.1.1 What is Data Rendering?

Data rendering is the process of taking raw data from ODK forms and converting it into formatted,
readable content in your PDF. This involves:

 Data Transformation: Converting raw values into display-ready formats

 Conditional Display: Showing or hiding content based on data values

 Error Handling: Managing missing, null, or invalid data gracefully

 Localization: Adapting content for di erent languages and regions

7.1.2 Core Rendering Principles

Always Assume Data Might Be Missing:

Use Consistent Patterns:

Separate Logic from Display:

7.2 Text Data Rendering Patterns

7.2.1 Simple Text Display

Pattern for basic text fields:

7.2.2 Text with Formatting Functions

Pattern for text that needs formatting:

7.2.3 Multi-line Text Rendering

Pattern for long text fields:

7.2.4 Text in Table Cells

Pattern for table text display:

7.3 Date Rendering Patterns

7.3.1 Standard Date Display

Pattern for consistent date formatting:

7.3.2 Date Range Display

Pattern for start/end date ranges:

7.3.3 Date in Tables

Pattern for table date display:

7.3.4 Relative Date Display

Pattern for showing time relationships:

7.4 Monetary Value Rendering Patterns

7.4.1 Standard Money Display

Pattern for consistent monetary formatting:

7.4.2 Money in Tables

Pattern for table monetary display:

7.4.3 Money Totals and Calculations

Pattern for calculated monetary values:

7.5 Boolean and Choice Data Rendering

7.5.1 Yes/No Display Patterns

Pattern for Boolean value display:

7.5.2 Checkbox Rendering Patterns

Pattern for checkbox display in PDFs:

7.5.3 Select/Dropdown Value Display

Pattern for dropdown selection display:

7.6 Array and Repeating Group Patterns

7.6.1 Standard Repeating Group Pattern

The universal pattern for handling repeating data:

Handling repeating data is complex in most cases but this pattern is very helpful in rendering the
repeating data into the pdf.
7.6.2 Conditional Repeating Groups

Pattern for arrays that depend on selections:

7.6.3 Nested Repeating Groups

Pattern for complex nested data structures:

7.7 Complex Data Rendering Patterns

7.7.1 Address Rendering

Pattern for structured address display:

7.7.2 Contact Information Rendering

Pattern for comprehensive contact display:

7.7.3 File/Document Reference Rendering

Pattern for document references and attachments:

7.8 Error Handling and Data Validation Patterns

7.8.1 Data Validation Patterns

Pattern for validating data before rendering:

7.8.2 Graceful Degradation Patterns

Pattern for handling missing or corrupt data:

7.8.3 Debug Information Patterns

Pattern for development debugging:

7.9 Performance Optimization Patterns

7.9.1 E icient Data Processing

Pattern for optimizing data operations:

8. Internationalization and Translation
8.1 Understanding Internationalization in Forms

8.1.1 What is Internationalization (i18n)?

Internationalization is the process of designing and developing forms that can be easily adapted for
di erent languages, regions, and cultures without requiring engineering changes. In the context of Pug
templates, this means:

 Text Translation: Converting all user-facing text to di erent languages

 Date Formatting: Displaying dates according to local conventions

 Number Formatting: Using appropriate decimal separators and currency symbols

 Layout Adaptation: Adjusting layouts for di erent text lengths and reading directions

8.1.2 Key Components of Internationalization

Translation System:

 Translation files containing text in multiple languages

 getText() function to retrieve appropriate translations

 Fallback mechanisms for missing translations

Locale-Aware Formatting:

 Date formatting based on user's locale

 Number and currency formatting

 Address formatting according to regional standards

Content Adaptation:

 Handling text expansion/contraction in di erent languages

 Managing right-to-left languages (if applicable)

 Cultural considerations for colors, symbols, and imagery

8.2 Translation File Structure and Management

8.2.1 Translation File Format

File: [Link]
8.3 The getText Function Implementation

8.3.1 Complete getText Function

Location: In your [Link] file

1. getText Function - Translation System

2. Retrieves translated text based on user locale
3. Parameters:
1. key: Translation key to lookup
2. fallback: Optional fallback text if translation not found
3. interpolations: Optional object for variable replacement
9. Common Patterns and Examples
13.1 Quick Reference Template Structure

13.1.1 Complete Form Template Skeleton

13.2 Data Display Patterns

13.2.1 Standard Data Rendering

13.2.2 Repeating Data Pattern

13.3 Table Patterns

13.3.1 Standard Data Table

13.3.2 Information Table (No Borders)

13.4 Form Section Patterns

13.4.1 Section with Header

13.4.2 Conditional Section

13.5 Validation Patterns

13.5.1 Safe Data Access

13.5.2 Data Type Validation

13.6 Layout Patterns

13.6.1 Two-Column Layout

13.6.2 Signature Block

13.7 Conditional Content Patterns

13.7.1 Multi-Option Display

13.7.2 Progressive Enhancement

13.8 Error Handling Patterns

13.8.1 Graceful Degradation

13.8.2 Missing Data Handling

13.9 Performance Patterns

13.9.1 Pre-compute Values

13.9.2 E icient Conditionals

13.10 Accessibility Patterns

13.10.1 Semantic Structure

13.10.2 Table Accessibility

13.11 Quick Reference Checklist

13.11.1 Before Starting Development

 ODK form structure analyzed

 Required translations identified

 Sample data prepared

 Dependencies listed

13.11.2 During Development

 Include mixins file

 Use getText() for all text

 Handle missing data gracefully

 Apply consistent styling

 Add proper comments

13.11.3 Before Deployment

 Test with empty data

 Test with full data

 Validate in both languages

 Check PDF generation

 Verify all sections render

13.12 Common Mistakes to Avoid

13.12.1 Data Access Errors

13.12.2 Hardcoded Text

13.12.3 Missing Fallbacks