Fonctions EditForm, NewForm, SubmitForm, ResetForm et ViewForm

  • Article

S’applique à : Applications canevas

Affichez, modifiez ou créez un élément, enregistrez le contenu et réinitialisez les contrôles dans un contrôle Edit form.

Vue d’ensemble

Ces fonctions modifient l’état du contrôle Edit Form. Le contrôle Form peut être dans un des modes suivants :

Mode Description
FormMode.Edit Le formulaire est rempli avec un enregistrement actuel et l’utilisateur peut modifier les valeurs des champs. Une fois qu’il a terminé, l’utilisateur peut enregistrer les modifications apportées à l’enregistrement.
FormMode.New Le formulaire est rempli avec les valeurs par défaut et l’utilisateur peut modifier les valeurs des champs. Une fois qu’il a terminé, l’utilisateur peut ajouter l’enregistrement à la source de données.
FormMode.View Le formulaire est rempli avec un enregistrement actuel mais l’utilisateur ne peut pas modifier les valeurs des champs.

Description

Ces fonctions sont souvent appelées à partir de la formule OnSelect d’un contrôle Button ou Image, afin que l’utilisateur puisse enregistrer ou abandonner des modifications, ou créer un enregistrement. Vous pouvez utiliser des contrôles avec ces fonctions, afin de créer une solution complète.

Ces fonctions ne renvoient aucune valeur.

Utilisez ces fonctions ensemble uniquement dans les formules de comportement.

SubmitForm

Utilisez la fonction SubmitForm dans la propriété OnSelect d’un contrôle Button pour enregistrer les modifications apportées dans un contrôle Form au sein de la source de données.

Avant de soumettre des modifications, cette fonction vérifie les problèmes de validation associés aux champs signalés comme obligatoires, ou dont la valeur présente une ou plusieurs contraintes. Ce comportement correspond à celui de la fonction Validate.

La fonction SubmitForm vérifie également la propriété Valid du formulaire, qui regroupe toutes les propriétés Valid des contrôles Card que contient le contrôle Form. En cas de problème, les données ne sont pas envoyées et les propriétés Error et ErrorKind du contrôle Form sont définies en conséquence.

Si la validation réussit, la fonction SubmitForm soumet la modification à la source de données.

  • En cas de réussite, le comportement OnSuccess du formulaire est exécuté et les propriétés Error et ErrorKind sont effacées. Si le formulaire a adopté le mode FormMode.New, il revient au mode FormMode.Edit.
  • En cas d’échec, le comportement OnFailure du formulaire est exécuté et les propriétés Error et ErrorKind sont définies en conséquence. Le mode du formulaire reste le même.

EditForm

La fonction EditForm remplace le mode du contrôle Form par FormMode.Edit. Dans ce mode, le contenu de la propriété Item du contrôle Form est utilisé pour remplir le formulaire. Si la fonction SubmitForm s’exécute lorsque le formulaire est dans ce mode, un enregistrement est modifié, et non créé. FormMode.Edit est la valeur par défaut pour le contrôle Form.

Note

Lorsque le formulaire est en mode Édition et que la valeur Item est nulle, les propriétés de la fiche de données ne sont pas évaluées et renvoient des valeurs par défaut.

NewForm

La fonction NewForm remplace le mode du contrôle Form par FormMode.New. Dans ce mode, le contenu de la propriété Item du contrôle Form est ignoré, et les valeurs par défaut de la propriété DataSource sont insérées dans le formulaire. Si la fonction SubmitForm s’exécute lorsque le formulaire est dans ce mode, un enregistrement est créé, et non modifié.

ResetForm

La fonction ResetForm rétablit les valeurs initiales du contenu d’un formulaire, avant toute modification effectuée par l’utilisateur. Si le formulaire a adopté le mode FormMode.New, il est réinitialisé sur le mode FormMode.Edit. Le comportement OnReset du contrôle Form s’exécute également. Vous pouvez également réinitialiser des contrôles spécifiques avec la fonction Reset, mais uniquement à partir du formulaire.

ViewForm

