Champs personnalisés

Les champs personnalisés permettent d'associer des informations supplémentaires à un panier. Ces informations sont réclamées par les différents acteurs du panier (les représentations, évènements, tarifs, modules impliqués, etc.).

Les modules de vente doivent impérativement fournir les valeurs de champs requises pour permettre la validation du panier.

Dans l'API 'Basket', la liste des champs attendus est récupérable via la méthode GetCustomFields, et la transmission des valeurs se fait avec la méthode SetCustomFields.

Modification du panier

Toute modification du panier peut entraîner la modification des champs attendus. Il est donc conseillé d'appeler GetCustomFields/SetCustomFields en fin de parcours, ou à défaut de s'assurer
que les champs requis sont bien renseignés après chaque modification du panier.

Organisation des champs

La méthode GetCustomFields retourne la liste des champs personnalisés attendus pour le panier.
Les informations peuvent être attendues à différents niveaux :

• Globalement, pour tout le panier (la commande : Order)
• Globalement pour le panier, mais spécifiquement rattachées au client (informations client : Customer).
• Au niveau d'un 'produit' particulier (ex: "Le concert du 3 avril à 20h") : Items.
• Au niveau d'un 'produit' à un 'tarif' particulier (ex: "Le concert du 3 avri à 20h" en "tarif réduit") : Items/Lines.
• Au niveau d'un élément spécifique du panier (ex: un billet particulier) : `Items/Lines/Items'.

Ces différents niveaux sont appelés des sections (FieldInventorySection).

Description de l'inventaire des champs

Les champs (FieldInventoryItemInfo) sont regroupés par groupe (FieldInventoryGroupInfo).
Un groupe est un ensemble logique de champs, utilisé principalement pour structurer l'affichage.

Groupe de champs (FieldInventoryGroupInfo)

Propriété	Type	Description
Name	string	Nom interne du groupe de champs. Cette valeur peut être utilisée comme identifiant pour le stockage des valeurs dans les modules qui le souhaitent.
Label	string	Libellé du groupe de champs, destiné à l'affichage.
Description	string	Description du groupe de champs, destiné à l'affichage.
DisplayOrder	int	Ordre d'affichage du groupe de champs au sein de la section parente (du plus petit au plus grand).
IconSvg	string	Eventuel code SVG de l'icône associée au groupe de champs, destinée à l'affichage.
Fields	List<FieldInventoryItemInfo>	Liste des champs appartenant à ce groupe.

Champ personnalisé (FieldInventoryItemInfo)

