Affichez, modifiez et créez un enregistrement dans une source de données.

Description

Si vous ajoutez un contrôle Display form, l’utilisateur peut afficher tous les champs d’un enregistrement ou uniquement les champs que vous spécifiez. Si vous ajoutez un contrôle Edit form, l’utilisateur peut modifier ces champs, créer un enregistrement et enregistrer ces modifications dans une source de données.

Exemple de formulaire et de contrôles d’affichage de formulaire

Si vous ajoutez un contrôle Gallery, vous pouvez le configurer de façon qu’il affiche une table dans une source de données, puis configure un formulaire pour afficher l’enregistrement que l’utilisateur sélectionne dans la galerie. Vous pouvez également ajouter un ou plusieurs contrôles Button que l’utilisateur peut sélectionner pour enregistrer des modifications, annuler des modifications et créer un enregistrement. En utilisant ces contrôles ensemble, vous pouvez créer une solution complète.

Sélection d’enregistrements

Pour chaque type de formulaire, vous définissez sa propriété DataSource sur une table d’enregistrements et vous définissez la propriété Item du formulaire de façon qu’elle affiche un enregistrement spécifique dans cette table. Par exemple, vous pouvez définir la propriété Item d’un formulaire sur la propriété SelectedItem d’un contrôle Gallery. Lorsque l’utilisateur sélectionne un enregistrement dans la galerie, le même enregistrement s’affiche dans le formulaire, à ceci près que le formulaire peut présenter plus de champs. Si l’utilisateur retourne à la galerie et sélectionne un autre enregistrement, la propriété SelectedItem de la galerie change. Cette opération met à jour la propriété Item du formulaire, qui présente ensuite l’enregistrement qui vient d’être sélectionné.

Chaque contrôle de formulaire contient un ou plusieurs contrôles Card. En définissant la propriété DataField d’une carte, vous spécifiez le champ que la carte affiche, ainsi que les autres informations.

Créer un enregistrement

Lorsqu’un contrôle Edit form se trouve en mode Édition, l’utilisateur peut mettre à jour l’enregistrement qui est spécifié dans la propriété Item du formulaire. Si inspectée, la propriété Mode renvoie Édition.

Lorsqu’un contrôle Edit form se trouve en mode Nouveau, la propriété Item est toutefois ignorée. Le formulaire n’affiche pas d’enregistrement existant ; au lieu de cela, les valeurs de chaque champ correspondent aux valeurs par défaut de la source de données avec laquelle vous avez configuré le formulaire. La fonction NewForm fait basculer un formulaire sur ce mode.

Par exemple, vous pouvez définir la propriété Text d’un bouton pour indiquer Nouveau et sa propriété OnSelect sur une formule incluant la fonction NewForm. Si l’utilisateur sélectionne ce bouton, le formulaire bascule en mode Nouveau, afin que l’utilisateur puisse créer un enregistrement commençant par des valeurs connues.

Un formulaire rebascule en mode Édition si la fonction ResetForm s’exécute ou si la fonction SubmitForm s’exécute correctement.

  • Vous pouvez définir la propriété Text d’un bouton pour indiquer Annuler et sa propriété OnSelect sur une formule incluant la fonction ResetForm. Si l’utilisateur sélectionne ce bouton, toutes les modifications en cours sont ignorées et les valeurs dans le formulaire, une fois encore, correspondent aux valeurs par défaut de la source de données.
  • Vous pouvez définir la propriété Text d’un bouton pour indiquer Enregistrer les modifications et sa propriété OnSelect sur une formule incluant la fonction SubmitForm. Si l’utilisateur sélectionne ce bouton et si la source de données est mise à jour, les valeurs du formulaire sont réinitialisées et remplacées par les valeurs par défaut de la source de données.

Enregistrer des modifications

Si vous créez un bouton Enregistrer les modifications comme décrit dans la section précédente, l’utilisateur peut créer ou mettre à jour un enregistrement, puis sélectionnez ce bouton pour enregistrer les modifications apportées à la source de données. Sinon, vous pouvez configurer un contrôle Image ou tout autre contrôle pour effectuer la même tâche, tant que vous configurez ce contrôle avec la fonction SubmitForm. Dans tous les cas, les propriétés Error, ErrorKind, OnSuccess et OnFailure fournissent des indications sur le résultat.

