Référence de l'API JavaScript (V3)

Cette référence décrit chaque méthode, chaque événement et chaque paramètre que le moteur frontend V3 met à disposition sur window.Configento – avec signature, valeur renvoyée, cas d'erreur et un court exemple. Elle s'adresse aux développeurs de thèmes de boutique, de plugins et d'intégrations personnalisées. Le guide Interface JavaScript (V3) montre comment résoudre les tâches courantes et migrer depuis du code Legacy.

Les signatures sont écrites en notation TypeScript. Tout fonctionne aussi en JavaScript pur.

Cycle de vie

1. La page charge https://cloud.configento.app/configento-v3/configento.js (avec defer).
2. Le script crée window.Configento, recherche une seule fois tous les éléments portant data-configento et enregistre une instance pour chacun. Son id est l'id de l'élément, sinon configento-anon-<n>.
3. Pour chaque instance, le chargement du composant démarre aussitôt (ou le composant intégré est utilisé, voir component).
4. Dès qu'un composant est chargé, son instance reçoit les méthodes ci-dessous. Avant, elles lèvent Configento instance not ready — await Configento.ready first.
5. Configento.ready est résolue lorsque toutes les instances de la page sont chargées.

Les éléments qui n'arrivent dans la page qu'après l'étape 2 ne sont pas reconnus. Une référence d'instance reste valable pendant tout le chargement : si vous détenez Configento.instances.get(id) avant ready, le même objet reçoit ensuite les vraies méthodes.

Global : window.Configento

Propriété / méthode	Type	Description
version	string	Version du moteur, p. ex. 3.1.0
frontendVersionTag	'v3'	Identifiant de la génération du moteur. Testez cette valeur, et non version, si votre code ne fonctionne qu'avec une génération.
ready	Promise<void>	Résolue lorsque toutes les instances sont chargées
instances	ReadonlyMap<string, ConfiguratorInstance>	Toutes les instances, la clé étant l'id de l'instance
first()	ConfiguratorInstance ou null	La première instance de la page
forElement(el)	(el) => ConfiguratorInstance (ou null) ; el est un HTMLElement ou une string	L'instance correspondant à un élément ou à un sélecteur CSS ; cherche aussi vers l'extérieur (closest('[data-configento]'))
loadAsset(id, opts?)	(id: string, opts?: { instance?: ConfiguratorInstance }) => Promise<AssetPayload>	Lit une configuration enregistrée, voir Enregistrer et charger
setModalAdapter(adapter?)	(adapter?: ModalAdapter) => void	Fenêtre personnalisée pour les images en grand format, voir Adaptateur de fenêtre modale
registerRenderer(name, renderer)	(name: string, renderer: CharacteristicRenderer) => () => void	Rendu personnalisé de caractéristiques, voir Rendu personnalisé. Renvoie une fonction de désinscription.
CloudError	Classe	Classe d'erreur de storeAsset() et loadAsset(), voir CloudError

window.addEventListener('DOMContentLoaded', async () => {
  await Configento.ready;
  const k = Configento.forElement('#product-form');
});

Instance : ConfiguratorInstance

Propriétés (lecture seule) :

Propriété	Type	Description
id	string	id de l'instance
componentId	string ou null	ID du composant
element	HTMLElement	L'élément portant data-configento
config	WebshopConfig ou null	Les paramètres au chargement, figés – voir Intégration

Vous indiquez les caractéristiques par leur nom interne (string) ou leur ID numérique (CharacteristicRef), les valeurs par le champ Valeur (string) ou leur ID numérique (ValueRef). Un nom inconnu, une valeur inconnue ou un type de donnée inadapté lève une Error.

Lire

getValue(characteristic): unknown

Valeur d'une caractéristique sous la forme que voient aussi les formules :