Propriété	Type	Description
Name	string	Identifiant du champ (unique dans un groupe).
UniqueName	string	Nom unique de la propriété associée au champ personnalisé. Lorsque la valeur est associée à un élément de ligne (Items/Lines/Items), elle doit être spécifiée autant de fois que la quantité associée à la ligne, avec un UniqueName suffixé de $x ou x est l'indice de la valeur (base 0).
Label	string	Libellé du champ dans les formulaires.
Description	string	Description optionnelle du champ dans les formulaires.
PromptMode	FieldPromptModeEnum	Informations sur le mode de saisie/transmission des valeurs. Les valeurs possibles sont : Auto (aucune préconisation, dépend du type d'interface), ShowReadOnly (lecture seule, affichage sans modification), ShowWriteOnly (écriture seule, saisie obligatoire sans pré-remplissage), Hidden (aucun affichage, valeur attendue mais sans saisie utilisateur).
Parameters	FieldDefinitionParameters (voir ci-dessus)	Paramètres de configuration du champ personnalisé.

Paramètres de définition du champ (FieldDefinitionParameters)

Propriété	Type	Description
IsRequired	bool	Indique si le champ est obligatoire.
RequiredMessage	string	Si spécifié, indique le message à afficher si le champ obligatoire n'est pas renseigné.
Validators	List<IFieldValidator> (voir ci-dessous)	Liste des validateurs à appliquer au champ.
ValueType	CustomFieldTypeEnum	Type de valeur du champ personnalisé (String, Number, Boolean, DateTime).
StringKind	StringFieldKindEnum	Type de champ String : indique le genre de la chaîne de caractères attendue (Standard, Email, PhoneNumber, Multiline, Lookup, Url )
DateTimeKind	DateTimeFieldKindEnum	Type de champ DateTime : indique le sous-type (DateOnly, TimeOnly, DateAndTime)
NbDecimals	int?	Type de champ Number : Nombre de décimales à afficher pour les champs numériques.
Tooltip	string	Infobulle affichée à l'utilisateur lors de la saisie.
IconSvg	string	Icône SVG associée au champ pour l'affichage.
DisplayOrder	int	Ordre d'affichage du champ à l'intérieur du groupe (du plus petit au plus grand).
DefaultWidth	FieldSizeEnum	Indication de largeur d'affichage par défaut du champ (Unspefied, Small, Medium, Large, XLarge). Il s'agit d'une indication pouvant être utilisée pour organiser l'interface utilisateur du formulaire; le développeur est libre d'en tenir compte ou non.
IsMultiSelect	bool	Indique si la sélection multiple est autorisée pour les listes de valeurs (Lookup). Si les valeurs multiples sont aurtorisées, elles devront être séparées par une virgule , dans la valeur fournie.
LookupItems	List<LookupFieldItem> (_voir ci-dessous)	Liste des éléments disponibles pour un champ de type lookup.

Validateur de champ (IFieldValidator)

Les validateurs sont utilisés pour vérifier la validité des valeurs saisies dans les champs personnalisés. Un type de validateur est identifié par son nom (Name) et peut posséder un ou plusieurs paramètres de configuration de la validation.

Validateurs pour les champs de type String

Type de validateur (Name)	Paramètres supplémentaires
MinLength	MinLength (int) : longueur minimale autorisée.
MaxLength	MaxLength (int) : longueur maximale autorisée.
Regex	Pattern (string) : expression régulière que la valeur doit respecter. ErrorMessage : message à afficher en cas d'erreur de validation.
MaxLines	MaxLines (int) : nombre maximal de lignes autorisées (pour les champs Multiline).

Validateurs pour les champs de type Number

Type de validateur (Name)	Paramètres supplémentaires
MinValue	MinValue (double) : valeur minimale autorisée.
MaxValue	MaxValue (double) : valeur maximale autorisée.

Validateurs pour les champs de type DateTime

Type de validateur (Name)	Paramètres supplémentaires
MinDateTime	MinDateTime (double) : Date minimale autorisée.
MaxDateTime	MaxDateTime (double) : Date maximale autorisée.

Elément de liste pour les champs Lookup (LookupFieldItem)

Lorsqu'un champ personnalisé est de type Lookup, la liste des valeurs possibles est définie via des éléments LookupFieldItem.

Propriété	Type	Description
Value	string	Valeur interne de l'élément de liste. C'est cette valeur qui doit être renseignée dans le champ de référence lorsque cette ligne est sélectionnée.
Label	string	Libellé de l'élément de liste, destiné à l'affichage.
Description	string	Description optionnelle de l'élément de liste, destinée à l'affichage.
IconSvg	string	Eventuel code SVG de l'icône associée à l'élément de liste, destinée à l'affichage.
DisplayOrder	int	Ordre d'affichage de l'élément de liste (du plus petit au plus grand).

Enregistrement des valeurs des champs personnalisés

Les valeurs des champs personnalisés sont transmises via la méthode SetCustomFields.
Chaque valeur est transmise en utilisant le UniqueName du champ personnalisé comme identifiant, et la valeur associée.
Toutes les valeurs sont placées au même niveau dans le tableau des valeurs, quel que soit le niveau de la section d'origine (commande, client, produit, tarif, élément).

Valeurs associées aux éléments de ligne

Pour les champs personnalisés associés aux éléments de ligne (Items/Lines/Items), la valeur doit être fournie autant de fois que la quantité associée à la ligne, avec un UniqueName suffixé de $x où x est l'indice de la valeur (base 0).
Par exemple, pour une ligne avec une quantité de 3 et un champ personnalisé ayant pour UniqueName la valeur SeatNumber, les valeurs doivent être fournies avec les identifiants suivants : P20$xx$SeatNumber$0, P20$xx$SeatNumber$1, P20$xx$SeatNumber$2.

Exemple de transmission des valeurs des champs personnalisés :

{
  "Order$CustomerNote": "Merci de prendre en compte mes desiderata",
  "Customer$birthDate": "2001-02-10",
  "Item$P20$xx$SeatNumber$0": "A12",
  "Item$P20$xx$SeatNumber$1": "A13",
  "Item$P21$yy$itemNum$0": 123.45,
  "Item$P21$yy$isStudent$1": true  
}