Avec l'interface JavaScript, vous reliez le configurateur à votre propre logique sur la page : afficher le prix dans votre barre d'achat, reprendre la sélection dans votre propre formulaire, définir des valeurs depuis l'extérieur ou enregistrer une configuration pour la rouvrir plus tard. Le moteur frontend V3 met pour cela à disposition l'objet window.Configento – qu'il arrive sur la page via l'extrait HTML ou via un plugin de boutique. Ce guide montre, à l'aide d'exemples prêts à l'emploi, comment résoudre les tâches courantes et passer à V3 du code écrit pour le moteur Legacy. Chaque méthode avec sa signature, tous les événements, types de données et paramètres figurent dans la Référence de l'API JavaScript (V3).
Où l'interface est disponible
window.Configento existe partout où la page charge le moteur V3 :
| Intégration | Interface JavaScript |
|---|---|
| Extrait HTML (carte HTML5 (V3 Bêta)) | Toujours |
| Shopify | Toujours |
| PrestaShop | Toujours |
| Magento 2 | Si le composant est réglé sur V3 (Bêta) ou nécessite V3, voir Moteur frontend : Legacy ou V3 |
| Shopware 6 et l'extrait HTML5 classique | Non – les deux chargent Legacy |
Les plugins utilisent eux-mêmes l'interface, par exemple pour transmettre le prix et la configuration au panier. Votre propre code s'exécute en parallèle – vous n'avez rien à désactiver.
Premiers pas
<script>
window.addEventListener('DOMContentLoaded', function () {
Configento.ready.then(function () {
var configurateur = Configento.first();
configurateur.on('price', function (p) {
document.querySelector('#mon-prix').textContent = p.total.toFixed(2) + ' ' + p.currency;
});
configurateur.on('change', function () {
console.log('Largeur :', configurateur.getValue('largeur'));
});
});
});
</script>Trois règles qui évitent presque tous les problèmes :
- Attendez
Configento.ready. Ce n'est qu'à ce moment que tous les configurateurs de la page sont chargés. Si vous appelez une méthode avant, elle signale que le configurateur n'est pas encore prêt. window.Configenton'existe qu'une fois le scriptconfigento.jsexécuté. Il est chargé avecdefer, donc après la construction de la page. Lancez donc votre code auDOMContentLoadedou plus tard – pas directement dans un script du<head>.- Le configurateur ne cherche ses emplacements qu'une seule fois, au chargement : chaque élément portant
data-configento. Les éléments que votre code insère plus tard ne sont pas reconnus.
Vous désignez les caractéristiques par leur nom interne (ID) et les valeurs par le champ Valeur. Les ID numériques fonctionnent également.
Charger plus vite et réserver la place
Trois réglages sur l'élément portant data-configento aident lors de la construction de la page :
| Attribut | Effet |
|---|---|
data-configento-min-height="640px" |
Réserve la hauteur pendant le chargement du configurateur – la page en dessous ne saute pas lorsque la première étape apparaît. Ensuite, la hauteur s'adapte de nouveau. |
data-configento-min-height-keep |
Conserve la hauteur également après le chargement |
data-configento-component-json='{…}' |
Le composant directement dans la page, exactement tel que GET /api/v3/components/{id} le renvoie. La requête au chargement n'a alors plus lieu. Utile uniquement si votre page maintient à jour côté serveur la version publiée – après la publication, la page doit livrer la nouvelle version. |
Dans l'attribut JSON data-configento-config, ils s'appellent minHeight, minHeightKeep et component.
Il est en outre utile d'ajouter dans le <head> une indication qui demande au navigateur d'établir tôt la connexion au cloud :
<link rel="preconnect" href="https://cloud.configento.app" crossorigin>Le configurateur charge le composant dès le démarrage du script. Les visiteurs récurrents ne le rechargent pas : s'il n'a pas changé depuis leur dernière visite, le serveur se contente de le confirmer brièvement.
Afficher le prix dans votre barre d'achat
window.addEventListener('DOMContentLoaded', function () {
Configento.ready.then(function () {
var k = Configento.first();
var champ = document.querySelector('#prix-barre-achat');
k.on('price', function (p) {
champ.textContent = p.total.toLocaleString('fr-FR', { style: 'currency', currency: p.currency });
});
});
});price arrive une fois juste après le chargement, puis à chaque changement de prix. Sans code personnel, data-configento-price-mount="#prix-barre-achat" fonctionne aussi – le configurateur dessine alors lui-même le prix dans votre élément.
Reprendre la sélection dans votre propre formulaire
Pour une demande via votre propre formulaire, vous vérifiez la configuration avec finalize() et écrivez le résultat dans des champs masqués :
<form id="demande" action="/demande" method="post">
<input type="hidden" name="configuration">
<input type="hidden" name="recapitulatif">
<input type="hidden" name="reference">
<input type="hidden" name="prix">
<button type="submit">Demander un devis</button>
</form>
<script>
document.querySelector('#demande').addEventListener('submit', function (e) {
e.preventDefault();
var formulaire = e.target;
var k = Configento.first();
k.finalize().then(function (resultat) {
if (!resultat.ok) return; // les erreurs sont maintenant affichées sur la caractéristique
formulaire.configuration.value = JSON.stringify(resultat.payload);
formulaire.recapitulatif.value = k.getSummary({ format: 'text', separator: '\n' });
formulaire.reference.value = k.getCombinedSku();
formulaire.prix.value = resultat.priceTotal;
formulaire.submit();
});
});
</script>finalize() affiche sur la caractéristique les champs obligatoires manquants et les erreurs issues des règles, exactement comme le bouton d'action, mais n'envoie rien lui-même. getCombinedSku() renvoie la référence combinée à partir des valeurs choisies, p. ex. CL-W-GR ; elle figure aussi sous _combined_sku dans resultat.payload.
Présélectionner des valeurs
Vous désignez les caractéristiques par leur nom interne et les valeurs par le champ Valeur :
Configento.ready.then(function () {
var k = Configento.first();
k.selectValue('couleur', 'anthracite'); // sélection, boutons radio, liste avec images
k.toggleValue('accessoires', 'manivelle'); // case à cocher, sélection multiple
k.setText('largeur', '120'); // champ de saisie
k.setQuantity('vis', 'm6', 4); // sélection multiple avec quantités
});Chaque appel agit comme un clic de votre client : règles, formules et prix sont recalculés. Avec resetSelection('couleur'), vous réinitialisez une caractéristique.
Depuis l'adresse : voici comment reprendre ?couleur=anthracite&largeur=120 :
var parametres = new URLSearchParams(location.search);
if (parametres.has('largeur')) k.setText('largeur', parametres.get('largeur'));
if (parametres.has('couleur')) k.selectValue('couleur', parametres.get('couleur'));Variante changée dans la boutique : si des formules dépendent d'attributs de produit comme la largeur ou le poids, transmettez les nouvelles valeurs avec k.setProductAttributes({ largeur: '140' }). La sélection est conservée, tout est recalculé. Les valeurs initiales se placent lors de l'intégration dans l'attribut JSON, sous "productAttributes".
Changer de langue
Si le choix de la langue est activé, showLanguageSelect() affiche à nouveau les drapeaux – p. ex. pour un bouton « Changer de langue » :
<button type="button" onclick="Configento.first().showLanguageSelect()">Changer de langue</button>La sélection actuelle du configurateur est conservée ; après le nouveau choix, il continue dans la nouvelle langue. Sans choix de la langue activé, ou pour un composant avec une seule langue, rien ne se passe. Vous pouvez aussi appeler la méthode avant que le configurateur soit chargé.
Piloter l'assistant et les groupes
Avec la disposition Onglets et dans l'Assistant, le configurateur affiche toujours un groupe. Avec ces méthodes, vous construisez votre propre affichage des étapes :
<ol id="etapes"></ol>
<script>
Configento.ready.then(function () {
var k = Configento.first();
var liste = document.querySelector('#etapes');
function dessiner() {
var actif = k.getActiveGroup();
liste.innerHTML = '';
k.getGroups().forEach(function (groupe) {
var point = document.createElement('li');
point.textContent = groupe.title;
if (actif && groupe.id === actif.id) point.className = 'actif';
point.onclick = function () { k.setActiveGroup(groupe.id); };
liste.appendChild(point);
});
}
dessiner();
k.on('group', dessiner); // après chaque changement d'étape
k.on('change', dessiner); // les règles peuvent afficher et masquer des groupes
});
</script>getGroups() renvoie les groupes affichés avec id, key, index et title, getActiveGroup() le groupe actuel. setActiveGroup() change de groupe par ID ou nom interne et, en avançant, vérifie chaque étape du parcours comme Suivant ; nextGroup() et prevGroup() correspondent à Suivant et Retour.
key est le nom interne du groupe. Vous le définissez dans l'éditeur, dans les paramètres du groupe, sous Nom interne (ID), p. ex. vehicule. Contrairement à la position, il reste identique lorsque vous réordonnez les groupes ou qu'une règle masque un groupe, et il se lit mieux dans le code qu'un numéro. L'élément du groupe affiché le porte en outre sous la forme data-configento-group-key.
Votre propre vérification avant le changement d'étape
Avec setStepGuard(), vous effectuez votre propre vérification avant que votre client ne passe à la suite – par exemple une date de naissance ou un numéro d'identification du véhicule. Elle s'exécute après la vérification intégrée des champs obligatoires, et uniquement en avançant :
k.setStepGuard(function (etape) {
if (etape.from.key !== 'titulaire') return true;
if (estMajeur(k.getValue('date_naissance'))) return true;
return [{ characteristic: 'date_naissance', message: 'Le titulaire doit être majeur.' }];
});true laisse passer le client, false le retient sans message, une liste le retient et affiche chaque message sur la caractéristique indiquée. La fonction peut aussi renvoyer une promesse, p. ex. pour une vérification via le réseau ; jusqu'à la réponse, Suivant et Retour sont bloqués. Si elle lève une erreur, l'étape change malgré tout – votre client ne doit pas rester bloqué.
Désactiver la navigation intégrée
Si vous construisez vous-même l'affichage des étapes, masquez celui qui est intégré :
data-configento-wizard-nav |
Effet |
|---|---|
full (par défaut) |
Onglets, barre de progression, Retour et Suivant |
buttons |
Uniquement Retour et Suivant |
none |
Rien de tout cela – votre code pilote les étapes |
Le même réglage existe dans l'éditeur sous Paramètres → Général → Disposition du groupe → Navigation de l'assistant (V3) ; l'attribut sur l'élément est prioritaire.
Enregistrer et rouvrir une configuration
storeAsset() enregistre la configuration actuelle et renvoie { id, url }. Avec l'id, vous construisez un lien profond : l'adresse de la page produit avec ?dl= et l'id. Si quelqu'un ouvre cette adresse, V3 restaure de lui-même la configuration dans le premier configurateur de la page.
k.storeAsset().then(function (enregistre) {
var lien = new URL(location.href);
lien.searchParams.set('dl', enregistre.id);
navigator.clipboard.writeText(lien.toString());
}).catch(function (erreur) {
if (erreur instanceof Configento.CloudError && erreur.code === 'NO_SELECTIONS') {
alert('Veuillez d’abord faire une sélection.');
}
});Restaurer vous-même – p. ex. dans un configurateur précis parmi plusieurs :
Configento.loadAsset(id, { instance: k }).then(function (donnees) {
k.restoreFromAssetJson(donnees);
});Rien ne peut être enregistré dans l'aperçu de l'administration (CONFIG_MISSING) ; testez sur votre site web ou dans la boutique. Tous les codes d'erreur figurent dans la référence.
Fenêtre personnalisée pour le choix d'images
Certaines caractéristiques ouvrent une fenêtre, p. ex. une liste avec images en grand format. Par défaut, V3 dessine cette fenêtre lui-même. Si elle doit ressembler aux fenêtres de votre boutique, passez un adaptateur :
Configento.setModalAdapter({
openOverlay: function (args) {
// args.title, args.container (rempli par le configurateur), args.onClose
var fenetre = maBoutique.ouvrirFenetre(args.title, args.container, args.onClose);
return { close: function () { fenetre.fermer(); } };
}
});Insérez args.container dans votre fenêtre et appelez args.onClose() lorsque votre client la ferme. Le configurateur appelle close() lorsqu'il veut fermer la fenêtre lui-même. Définissez l'adaptateur dès que window.Configento existe et avant que votre client n'ouvre une fenêtre. Le plugin Magento fournit déjà un adaptateur pour les fenêtres de Magento.
Migrer depuis Legacy
Le moteur Legacy avait sa propre interface, plus ancienne : des paramètres dans l'objet _configentoSettings, l'objet CONFIGENTO_PRODUCT, des objets globaux comme Justselling_Configento_App_Api et des événements jQuery comme configentoUpdateOptionsInDomAfter. Si vous passez à V3, trois choses changent :
- Intégration : au lieu de
_configentoSettingsethtml5.js, vous utilisez l'extrait V3 avec des attributsdata-configento-*. La marche à suivre est décrite dans Intégration extrait HTML. Le jeton est différent ; il provient de la carte HTML5 (V3 Bêta). - Votre propre code : il s'adresse désormais à
window.Configento– ou continue de fonctionner via le script de compatibilité. - Fonctions : ce que seul Legacy sait faire est décrit dans Moteur frontend : Legacy ou V3.
Paramètres
Legacy (_configentoSettings) |
V3 |
|---|---|
_template |
data-component-id |
_customer |
data-configento-customer |
_token |
data-configento-token – nouveau jeton de la carte HTML5 (V3 Bêta) |
_cloudbase |
data-configento-cloud-base-url |
_taxrate |
data-configento-tax-rate |
_currencyCode |
data-configento-currency |
_cssPathCombinedImage ou .configento-combinedImage |
data-configento-combined-image-mount |
Élément #configento-price |
data-configento-price-mount |
Élément #configurator1 |
Un élément portant data-configento |
_loadjQuery, _loadChart, _loadDropzone |
Supprimés – V3 apporte tout et n'a pas besoin de jQuery |
Vous n'avez plus besoin de _debug, _development, _cloudport et _productOptionId.
Voie 1 : script de compatibilité
Les thèmes de boutique en particulier ont accumulé au fil des ans du code qui accède aux anciens objets. Pour qu'il continue de fonctionner sous V3, chargez en plus configento-compat.js avant configento.js :
<script src="https://cloud.configento.app/configento-v3/configento-compat.js" defer></script>
<script src="https://cloud.configento.app/configento-v3/configento.js" defer></script>Le plugin Magento le charge de lui-même avec V3. Le script prend en charge :
| Legacy | Ce que le script en fait |
|---|---|
Événements configentoUpdateOptionsInDomBefore/…After et configentoUpdateHeaderInDomBefore/…After |
Sont déclenchés sur document à chaque modification – accessibles avec jQuery .on() et avec addEventListener |
CONFIGENTO_PRODUCT.setPrice(prix) |
Est appelé avec le prix total à chaque changement de prix – à condition que votre page définisse CONFIGENTO_PRODUCT |
Élément #configurator1 |
Devient l'emplacement du configurateur ; l'ID du composant provient de CONFIGENTO_PRODUCT.getTemplateId() |
Justselling_Configento_App_Helper.getConfigurator(), getBackendUrl() |
Renvoient le configurateur V3 ou l'adresse du cloud |
Justselling_Configento_App_Webshop.finalizeAction(termine) |
Vérifie avec finalize(), écrit la configuration dans les champs de formulaire masqués du panier, puis appelle termine |
Justselling_Configento_App_CloudAsset.storeCloudAsset(…) |
Enregistre avec storeAsset(). Le rappel ne reçoit que l'ID, pas le dossier ni le nom de fichier. |
Justselling_Configento_App_Wizard.validateForm() et les autres fonctions de vérification |
Renvoient toujours true – la vérification a lieu lors de la conclusion |
Justselling_Configento_App_Wizard.setActivateGroup(numero) |
Passe au groupe situé à cette position, sans vérification |
setDisableGroup, setEnableGroup, updateWizard |
Ne font rien |
Si votre code a déjà défini lui-même l'un de ces objets, votre version est conservée.
Ce que le script ne prend pas en charge : il ne lit pas _configentoSettings et ne crée pas CONFIGENTO_PRODUCT – sur une page HTML simple, c'était jusqu'ici le rôle de html5.js. Vous y avez donc besoin dans tous les cas des attributs data-configento-*. Ne sont pas non plus pris en charge Justselling_Configento_App_Api, Justselling_Configento_App_Summary et tous les autres événements. Pour ceux-ci, il existe les équivalents ci-dessous.
Voie 2 : réécrire pour la nouvelle interface
À long terme, le code utilisant window.Configento est plus clair : il reçoit les contenus avec les événements, lève des erreurs compréhensibles et ne dépend pas des ID d'éléments. Voici la correspondance entre anciens et nouveaux appels – tout le nouveau code se place dans Configento.ready.then(…), sur un configurateur k = Configento.first() :
| Legacy | V3 |
|---|---|
Justselling_Configento_App_Helper.getConfigurator() |
Configento.first() ou Configento.forElement(…) |
Justselling_Configento_App_Api.getOptionValue(caracteristique) |
k.getValue('caracteristique') |
Justselling_Configento_App_Api.setOptionValue(caracteristique, valeur), setOptionValues([…]) |
Selon le type de donnée, k.selectValue(), k.toggleValue(), k.setText() ou k.setQuantity() |
Justselling_Configento_App_Api.setEventHook(…) |
k.on('change', …) – de même price, finalize, error et group |
setEventHook('configentoValidateGroupBefore', fn) (empêcher le changement d'étape) |
k.setStepGuard(fn) |
getConfigurator().getActiveGroup() |
k.getActiveGroup() |
Justselling_Configento_App_Wizard.setActivateGroup(numero) |
k.setActiveGroup(id ou nom interne) |
Événement configentoSetActiveGroupAfter |
k.on('group', …) |
CONFIGENTO_PRODUCT.setPrice(prix) |
k.on('price', function (p) { … p.total … }) – ou data-configento-price-mount |
Justselling_Configento_App_Summary.getSummaryAsText() |
k.getSummary() |
Justselling_Configento_App_Wizard.validateForm() |
k.finalize() → ok |
Justselling_Configento_App_Webshop.finalizeAction(termine) |
k.finalize().then(…) |
Justselling_Configento_App_CloudAsset.storeCloudAsset(…) |
k.storeAsset() → { id, url } |
Champ #configurator1-header ou generateHeaderValue() |
k.getHeaderValue() (Base64, comme avant) ou k.getAssetPayload() (JSON) |
Événements configentoUpdateOptionsInDomAfter, configentoUpdateHeaderInDomAfter, configentoApiSetOptionValueAfter |
k.on('change', …) |
Événement configentoRenderSummaryAfter |
k.on('change', …) et, à l'intérieur, k.getSummary() |
Événement configentoFinalizeActionAfter |
k.on('finalize', …) |
Événements configentoRenderAfter, configentoLoadTemplateAfter |
Configento.ready |
| Événements liés aux graphiques, images d'aperçu et téléversements de fichiers | Pas d'équivalent |
?dl=… et ?tb=1 dans l'adresse |
Inchangés |
Présélectionner des caractéristiques via l'adresse, p. ex. ?largeur=120 |
Non intégré – quelques lignes, voir Présélectionner des valeurs |
Comment présélectionner des caractéristiques via l'adresse est montré dans Présélectionner des valeurs.
Différence pour les événements : les événements Legacy ne déclenchaient que des gestionnaires jQuery et ne fournissaient généralement aucune donnée. Les événements V3 transmettent directement la nouvelle sélection ou le nouveau prix – vous n'avez plus rien à lire dans le DOM.
Dépannage
Configento is not defined– votre code s'exécute avant queconfigento.jssoit chargé. Lancez-le auDOMContentLoadedet attendezConfigento.ready. Vérifiez aussi que la page charge bien V3 (voir plus haut).Configento instance not readylors de l'appel d'une méthode – le configurateur est encore en cours de chargement. N'appelez les méthodes que dansConfigento.ready.then(…).Configento.first()renvoienull– la page ne contient aucun élément portantdata-configento, ou il n'a été inséré qu'après le chargement.- Un appel comme
selectValue()déclenche une erreur – le nom interne ou la valeur est incorrect, ou le type de donnée ne correspond pas à la méthode. Les majuscules et minuscules comptent ; vous trouvez le nom dans l'éditeur sous Nom interne (ID). storeAsset()signaleCONFIG_MISSING– rien ne peut être enregistré dans l'aperçu de l'administration. Testez sur votre site web ou dans la boutique.- L'ancien code du thème déclenche des erreurs comme
Justselling_Configento_App_Wizard is not defined– le script de compatibilité manque ou se trouve aprèsconfigento.js.