Validation sans larmes à l’aide du formulaire Telerik ASP.NET Core

Une caractéristique clé de l’interface utilisateur Telerik pour ASP.NET Core Form est la facilité avec laquelle il est possible d’ajouter des fonctionnalités. Et si vous souhaitez aller un peu plus loin, vous pouvez également ajouter votre propre validation personnalisée.

Question : D’où viennent les bugs ? Réponse : Utilisateurs. Retirez les utilisateurs du système et aucune de vos applications n’aura d’autre bug. Ce n’est bien sûr pas une option, vous devez donc prendre le temps d’ajouter une validation pour empêcher de mauvaises données de s’infiltrer dans votre système… et ce code n’est qu’une autre source potentielle de bugs. De plus, bien sûr, vous devez prendre des dispositions pour informer vos utilisateurs lorsqu’ils ont mal agi. Tout cela va prendre beaucoup de temps et, potentiellement, être douloureux.

Interface utilisateur Progress Telerik pour Composant de formulaire ASP.NET Core accélère la création de formulaires d’acceptation de saisie, vous permet d’implémenter la validation plus facilement et vous permet de le faire de manière déclarative (plutôt que via du code) pour réduire les risques d’introduction de bogues supplémentaires.

Un formulaire par défaut

À titre d’étude de cas, imaginez un formulaire qu’un service RH utilise pour intégrer un nouvel employé. Ce formulaire comportera une variété de contrôles de saisie : zones de texte, cases à cocher, contrôles de date, adresses e-mail, zones de texte, entre autres, qui nécessiteront tous un certain niveau de validation.

La classe modèle pour un Employee et ses classes associées pourraient ressembler à ceci :

class Employee
{
        public int Id { get; set; }
         [Required]
        public string FirstName { get; set; } = string.Empty;
         [Display(Prompt = "Last Name")]
         [Required]
        public string LastName { get; set; } = string.Empty;
         [EmailAddress]
        public string Email { get; set; } = string.Empty;
        public DateTime HireDate { get; set; }
        public int Age {get; set; }
        public string? Notes { get; set; } = string.Empty;
        public bool ImmediatelyAvailable {  get; set; }
        public int Department { get; set;}
}

Configuration d’un projet ASP.NET Core pour utiliser les contrôles Telerik est simple, donc je ne l’examinerai pas ici. Créer une page Razor pour l’utiliser Employee classe comme objet Model pourrait être aussi simple que ceci (et en utilisant cela Employee classe en tant qu’objet Model transmis à une vue MVC serait aussi simple) :

