Services

FormKrafter ne présume jamais du fonctionnement de votre infrastructure. Tout ce qui touche au monde extérieur — uploader un fichier, récupérer une liste d’options, charger un formulaire référencé — passe par un service que vous pouvez remplacer. Surchargez-le une fois au démarrage de l’application et chaque builder et renderer de la page le reprend.

Les cinq services

Service	Par défaut	Remplacez-le quand…
jsRunnerService	SandboxJsRunnerService (interpréteur d’AST)	vous avez besoin du JS complet dans un contexte de confiance
dataSourceService	FetchDataSourceService	les options distantes d’un select nécessitent une auth, une URL de base ou une politique de retry
fileUploadService	Base64FileUploadService (data URLs)	vous voulez de vrais uploads plutôt que du base64 inliné
specSourceService	FetchSpecSourceService	les formulaires imbriqués viennent de votre propre stockage
optionSourceService	FetchOptionSourceService	les catalogues d’options partagés viennent de votre propre stockage

app-startup.ts

import { services, UrlFileUploadService } from '@streamline-pulse/formkrafter-core'

services.fileUploadService = new UrlFileUploadService({
  url: '/api/uploads',
  credentials: 'include',
})

Uploads de fichiers

Le service par défaut transforme chaque fichier en data URL base64 — parfait pour une démo, inadapté à la production. UrlFileUploadService envoie plutôt chaque fichier en POST multipart :

1. Pointez-le vers votre endpoint.

   services.fileUploadService = new UrlFileUploadService({
     url: '/api/uploads',
     headers: { 'X-Tenant': 'acme' },
     credentials: 'include',
   })

2. Retournez l’emplacement stocké depuis votre endpoint. Le service lit la première clé parmi url, path, location ou href qu’il trouve dans la réponse JSON.

   { "url": "https://cdn.example.com/f/8a2c.pdf" }

3. Implémentez la suppression si vous voulez que le bouton de retrait fasse le ménage. Le service appelle remove() quand l’utilisateur supprime un fichier.

Une config uploadUrl au niveau de la brick surcharge l’URL par défaut du service : un formulaire peut donc envoyer ses pièces jointes ailleurs.

Options distantes et authentification

Un select peut charger ses options depuis une URL, en interpolant des placeholders {key} depuis le context d’exécution et les données courantes du formulaire — context d’abord :

Config de la brick

URL      {api.base}/employees?dept={department}
Headers  Authorization: Bearer {auth.token}

La réponse peut être un tableau JSON nu ou une enveloppe : un payload dont la propriété data est un tableau est déballé automatiquement, ce qui couvre la plupart des API paginées. Pour toute autre forme, pointez optionsPath sur le tableau — result.items. Un payload ne correspondant à aucun de ces cas échoue bruyamment plutôt que d’afficher un select vide.

Les tokens acceptent les chemins pointés : un contexte imbriqué n’a donc pas besoin d’être aplati. Une clé contenant un point est cherchée en premier, puis le chemin est parcouru ; les propriétés héritées ne sont jamais atteignables. Un token qui ne résout rien devient une chaîne vide. C’est toute la grammaire — pas d’expressions, pas de valeurs par défaut, pas d’échappement.

Attention

Les doubles accolades ({{valeur}}) ne sont pas une syntaxe de template ici — elles appartiennent au templeter côté serveur. Une grammaire par côté, délibérément.

Deux schémas d’authentification, qui se composent :

1. Cookie httpOnly — recommandé pour les API de même origine. Aucun secret n’entre jamais dans le spec ni dans le panneau de propriétés.

   import { services, FetchDataSourceService } from '@streamline-pulse/formkrafter-core'
   
   services.dataSourceService = new FetchDataSourceService({ credentials: 'include' })

2. Token de contexte — quand l’API est cross-origin. L’hôte l’injecte via la prop context du renderer.

   <FkFormRender spec={spec} context={{ auth: { token } }} />

Astuce

Tout ce que contient context est lisible par les règles et l’interpolation d’URL et n’est jamais dans un payload émis. Les clés data préfixées d’un underscore se comportent pareil et restent supportées — voir la référence des composants.

Un singleton à l’échelle de la page, par conception

services vit sur globalThis sous Symbol.for("formkrafter.core.services"). Les bundlers se retrouvent couramment avec plusieurs copies d’un module dans une même application : votre bundle importe le core directement, et le bundle Web Components embarque le sien. Le store partagé garantit qu’une surcharge faite depuis votre application est vue par les composants, quelle que soit la copie qui s’exécute.

Attention

Parce qu’il vaut pour toute la page, les services sont une configuration au niveau de l’hôte. Les différences par formulaire appartiennent au spec (le uploadUrl d’une brick, le optionsUrl d’un select), pas à un service que vous permuteriez au fil de l’exécution.

Le registre de bricks et les traductions du chrome suivent le même schéma.

Étapes suivantes

Formulaires imbriquésspecSourceService en pratique : résoudre un formulaire référencé par un autre.

BricksQuelles bricks consomment quel service — file, select, nested-form.

Règles dynamiquesCe qu'exécute jsRunnerService, et ce que le bac à sable autorise.

PackagesD'où chaque type de service est exporté.