Composants de champ personnalisé

Découvrez comment utiliser des composants personnalisés pour créer des champs qui nécessitent une logique ou une interface utilisateur particulières à l’aide de JavaScript, HTML et CSS.

Le champ personnalisé vous permet d’enrichir l’apparence de vos formulaires et d’ajouter une logique puissante avec JavaScript, HTML et CSS.

Le champ personnalisé comprend des méthodes internes qui facilitent la transmission des données au formulaire, l’ajout de validations côté client et côté serveur, ainsi que la gestion d’événements courants comme focus ou blur.

Vous pouvez utiliser le champ personnalisé pour créer :

• Des champs avec une structure de données personnalisée.

  • Exemple : objets, tableau de chaînes de caractères

• Des champs qui utilisent des widgets tiers.

  • Exemple : autocomplétion d’adresse Google

• Des champs avec une logique permettant de masquer ou d’afficher d’autres champs.

• Des champs qui nécessitent des API externes pour obtenir une valeur.

Pour utiliser des champs personnalisés, vous devez activer les Domaines personnalisés. Le rendu d’un formulaire contenant un champ personnalisé en dehors d’un domaine personnalisé affichera une erreur.

​

Paramètres du champ personnalisé

Les paramètres du champ personnalisé sont les suivants :

​

Params

Ajoutez des paires clé-valeur à utiliser dans le code source du champ personnalisé. Les paires clé-valeur peuvent inclure des variables de champs du formulaire.

Les valeurs des paramètres ne sont accessibles qu’après l’appel de la méthode init() par le formulaire.

Exemple :

Dans l’exemple ci-dessous, les paramètres du champ personnalisé sont définis avec les paires clé-valeur symbol={{fields.symbol}} et separator=,

function CustomComponent(context) {
  const input = document.createElement('input');
  let mask = null;

  function mountComponent() {
    /** La méthode getParams() retourne les params que vous avez configurés dans votre champ */
    const config = context.custom.getParams();
    const { symbol, separator } = config;

    mask = IMask(input,
    {
      mask: `${symbol}num`,
      blocks: {
        num: {
          mask: Number,
          thousandsSeparator: separator,
        }
      }
    });
  }

  return {
    /** Invoqué une seule fois à la création du champ */
    init() {
      mountComponent();
      return input;
    },
    ...
  };
}

​

Code source

Ajoutez votre code Javascript dans le champ personnalisé.

Exemple:

function customInput() {
  const input = document.createElement('input');
  input.type = 'text';

  return {
    init() {
      return input;
    },

    block() {
      input.disabled = true;
    },

    unblock() {
      input.disabled = false;
    },

    getValue() {
      return input.value;
    }
  };
}

​

JSON Schema

Par défaut, le champ personnalisé accepte n’importe quel format de valeur. Toutefois, vous pouvez utiliser JSON Schema pour valider les valeurs côté serveur.

Exemple:

{
  "type": "array",
  "items": {
    "type": "string"
  },
  "minItems": 2
}

Pour gérer des exigences de validation complexes, vous pouvez utiliser un flow.

​

CSS

Ajoutez vos styles CSS dans le champ personnalisé.

​

Gestionnaires de champ personnalisé

Vous pouvez utiliser ces gestionnaires pour personnaliser le comportement du champ :

​

init()

Appelée une seule fois lors de la création du champ et reçoit les valeurs de params que vous configurez dans les paramètres de Params.

Retourne un élément HTML, une chaîne de caractères ou aucune valeur.

Exemple:

const input = document.createElement('input');
input.type = 'text';

init() {
  return input;
}

​

update()

Appelée lorsque l’utilisateur revient à la même étape du formulaire.

Cette option est utile lorsque vous devez relancer la logique de rendu de l’UI ou actualiser les valeurs des params qui ont pu changer.

​

onFocus()

Invoquée lorsque le focus arrive sur l’élément HTML du champ personnalisé.

​

onBlur()

Appelée lorsque le focus quitte l’élément HTML du champ personnalisé.

​

getValue()

Invoquée lorsque le formulaire doit récupérer la valeur du champ personnalisé une ou plusieurs fois. Cette fonction est généralement appelée lorsque l’utilisateur soumet l’étape du formulaire. Si vous devez effectuer des validations côté client, vous pouvez lever une erreur pour afficher un message d’erreur personnalisé à l’utilisateur.

