Configuración: páginas compuestas

#Plantillas de página

Una página compuesta es una página que toma su forma de una plantilla de página de la configuración y su contenido del Markdown de un bloque ::::page{template="…"}. La plantilla da nombre a unos rectángulos, llamados marcos; el Markdown manda cada pieza de contenido a un marco por su nombre (su hueco). La geometría nunca aparece en el Markdown, y el texto del contenido nunca aparece en la plantilla. La propiedad pageTemplates guarda las plantillas del libro:

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'] },
      ],
    },
  ],
};

Una plantilla que solo fija su id y un marco es una página entera con ese marco ocupando el área de texto. Todos los demás campos son opcionales:

#Marcos

Un marco es un rectángulo con nombre que recibe contenido compuesto. Su name es el hueco que pide el Markdown, y es único en su plantilla (un grupo tampoco puede llevar el nombre de un marco, porque los anclajes nombran a los dos de la misma manera).

Un marco se coloca por su celda de grid cuando la plantilla tiene rejilla y, si no, por su placement, que funciona como el de un elemento de diseño: un anclaje ('container' es el área, 'page', 'bleed', o '#name' para otro marco o grupo), un borde, un desplazamiento y un tamaño. Un marco anclado a otro se mueve con él. Sin ninguno de los dos, el marco ocupa toda el área.

#Grupos

Un grupo es una pila (de arriba abajo) o una fila (del principio al final) de marcos que se reparten el espacio y se mueven juntos. Dentro de un grupo se ignora la posición propia de los marcos en la dirección del grupo: el grupo los coloca en orden, con gap entre ellos. Cuando crece el texto de un marco, los marcos que van detrás se desplazan. Un grupo es una caja a la que pueden anclarse marcos y decoración ('#pagina').

#Herencia y variantes

Una plantilla con extends parte de la plantilla que nombra (que a su vez puede extender otra) y cambia solo lo que escribe:

• Un campo como area, header u overflowTemplate sustituye al del padre. grid se combina clave a clave. spread, gutter y role también se heredan; id, name y extends son propios de la plantilla.
• frames y groups se combinan por nombre: una entrada con el nombre de una heredada cambia los campos que escribe y conserva el resto (fit, overflow y padding se combinan clave a clave; placement se sustituye entero); remove: true la quita; un nombre nuevo se añade detrás de los heredados.
• Los elementos de decoración se combinan por id de la misma manera; un elemento con un id nuevo, o sin id, se añade.

variants.recto y variants.verso se escriben como una plantilla y se combinan igual, en una página impar o en una par. Se aplican después de toda la cadena de extends, primero la variante de la raíz. Una doble página tiene los dos lados, así que no se le aplica ninguna variante.

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 }] },
]

Cuando el Sandbox guarda una plantilla, nunca descarta un valor igual al valor por defecto: en una plantilla que extiende otra, o en una variante, ese valor sustituye al del padre.

Desde código, resolvePageTemplate(config, id, { parity }) devuelve una plantilla con su cadena combinada, la variante del lado aplicada, todos los valores por defecto rellenos y cada referencia resuelta como describen los avisos de abajo; validatePageTemplates(config) devuelve los avisos.

#Estilos de rótulo

La propiedad labelStyles da nombre a los aspectos de los rótulos que se ponen sobre una imagen: los mares y las ciudades de un mapa, las partes de un esquema. Un rótulo se sitúa en un anclaje de la imagen (un punto guardado con el recurso, como los hablantes de un cómic) y toma el estilo que nombra el anclaje o el rótulo.

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' } } },
]

#Campos de rótulo de un anclaje

Los anclajes de una imagen (Resource.anchors, los puntos que usan los cómics para los hablantes) admiten unos pocos campos opcionales para rótulos. Son fracciones de la imagen, así que valen en todos los idiomas y con cualquier recorte de la imagen. Los cómics los ignoran.

#Avisos de las plantillas de página

En el resto de la configuración, el motor ignora una clave que no conoce. Las plantillas de página y los estilos de rótulo, en cambio, se comprueban, y cada problema es un aviso de configuración en postext check y en el panel Revisión del Sandbox. El campo path de estos avisos es un puntero JSON al campo que falla: /pageTemplates/3/frames/2/style, /pageTemplates/0/variants/recto/frames/1/next, /resources/4/anchors/0/style. Cuando el campo es heredado, el puntero nombra la plantilla que lo escribió. Un aviso que nombra un id o un nombre que no existe propone además el existente que más se le parece.

Una clave mal escrita de una plantilla, un marco, un grupo, una rejilla, fit, overflow, una variante o un estilo de rótulo es un unknownConfigKey; una palabra fuera de las opciones de un ajuste (area, verticalAlign, exclude, takes, kind, align, writingMode, direction, fontStyle, textTransform) es un unknownConfigValue, y el ajuste conserva su valor por defecto. Una plantilla sin id, o un marco o un grupo sin name, se ignora con un unknownConfigValue en ese campo.

La versión de la configuración es la 15 desde las plantillas de página (los paquetes escritos antes se siguen cargando sin cambios: nada de lo que dice una configuración anterior cambia de significado).