Rendu HTML

HtmlRenderer::render($document) produit le rendu d'un document, un bloc de premier niveau par ligne, avec le BlockRenderer enregistré pour chaque type. HtmlRenderer::default() enregistre cinq moteurs de rendu pour tous les types : TextRenderer, CodeRenderer, ListRenderer, MediaRenderer et LayoutRenderer. Un type sans moteur de rendu lance UnknownBlockType.

Purification

La sortie est purifiée par construction, grâce à l'assainisseur en ligne propre au moteur de rendu :

• chaque valeur brute est échappée ;
• chaque valeur HTML est assainie de nouveau avec le profil de son champ (raw pour un bloc raw, rich sinon) ;
• chaque élément et chaque attribut qui n'est pas une valeur est écrit par le moteur de rendu lui-même.

Les valeurs qui deviennent des classes, des identifiants, des styles et des adresses sont vérifiées par Normalizer, pas par le moteur de rendu : produisez le rendu d'un document normalisé. Ujo::toHtml() normalise d'abord ; donnez-lui le document ou son JSON.

Le HTML de chaque type

Chaque élément racine a la classe ujo- suivie de son type en kebab case : ujo-paragraph, ujo-link-tool, ujo-page-break.

Réglages

La solution de repli pour le papier

Un cadre, une vidéo et un son ne peuvent pas jouer sur papier. Chacun est suivi d'un <a class="ujo-print-fallback">, en lien vers la page du cadre ou la première source du lecteur, avec son affiche ujo-print-fallback__poster, son titre ujo-print-fallback__title et son adresse ujo-print-fallback__url. Quand le qrCode du bloc est vrai, il est aussi suivi d'un <div class="ujo-print-fallback ujo-qr-code" data-qr-code>, que dessine un moteur de rendu de codes QR. Un style d'écran masque .ujo-print-fallback et un style d'impression le montre à la place du lecteur.

Remplacer ou ajouter un moteur de rendu

final readonly class CalloutRenderer implements BlockRenderer
{
    public function render(Block $block, Rendering $rendering): string
    {
        return $rendering->element('aside', $block, $rendering->inline($block->data['text'] ?? null), ['role' => 'note'], ['ujo-callout--'.Rendering::text($block->data['tone'] ?? 'calm')]);
    }
}

$renderer = HtmlRenderer::default()->with('callout', new CalloutRenderer());

Rendering donne à un moteur de rendu le document ($rendering->document), les blocs imbriqués (blocks()), l'assainisseur (inline(), plain()), l'échappement (text()), l'élément racine avec les réglages (element()), les éléments simples (tag()) et les valeurs calculées une fois par rendu (remember($key, $compute)) : un moteur de rendu qui lit le document entier le lit une seule fois, quel que soit le nombre de ses blocs que contient le document. Les titres de toc et les abréviations de abbreviations sont lus de cette façon. Un autre assainisseur se donne à HtmlRenderer::default($sanitizer).

Surligner le code

withCodeHighlighter() donne un surligneur aux blocs de code : une fermeture qui reçoit le code et sa langue et retourne du HTML, ou null quand elle ne connaît pas la langue. Elle n'est pas appelée pour un bloc sans langue. Highlighter::highlight() de phil/highlight a cette forme :

$renderer = HtmlRenderer::default()->withCodeHighlighter(Highlighter::default()->highlight(...));

Le moteur de rendu ne garde le HTML du surligneur que s'il ne contient rien d'autre que le texte du code, échappé, dans des éléments <span class="…"> (lettres minuscules, chiffres, espaces, _ et - dans la classe) qui s'ouvrent et se ferment dans l'ordre (CodeRenderer::holds()). Tout le reste se rabat sur le code échappé : le moteur de rendu reste ainsi purifié par construction, quoi que retourne le surligneur. Un bloc que le surligneur laisse garde sa classe language-…, pour un surligneur dans le navigateur.

Dessins stockés

withStoredMarkup(Closure $trusts, array $types = StoredMarkup::TYPES) dessine les blocs math, mermaid, chart et qrCode à partir du balisage qu'ils gardent sous rendered. $trusts reçoit le bloc, le balisage et sa clé, et dit si le serveur les a écrits pour la source actuelle du bloc ; Signer::trusts(...) de phil/svg-blocks a cette forme :

$renderer = HtmlRenderer::default()->withStoredMarkup($signer->trusts(...));

Une formule approuvée s'écrit comme un <div class="ujo-math"> autour de son MathML ; un dessin approuvé comme une <figure> autour de son SVG, avec la légende du bloc. Le balisage est écrit tel quel, sans nouvel assainissement : on lui fait confiance parce que sa clé prouve qui l'a écrit, et $trusts doit donc refuser toute clé qu'il n'a pas émise. Un bloc sans dessin, avec un dessin mal formé ou avec une clé non approuvée se rabat sur le moteur de rendu que le type avait avant (StoredMarkupRenderer).

Filtrer le HTML produit

withFilter() ajoute un HtmlFilter, une dernière passe sur le HTML de chaque document, exécutée après les filtres que le moteur de rendu a déjà. Un filtre reçoit du HTML purifié et doit retourner du HTML aussi sûr : il peut réécrire du texte (guillemets typographiques, espaces insécables, césures conditionnelles), jamais ajouter de balisage ni d'attributs.

final readonly class Typography implements HtmlFilter
{
    public function filter(string $html): string
    {
        return str_replace('...', '…', $html);
    }
}

$renderer = HtmlRenderer::default()->withFilter(new Typography());