Exemple :

function customTextInput() {
  const input = document.createElement('input');
  input.type = 'text';

  return {
    init() {
      return input;
    },

    getValue() {
      if (input.value !== 'Auth0') {
        throw new Error('The value must be Auth0')
      }

      return input.value;
    }
  };
}

​

block()

Appelée lorsque le champ personnalisé doit être bloqué. Elle est généralement exécutée lorsque l’utilisateur soumet l’étape du formulaire et que les données sont en cours de traitement sur notre backend.

​

unblock()

Appelée lorsque le champ personnalisé doit être débloqué. Cette opération est généralement exécutée après que l’utilisateur a soumis l’étape du formulaire ou que le traitement des données par notre back-end a cessé en raison d’une erreur de validation.

​

getScripts()

Retourne une liste d’URL dont le formulaire garantit le chargement complet avant l’appel de la méthode init().

Exemple :

getScripts() {
  return ['https://example.com/script_a.js', 'https://example.com/script_b.js'];
}

​

Objet de contexte

Lorsque vous transmettez un objet de contexte, vous pouvez utiliser ces méthodes pour gérer la logique de votre formulaire et de vos composants.

​

Méthodes personnalisées

​

context.custom.getValue()

Retourne la valeur du champ personnalisé actuel.

​

context.custom.setValue()

Attribue une valeur au champ personnalisé actuel.

Exemple:

function customInput(context) {
  const input = document.createElement('input');
  input.type = 'text';

  input.addEventListener('change', () => {
    context.custom.setValue(input.value);
  });

  return {
    init() {
      return input;
    },
  };
}

​

context.custom.createUid()

Renvoie l’identifiant unique du champ personnalisé actuel.

Exemple:

function customInput(context) {
  const input = document.createElement('input');
  input.type = 'text';
  input.id = context.custom.createUid();

  return {
    init() {
      return input;
    },

    getValue() {
      return input.value;
    }
  };
}

​

context.custom.getParams()

Récupère les paramètres du champ personnalisé actuel.

Les valeurs des paramètres sont disponibles uniquement après que le formulaire a appelé la méthode init().

Exemple :

function customInput(context) {
  // L'accès aux paramètres à la racine de la fonction ne fonctionne PAS
  // const { defaultValue } = context.custom.getParams();
  // console.log(defaultValue); // undefined

  function buildInput() {
    const { defaultValue } = context.custom.getParams();
    const input = document.createElement('input');
    input.type = 'text';
    input.value = defaultValue;

    return input;
  }

  return {
    init() {
      return buildInput();
    },

    getValue() {
      return input.value;
    }
  };
}

​

Méthodes du formulaire

Lorsque vous devez interagir avec le formulaire pour obtenir les valeurs d’autres champs ou passer à d’autres étapes du formulaire, vous pouvez utiliser les méthodes de formulaire suivantes :

​

context.form.getId()

Renvoie l’identifiant unique du formulaire actuel.

​

context.form.getRoot()

Retourne l’élément HTML racine du formulaire actuel.

​

context.form.goForward()

Passe à l’étape suivante du formulaire.

​

context.form.goPrevious()

Revient à l’étape précédente du formulaire.

​

context.form.isValid()

Retourne un booléen indiquant si le formulaire passe toutes les validations côté client.

​

context.form.validate()

Valide les valeurs de champ existantes au moyen de la validation côté client avant de poursuivre. Si un champ ne satisfait pas à la validation, un message d’erreur s’affiche.

​

context.form.getAllHiddenFields()

Renvoie un objet contenant toutes les valeurs des champs masqués.

​

context.form.setHiddenField(id, value)

Définit la valeur d’un champ masqué.

Paramètre	Description
id	String. L’ID du champ masqué.
value	String. La valeur du champ masqué.

​

context.form.getValues()

Retourne un objet contenant toutes les valeurs des champs, y compris les champs masqués.

​

context.form.getField(id)

Retourne une instance du champ spécifié.

• getNode() | true Retourne l’élément HTML racine du champ.
• getValue() Retourne la valeur du champ.
• setRequired(boolean) Définit ou supprime le caractère obligatoire du champ.

Paramètre	Description
id	*String *. La valeur du champ ID.

Exemple :

const fullName = context.form.getField('full_name');
const fullNameValue = fullName.getValue();
console.log(fullNameValue); // Jean Dupont