Lorsque la fonction SubmitForm s’exécute, elle commence par vérifier les données que l’utilisateur souhaite envoyer. Si un champ obligatoire ne contient pas de valeur ou si une autre valeur n’est pas conforme à une autre contrainte, les propriétés ErrorKind sont définies et la formule OnFailure s’exécute. Vous pouvez configurer le bouton Enregistrer les modifications ou tout autre contrôle de façon que l’utilisateur puisse le sélectionner uniquement si les données sont valides (autrement dit, si la propriété Valid du formulaire est définie sur true). Notez que l’utilisateur doit non seulement résoudre le problème, mais également sélectionner une nouvelle fois le bouton Enregistrer les modifications (ou ignorer les modifications en sélectionnant un bouton Annuler, comme décrit précédemment) pour réinitialiser les propriétés Error et ErrorKind.

Si les données sont validées, SubmitForm les envoie à la source de données, ce qui peut prendre un certain temps en fonction de la latence du réseau.

  • Si l’envoi se déroule correctement, la propriété Error propriété est désactivée, la propriété ErrorKind est définie sur ErrorKind.None et la formule OnSuccess s’exécute. Si l’utilisateur a créé un enregistrement (autrement dit, si le formulaire était précédemment en mode Nouveau), le formulaire bascule en mode Édition, afin que l’utilisateur puisse modifier l’enregistrement qui vient d’être créé ou un autre enregistrement.
  • Si l’envoi échoue, la propriété Error contient un message d’erreur convivial en provenance de la source de données, expliquant le problème. La propriété ErrorKind est définie correctement, en fonction du problème, et la formule OnFailure s’exécute.

Certaines sources de données peuvent détecter lorsque deux personnes essaient de mettre à jour le même enregistrement en même temps. Dans ce cas, ErrorKind est défini sur ErrorKind.Conflict, et la solution consiste à actualiser la source de données avec les autres modifications de l’utilisateur et à réappliquer la modification effectuée par cet utilisateur.

Conseil : si vous proposez un bouton Annuler sur votre formulaire afin que l’utilisateur puisse annuler les modifications en cours, ajoutez la fonction ResetForm à la propriété OnSelect du bouton même si cette propriété contient également une fonction Navigate pour modifier les écrans. Dans le cas contraire, le formulaire conservera les modifications apportées par l’utilisateur.

Principales propriétés

DataSource : source de données qui contient l’enregistrement que l’utilisateur affichera, modifiera ou créera.

  • Si vous ne définissez pas cette propriété, l’utilisateur ne peut pas afficher, modifier ou créer un enregistrement, et aucune validation ou métadonnée supplémentaire n’est fournie.

Error : un message d’erreur convivial à afficher pour ce formulaire lorsque la fonction SubmitForm échoue.

  • Cette propriété s’applique uniquement au contrôle Edit form.
  • Cette propriété est modifiée uniquement lorsque la fonction SubmitForm, EditForm ou ResetForm s’exécute.
  • Si aucune erreur ne se produit, cette propriété est vide, et ErrorKind est défini sur ErrorKind.None.
  • Lorsque cela est possible, le message d’erreur renvoyé sera dans la langue de l’utilisateur. Certains messages d’erreur proviennent directement de la source de données et ne peuvent pas être dans la langue de l’utilisateur.

ErrorKind : si une erreur se produit lorsque SubmitForm s’exécute, le type d’erreur qui s’est produit est indiqué.

  • S’applique uniquement à un contrôle Edit form.
  • L’énumération de cette propriété est identique à celle de la fonction Errors. Un contrôle Edit form peut renvoyer ces valeurs :
ErrorKind Description
ErrorKind.Conflict Un autre utilisateur modifie le même enregistrement, ce qui entraîne un conflit de modifications. Exécutez la fonction Refresh pour recharger l’enregistrement, puis réessayez d’effectuer la modification.
ErrorKind.None L’erreur est d’un type inconnu.
ErrorKind.Sync La source de données a signalé une erreur. Vérifiez la propriété Error pour plus d’informations.
ErrorKind.Validation Un problème de validation générale a été détecté.

Item : l’enregistrement dans DataSource que l’utilisateur affichera ou modifiera.

LastSubmit : dernier enregistrement envoyé avec succès, y compris les champs générés par le serveur.

  • Cette propriété s’applique uniquement au contrôle Edit form.
  • Si la source de données génère ou calcule automatiquement des champs, comme un champ ID avec un numéro unique, la propriété LastSubmit aura cette nouvelle valeur après l’exécution correcte de SubmitForm.
  • La valeur de cette propriété est disponible dans la formule OnSuccess.

Mode : le contrôle est en mode Édition ou Nouveau.

