Composants de champ personnalisé

Dashboard > Actions > Forms > Custom field

En utilisant les champs personnalisés, vous pouvez étendre l’aspect et la convivialité de vos formulaires et ajouter une logique puissante avec JavaScript, HTML et CSS. Le champ personnalisé possède des méthodes internes qui facilitent le passage des données vers le formulaire, l’ajout de validations du côté client et dorsales et la gestion d’événements courants tels que le focus ou le brouillage (blur). Vous pouvez personnaliser les champs pour créer :

Des champs avec une structure de données personnalisée.
- Exemple : Objets, tableau de chaînes
Des champs qui utilisent des gadget logiciel tiers.
- Exemple : Remplissage automatique Google Address
Champs dont la logique permet de masquer ou d’afficher d’autres champs.
Champs qui nécessitent des API externes pour obtenir une valeur.

Pour utiliser les champs personnalisés, vous devez activer des Domaines personnalisés. L’affichage d’un formulaire avec un champ personnalisé en dehors d’un domaine personnalisé provoquera une erreur.

Paramètres des champs personnalisés

Les configurations de champ personnalisées sont :

Params

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

Les valeurs des paramètres ne sont disponibles qu’après que le formulaire a invoqué la méthode init().

Exemple : Dans l’exemple ci-dessous, les configurations de champ personnalisé sont remplies avec les paires clé-valeur symbol=\{\{fields.symbol}} et separator=,

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

  function mountComponent() {
    /** getParams() method returns the params you've configured in your input */
    const config = context.custom.getParams();
    const { symbol, separator } = config;

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

  return {
    /** Invoked once when the field is created */
    init() {
      mountComponent();
      return input;
    },
    ...
  };
}

Code source

Ajoutez votre code Javascript au 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;
    }
  };
}

Schéma JSON

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

Exemple :

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

Pour répondre à des exigences de validation complexes, vous pouvez utiliser un flux.

CSS

Ajoutez vos styles CSS au champ personnalisé.

Gestionnaires de champs personnalisés

Vous pouvez utiliser ces gestionnaires pour ajouter des comportements personnalisés aux champs :

init(params?)

Invoqué une fois lorsque le champ est créé et transmet les valeurs des paramètres que vous configurez dans les réglages Params. Renvoie un élément HTML, une chaîne ou aucune valeur.

Paramètre	Description
`params`	Objet facultatif. Paramètres pris à partir des réglages des champs personnalisés.

Exemple :

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

init() {
  return input;
}

update(params?)

Invoqué lorsque l’utilisateur visite à nouveau la même étape du formulaire. Cette option est utile lorsque vous devez restituer la logique de l’interface utilisateur ou actualiser les valeurs des paramètres qui peuvent avoir changé.

Paramètre	Description
`params`	Objet facultatif. Paramètres pris à partir des réglages des champs personnalisés.

onFocus()

Invoquée lorsque le focus entre dans l’élément HTML du champ personnalisé.

onBlur()

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

getValue()

Invoquée lorsque le formulaire doit obtenir la valeur du champ personnalisé une ou plusieurs fois. Cette fonction est généralement exécutée lorsque l’utilisateur soumet le formulaire. Si vous devez effectuer des validations côté client, vous pouvez lancer 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()

Invoquée lorsque le champ personnalisé doit être bloqué. Cette fonction est généralement exécutée lorsque l’utilisateur soumet l’étape du formulaire et que les données sont traitées par notre système dorsal.

unblock()

Invoquée lorsque le champ personnalisé doit être débloqué. Cette fonction est généralement exécutée après que l’utilisateur a soumis le formulaire ou que les données ont cessé d’être traitées par notre système en raison d’une erreur de validation.

getScripts()

Renvoie une liste d’URL que les garanties de formulaire auront fini de charger avant que la méthode init() ne soit invoquée. Exemple :

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

Objet de contexte

Lorsque vous passez 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()

Reçoit la valeur du champ personnalisé actuel.

context.custom.setValue()

Définit une valeur pour le 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 un identifiant unique pour le 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()

Reçoit les paramètres du champ personnalisé actuel.

Les valeurs des paramètres ne sont disponibles qu’après que le formulaire a invoqué la méthode init().

Exemple :