setRequired() sert uniquement à définir ou à retirer le caractère obligatoire du champ côté client. Par exemple, si vous retirez le caractère obligatoire d’un champ, mais qu’il est marqué comme obligatoire dans les paramètres du champ, le formulaire renverra une erreur si ce champ n’a aucune valeur.

​

Exemples de champs personnalisés

Les sections suivantes présentent des exemples de champs personnalisés que vous pouvez ajouter à vos formulaires :

​

Champ personnalisé de type plage

Un champ personnalisé qui retourne une valeur dans une plage prédéfinie.

Code source:

function rangeInput() {
  const input = document.createElement('input');
  input.type = 'range';
  input.min= '0';
  input.max= '100';
  input.value = '0';

  return {
    init() {
      return input;
    },

    getValue() {
      return input.value;
    }
  };
}

​

Champ personnalisé de saisie de couleur

Un champ personnalisé qui renvoie une valeur hexadécimale correspondant à une couleur.

Code source:

function colorInput() {
  const input = document.createElement('input');
  input.type = 'color';
  input.value = '#20c5a0';

  return {
    init() {
      return input;
    },

    getValue() {
      return input.value;
    },
  };
}

​

Champ personnalisé de saisie semi-automatique utilisant les valeurs d’une API

Un champ personnalisé qui renvoie une valeur de saisie semi-automatique à l’aide d’une API tierce.

Code source:

function textInputWithAutocomplete(context) {
  const input = document.createElement('input');
  input.type = 'text';

  function populateInputValue(json) {
    const { city } = json;

    input.value = city;
  }

  function fetchIpInfo() {
    const url = 'https://ipinfo.io/json';
    fetch(url)
      .then((res) => res.json())
      .then((json) => populateInputValue(json));
  }

  return {
    init() {
      fetchIpInfo();
      return input;
    },

    getValue() {
      return input.value;
    },
  };
}

​

Champ personnalisé de liste déroulante dynamique avec des valeurs provenant d’une API

Un champ personnalisé qui renvoie une valeur à partir d’une liste déroulante dynamique alimentée par une API tierce partie.

Code source :

function dynamicDropdown() {
  const select = document.createElement('select');
  select.classList.add('af-stringField-input');

  function buildOption(data) {
    const { name: { first } } = data;
    const option = document.createElement('option');
    option.value = first;
    option.innerText = first;

    return option;
  }

  function populateNames(json) {
    const { results } = json;

    results.forEach((o) => {
      const option = buildOption(o);

      select.appendChild(option);
    });
  }

  function fetchNames() {
    const url = 'https://randomuser.me/api/?results=10&inc=name';
    fetch(url)
      .then((res) => res.json())
      .then((json) => populateNames(json));
  }

  return {
    init() {
      fetchNames();
      return select;
    },

    getValue() {
      return select.value;
    },
  };
}

​

Champ personnalisé à saisie dynamique avec un bouton (+) pour ajouter d’autres champs

Un champ personnalisé qui permet aux utilisateurs d’ajouter d’autres champs.

Code source:

function DynamicInputs(context) {
  const DEFAULT_INITIAL_INPUTS = 2;
  const DEFAULT_PLACEHOLDER = '[e-mail]';
  const DEFAULT_ADD_BUTTON_TEXT = 'Add new item';
  const DEFAULT_INPUT_TYPE = 'email';
  const STATE_VALUE = {};
  const FIELD_ID = context.custom.createUid();
  let UUID_COUNTER = 0;
  let INPUTS_COUNTER = 0;

  const container = document.createElement('div');

  const inputsContainer = document.createElement('div');
  container.appendChild(inputsContainer);

  function buildAddNewItem() {
    const config = context.custom.getParams();
    const { add_button_text } = config;

    const ADD_BUTTON_TEXT = add_button_text || DEFAULT_ADD_BUTTON_TEXT;

    const addInputButton = document.createElement('button');
    addInputButton.type = 'button';
    addInputButton.classList.add('af-dynamic-input-add-button');
    addInputButton.id = `${FIELD_ID}_add-input-button`;
    addInputButton.onclick = buildInputContainer.bind(this);

    const addInputButtonIcon = document.createElement('span');
    addInputButtonIcon.classList.add('af-button', 'af-dynamic-input-add-button-icon');
    addInputButtonIcon.innerText = '+';

    const addInputButtonText = document.createElement('span');
    addInputButtonText.classList.add('af-dynamic-input-add-button-text');
    addInputButtonText.innerText = ADD_BUTTON_TEXT;

    addInputButton.appendChild(addInputButtonIcon);
    addInputButton.appendChild(addInputButtonText);
    container.appendChild(addInputButton);
  }

  function removeInput(container, input) {
    delete STATE_VALUE[input.name];
    container.remove();
  }

  function buildRemoveInputButton(container, input) {
    const button = document.createElement('button');
    button.type = 'button';
    button.classList.add('af-button', 'af-dynamic-input-remove-button');
    button.innerText = '-';
    button.onclick = removeInput.bind(this, container, input);

    INPUTS_COUNTER--;

    return button;
  }

  function buildInput() {
    const config = context.custom.getParams();
    const { placeholder, input_type } = config;

    const PLACEHOLDER = placeholder || DEFAULT_PLACEHOLDER;
    const INPUT_TYPE = input_type || DEFAULT_INPUT_TYPE;

    const input = document.createElement('input');
    input.type = INPUT_TYPE;
    input.placeholder = PLACEHOLDER;
    input.classList.add('af-stringField-input');
    input.name = `${FIELD_ID}_${UUID_COUNTER}`;
    input.id = input.name;
    input.addEventListener('change', () => {
      STATE_VALUE[input.name] = input.value;
    });

    UUID_COUNTER++;

    return input;
  }

  function buildInputContainer() {
    const container = document.createElement('div');
    container.classList.add('af-dynamic-input-container');

    const input = buildInput();
    container.appendChild(input);

    const removeButton = buildRemoveInputButton(container, input);
    container.appendChild(removeButton);

    inputsContainer.appendChild(container);

    INPUTS_COUNTER++;
  }

  function initComponent() {
    const config = context.custom.getParams();
    const { initial_inputs } = config;

    const INITIAL_INPUTS = initial_inputs || DEFAULT_INITIAL_INPUTS;
    INPUTS_COUNTER = INITIAL_INPUTS

    for (let i = 0; i < INITIAL_INPUTS; i++) {
      buildInputContainer();
    }
  }

  function blockFields(value) {
    const inputKeys = Object.keys(STATE_VALUE);

    inputKeys.forEach((o) => {
      const selector = document.getElementById(o);
      selector.disabled = value;
    });
  }

  return {
    init() {
      buildAddNewItem();
      initComponent();
      return container;
    },

    block() {
      blockFields(true);
    },

    unblock() {
      blockFields(false);
    },

    getValue() {
      return Object.values(STATE_VALUE);
    },
  };
}

Code CSS :

.af-button.af-dynamic-input-remove-button {
  width: 48px;
  color: var(--button-font-color);
  background: var(--button-background-color);
}

.af-dynamic-input-container {
  display: flex;
  margin-bottom: var(--spacing-1);
}

.af-dynamic-input-container input {
  margin-right: var(--spacing-1);
}

button.af-dynamic-input-add-button {
  background: none;
  border: none;
  padding: 0;
  margin: 0;
  margin-top: var(--spacing-1);
  display: inline-flex;
  cursor: pointer;
  align-items: center;
}

.af-button.af-dynamic-input-add-button-icon {
  background: var(--primary-color);
  width: 24px;
  padding: 0;
  height: 24px;
  border-radius: .3em;
  display: flex;
  justify-content: center;
  align-items: center;
  color: #fff;
  margin-right: var(--spacing-1);
}

.af-dynamic-input-add-button-text {
  color: var(--label-font-color);
  font-size: var(--label-font-size);
}

.af-dynamic-input-add-button:focus {
  outline: none;
}

.af-dynamic-input-add-button:hover .af-button {
  transition: filter var(--transition-normal), box-shadow var(--transition-normal);
  filter: brightness(1.1);
  box-shadow: 0 0 0 var(--outline-width) var(--outline-color), 0px 4px 8px -4px var(--shadow-color), 0px 16px 24px var(--shadow-color);
}

.af-dynamic-input-add-button:focus .af-button {
  box-shadow: 0 0 0 var(--outline-width) var(--outline-color), 0px 4px 8px -4px var(--shadow-color), 0px 16px 24px var(--shadow-color);
}