public class IndexModel : PageModel
{
  public Employee employee { get; set; } 

Même la configuration d’un composant Telerik Form dans cette page ou cette vue est simple :

1. Ajouter un forme kendo élément à votre page.
2. Définir la forme kendo name attribut à une chaîne.
3. Attachez la forme kendo à votre modèle via les liens du formulaire. form-data attribut (pour ma page Razor, c’est la propriété de mon employé ; pour une vue MVC, ce serait la propriété Model de la vue).
4. Dans cet élément de forme kendo, ajoutez un élément de formulaire élément pour obtenir un formulaire par défaut.
   Cela signifie ce balisage minimal :

<h1> Add New Employee </h1>
<div style="width:50%">
<kendo-form name="AddEmployee" 
                            form-data="@Model.employee">
    <forms-item/>
</kendo-form>
</div>

vous donnera ce formulaire par défaut (certaines propriétés ennuyeuses omises), complété par les boutons Soumettre et Effacer :

Si vous regardez attentivement cette capture d’écran, vous pouvez voir que ce formulaire par défaut vous a déjà donné une certaine validation contre les mauvaises données : l’âge utilise un sélecteur numérique et la date d’embauche a un sélecteur de date.

Ajout de contrôles de données

Mais même si cela est très pratique (et constitue un moyen rapide de générer une page de démonstration que vous pouvez utiliser dans les discussions avec vos utilisateurs finaux), cela ne sera pas non plus suffisant pour la production. Dans la vraie vie, vous souhaiterez exercer davantage de contrôle sur ce qui est affiché dans votre formulaire et sur la façon dont la saisie de l’utilisateur est validée.

Pour cet exemple, cela peut aller du simple masquage du champ ID de l’employé à l’amélioration de la validation de certains de vos contrôles de saisie. Vous contrôlez cela en ajoutant form-item éléments à l’intérieur de la forme kendo form-items élément.

Par exemple, alors que le FirstName property est affiché sur mon formulaire par défaut, le [Required] attribut d’annotation de données que j’ai sur la propriété dans mon Employee la classe est ignorée.

Pour que la forme kendo applique cet attribut (ou tout autre des attributs d’annotation de données), il me suffit d’ajouter un form-item élément lié au FirstName propriété (cela se fait en définissant l’attribut field de l’élément de formulaire). Dès que vous commencez à utiliser explicitement les éléments d’élément de formulaire, le formulaire kendo arrête de générer automatiquement du code HTML pour les propriétés de votre modèle, ce qui masque efficacement le champ de mon identifiant d’employé. Maintenant, j’ai le contrôle.

Cela signifie que ce balisage :

<form-items>
      <form-item field="FirstName"/>

les deux me donnent plus de contrôle sur le contenu de mon formulaire et invoquent le [Required] annotation de données sur mon prénom. Désormais, si l’utilisateur laisse la zone de texte Prénom vide, le formulaire affiche un message par défaut et ne permettra pas à l’utilisateur de soumettre le formulaire :

Je peux utiliser des éléments supplémentaires dans l’élément form-item pour gérer la propriété. Par exemple, ajouter un item-label L’élément me permet de prendre le contrôle de l’étiquette utilisée pour inviter l’utilisateur à saisir les bonnes données. Je pourrais améliorer le LastName propriété comme celle-ci :

<form-item field="LastName">
  <item-label text="Family Name:" />
</form-item>

Un autre contrôle qui nécessite une validation supplémentaire est la zone de texte Âge : l’éditeur par défaut permet à l’utilisateur de saisir n’importe quel nombre, y compris les nombres négatifs. Vous pouvez éviter cela en ajoutant un élément de formulaire pour la propriété Age et en insérant un éditeur de zone de texte numérique à l’intérieur de cet élément de formulaire (le formulaire kendo prend actuellement en charge plus de deux douzaines d’éditeurs). Avec un éditeur numérique en place, vous pouvez définir ses valeurs minimales et maximales pour contrôler les données que l’utilisateur peut saisir.

Cet exemple restreint l’utilisateur à une plage d’âge raisonnable et définit le format du nombre pour supprimer l’affichage des décimales (cela ne ferait qu’encourager les utilisateurs à essayer de saisir une valeur décimale) :

<form-item field="Age">
  <numerictextbox-editor min="18" 
    max="80"
    format="#"/>
  </numerictextbox-editor>
</form-item>

Par défaut, le numerictextbox-editor et le datepicker-editor corrigera automatiquement toutes les entrées hors limites : dans le champ Mon âge, si l’utilisateur saisit 81 ans comme âge, il sera automatiquement corrigé à 80 sans afficher de message d’erreur. Si vous préférez désactiver cette option et que l’utilisateur reçoive le message, vous pouvez définir le auto-adjust attribuer à false, comme ceci :

<form-item field="Age">
  <numerictextbox-editor min="18" 
    max="80"
	auto-adjust="false"
    format="#"/>
  </numerictextbox-editor>
</form-item>

Comme autre exemple, le contrôle par défaut pour Department n’est vraiment pas satisfaisant pour deux raisons : premièrement, il affiche le DepartmentId plutôt que le DepartmentName et, deuxièmement, il n’empêche pas l’utilisateur de sélectionner des départements valides.

C’est facile à résoudre en ajoutant un élément de formulaire lié au Department propriété et mettre un éditeur-groupe radio à l’intérieur pour limiter l’utilisateur à la liste approuvée des départements :

<form-items>
<form-item field="Department">
        <radiogroup-editor label-position="RadioGroupLabelPosition.Before"
                                                  layout="RadioGroupLayout.Horizontal">
            <kendo-radiogroup-items>
                <kendo-radiogroup-item label="Receiving" value="1" />
                <kendo-radiogroup-item label="Sales" value="2" />
                <kendo-radiogroup-item label="Accounting" value="3" />
            </kendo-radiogroup-items>
        </radiogroup-editor>
</form-item>

Maintenant, la zone d’entrée de mon service ressemble à ceci :

Et j’aurais pu utiliser celui de l’éditeur datasource attribut pour extraire les données d’un service Web plutôt que de coder en dur les valeurs comme je l’ai fait ici.

Comme avantage secondaire, ces contrôles conservent leur apparence et leur comportement sur tous les navigateurs et plates-formes, de sorte que vous offrirez également à vos utilisateurs une expérience cohérente lorsqu’ils passent d’un navigateur ou d’un appareil à un autre.

Configuration de la validation

Après avoir abordé les contrôles que vous souhaitez améliorer (en ajoutant un textbox-editor pour le Notes serait une autre bonne idée), vous pouvez également configurer la manière dont la validation est effectuée au niveau du formulaire à l’aide du formulaire kendo. validatable élément.

Par défaut, par exemple, le formulaire kendo valide le contenu de vos contrôles lorsque l’utilisateur quitte le contrôle (c’est-à-dire lors de l’événement de flou du contrôle), puis à nouveau lorsque l’utilisateur clique sur le bouton Soumettre du formulaire. Le validatable L’élément vous permet de désactiver la validation lorsque l’utilisateur quitte le contrôle et d’appliquer simplement votre validation lorsque l’utilisateur soumet le formulaire.

Vous pouvez également utiliser le validatable élément pour activer un résumé de toutes les erreurs de validation du formulaire. Par défaut, ceci est affiché en haut du formulaire.

Ce balisage fait les deux :

<validatable validate-on-blur="false" 
             validation-summary="true"  />

Le résumé de validation par défaut ressemblera à ceci :

D’ailleurs : L’utilisateur peut cliquer sur les messages d’erreur dans le récapitulatif de validation pour être automatiquement redirigé vers le contrôle avec l’erreur dans le formulaire.

Le validatable l’élément a également un error-template attribut qui vous permet de personnaliser les messages d’erreur affichés sous chaque contrôle et la manière dont ces messages sont affichés. Le modèle reçoit plusieurs paramètres que vous pouvez intégrer dans votre message personnalisé, notamment le message d’erreur par défaut (message) et le Model propriété. Que Model La propriété elle-même possède deux propriétés utiles : l’entrée de l’utilisateur (la value propriété) et le nom de la propriété Modèle (le field propriété).

Cet exemple génère un message d’erreur personnalisé à utiliser avec tous les contrôles du formulaire et modifie également la couleur de la police du message :

<validatable validate-on-blur="true" 
              validation-summary="true"                     
              error-template=
                      "<span style='color: blue'>For #=data.field#, #=data.value# is not acceptable (#=message#)" />

Maintenant, mon message pour un nom manquant ressemble à ceci :

Le validatable L’élément vous permet également de contrôler où et comment le résumé de validation est affiché.

Il n’y a que deux étapes pour y parvenir :

1. Ajoutez un élément à votre page où vous souhaitez que le résumé soit affiché, en définissant les attributs id et style/class de cet élément.
2. Ajoutez un élément de résumé de validation à l’intérieur du validatable élément qui fait référence à votre nouvel élément de résumé de validation par cet attribut id.

Cet exemple place le résumé de validation après la fin du formulaire kendo (c’est-à-dire plus près du bouton de soumission) et définit sa couleur d’arrière-plan sur bleu clair :

    <validatable validate-on-blur="false" 
                 validation-summary="true">
                   <validation-summary container="#errorList"/>
   </validatable>
</kendo-form>

<div id="errorList"
         style="background-color:skyblue"/>

Le résultat ressemblerait à ceci :

Toutes ces options vous permettent à la fois d’empêcher vos utilisateurs de saisir des données erronées et d’indiquer à vos utilisateurs où ils se sont trompés… et tout cela sans écrire une ligne de code. Il faut que vous aimiez ça (enfin, à moins que vous ne soyez payé à l’heure, alors peut-être préféreriez-vous tout faire vous-même).

Voir le Démo du formulaire ASP.NET Coreet essayez tout cela par vous-même, gratuitement pendant 30 jours :

Essayez maintenant