Skip to content

Variants and presets

Variants let you offer alternative defaults—different margins, paper sizes, or feature toggles—without duplicating the entire template. They live inside configuration.sfo.yml as separate YAML documents using kind: Variant.

About Variants

Variants are currently not yet implemented in the reference editor implementation.

Anatomy of a variant

A variant block contains metadata for the UI and a list of patches that adjust existing components:

kind: Variant
metadata:
  title: Thesis (online)
  description: Optimised for single-sided printing and web-sized images.
spec:
  patches:
    - type: default
      target:
        kind: Page
      patch:
        - op: replace
          path: /properties/page/properties/handling/default
          value: single-sided
    - type: conf
      target:
        kind: Environment
      patch:
        - op: replace
          path: /spec/transformImages/dpi
          value: 96

Key ideas:

  • type: default changes the JSON Schema defaults shipped with a component. Use this when you want the editor to show different starting values. (See patchDefault in libs/export/src/html/components/variant/variant.schema.ts.)
  • type: conf overwrites the configuration values saved in the YAML file without touching the schema defaults. (See patchConf in the same schema.)
  • Each patch entry is a standard JSON Patch operation. Paths point to keys within the component schema. When targeting defaults you must end the path in /default; when updating saved configuration values start the path with /spec.
  • target.kind picks which component to adjust. Combine it with target.metadata.name if the same component appears multiple times.

Grouping and exposing variants

The main Configuration block can add extra structure so the editor presents variants clearly:

  • variantGroups (see ConfigurationConfiguration in libs/export/src/html/components/configuration/configuration.schema.ts) prevent contradictory variants from being selected together. Use them for mutually exclusive layouts such as “Single sided” vs “Double sided”.
  • subTemplates bundle a list of variant names into a ready-made preset. The order of names in variantOrder matters because patches apply sequentially.

When to create a new template instead

Variants are ideal when 90% of the layout stays the same. If you find yourself rewriting large parts of the component list or shipping vastly different assets, fork the template instead. Keeping variants focused avoids confusion for less technical users and simplifies maintenance.