Configuration : pages composées

#Gabarits de page

Une page composée est une page dont la forme vient d’un gabarit de la configuration et dont le contenu vient du Markdown d’une clôture ::::page{template="…"}. Le gabarit nomme des rectangles, appelés blocs ; le Markdown envoie chaque morceau de contenu vers un bloc par son nom (son emplacement). La géométrie n’apparaît jamais dans le Markdown, et le texte du contenu n’apparaît jamais dans le gabarit. La propriété pageTemplates contient les gabarits du livre :

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

Un gabarit qui ne fixe que son id et un bloc est une page entière dont ce bloc remplit la zone de contenu. Tous les autres champs sont facultatifs :

#Blocs

Un bloc est un rectangle nommé qui reçoit du contenu composé. Son name est l’emplacement que demande le Markdown, et il est unique dans son gabarit (un groupe ne peut pas non plus prendre le nom d’un bloc, puisque les ancrages nomment les deux de la même façon).

Un bloc se place par sa cellule grid quand le gabarit a une grille, sinon par son placement, qui fonctionne comme celui d’un élément de maquette : un ancrage ('container' est la zone, 'page', 'bleed', ou '#name' pour un autre bloc ou groupe), un bord, un décalage et une taille. Un bloc ancré à un autre se déplace avec lui. Sans l’un ni l’autre, le bloc prend toute la zone.

#Groupes

Un groupe est une pile (de haut en bas) ou une rangée (du début à la fin) de blocs qui se partagent l’espace et se déplacent ensemble. Dans un groupe, la position propre des blocs dans le sens du groupe est ignorée : le groupe les dispose dans l’ordre, avec gap entre eux. Quand le texte d’un bloc s’allonge, les blocs qui le suivent se décalent. Un groupe est une boîte à laquelle les blocs et le décor peuvent s’ancrer ('#pagina').

#Héritage et variantes

Un gabarit doté d’extends part du gabarit qu’il nomme (qui peut lui-même en étendre un autre) et ne change que ce qu’il écrit :

• Un champ comme area, header ou overflowTemplate remplace celui du parent. grid se fusionne clé par clé. spread, gutter et role sont hérités aussi ; id, name et extends sont propres au gabarit.
• frames et groups se fusionnent par nom : une entrée qui porte le nom d’une entrée héritée change les champs qu’elle écrit et garde les autres (fit, overflow et padding se fusionnent clé par clé ; placement est remplacé en entier) ; remove: true la supprime ; un nom nouveau s’ajoute après les entrées héritées.
• Les éléments du décor se fusionnent par id de la même façon ; un élément avec un id nouveau, ou sans id, s’ajoute.

variants.recto et variants.verso s’écrivent comme un gabarit et se fusionnent de la même façon, sur une page de droite ou de gauche. Elles s’appliquent après toute la chaîne d’extends, la variante de la racine en premier. Une double page a les deux côtés : aucune variante ne s’y applique.

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

Une valeur égale à une valeur par défaut n’est jamais abandonnée quand le Sandbox enregistre un gabarit : dans un gabarit qui en étend un autre, ou dans une variante, elle remplace la valeur du parent.

Depuis le code, resolvePageTemplate(config, id, { parity }) renvoie un gabarit avec sa chaîne fusionnée, la variante du côté appliquée, toutes les valeurs par défaut remplies et chaque référence réglée comme le décrivent les avertissements ci-dessous ; validatePageTemplates(config) renvoie les avertissements.

#Styles d’étiquette

La propriété labelStyles nomme les apparences des étiquettes posées sur une image : les mers et les villes d’une carte, les parties d’un schéma. Une étiquette se place à un ancrage de l’image (un point enregistré avec la ressource, comme les locuteurs de la bande dessinée) et prend le style que nomme l’ancrage ou l’étiquette.

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

#Champs d’étiquette d’un ancrage

Les ancrages d’une image (Resource.anchors, les points que la bande dessinée utilise pour les locuteurs) acceptent quelques champs facultatifs pour les étiquettes. Ce sont des fractions de l’image : ils restent valables dans toutes les langues et quel que soit le recadrage de l’image. La bande dessinée les ignore.

#Avertissements des gabarits de page

Ailleurs, le moteur ignore une clé qu’il ne connaît pas. Les gabarits de page et les styles d’étiquette sont au contraire vérifiés, et chaque problème devient un avertissement de configuration dans postext check et dans le panneau Vérifications du Sandbox. Le path de ces avertissements est un pointeur JSON vers le champ en cause : /pageTemplates/3/frames/2/style, /pageTemplates/0/variants/recto/frames/1/next, /resources/4/anchors/0/style. Quand le champ a été hérité, le pointeur nomme le gabarit qui l’a écrit. Un avertissement qui nomme un id ou un nom inexistant propose aussi le plus proche qui existe.

Une clé mal orthographiée d’un gabarit, d’un bloc, d’un groupe, d’une grille, de fit, d’overflow, d’une variante ou d’un style d’étiquette est un unknownConfigKey ; un mot hors des choix d’un réglage (area, verticalAlign, exclude, takes, kind, align, writingMode, direction, fontStyle, textTransform) est un unknownConfigValue, et le réglage garde sa valeur par défaut. Un gabarit sans id, ou un bloc ou un groupe sans name, est ignoré avec un unknownConfigValue sur ce champ.

La version de la configuration est 15 depuis les gabarits de page (les bundles écrits avant continuent de se charger sans changement : rien de ce que dit une configuration plus ancienne ne change de sens).