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. The two sample templates demonstrate different use cases:

  • The journal templates ship without variants by default, keeping the configuration straightforward for article workflows.
  • The monograph template defines two variants (A5 and engineering) grouped under page-sizes, showing how to adapt page dimensions and inject faculty-specific CSS without cloning the whole template.
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.

Monograph example
The A5 variant updates the Page defaults (size, margins, font size) and then narrows multiple header/footer variants by matching metadata.name (for-front, for-body, for-back). This approach keeps front/back matter aligned without duplicating assets.

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.

Monograph templates usually expose a single variant group (page sizes) with clear titles so faculty administrators can pick the correct preset. Journals tend to leave variants turned off unless there is a compelling set of alternate defaults.

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.

Variant testing checklist

  1. Apply the variant locally (or via the API) and export every supported format—PrinceXML, HTML, EPUB, etc.
  2. Disable the variant and repeat the exports to ensure defaults still work.
  3. For monographs with multiple header/footer components, verify that page counters and translations remain correct after patches run.
  4. Update the template readme with a short description of each variant so editors know when to use them.