Caractéristique	Résultat	Vide
Sélection, boutons radio, liste avec images	Champ Valeur de l'entrée choisie (sans valeur : son ID)	null
Sélection multiple, case à cocher	Liste des valeurs	[]
Champs de saisie	Texte, sans espaces en début et en fin	''
Sélection multiple avec quantités	{ [ID de valeur]: quantité }	{}
Formule, liste de prix, combinaison, attribut de produit, service web	Résultat du calcul	null

Une caractéristique qu'une règle masque renvoie toujours « vide ».

k.getValue('largeur');      // → '120'
k.getValue('accessoires');  // → ['manivelle', 'telecommande']

getSelections(): SelectionsMap

La sélection actuelle de toutes les caractéristiques sous la forme { [ID de caractéristique]: sélection } – voir Sélection. Les caractéristiques qu'une règle masque n'y figurent pas ; les valeurs bloquées sont retirées.

getState(): ConfiguratorSnapshot

{
  selections: SelectionsMap;                     // comme getSelections()
  evaluated: Record<number, number | string | null>;  // résultats de tous les calculs par ID de caractéristique
  hiddenCharacteristics: number[];               // caractéristiques masquées par des règles
  blacklistedValues: number[];                   // valeurs bloquées par des règles
  price: PriceSnapshot;                          // comme getPriceBreakdown()
  characteristicPrices: Record<string, number>;  // supplément par caractéristique, par nom interne
}

Simple requête – peut être appelée aussi souvent que nécessaire. characteristicPrices indique ce que chaque caractéristique ajoute à price.total, dans la devise et sur la base fiscale de la boutique. Les caractéristiques sans part de prix, sans nom interne ou masquées par une règle n'y figurent pas.

getPriceBreakdown(): PriceSnapshot

{ total: number; currency: string; priceIncludesTax: boolean }

total est déjà converti selon le taux de taxe et la devise de la boutique (data-configento-tax-rate, data-configento-currency).

getSummary(opts?): string

Option	Par défaut	Effet
format	'text'	'html' renvoie <dl><dt>Caractéristique</dt><dd>Valeur</dd>…</dl>
includePrices	false	Supplément de la caractéristique après la valeur, comme dans characteristicPrices ; les caractéristiques sans supplément n'en ont pas
separator	'; '	Séparateur au format texte

Ne contient que les caractéristiques visibles. Si le composant affiche la référence combinée dans le récapitulatif, elle figure à la fin.

k.getSummary({ format: 'html', includePrices: true });

getCombinedSku(): string

Référence du produit configuré à partir des numéros d'article des valeurs choisies, reliés par -, p. ex. CL-W-GR-TXT. Pour chaque caractéristique, dans l'ordre du composant : le numéro d'article de la valeur choisie (pour une sélection multiple, le premier disponible), sinon celui de la caractéristique. Les parties vides sont omises, les caractéristiques masquées ne comptent pas. '' si rien ne porte de numéro d'article. Si elle n'est pas vide, elle figure aussi sous _combined_sku dans chaque payload de commande.

getCharacteristics(): CharacteristicInfo[]

Décrit toutes les caractéristiques du composant dans leur ordre – indépendamment des règles et de la sélection. Vous lisez ainsi la classe CSS et les champs personnalisés des caractéristiques et des valeurs.

type CharacteristicInfo = {
  id: number;
  key: string | null;          // nom interne, clé dans getAssetPayload()
  groupId: number;
  groupKey: string | null;
  title: string;
  type: string;                // par ex. 'radiobuttons', 'text'
  visibility: 'visible' | 'hidden' | 'shop' | 'backend';
  cssClass: string;            // champ « Classe CSS » tel que saisi, '' si vide
  customFields: { [numéroDuChamp]: CustomField };
  values: Array<{
    id: number;
    key: string | null;        // value de la valeur
    label: string;
    sku: string | null;
    customFields: { [numéroDuChamp]: CustomField };
  }>;                          // toutes les valeurs, y compris bloquées ; vide pour les champs de saisie
};

CustomField est décrit sous Entrée de la payload. Trouver une valeur d'après le contenu d'un champ :

