Formulaires pour les modèles Typst

Un modèle Typst fournit souvent ses propres fonctions : une page de couverture, un encadré d’information, un bloc de validation. Celui qui rédige le rapport les appelle, comme dans #info-box(title: "Supply risk", tone: "risk")[...]. Si vous maintenez le modèle, vous pouvez décrire une seule fois les arguments de chaque fonction. Le mode Visuel affiche alors chaque appel de cette fonction sous forme de formulaire : des champs avec libellé, une liste pour les choix fixes, un interrupteur pour oui ou non. Modifier un champ réécrit uniquement cet argument dans le fichier .typ, de sorte que le rapport reste un source Typst ordinaire qui compile de la même façon.

Ce que voit le lecteur

Un appel sur ses propres lignes devient une carte. L’en-tête de la carte affiche le nom du formulaire et, si vous en choisissez un, un court résumé comme le titre de l’encadré. Chaque argument a une ligne avec son libellé et un contrôle.

Un appel à l’intérieur d’une phrase, comme #badge("review"), devient une pastille dans la ligne de texte. Cliquer sur la pastille ouvre les mêmes champs dans une petite fenêtre contextuelle.

Les champs de texte et de balisage s’enregistrent quand vous appuyez sur Enter (⌘ Enter ou Ctrl Enter dans un champ multiligne) ou quand vous quittez le champ. Esc remet l’ancienne valeur. Les listes et les interrupteurs s’enregistrent aussitôt. Chaque modification est une étape d’annulation.

Placer le curseur dans un appel affiche son source, comme n’importe quel autre élément du mode Visuel. Modifier dans le source sur la carte fait la même chose.

Où déclarer les formulaires

Il y a deux endroits, avec le même format :

• Dans un paquet. Ajoutez une section [tool.oleafly] au typst.toml du paquet. Typst réserve les sections [tool.*] à d’autres outils, donc le paquet s’installe et compile toujours partout. Cela fonctionne pour les paquets @local et pour les paquets @preview de Typst Universe.
• Dans le projet. Pour les modèles gardés sous forme de fichiers .typ simples dans le projet, créez oleafly-forms.toml à la racine du projet. Chaque formulaire nomme aussi le fichier qui définit la fonction, avec module.

Un formulaire de paquet :

[tool.oleafly]
schema = 1

[[tool.oleafly.forms]]
function = "info-box"
label = "Info box"
summary = "title"

  [[tool.oleafly.forms.fields]]
  arg = "title"
  kind = "text"
  label = "Heading"
  placeholder = "Short heading"
  required = true

  [[tool.oleafly.forms.fields]]
  arg = "tone"
  kind = "choice"
  label = "Tone"
  default = "note"
  options = [{ value = "note", label = "Note" }, { value = "risk", label = "Risk" }, "neutral"]

  [[tool.oleafly.forms.fields]]
  arg = 0
  kind = "content"
  label = "Text"

Un formulaire de projet, dans oleafly-forms.toml :

[tool.oleafly]
schema = 1

[[tool.oleafly.forms]]
module = "template/memo.typ"
function = "memo-header"
label = "Memo header"
fields = [
  { arg = "to", kind = "text", label = "To" },
  { arg = "subject", kind = "text", label = "Subject" },
]

Les clés

schema = 1 est obligatoire. Un fichier qui n’en a pas, ou qui a un autre nombre, est ignoré.

Chaque entrée [[tool.oleafly.forms]] a :

Clé	Obligatoire	Signification
function	Oui	Le nom de la fonction, sous forme d’un seul identifiant Typst. Les traits d’union sont acceptés.
module	Dans oleafly-forms.toml seulement	Le fichier du projet qui définit la fonction, relatif à la racine du projet, avec / entre les dossiers.
label	Non	Le nom du formulaire sur les cartes et les pastilles. Par défaut, le nom de la fonction.
summary	Non	L’argument dont la valeur apparaît à côté du libellé, écrit comme le arg d’un champ.
fields	Oui	Un ou plusieurs champs.

Chaque champ a :