La fonction ViewForm remplace le mode du contrôle Form par FormMode.View. Dans ce mode, le contenu de la propriété Item du contrôle Form est utilisé pour remplir le formulaire. Les fonctions SubmitForm et ResetForm n’ont aucun effet dans ce mode.

Propriété DisplayMode

Le mode actuel peut être lu par le biais de la propriété Mode. Le mode détermine également la valeur de la propriété DisplayMode, qui peut être utilisée par des cartes de données et des contrôles dans le contrôle Form. Souvent, la propriété DisplayMode de la carte de données est définie sur Parent.DisplayMode (qui référence le formulaire) ainsi que sur la propriété DisplayMode (qui référence la carte de données) :

Mode DisplayMode Description
FormMode.Edit DisplayMode.Edit Les contrôles et les cartes de données sont modifiables, prêts à accepter les modifications apportées à un enregistrement.
FormMode.New DisplayMode.Edit Les contrôles et les cartes de données sont modifiables, prêts à accepter un nouvel enregistrement.
FormMode.View DisplayMode.View Les contrôles et les cartes de données ne sont pas modifiables ni optimisés pour l’affichage.

Syntaxe

SubmitForm( FormName )

  • FormName : obligatoire. Contrôle Form à envoyer à la source de données.

EditForm( FormName )

  • FormName : obligatoire. Contrôle Form devant basculer sur le mode FormMode.Edit.

NewForm( FormName )

  • FormName : obligatoire. Contrôle Form devant basculer sur le mode FormMode.New.

ResetForm( FormName )

  • FormName : obligatoire. Contrôle Form dont les valeurs initiales doivent être rétablies. Fait basculer également le formulaire du mode FormMode.New vers le mode FormMode.Edit.

ViewForm( FormName )

  • FormName : obligatoire. Contrôle Form devant basculer sur le mode FormMode.View.

Exemples

Consultez la page Understand data forms (Comprendre les formulaires de données) pour obtenir des exemples complets.

  1. Ajoutez un contrôle button, en définissant sa propriété Text de manière à afficher Save, et définissez sa propriété OnSelect sur la formule suivante :

    SubmitForm( EditForm )

  2. Définissez la propriété OnFailure d’un contrôle Form sur la valeur vide, et sa propriété OnSuccess sur la formule suivante :

    Back()

  3. Nommez un contrôle LabelErrorText, et définissez sa propriété Text sur cette formule :

    EditForm.Error

    Lorsque l’utilisateur sélectionne le bouton Save, toutes les modifications apportées dans le contrôle Form sont envoyées à la source de données sous-jacente.

    • Si l’envoi aboutit, toutes les modifications sont enregistrées, ou un enregistrement est créé si le contrôle Form a adopté le mode New. Le paramètre ErrorText est vide et l’écran précédent réapparaît.
    • Si l’envoi échoue, le paramètre ErrorText affiche un message d’erreur convivial ; l’écran actuel reste visible, afin que l’utilisateur puisse corriger le problème et réessayer.

  4. Ajoutez un contrôle button, en définissant sa propriété Text de manière à afficher Cancel, et définissez sa propriété OnSelect sur la formule suivante :

    ResetForm( EditForm ); Back()

    Lorsque l’utilisateur sélectionne le bouton Cancel, les valeurs affichées dans le contrôle Form sont réinitialisées sur leur valeur avant les modifications apportées par l’utilisateur ; l’écran précédent réapparaît et le contrôle Form revient au mode Edit (si son mode était New).

  5. Ajoutez un contrôle button, en définissant sa propriété Text de manière à afficher Nouveau, et définissez sa propriété OnSelect sur la formule suivante :

    NewForm( EditForm ); Navigate( EditScreen, None )

    Lorsque l’utilisateur sélectionne le bouton New, le contrôle Form bascule sur le mode New. Les valeurs par défaut de la source de données du contrôle Form sont insérées dans ce contrôle, et l’écran qui contient le contrôle Form s’affiche. Lorsque la fonction SubmitForm s’exécute, un enregistrement est créé, et non mis à jour.