const couleur = k.getCharacteristics().find((c) => c.key === 'couleur');
const valeur = couleur.values.find((v) =>
  Object.values(v.customFields).some((f) => f.id === 'checkout-titel' && f.value === 'Rouge'));

La classe du champ Classe CSS peut aussi servir de valeur de contrôle pour votre propre script. Un rendu personnalisé ne s'applique que si exactement ce nom est enregistré avec registerRenderer().

getAssetPayload(): AssetPayload | null

La configuration en JSON, classée par noms internes – la même forme que finalize().payload, mais sans vérification. null tant que rien n'est sélectionné. Elle contient toujours tous les groupes, pas seulement celui affiché, dans l'ordre du composant. Les champs par caractéristique sont décrits sous Entrée de la payload. Outre les caractéristiques, elle contient _component_title, _locale, le cas échéant _combined_sku et – pour les composants avec Captcha – altcha.

getHeaderValue(opts?): string | null

La même configuration encodée en Base64 (compatible UTF-8) – la forme que les plugins de boutique transmettent au panier et que Legacy avait dans le champ configurator1-header. Avec opts.assets (résultat de storeCombinedImage() sous la forme { type: 'imgData', id, url, file }), la liste d'images est ajoutée ; le plugin Magento, par exemple, y lit l'image du panier.

Modifier

Méthode	Signature	Pour
selectValue	(characteristic, value) => void ; value peut être null	Sélection, boutons radio, liste avec images. null vide la sélection.
toggleValue	(characteristic, value) => void	Case à cocher, sélection multiple, liste avec images à sélection multiple
setText	(characteristic, text: string) => void	Champs de saisie
setQuantity	(characteristic, value, quantity: number) => void	Sélection multiple avec quantités ; les quantités négatives deviennent 0
resetSelection	(characteristic) => void	Tous les types de données ; les règles peuvent ensuite présélectionner à nouveau la caractéristique
setProductAttributes	(attributes: Record<string, string>) => void	Remplace les valeurs des attributs de produit, p. ex. après un changement de variante. Peut aussi être appelée avant ready.
showLanguageSelect	() => void	Affiche à nouveau le choix de la langue (uniquement avec languageSelect et plusieurs langues) ; la sélection est conservée

Chaque modification agit comme une saisie du client : règles, formules et prix sont recalculés, puis suivent change et – si le prix change – price.

Conclure

finalize(): Promise<FinalizeResult>

Vérifie toute la configuration comme un clic sur le bouton d'action et affiche les erreurs sur la caractéristique.

{
  ok: boolean;
  validationErrors: ValidationError[];
  payload?: AssetPayload;        // uniquement si ok
  priceTotal: number;
  summary: string;               // texte, 1024 caractères au maximum
  combinedImage?: string;        // PNG en URL de données si le composant a une image combinée
}

finalize() n'envoie rien et déclenche ensuite l'événement finalize.

Enregistrer et charger

Méthode	Signature	Description
storeAsset	() => Promise<{ id: string; url: string }>	Enregistre la configuration. id est la clé du lien profond, url l'adresse du fichier JSON enregistré.
Configento.loadAsset	(id, { instance? }) => Promise<AssetPayload>	Lit une configuration enregistrée. Sans instance, la première s'applique.
restoreFromAssetJson	(payload) => void	Transfère dans l'instance une configuration lue
storeCombinedImage	() => Promise<{ id: string; url: string }> (ou null)	Enregistre l'image de produit combinée pour le panier ou la commande ; null si le composant n'en a pas

Si quelqu'un ouvre la page produit avec ?dl=<id> (ou ?configento_asset=<id>), V3 restaure de lui-même la configuration dans le premier configurateur. Pour d'autres paramètres ou un autre configurateur, appelez vous-même loadAsset() et restoreFromAssetJson().

const { id } = await k.storeAsset();
const lien = new URL(location.href);
lien.searchParams.set('dl', id);

storeAsset() et loadAsset() ont besoin des paramètres de la boutique (ID client, jeton). Dans l'aperçu de l'administration, elles lèvent donc CONFIG_MISSING. Le configurateur ne relance pas de lui-même les téléversements échoués – sinon des entrées en double seraient créées.

