Champs

Définition et configuration des champs de formulaire.

Vue d'ensemble

Les champs (fields) sont les éléments fondamentaux d'un formulaire qui permettent de collecter, stocker et afficher les données. Chaque champ possède un type, des propriétés et des options qui définissent son comportement et son affichage.

Un champ est défini par la classe FormularField et stocké dans la table FormularFields de la base de données.

Caractéristiques principales

Type de données : Détermine le format et la validation (texte, nombre, date, etc.)
Options : Configurent le comportement spécifique (obligatoire, multiple, ressource annuaire, etc.)
Nom technique : Identifiant unique du champ dans le formulaire
Label : Libellé affiché à l'utilisateur
Colonne SQL : Correspondance avec la structure de base de données

Types de champs

Types disponibles

Process Studio supporte plusieurs types de champs définis par l'énumération FieldType :

public enum FieldType
{
    /// <summary>
    /// Texte, Liste, Case à cocher, Bouton radio, Zone de texte, ...
    /// </summary>
    Text = 1,

    /// <summary>
    /// Nombre, Devise, ...
    /// </summary>
    Number = 2,

    /// <summary>
    /// Date, Heure
    /// </summary>
    Date = 3,

    /// <summary>
    /// Texte enrichi
    /// </summary>
    RichText = 5,

    /// <summary>
    /// Champ virtuel lié à DocumentObjects.FieldName
    /// </summary>
    File = 6,
}

Type Text (1)

Le type Text est le plus polyvalent et supporte de nombreuses variantes :

Zone de texte simple : Saisie d'une ligne de texte
Zone de texte multi-lignes : Saisie de texte sur plusieurs lignes
Liste déroulante : Sélection d'une valeur parmi une liste
Case à cocher : Valeur booléenne
Bouton radio : Choix unique parmi plusieurs options
Ressource annuaire : Sélection d'utilisateur, rôle ou service

Type Number (2)

Le type Number permet la saisie de valeurs numériques :

Nombre entier : Sans décimales
Nombre décimal : Avec virgule
Devise : Montant avec formatage monétaire

Type Date (3)

Le type Date gère les informations temporelles :

Date : Jour/mois/année
Heure : Heures/minutes/secondes
Date et heure : Combinaison des deux

Type RichText (5)

Le type RichText permet la saisie de texte formaté avec :

Mise en forme (gras, italique, souligné)
Listes à puces ou numérotées
Insertion d'images
Liens hypertexte

Type File (6)

Le type File est un champ virtuel lié à la gestion des pièces jointes du document.

Propriétés d'un champ

Propriétés de base

Chaque champ possède les propriétés suivantes :

public string Id { get; set; }              // Identifiant unique
public string Name { get; set; }            // Nom technique du champ
public string Label { get; set; }           // Libellé affiché
public string IdLabel { get; set; }         // ID de localisation
public string Description { get; set; }     // Description du champ
public FieldType Type { get; set; }         // Type de champ
public FieldSystemFlag SystemFlag { get; set; } // Standard ou Système
public DicoApsOptions ApsOptions { get; private set; } // Options du champ

Champs système vs. champs standard

Les champs sont distingués par le flag FieldSystemFlag :

public enum FieldSystemFlag
{
    /// <summary>
    /// Champ défini avec Process.Studio via le concepteur de formulaire
    /// </summary>
    Standard = 0,

    /// <summary>
    /// Champ système géré par l'application
    /// </summary>
    System = 1,
}

Champs système : Gérés automatiquement par l'application (created_by, modified_by, reference, etc.)

Champs standard : Créés par les concepteurs via Process Studio

Options des champs

Concept des options

Les options (ApsOptions) sont des paramètres configurables qui modifient le comportement d'un champ. Elles sont stockées dans un dictionnaire Dictionary<string, IApsOption>.

Options principales

Option Multiple

Permet à un champ de contenir plusieurs valeurs :

