Placeholder System¶

New Feature

The placeholder system ensures incomplete documents are never accidentally finalized by displaying highlighted warnings for missing information.

Overview¶

When generating documents, missing data can lead to incomplete or invalid contracts. The placeholder system solves this by displaying color-coded, highlighted placeholders instead of silently omitting content or leaving blank spaces.

The Problem¶

Before placeholders:

{% if property.easements %}
Easements: {{ property.easements }}
{% endif %}

If property.easements is missing, the entire section is silently omitted. You might not realize the document is incomplete until it's too late.

With placeholders:

Easements: {{ property.easements | review('Check title search for easements') }}

If property.easements is missing, you'll see: [REVIEW REQUIRED: Check title search for easements] with yellow highlighting.

Available Filters¶

Required Filter¶

Use for critical information that must be completed before finalizing.

Syntax:

{{ variable | required }}
{{ variable | required("Description") }}

Example:

Purchase Price: ${{ transaction.purchase_price | currency | required }}
Property Address: {{ property.address | required('Property address from contract') }}

Appearance: - Missing: [REQUIRED: Description] or [REQUIRED: Missing information] - Color: Dark red text, yellow highlight, bold

Optional Filter¶

Use for information that may not apply to all matters.

Syntax:

{{ variable | optional }}
{{ variable | optional("Description") }}

Example:

Parking Spaces: {{ property.parking_spaces | optional('Number of parking spaces') }}
GST Amount: {{ transaction.gst_amount | optional('GST if commercial property') }}

Appearance: - Missing: [OPTIONAL: Description - review if applicable] - Color: Blue text, yellow highlight, bold

Review Filter¶

Use for information requiring manual verification or special attention.

Syntax:

{{ variable | review("Message") }}
{{ variable | review }}

Example:

Easements: {{ property.easements | review('Check title search') }}
Pool Compliance: {{ property.pool_compliance | review('Verify certificate if applicable') }}

Appearance: - Missing: [REVIEW REQUIRED: Message] - Color: Orange text, yellow highlight, bold

Visual Guide¶

Filter Type	Text Color	Background	Example
`required`	Dark Red	Yellow	Critical fields (names, prices, dates)
`optional`	Blue	Yellow	Fields that may not apply
`review`	Orange	Yellow	Needs verification

In Excel documents, placeholders also add cell comments explaining what's needed.

Common Use Cases¶

Legal Descriptions¶

Lot {{ property.lot_number | required('Lot number from title') }}
in Deposited Plan {{ property.dp_number | required('DP number from title') }}

Financial Terms¶

Purchase Price: ${{ transaction.purchase_price | currency | required }}
Deposit: ${{ transaction.deposit_amount | currency | required }}
Balance: ${{ transaction.balance | currency | required }}

Dates¶

Contract Date: {{ transaction.contract_date | date | required }}
Settlement Date: {{ transaction.settlement_date | date('%d %B %Y') | required }}

Verification Items¶

Easements: {{ property.easements | review('Check title search - enter "None" if no easements') }}
Pool Compliance: {{ property.pool_compliance | review('Check certificate if property has pool') }}
Vendor Warranties: {{ transaction.warranties | review('Confirm with vendor solicitor') }}

Optional Fields¶

Parking: {{ property.parking_spaces | optional('Number of spaces if applicable') }}
GST: {{ transaction.gst_amount | currency | optional('GST for commercial properties only') }}

Best Practices¶

1. Choose the Right Filter¶

Use Case	Filter
Legal/financial requirements	`required`
May not apply to all matters	`optional`
Needs verification	`review`

2. Write Helpful Descriptions¶

❌ Bad:

{{ property.easements | required }}

Shows: [REQUIRED: Missing information] - not helpful

✅ Good:

{{ property.easements | required('Easements from title search - check Schedule 2') }}

Shows exactly what's needed and where to find it.

3. Always Show Critical Sections¶

❌ Bad:

{% if property.easements %}
Easements: {{ property.easements }}
{% endif %}

Section disappears if missing.

✅ Good:

Easements: {{ property.easements | review('Check title search - enter "None" if not applicable') }}

Always visible, with placeholder if missing.

4. Chain Filters Correctly¶

✅ Correct order: Format → Placeholder

