Template Editor Guide

Everything you need to know about building document templates in SalesCFG — from basic sections to dynamic tag-bound content that pulls data from your configurator options.

Overview

The Template Editor (also called the "Template Machine") lets you design PDF document templates for your configurators. Each template is a list of sections that compose a full document — cover page, pricing table, technical specs, signature block, and so on.

When a customer (or sales rep) generates a document from the configurator, the system takes the template, fills it with the selected options and customer data, and renders a branded PDF.

Core Concepts

• Section — a single block in the template (text, image, table, pricing, etc.).
• Tag binding — a section can have config.tags that link it to option content at generation time.
• Variable — a placeholder like {{customer_name}} that gets replaced with real data.
• Branding — colors, fonts, logo, and page layout that apply to the whole document.
• Visibility rules — conditions that show or hide sections based on the configuration.

Section Types

The editor supports over 20 section types. Here are the most commonly used:

Tag Binding

Tag binding is the core mechanism that makes templates dynamic. Instead of creating a generic "tagged content slot", you create a real section (text, image, certifications, etc.) and attach tags to it. At generation time, the system finds matching content from the selected options and binds it into that section.

This means you always control the layout — you know exactly what type of content goes where, and you can provide default/fallback content for when no options match.

How It Works

1. Add a section to your template (e.g., a text section titled "Technical Specifications").
2. In the Tag Binding panel, add one or more content tags (e.g., specs).
3. In your configurator options, add documentSections of the same type (text) tagged with specs.
4. At generation time, the resolver finds all selected options with matching text sections tagged specs and binds their content into the template section.

// Template section (in the editor)
{
  type: "text",
  config: {
    title: "Technical Specifications",
    body: "No specs available for this configuration.",
    tags: ["specs"],
    tagRepeat: "merge",
    tagEmptyBehavior: "show_default"
  }
}

// Option documentSection (on each configurator option)
{
  type: "text",           // ← must match the template section type
  tags: ["specs"],        // ← must match the template section tags
  config: {
    title: "Pump Specifications",
    body: "Flow rate: 100 L/min\nPressure: 6 bar"
  }
}

Repeat Modes

When multiple selected options have matching content, the repeat mode controls how they are assembled:

Empty Behavior

When no selected options have matching content:

• Show default — renders the section with its own config (the title/body you wrote in the editor). Good for sections that should always appear.
• Hide — removes the section entirely from the generated document. Good for sections that only make sense with option content.

Legacy: Tagged Content Slot

Older templates may use a special tagged_content section type. This is a slot that expands into multiple sections at generation time — the option content replaces the slot entirely.

This still works for backwards compatibility, but we recommend converting to type-bound tag binding instead:

• Replace tagged_content with a real section type (text, image, etc.).
• Move config.tags to the new section.
• Set tagRepeat to merge (replaces tagMergeMode: merge_by_type) or repeat (replaces tagMergeMode: individual).
• Add fallback content in the section body for when no options match.

Variables & Placeholders

Template variables let you insert dynamic text anywhere in the document. Use double curly braces:

{{customer_name}}           → value from variables
{{customer_name|John Doe}}  → with fallback if empty
{{product.name}}            → nested path from payload
{{pricing.total}}           → pricing data

Variables are defined in the template's variable definitions panel. When generating a document, values come from:

1. The variables map in the template JSON.
2. The variableDefinitions array (overrides the map).
3. The generation payload (product, selections, pricing data).

Tip: Always use the pipe syntax {{variable|fallback}} for customer-facing fields. This way, documents generated without customer data still look clean.

Conditional Visibility

Any section can have visibility rules that control whether it appears based on the configuration:

visibleIf: [
  { field: "total_price", operator: ">", value: 5000 },
  { field: "option_selected.installation", operator: "is_true" }
]

All conditions must be true for the section to appear (AND logic). Available operators:

• =, !=, >, >=, <, <= — standard comparisons
• contains, in, not_in — list membership
• option_selected — checks if an option is in the selection
• exists, is_true, is_false — presence and boolean checks

Branding & Layout

The branding panel controls the global look of generated documents:

• Logo — uploaded image shown on the cover page and optionally in headers.
• Cover image — background image for the cover section.
• Colors — primary, secondary, and accent colors used for headings, tables, and accents.
• Font family — applied to all document text.
• Page size — A4 or Letter.
• Page margin — margin in millimeters.

Option Document Sections

Each configurator option can have documentSections — content blocks that get pulled into the template via tag binding. Each document section has:

• Type — must match the template section type (text, image, certifications, etc.)
• Tags — used to match against template section tags (e.g., specs, safety)
• Config — the content payload (title, body, imageUrl, items, etc.)

Options also have documentTags — a fallback list of tags. If a document section has no tags of its own, the system uses the option-level documentTags instead.

// Example option with document sections
{
  label: "Electric Heater 24kW",
  price: 4500,
  documentTags: ["specs", "safety"],
  documentSections: [
    {
      type: "text",
      tags: ["specs"],
      config: {
        title: "Heater Specifications",
        body: "Power: 24 kW\nVoltage: 400V 3-phase"
      }
    },
    {
      type: "text",
      tags: ["safety"],
      config: {
        title: "Heater Safety",
        body: "Warning: Surface temperature exceeds 80°C."
      }
    }
  ]
}

Best Practices

1. Use real section types, not tagged content slots. A text section with tags: ["specs"] is always better than a tagged_content slot because you control the layout, see a preview, and have fallback content.
2. Match types between template and options. If your template has an image section tagged drawings, your options must provide image document sections tagged drawings — not text.
3. Use pipe fallbacks for variables. Write {{customer_name|Valued Customer}} instead of {{customer_name}} so documents always look complete.
4. Keep tag names consistent. Use simple lowercase tag names like specs, safety, overview, compliance, service. The Tag Library panel shows all tags in use.
5. Use "hide" for optional sections. Set tagEmptyBehavior: "hide" for sections that only make sense when options provide content (safety warnings, compliance notes).
6. Use "show default" for always-present sections. Sections like "Technical Specifications" should show fallback content even when no matching options are selected.
7. Set page breaks intentionally. Use pageBehavior: "new_page" for major sections (cover, specs, pricing) and continue for sections that flow naturally.

FAQ

What happens if I tag an image section but options provide text?

Nothing — tag binding requires type matching. An image section only pulls from image document sections. If no images match, the section either shows its default content or is hidden (based on your empty behavior setting).

Can I use the same tag on multiple template sections?

Yes. You might have both a text section and an image section both tagged specs. Each will pull only its matching type from the options.

How do I migrate from tagged_content to type-bound sections?

Replace the tagged_content section with the appropriate real type (usually text). Copy the tags from the old config. Set tagRepeat to merge (was merge_by_type) or repeat (was individual). Add a fallback body.

Do I need to restart the server after editing a template?

No. Templates are stored in the document generator service and loaded fresh for each generation. Save your template and generate immediately.