Mode Description
FormMode.Edit L’utilisateur peut modifier un enregistrement à l’aide du formulaire. Les valeurs dans les cartes du formulaire sont préremplies avec l’enregistrement existant et l’utilisateur peut les modifier. Si la fonction SubmitForm s’exécute correctement, un enregistrement existant est modifié.
FormMode.New L’utilisateur peut créer un enregistrement à l’aide du formulaire. Les valeurs dans les contrôles de formulaire sont préremplies avec les valeurs par défaut pour un enregistrement de la source de données. Si la fonction SubmitForm s’exécute correctement, un enregistrement est créé.
  • Par défaut, le contrôle de formulaire est en mode Édition, mais bascule sur le mode Nouveau lorsque la fonction NewForm s’exécute.

Le formulaire bascule du mode Nouveau au mode Édition lorsque l’une des modifications suivantes se produit : - L’envoi du formulaire se déroule correctement et un enregistrement est créé. Si la galerie est définie pour déplacer automatiquement la sélection vers ce nouvel enregistrement, le formulaire sera en mode Édition pour l’enregistrement créé, afin que l’utilisateur puisse apporter des modifications supplémentaires. - La fonction EditForm s’exécute. - La fonction ResetForm s’exécute. Par exemple, l’utilisateur peut sélectionner un bouton Annuler qui a été configuré avec cette fonction.

OnFailure : façon dont une application répond lorsqu’une opération de données ne s’est pas déroulée correctement.

  • Cette propriété s’applique uniquement au contrôle Edit form.

OnReset : façon dont une application répond lorsqu’un contrôle Edit form est réinitialisé.

  • Cette propriété s’applique uniquement au contrôle Edit form.

OnSuccess : façon dont une application répond lorsqu’une opération de données s’est déroulée correctement.

  • Cette propriété s’applique uniquement au contrôle Edit form.

Unsaved : défini sur true si le contrôle Edit form contient des modifications utilisateur qui n’ont pas été enregistrées.

  • Cette propriété s’applique uniquement au contrôle Edit form.
  • Utilisez cette propriété pour avertir l’utilisateur avant qu’il ne perde toutes les modifications non enregistrées. Pour empêcher l’utilisateur de sélectionner un autre enregistrement dans un contrôle Gallery avant d’enregistrer les modifications apportées à l’enregistrement actuel, définissez la propriété Disabled sur Form.Unsaved et de la même manière, désactivez les opérations d’actualisation.

Updates : valeurs à écrire dans la source de données pour un enregistrement chargé dans un contrôle de formulaire.

  • Cette propriété s’applique uniquement au contrôle Edit form.
  • Utilisez cette propriété pour extraire les valeurs de champ des cartes dans le contrôle. Vous pouvez ensuite utiliser ces valeurs pour mettre à jour manuellement la source de données avec un appel de fonction Patch ou une autre méthode exposée par une connexion. Vous n’avez pas besoin de cette propriété si vous utilisez la fonction SubmitForm.
  • Cette propriété renvoie un enregistrement des valeurs. Par exemple, si le contrôle de formulaire contient des contrôles de carte pour les champs Nom et Quantité et si les valeurs des propriétés Updates pour ces cartes renvoient, respectivement, « Widget » et « 10 », la propriété Updates du contrôle de formulaire renvoie { Name: "Widget", Quantity: 10 }.

Valid : indique si un contrôle Card ou Edit form contient des entrées valides, prêtes à être envoyées à la source de données.

  • Cette propriété s’applique uniquement au contrôle Edit form.
  • Une propriété Valid d’un contrôle Form agrège les propriétés Valid de tous les contrôles Card dans le formulaire. Une propriété Valid est définie sur true uniquement si les données de toutes les cartes dans ce formulaire sont valides ; dans le cas contraire, la propriété Valid du formulaire est définie sur false.
  • Pour qu’un bouton puisse enregistrer les modifications uniquement lorsque les données dans un formulaire sont valides mais qu’elles n’ont pas encore été envoyées, définissez la propriété Enabled du bouton sur la formule suivante :

    SubmitButton.Enabled = IsBlank( Form.Error ) || Form.Valid

Propriétés supplémentaires

BorderColor : couleur de bordure du contrôle.

BorderStyle : indique si la bordure d’un contrôle est unie, discontinue, en pointillés ou s’il n’y en a aucune.

BorderThickness : épaisseur de bordure d’un contrôle.

Fill : couleur d’arrière-plan d’un contrôle.

Height : distance entre le haut et le bas d’un contrôle.

Visible : indique si un contrôle est visible ou est masqué.

Width : distance entre les côtés droit et gauche d’un contrôle.

X : distance entre le bord gauche d’un contrôle et le bord gauche de son conteneur parent (ou l’écran s’il n’y a pas de conteneur parent).

Y : distance entre le bord supérieur d’un contrôle et le bord supérieur du conteneur parent (ou l’écran s’il n’y a pas de conteneur parent).