Configuration: composed pages

#Page templates

A composed page is a page whose form comes from a template in the configuration and whose content comes from the Markdown of a ::::page{template="…"} fence. The template names rectangles, called frames; the Markdown sends each piece of content to a frame by its name (its slot). Geometry never appears in the Markdown, and content text never appears in the template. The pageTemplates property holds the templates of the book:

const config: PostextConfig = {
  calloutStyles: [{ id: 'caja-azul' }, { id: 'tab-titulo' }],
  pageTemplates: [
    {
      id: 'tema-cajas',
      decoration: {
        elements: [
          { kind: 'image', id: 'fondo', resourceId: '{attr.fondo}', decorative: true,
            placement: { anchor: { to: 'bleed', edge: 'top-left' }, size: { width: 'fill', height: 'fill' } } },
        ],
      },
      frames: [
        { name: 'titulo', takes: 'h1', style: 'tab-titulo' },
        { name: 'texto', flow: true },
        { name: 'dinero', style: 'caja-azul', padding: { right: { value: 62, unit: 'mm' } } },
        { name: 'dinero-fotos', layer: 2, width: { value: 60, unit: 'mm' },
          placement: { anchor: { to: '#dinero', edge: 'top-right' } } },
      ],
      groups: [
        { name: 'pagina', kind: 'stack', gap: { value: 6, unit: 'mm' }, frames: ['titulo', 'texto', 'dinero'] },
      ],
    },
  ],
};

A template that sets nothing but its id and one frame is a whole page with that frame filling the content area. Every other field is optional:

#Frames

A frame is a named rectangle that receives typeset content. Its name is the slot the Markdown asks for, and it is unique in its template (a group cannot take the name of a frame either, since anchors name both the same way).

A frame is placed by its grid cell when the template has a grid, else by its placement, which works like a design element's: an anchor ('container' is the area, 'page', 'bleed', or '#name' for another frame or group), an edge, an offset and a size. A frame anchored to another one moves with it. Without either, the frame takes the whole area.

#Groups

A group is a stack (top to bottom) or a row (start to end) of frames that share space and move together. Inside a group, the frames' own position along the group's direction is ignored: the group lays them out in order, with gap between them. When the text of one frame grows, the frames after it move along. A group is a box that frames and decoration can anchor to ('#pagina').

#Inheritance and variants

A template with extends starts from the template it names (which may itself extend another) and changes only what it writes:

• A field such as area, header or overflowTemplate replaces the parent's. grid merges key by key. spread, gutter and role are inherited too; id, name and extends are the template's own.
• frames and groups merge by name: an entry with the name of an inherited one changes the fields it writes and keeps the rest (fit, overflow and padding merge key by key; placement is replaced whole); remove: true drops it; a new name is added after the inherited ones.
• Decoration elements merge by id the same way; an element with a new id, or none, is added.

variants.recto and variants.verso are written like a template and merge the same way, on a right or a left page. They apply after the whole extends chain, the root's variant first. A spread has both sides, so no variant applies to it.

pageTemplates: [
  { id: 'tema', frames: [{ name: 'texto', flow: true }, { name: 'margen', width: { value: 30, unit: 'mm' },
      placement: { anchor: { to: 'container', edge: 'top-left' } } }],
    variants: { recto: { frames: [{ name: 'margen', placement: { anchor: { to: 'container', edge: 'top-right' } } }] } } },
  { id: 'tema-sin-margen', extends: 'tema', frames: [{ name: 'margen', remove: true }] },
]

A value equal to a default is never dropped when the Sandbox saves a template: in a template that extends another, or in a variant, it overrides the parent's value.

From code, resolvePageTemplate(config, id, { parity }) returns a template with its chain merged, the variant of the side applied, every default filled in and every reference settled as the warnings below describe; validatePageTemplates(config) returns the warnings.

#Label styles

The labelStyles property names the looks of the labels set on a picture: the seas and towns of a map, the parts of a diagram. A label stands at an anchor of the picture (a point stored with the resource, as comic speakers are) and takes the style the anchor or the label names.

labelStyles: [
  { id: 'mar', fontStyle: 'italic', textTransform: 'uppercase', letterSpacing: 0.12,
    color: { hex: '#2b6ca3', model: 'hex' } },
  { id: 'ciudad', fontWeight: 600, halo: { color: { hex: '#ffffff', model: 'hex' }, width: { value: 0.6, unit: 'pt' } } },
]

#Label fields of an anchor

A picture's anchors (Resource.anchors, the points comics use for speakers) take a few optional fields for labels. They are fractions of the picture, so they hold in every language and through any crop of the picture. Comics ignore them.

#Page template warnings

Elsewhere the engine ignores a key it does not know. Page templates and label styles are checked instead, and every problem is a configuration warning in postext check and in the Sandbox's Checks panel. The path of these warnings is a JSON pointer to the field at fault: /pageTemplates/3/frames/2/style, /pageTemplates/0/variants/recto/frames/1/next, /resources/4/anchors/0/style. When the field was inherited, the pointer names the template that wrote it. A warning that names an id or a name that does not exist also suggests the closest one that does.

A misspelt key of a template, frame, group, grid, fit, overflow, variant or label style is an unknownConfigKey; a word outside a setting's choices (area, verticalAlign, exclude, takes, kind, align, writingMode, direction, fontStyle, textTransform) is an unknownConfigValue, and the setting keeps its default. A template with no id, or a frame or group with no name, is ignored with an unknownConfigValue at that field.

The configuration version is 15 since page templates (bundles written before keep loading unchanged: nothing an older configuration says changes meaning).