public static bool IsMultiple(DicoApsOptions apsOptions)
{
    return HasOption(apsOptions, "Multiple");
}

Utilisation :

Sélection multiple d'utilisateurs
Liste de valeurs multiples
Stockage dans une table de détails

Option IsDirectoryResource

Indique qu'un champ représente une ressource de l'annuaire :

public static bool IsDirectoryResource(string fieldName, DicoApsOptions apsOptions)
{
    if (fieldName.Equals("created_By", StringComparison.InvariantCultureIgnoreCase) ||
        fieldName.Equals("modified_By", StringComparison.InvariantCultureIgnoreCase) ||
        fieldName.Equals("created_by_new", StringComparison.InvariantCultureIgnoreCase))
    {
        return true;
    }
    return
        apsOptions.Any(
            kp =>
                kp.Value.Name == "IsDirectoryResource" &&
                ((ApsOptionBool)kp.Value).GetValue());
}

Comportement :

Active le sélecteur d'annuaire (DirectoryPicker)
Permet la sélection d'utilisateurs, rôles, services
Stocke le DN (Distinguished Name) de la ressource

Autres options courantes

Required : Champ obligatoire
ReadOnly : Champ en lecture seule
Hidden : Champ masqué
DefaultValue : Valeur par défaut
MaxLength : Longueur maximale
Separator : Séparateur pour valeurs multiples
TechnicalField : Champ technique (non affiché)

Création de champs

Procédure dans Process Studio

Ouvrir le formulaire dans Process Studio
Accéder à l'onglet Champs
Cliquer sur Nouveau champ
Configurer les propriétés :
- Label : Libellé affiché
- Nom technique : Identifiant (auto-généré ou personnalisé)
- Type : Sélectionner le type de champ
- Description : Description optionnelle
Configurer les options selon le type
Valider

Génération automatique du nom technique

Le nom technique est généré automatiquement à partir du label :

Suppression des accents
Remplacement des espaces par des underscores
Conversion en format valide pour SQL

Exemple : "Date de création" → "Date_de_creation"

Configuration des options

Les options varient selon le type de champ sélectionné. L'interface affiche :

Mode simple : Options courantes et fréquemment utilisées
Mode avancé : Toutes les options disponibles

Champs et base de données

Correspondance avec le schéma SQL

Chaque champ non-multiple correspond à une colonne dans la table principale FRM_NomFormulaire :

Propriété champ	Colonne SQL	Type SQL
Name	Nom de colonne	Selon type
Type = Text	NVARCHAR	Texte
Type = Number	DECIMAL	Numérique
Type = Date	DATETIME	Date/heure
Type = RichText	NTEXT	Texte long

Champs multivalués

Les champs avec l'option Multiple génèrent une table de détails séparée :

FRM_NomFormulaire              Table principale
FRM_NomFormulaire_NomChamp     Table de détails pour le champ multiple

Structure de la table de détails :

id : Identifiant unique de la ligne
id_document : Référence vers le document parent
value : Valeur du champ

Champs spéciaux

Champs ressource annuaire

Les champs de type ressource annuaire permettent de sélectionner des éléments depuis l'annuaire organisationnel :

Types de ressources :

user : Utilisateurs
role : Rôles
service : Services
company : Sociétés

Configuration :

// Vérifier si un champ est une ressource annuaire
bool isDirectory = FormularField.IsDirectoryResource(fieldName, apsOptions);

Stockage :

CN (Common Name) : Format court (cn=jdupont)
DN (Distinguished Name) : Format complet (cn=jdupont,ou=users,dc=domain)

Champs de liste de valeurs

Les champs peuvent être liés à une liste de valeurs centralisée :

Liste simple (valeurs fixes)
Liste hiérarchique (arborescence)
Liste dynamique (requête SQL)

Validation et contraintes

Validation côté serveur

Les champs peuvent avoir des règles de validation :