{{ transaction.purchase_price | currency | required }}
{{ transaction.settlement_date | date('%d %B %Y') | required }}

❌ Wrong order:

{{ transaction.purchase_price | required | currency }}  <!-- Will fail! -->

Complete Example¶

Before: Silent Omission¶

CONTRACT OF SALE

Vendor: {{ transaction.vendor_name }}
Purchaser: {{ client.full_name }}
Property: {{ property.address }}

{% if property.easements %}
Easements: {{ property.easements }}
{% endif %}

Purchase Price: ${{ transaction.purchase_price | currency }}

Problems: - Missing vendor name → blank space - Missing easements → entire section omitted - Missing price → shows "$"

After: With Placeholders¶

CONTRACT OF SALE

Vendor: {{ transaction.vendor_name | required('Vendor legal name from contract') }}
Purchaser: {{ client.full_name | required }}
Property: {{ property.address | required('Property address from contract') }}

Easements: {{ property.easements | review('Check title search - enter "None" if no easements') }}

Purchase Price: ${{ transaction.purchase_price | currency | required }}

Result: - Missing fields show highlighted placeholders - Nothing is silently omitted - Clear instructions on what's needed

Testing Your Templates¶

Test with Incomplete Data¶

Create a matter with some fields missing
Generate a document
Open the generated file
Verify placeholders appear with yellow highlighting

Test with Complete Data¶

Fill in all fields
Generate the same document
Verify no placeholders appear - only actual values

Document Format Support¶

Word Documents (.docx)¶

Yellow background highlighting
Color-coded text
Bold formatting

Excel Spreadsheets (.xlsx)¶

Yellow cell background
Color-coded text
Cell comments with explanations

RTF Documents (.rtf)¶

Colored text with highlighting
Bold formatting

Migration Guide¶

Step 1: Identify Critical Fields¶

Review your template and identify: - Required: Names, dates, prices, legal descriptions - Optional: Fields that may not apply (GST, parking, etc.) - Review: Fields needing verification (easements, compliance, etc.)

Step 2: Add Filters¶

Update your template:

<!-- Before -->
{{ property.lot_number }}

<!-- After -->
{{ property.lot_number | required('Lot number from title') }}

Step 3: Convert Conditionals¶

Change silent conditionals to always-visible placeholders:

<!-- Before -->
{% if property.easements %}
Easements: {{ property.easements }}
{% endif %}

<!-- After -->
Easements: {{ property.easements | review('Check title search') }}

Step 4: Test¶

Generate documents with incomplete data to verify placeholders work correctly.

Decision Tree¶

Is this field critical for legal/financial validity?
├─ YES → Use `required`
│   Examples: Names, addresses, prices, dates
│
└─ NO → Does it apply to all matters?
    ├─ NO → Use `optional`
    │   Examples: GST, parking, special features
    │
    └─ YES → Does it need verification?
        ├─ YES → Use `review`
        │   Examples: Easements, compliance certificates
        │
        └─ NO → No filter needed

Quick Reference¶

<!-- Critical information -->
{{ field | required("What's needed") }}

<!-- May not apply -->
{{ field | optional("When it applies") }}

<!-- Needs verification -->
{{ field | review("What to check") }}

<!-- With formatting -->
{{ date_field | date('%d %B %Y') | required }}
{{ price_field | currency | required }}

Benefits¶

✅ Safety - Never accidentally finalize incomplete documents ✅ Visibility - Missing information is immediately obvious ✅ Clarity - Color-coding shows priority level ✅ Workflow - Built-in checklist for document completion ✅ Flexible - Works with all document formats ✅ Backward Compatible - Existing templates continue to work

Troubleshooting¶

Placeholder doesn't appear¶

Check that: - Filter is spelled correctly (required, not require) - Field name matches your matter.json - Value is actually missing (not empty string)

Wrong color appearing¶

Dark red = required
Blue = optional
Orange = review

Verify you're using the correct filter.

Placeholder shows even with data¶

Check if the value is: - An empty string "" - Just whitespace " " - Both are treated as missing

Pro Tip

Use descriptive messages in your placeholders. Instead of {{ property.easements | required }}, use {{ property.easements | required('Check title search Schedule 2 for easements') }}. Future you (and your colleagues) will thank you!

Real-World Example

See the Creating Templates guide for a complete Contract of Sale template using placeholders.