Clé	Obligatoire	Signification
arg	Oui	Un nom pour un argument nommé ("title"), ou un nombre pour un argument positionnel (0 est le premier). Un bloc [...] final compte comme un argument positionnel après ceux entre parenthèses.
kind	Oui	text, content, choice, number ou toggle.
label	Oui	Le libellé du champ.
help	Non	Une courte note sous le champ.
placeholder	Non	Texte gris dans un champ vide.
required	Non	true marque un champ vide comme manquant et masque son bouton Effacer. Oleafly n’ajoute jamais l’argument de lui-même.
default	Non	La valeur que votre fonction utilise quand l’argument est omis. Elle est affichée, jamais écrite.

Les types et leurs clés supplémentaires :

• text écrit une chaîne Typst. Ajoutez multiline = true pour une zone plus grande.
• content modifie du balisage Typst et l’écrit sous forme de bloc [...]. Un argument de type chaîne reste une chaîne.
• choice a besoin de options : une liste de chaînes, ou des tables { value, label } quand le libellé diffère de la valeur. Les valeurs sont écrites comme des chaînes.
• number accepte integer, min, max et step. Les nombres n’ont pas d’unités.
• toggle écrit true ou false.

Quels appels reçoivent un formulaire

Oleafly suit les lignes #import et #let du rapport, au niveau supérieur du fichier :

• #import "@local/acme-report:0.1.0" as acme fait de #acme.info-box(...) un formulaire.
• #import "@local/acme-report:0.1.0": info-box, status-badge as badge fait de #info-box(...) et de #badge(...) des formulaires.
• #import "@local/acme-report:0.1.0": * donne un formulaire à chaque fonction pour laquelle le paquet en déclare un.
• #import "template/memo.typ": memo-header correspond à un formulaire de projet dont le module est template/memo.typ. Les chemins sont lus depuis le dossier du rapport, ou depuis la racine du projet quand ils commencent par /.

La version du paquet doit correspondre exactement. Un #let de même nom, plus loin dans le fichier, remplace le formulaire à partir de ce point. Les appels atteints via un autre fichier qui réimporte le paquet gardent leur texte source.

Une fonction nommée comme un élément Typst que le mode Visuel dessine déjà, comme table ou figure, garde l’apparence intégrée quand elle est appelée par son nom seul. #acme.table(...) ou un import renommé obtient quand même le formulaire.

Champs affichés en lecture seule

Certains arguments ne peuvent pas être modifiés sans risque depuis un formulaire. Leur ligne affiche le source avec la raison, et Modifier dans le source y saute :

• Calculé dans le source : la valeur est une expression, comme title: data.title.
• Écrit comme un autre type de valeur : par exemple un nombre là où le formulaire attend du texte.
• Ne fait pas partie des choix : une valeur que vos options ne listent pas.
• Défini par un argument étalé : un appel avec ..args transmet des valeurs que le formulaire ne voit pas, donc tous les champs sont en lecture seule.

Quand un champ ne peut pas être ajouté à l’endroit où il irait, par exemple un argument positionnel après un argument manquant, le formulaire le dit et propose Ajouter dans le source.

Erreurs dans une définition

Ouvrez oleafly-forms.toml, ou le typst.toml d’un paquet intégré au projet, dans Oleafly, et chaque problème s’affiche comme un repère sur sa ligne : un type inconnu, un libellé manquant, un formulaire en double, un module hors du projet. Un formulaire cassé est laissé de côté et les autres continuent de fonctionner. Un fichier de plus de 256 Ko n’est pas lu.

Partager des modèles

Oleafly lit les formulaires des paquets dans les mêmes dossiers que le compilateur. Un collaborateur qui n’a pas le paquet @local voit du source simple et aucune erreur. Pour partager les formulaires avec tous les membres d’un projet, ouvrez la boîte de dialogue Paquets Typst, activez Utiliser les paquets du dossier du projet et choisissez Intégrer les paquets au projet. Le paquet, et ses formulaires, voyagent alors dans le dossier typst-packages du projet (voir Projets Typst).