// Vérifier la présence d'une option
public static bool HasOption(DicoApsOptions apsOptions, string name)
{
    return apsOptions.Any(kp => kp.Value.Name == name);
}

Contraintes d'intégrité

Obligatoire : Valeur requise pour enregistrer
Unique : Pas de doublons autorisés
Format : Expression régulière
Plage : Minimum/Maximum pour nombres et dates

Utilisation avancée

Champs calculés

Les champs peuvent contenir du code C# pour calculer automatiquement leur valeur :

// Exemple : calcul automatique d'une date d'échéance
return DateTime.Now.AddDays(30);

Champs conditionnels

L'affichage et le comportement des champs peuvent dépendre d'autres champs :

Masquage/affichage conditionnel
Caractère obligatoire conditionnel
Lecture seule conditionnelle

Recherche de champs dans requête SQL

Méthode pour extraire les noms de champs d'une requête SQL :

public static IEnumerable<string> FindFieldsInQueryAndReplaceByParams(
    string query, 
    out string queryWithParam)
{
    const string pattern = @"\$(?<fieldName>\w+)\$";
    var matches = Regex.Matches(query, pattern, RegexOptions.ExplicitCapture);
    queryWithParam = Regex.Replace(query, pattern, m => "@" + m.Result("$1"));
    return matches.Cast<Match>().SelectMany(
        match => match.Groups["fieldName"].Captures.Cast<Capture>(),
        (match, capture) => capture.Value).Distinct();
}

Utilisation :

SELECT * FROM FRM_Ref WHERE Aps_Societe = $Aps_Societe$

Devient :

SELECT * FROM FRM_Ref WHERE Aps_Societe = @Aps_Societe

Localisation des listes de valeurs

Les valeurs de liste peuvent être localisées :

public static string[] GetValueListLocalizedText(
    string helperFuncDeclare, 
    string[] fieldValues)
{
    // Récupération des textes localisés pour les valeurs de liste
}

Bonnes pratiques

Nommage des champs

Utiliser des noms explicites : Préférer DateEcheance à Date1
Éviter les caractères spéciaux : Pas d'accents ni de caractères réservés SQL
Respecter les conventions : PascalCase ou snake_case
Préfixer si nécessaire : Pour grouper logiquement les champs

Organisation

Regrouper les champs par thématique : Utiliser des composants
Limiter le nombre de champs : Créer plusieurs pages si nécessaire
Documenter les champs techniques : Ajouter une description claire

Performance

Indexer les champs de recherche : Pour améliorer les performances des vues
Limiter les champs RichText : Peuvent ralentir l'affichage
Utiliser les tables de détails avec parcimonie : Impact sur les performances

Maintenance

Ne pas supprimer de champs contenant des données : Risque de perte d'information
Tester les modifications : Vérifier l'impact sur les documents existants
Versionner les formulaires : Utiliser le versioning pour tracer les modifications

Vue d'ensemble​

Caractéristiques principales​

Types de champs​

Types disponibles​

Type Text (1)​

Type Number (2)​

Type Date (3)​

Type RichText (5)​

Type File (6)​

Propriétés d'un champ​

Propriétés de base​

Champs système vs. champs standard​

Options des champs​

Concept des options​

Options principales​

Option Multiple​

Option IsDirectoryResource​

Autres options courantes​

Création de champs​

Procédure dans Process Studio​

Génération automatique du nom technique​

Configuration des options​

Champs et base de données​

Correspondance avec le schéma SQL​

Champs multivalués​

Champs spéciaux​

Champs ressource annuaire​

Champs de liste de valeurs​

Validation et contraintes​

Validation côté serveur​

Contraintes d'intégrité​

Utilisation avancée​

Champs calculés​

Champs conditionnels​

Recherche de champs dans requête SQL​

Localisation des listes de valeurs​

Bonnes pratiques​

Nommage des champs​

Organisation​

Performance​

Maintenance​

Références​

Classes et interfaces principales​

Tables de base de données​

Documentation associée​