function customInput(context) {
  // Accessing parameters on the root of the function does NOT work
  // 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 de formulaire

Lorsque vous devez interagir avec le formulaire pour recueillir des valeurs dans d’autres champs ou naviguer vers d’autres étapes du formulaire, vous pouvez utiliser les méthodes de formulaire suivantes :

context.form.getId()

Renvoie un identifiant unique pour le formulaire actuel.

context.form.getRoot()

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

context.form.goForward()

Passe à l’étape suivante du formulaire.

context.form.goPrevious()

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

context.form.isValid()

Renvoie une valeur booléenne si le formulaire passe toutes les validations du côté client.

context.form.validate()

Évalue les valeurs des champs existants à l’aide de la validation côté client avant de poursuivre. Si un champ ne passe pas la validation, un message d’erreur apparaît.

context.form.getAllHiddenFields()

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

context.form.setHiddenField(id, value)

Définit une valeur pour le champ masqué.

Paramètre	Description
`id`	Chaîne. L’ID du champ masqué.
`value`	Chaîne. La valeur du champ masqué.

context.form.getValues()

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

context.form.getField(id)

Renvoie une instance pour le champ spécifié.

getNode() | true Renvoie l’élément HTML racine du champ.
getValue() Renvoie la valeur du champ.
setRequired(boolean) Définit ou désactive le champ selon les besoins.

Paramètre	Description
`id`	Chaîne. La valeur de l’ID du champ.

Exemple :

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

setRequired() définit ou désactive le champ comme requis côté client. Par exemple, si vous désactivez un champ qui était requis, mais qu’il a été marqué comme requis dans les paramètres de champ, le formulaire renvoie une erreur si le champ n’a pas de valeur.

Exemples de champs personnalisés

Les sections suivantes offrent des exemples de champs personnalisées que vous pouvez ajouter à vos formulaires :

Champ personnalisé d’entrée de plage

Un champ personnalisé qui renvoie une valeur à partir d’une plage prédéterminée.

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 de 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 de remplissage automatique utilisant les valeurs de l’API

Un champ personnalisé qui renvoie une valeur de remplissage 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 utilisant des valeurs provenant d’une API

Champ personnalisé qui renvoie une valeur à partir d’une liste déroulante dynamique à l’aide d’une API tierce.

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é de saisie dynamique avec un bouton (+) pour ajouter d’autres champs

Un champ personnalisé qui permet aux utilisateurs d’ajouter des champs supplémentaires.

Code source :

function DynamicInputs(context) {
  const DEFAULT_INITIAL_INPUTS = 2;
  const DEFAULT_PLACEHOLDER = 'jane.doe@example.com';
  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);
}

Personnalisation de la marque

Personnalisation du code

Personnalisation tierce

​Paramètres des champs personnalisés

​Params

​Code source

​Schéma JSON

​CSS

​Gestionnaires de champs personnalisés

​init(params?)

​update(params?)

​onFocus()

​onBlur()

​getValue()

​block()

​unblock()

​getScripts()

​Objet de contexte

​Méthodes personnalisées

​context.custom.getValue()

​context.custom.setValue()

​context.custom.createUid()

​context.custom.getParams()

​Méthodes de formulaire

​context.form.getId()

​context.form.getRoot()

​context.form.goForward()

​context.form.goPrevious()

​context.form.isValid()

​context.form.validate()

​context.form.getAllHiddenFields()

​context.form.setHiddenField(id, value)

​context.form.getValues()

​context.form.getField(id)

​Exemples de champs personnalisés

​Champ personnalisé d’entrée de plage

​Champ personnalisé de saisie de couleur

​Champ personnalisé de saisie de remplissage automatique utilisant les valeurs de l’API

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

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

Paramètres des champs personnalisés

Params

Code source

Schéma JSON

CSS

Gestionnaires de champs personnalisés

init(params?)

update(params?)

onFocus()

onBlur()

getValue()

block()

unblock()

getScripts()

Objet de contexte

Méthodes personnalisées

context.custom.getValue()

context.custom.setValue()

context.custom.createUid()

context.custom.getParams()

Méthodes de formulaire

context.form.getId()

context.form.getRoot()

context.form.goForward()

context.form.goPrevious()

context.form.isValid()

context.form.validate()

context.form.getAllHiddenFields()

context.form.setHiddenField(id, value)

context.form.getValues()

context.form.getField(id)

Exemples de champs personnalisés

Champ personnalisé d’entrée de plage

Champ personnalisé de saisie de couleur

Champ personnalisé de saisie de remplissage automatique utilisant les valeurs de l’API

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

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