Groupes et assistant

Méthode	Signature	Description
getGroups	() => GroupInfo[]	Groupes affichés, dans l'ordre ; ceux masqués par des règles n'y figurent pas
getActiveGroup	() => ActiveGroup (ou null)	Groupe affiché ; null avec Aucun groupe ou un seul groupe
setActiveGroup	(ref, opts?: { validate?: boolean }) => Promise<boolean> ; ref est un number ou une string	Change de groupe par ID ou nom interne. En avançant, vérifie chaque étape du parcours (validate: false l'évite) et interroge le step guard. true si l'étape a changé.
nextGroup	() => Promise<boolean>	Comme Suivant
prevGroup	() => Promise<boolean>	Comme Retour – sans vérification
setStepGuard	(guard, opts?: { backward?: boolean }) => void ; guard est un StepGuard ou null	Votre propre vérification avant le changement

type GroupRef   = { id: number; key: string | null; index: number };
type GroupInfo  = GroupRef & { title: string; characteristics: string[] };
type ActiveGroup = GroupRef & { total: number };

type StepGuard = (step: { from: GroupRef; to: GroupRef; direction: 'forward' | 'back' | 'jump' })
  => boolean | void | Array<{ characteristic: number | string; message: string }>
   | Promise<boolean | void | Array<{ characteristic: number | string; message: string }>>;

key est le nom interne du groupe défini dans l'éditeur, index la position parmi les groupes affichés. characteristics liste les noms internes des caractéristiques du groupe dans l'ordre d'affichage – les clés sous lesquelles elles figurent dans getAssetPayload(). Les caractéristiques masquées par des règles restent dans la liste, celles sans nom interne n'y figurent pas. Vous pouvez ainsi structurer votre propre récapitulatif par étape sans gérer la correspondance dans votre code :

const payload = k.getAssetPayload() ?? {};
for (const group of k.getGroups()) {
  const rows = group.characteristics
    .map((name) => payload[name])
    .filter((entry) => entry && entry.visibility !== 0);
  // group.title comme titre, rows comme lignes
}

Le step guard s'exécute après la vérification intégrée, par défaut uniquement en avançant. false retient l'étape sans message, une liste la retient et affiche chaque message sur la caractéristique (code d'erreur guard). Tant qu'une promesse est en attente, Suivant et Retour sont bloqués. Si le guard lève une erreur, l'étape change malgré tout.

En outre, une règle d'erreur dont « Exécuter lorsque » vaut Assistant et dont le Type d'erreur est Erreur retient l'étape à laquelle elle appartient.

Événements

on(event, callback) renvoie une fonction de désabonnement. Les écouteurs restent abonnés même si l'instance est reconnectée en interne (p. ex. lorsque des valeurs de service web arrivent plus tard).

Événement	Quand	Contenu
change	Après chaque modification de la sélection	{ selections: SelectionsMap } – comme getSelections()
price	Lorsque le prix total, la devise ou la base de taxe changent ; une fois juste après le chargement	{ total, currency, priceIncludesTax, delta } – delta par rapport au prix précédent
finalize	Lorsque finalize() est terminé	FinalizeResult
error	Lorsque des erreurs apparaissent sur la caractéristique	{ errors: ValidationError[] }
group	Après chaque changement du groupe affiché, pas lors du premier affichage	{ from, to, direction } ; to est un GroupRef, from un GroupRef ou null
action	Quand la requête d'un bouton d'action est terminée – aussi en cas de statut d'erreur ou d'erreur réseau, mais pas quand la vérification des saisies arrête le clic (alors error) – pour l'action Transmettre à la page (event), en revanche, dès que les saisies sont vérifiées, avant l'envoi	ActionEvent, voir ci-dessous

onChange(callback) est l'ancienne forme de on('change', …) sans contenu et sera supprimée.

ActionEvent

Champ	Signification
ok	true pour un statut HTTP 2xx. Toujours true pour event
status	Statut HTTP de la réponse, 0 sans réponse (erreur réseau). 0 pour event
body	Réponse du point de terminaison : sous forme d'objet si c'est du JSON, sinon sous forme de texte ; null pour un PDF ou sans réponse. null pour event
characteristic	Nom interne du bouton d'action
action	custom_url, pdf, email ou event (action Transmettre à la page)
payload	Uniquement pour event : la configuration à envoyer, avec la solution du Captcha sous altcha
preventDefault()	Le bouton n'affiche alors ni sa ligne de succès ni sa ligne d'erreur et ne redirige pas. Un téléchargement de PDF démarre quand même.
defaultPrevented	true si un écouteur a appelé preventDefault()

Pour event, le bouton attend la promesse que renvoie votre écouteur : { ok: true, message } affiche un succès (avec votre message, s'il est indiqué), { ok: false, message } affiche votre message comme erreur, une promesse rejetée affiche son texte d'erreur. Si l'écouteur ne renvoie rien, cela compte comme un succès. Depuis la version 3.2.0.

Depuis la version 3.1.0.

Types de données

Sélection

SelectionsMap est { [ID de caractéristique]: sélection } ; selon le type de donnée, une sélection est :

kind	Champs	Caractéristiques
single	valueId (number ou null), qty?: number	Sélection, boutons radio, liste avec images
multi	valueIds: number[], qtys?: { [ID de valeur]: number }	Case à cocher, sélection multiple
text	value: string	Champs de saisie
quantities	quantities: { [ID de valeur]: number }	Sélection multiple avec quantités
files	files: Array<{ id, folder, type, … }>	Téléchargement de fichier
captcha	payload: string	Captcha

Entrée de la payload

Chaque caractéristique figure dans getAssetPayload() et finalize().payload sous son nom interne. Ces champs sont garantis :

Champ	Type	Présent
label	string	Toujours. Titre de la caractéristique dans la langue du configurateur.
value	voir ci-dessous	Toujours.
valueLabel	voir ci-dessous	Toujours. Libellé de la valeur ou saisie.
visibility	number	Toujours. Suit la Visibilité de la caractéristique : 1 Oui (visible), 3 Backend uniquement, 0 Non (masqué) ou masquée par une règle.
valueId	number, null ou number[]	Pour les caractéristiques avec valeurs.
choiceSku	string ou string[]	Pour les caractéristiques avec valeurs. En sélection simple uniquement si la valeur choisie a une référence ; dans les tableaux, '' représente les valeurs sans référence.
valueQty	number ou number[]	Toujours pour la sélection multiple avec quantités, sinon uniquement si une quantité est définie sur la caractéristique.
sku	string	Si la caractéristique elle-même a une référence.
files	Array<{ id, folder, type, … }>	Pour le téléchargement de fichier.
customFields	{ [numéro du champ]: CustomField }	Si la caractéristique a des champs personnalisés.
choiceCustomFields	{ [numéro du champ]: CustomField }	Pour sélection, boutons radio et Package, si la valeur choisie a des champs personnalisés.

Selon le type de donnée :

Caractéristiques	value	valueLabel	valueId
Sélection, boutons radio, Package	string – value de la valeur, '' sans sélection	string	number, null sans sélection
Case à cocher, sélection multiple, liste avec images	string[]	string[]	number[]
Sélection multiple avec quantités	string[]	string[]	number[], plus valueQty: number[] à la même position
Champs de saisie	string	string (comme value)	–
Formule, Combinaison simple, Attribut de produit, Service web	string – le résultat, '' sans résultat	string	–
Téléchargement de fichier	string – noms de fichiers séparés par des virgules	string[]	–

Une liste avec images renvoie toujours des tableaux, même si une seule valeur peut être choisie. Une caractéristique masquée par une règle garde sa clé, mais vide : value et valueLabel valent '', visibility vaut 0, les autres champs sauf sku et customFields sont absents.

CustomField vaut { value: string; title: string; id: string } : value est le texte saisi (y compris ''), title le nom du champ défini dans les paramètres du composant et id en est dérivé – sans espaces ni caractères spéciaux, en minuscules, par ex. Checkout-Titel → checkout-titel. La clé est le numéro du champ. C'est la même forme que dans Legacy ; le plugin Magento reprend les deux champs dans la commande.

Absents de la payload : les caractéristiques avec la visibilité Boutique uniquement, celles sans nom interne ainsi que les champs statiques, graphiques, boutons d'action et Captchas. Les prix par caractéristique ne figurent pas dans la payload – getState().characteristicPrices les fournit.

ValidationError

{ characteristicId: number; altTitle: string; code: string; message: string }

message est déjà traduit dans la langue du configurateur. code est l'un des suivants : required, pattern, range, length, numeric, integer, gt-zero, gte-zero, email, url, zip, phone, iban, bic, vat, code, alpha, alphanum, data, lowercase, uppercase, rule (règle d'erreur), guard (step guard).

CloudError

storeAsset() et loadAsset() rejettent avec une Configento.CloudError : code, retryable et, pour les erreurs HTTP, status.

code	Signification	retryable
NO_SELECTIONS	Rien n'est encore sélectionné	non
CONFIG_MISSING	Pas de paramètres de boutique (aperçu de l'administration) ou pas d'instance	non
HTTP_4XX	Refusé, p. ex. jeton ou domaine	non
HTTP_5XX	Erreur du serveur	oui
BAD_RESPONSE	Réponse inattendue	non
NETWORK	Pas de connexion, CORS, certificat	oui
NOT_FOUND	La configuration enregistrée n'existe pas	non

try {
  await k.storeAsset();
} catch (err) {
  if (!(err instanceof Configento.CloudError)) throw err;
  if (err.retryable) planifierNouvelEssai();
}

Intégration : attributs et JSON

Chaque paramètre se définit soit comme attribut sur l'élément portant data-configento, soit comme clé dans l'attribut JSON data-configento-config. Si les deux sont présents, le JSON l'emporte.

Attribut	Clé JSON	Valeur
data-component-id	componentId	ID du composant – obligatoire
data-configento-customer	customer	ID client
data-configento-token	token	Jeton de la carte HTML5 (V3)
data-configento-token-endpoint	tokenEndpoint	Adresse qui délivre des jetons de courte durée (plugins de boutique). Si l'ID du composant (?id=) manque dans l'adresse, le configurateur l'ajoute lui-même.
data-configento-cloud-base-url	cloudBaseUrl	cloud.configento.app
data-configento-asset-base-url	assetBaseUrl	Hôte des configurations enregistrées (plugins de boutique)
data-configento-tax-rate	taxRate	Taux de taxe de la boutique en pourcentage
data-configento-currency	currency	Code de devise, p. ex. EUR
data-configento-currency-rates	currencyRates	Taux de change en JSON, p. ex. {"CHF": 0.94}
data-configento-locale	uiLocale	Langue, p. ex. de_DE
data-configento-content-locale	contentLocale	Langue différente uniquement pour les textes du composant
data-configento-embed-mode	embedMode	storefront (par défaut avec les attributs) ou admin-preview
data-configento-price-mount	priceMount	Sélecteur CSS pour le prix total
data-configento-summary-mount	summaryMount	Sélecteur CSS pour le récapitulatif
data-configento-summary-open	summaryOpen	Récapitulatif déplié ou replié au départ
data-configento-combined-image-mount	combinedImageMount	Sélecteur CSS pour l'image de produit combinée
data-configento-language-select	languageSelect	Choix de la langue avant le configurateur
data-configento-language-select-title	languageSelectTitle	Texte au-dessus du choix de la langue
data-configento-languages	languages	Langues proposées, séparées par des virgules (JSON : liste)
data-configento-min-height	minHeight	Hauteur réservée pendant le chargement, p. ex. 640px
data-configento-min-height-keep	minHeightKeep	Conserver la hauteur également après le chargement
data-configento-wizard-nav	wizardNav	full, buttons ou none
data-configento-component-json	component	Le composant lui-même, tel que GET /api/v3/components/{id} le renvoie
–	productAttributes	Valeurs des attributs de produit, p. ex. {"largeur": "120"}

Les attributs oui/non acceptent true/false, 1/0, yes/no ou l'attribut sans valeur pour « oui ». Les valeurs inconnues laissent la valeur par défaut en place et produisent un avertissement dans la console.

Affichage lors de l'intégration par attributs : en mode storefront, le configurateur n'affiche ni le prix total ni le récapitulatif – la boutique a les siens. Avec price-mount et summary-mount, vous les placez à l'endroit de votre choix. Si un sélecteur ne trouve aucun élément, la partie n'apparaît nulle part, plutôt qu'en double dans le configurateur. summary-open n'agit qu'avec summary-mount ; le récapitulatif y démarre déplié par défaut.

Demander le jeton plus tôt : avec tokenEndpoint, le configurateur ne demande son jeton qu'après son chargement. C'est plus rapide si la page lance cette requête dès le <head> et dépose la promesse sous window.ConfigentoTokenPrefetch, avec exactement l'URL de tokenEndpoint comme clé. Le configurateur reprend ce résultat une fois. Si la promesse renvoie null, une erreur ou aucun token, il fait lui-même la demande. Ainsi, seule l'URL figure dans la page, jamais un jeton – ce qui est compatible avec les caches de page. Le plugin Magento le fait de lui-même à partir de la version 5.0.0-beta22.

<script>
  (window.ConfigentoTokenPrefetch ||= {})['https://shop.example/configento/v3/token/id/42/'] =
    fetch('https://shop.example/configento/v3/token/id/42/', { method: 'POST', credentials: 'omit' })
      .then((r) => (r.ok ? r.json() : null))
      .catch(() => null);
</script>

Adaptateur de fenêtre modale

interface ModalAdapter {
  openOverlay(args: { title: string; container: HTMLElement; onClose: () => void }): { close(): void };
}

Le configurateur remplit container après le retour d'openOverlay. Votre adaptateur l'insère dans une fenêtre qui lui est propre et appelle onClose() lorsque le client la ferme. Le configurateur appelle close() lorsqu'il ferme lui-même la fenêtre (p. ex. après la sélection). Définissez l'adaptateur dès que window.Configento existe et avant qu'une fenêtre ne s'ouvre ; setModalAdapter() sans argument rétablit la fenêtre intégrée.

Script de compatibilité

https://cloud.configento.app/configento-v3/configento-compat.js – chargé avant configento.js – fait correspondre les objets globaux du moteur Legacy (Justselling_Configento_App_*, CONFIGENTO_PRODUCT.setPrice, les événements configentoUpdate…InDom…) à cette interface. Ce qu'il prend en charge en détail et comment réécrire l'ancien code est décrit dans le guide sous Migrer depuis Legacy.

Rendu personnalisé

Avec Configento.registerRenderer(name, renderer), votre code dessine lui-même une caractéristique. Si name figure dans le champ Classe CSS d'une caractéristique, le configurateur affiche à la place de l'élément de saisie un conteneur vide (div.cfg-custom avec data-configento-renderer="<name>"). Le configurateur ne touche jamais à son contenu. Votre code définit les valeurs via ctx – règles, prix, vérification, assistant, récapitulatif et commande fonctionnent comme pour une saisie du client.

interface CharacteristicRenderer {
  replace?: 'body' | 'all';     // par défaut 'body'
  combine?: boolean;            // par défaut false
  mount(el: HTMLElement, ctx: RendererContext): void;
  update?(ctx: RendererContext, el: HTMLElement): void;
  destroy?(el: HTMLElement): void;
}

Élément	Signification
name	Nom de classe composé de minuscules, de chiffres et de -. Une classe parmi plusieurs dans le champ Classe CSS suffit. Un second registerRenderer portant le même nom remplace le premier.
replace: 'body'	Le configurateur continue d'afficher le titre, l'astérisque obligatoire, le texte d'information et les messages d'erreur ; le conteneur se trouve dans .cfg-char__body.
replace: 'all'	Le conteneur est le seul enfant de .cfg-char. Vous affichez vous-même le titre et les erreurs à partir de ctx.
combine: true	Toutes les caractéristiques visibles du même groupe portant cette classe deviennent un seul widget, à l'emplacement de la première. Les autres n'affichent rien, mais restent prises en compte dans les règles, la vérification, le prix et la commande. Leurs erreurs apparaissent regroupées sur le widget.
mount	Une fois, dès que le conteneur est dans le DOM
update	Lorsque quelque chose change dans ctx : sélection, erreurs, valeurs autorisées, prix, langue. Pas lors de modifications d'autres caractéristiques.
destroy	Avant que le conteneur ne disparaisse : changement d'étape dans l'assistant, une règle le masque, désinscription. Ensuite, les méthodes de ce ctx n'ont plus d'effet. Si la caractéristique réapparaît, un nouveau mount suit.

ctx :

Propriété / méthode	Contenu
characteristic	La caractéristique, avec combine la première
characteristics	Toutes les caractéristiques du widget, sinon uniquement characteristic
locale	Langue du configurateur, p. ex. fr_FR
instance	L'instance, voir plus haut. Ses méthodes ne fonctionnent qu'après Configento.ready.
selectValue(valeur, caracteristique?), toggleValue(valeur, caracteristique?), setText(texte, caracteristique?), setQuantity(valeur, quantite, caracteristique?), reset(caracteristique?)	Comme les méthodes de même nom de l'instance. Sans caracteristique, c'est characteristic qui s'applique ; sinon uniquement une caractéristique de characteristics.

Chaque caractéristique dans ctx possède : id, key (nom interne), type, title, info (HTML), required, selection (comme getValue()), errors (ValidationError[]), values et, pour les champs de saisie, textConstraints (minLength, maxLength, validator). values ne contient que les valeurs autorisées ; celles bloquées par des règles en sont absentes. Chaque valeur possède id, key (champ Valeur), label, info, image, price (supplément dans la devise et la base de taxe de la boutique), priceLabel (formaté comme dans le configurateur, vide si aucun n'est affiché) et selected.

S'inscrire avant le bundle : si votre script s'exécute avant configento.js, déposez le renderer sous (window.ConfigentoRenderers ||= {})[name] = renderer. Les renderers inscrits plus tard fonctionnent également : les caractéristiques déjà affichées basculent immédiatement.

Solution de repli : si aucun renderer n'est inscrit – p. ex. dans l'aperçu de l'administration –, la caractéristique affiche le rendu intégré. Si mount ou update lève une erreur, le configurateur l'écrit dans la console et affiche de nouveau l'élément de saisie intégré pour cette caractéristique. Valable uniquement pour V3.

Mise en forme avec CSS

Vous adaptez les couleurs, la police et les coins via des variables comme --configento-color-accent, et des éléments individuels via des classes garanties comme .cfg-toggle-item__label. Les deux sont décrits sur la page Personnaliser le design (CSS).

Versions et engagements

Configento.version suit le Semantic Versioning. Les corrections de bogues changent le dernier chiffre, les nouvelles fonctions celui du milieu, et seul un nouveau premier chiffre casse du code existant – avec un guide de migration.

Appuyez-vous sur les méthodes, événements et types de données de cette page – y compris les champs sous Entrée de la payload – et sur les variables et classes décrites sous Personnaliser le design (CSS), et non sur d'autres classes ou le reste de la structure DOM du configurateur. Les attributs data-configento-group-id et data-configento-group-key sont également stables.

Étapes suivantes

• Interface JavaScript (V3) – guide avec exemples
• Intégration extrait HTML
• Téléversements & liens profonds
• Moteur frontend : Legacy ou V3