Formulaires et dialogues

Une part importante du développement d’une interface est la saisie d’informations par l’utilisateur. Dans x4js, elle passe en général par l’objet Form, le plus souvent placé dans un Dialog.

Form

Un Form est un conteneur qui sait retrouver ses champs. Il parcourt tous ses enfants, à n’importe quelle profondeur, et retient ceux qui ont un name.

import { Checkbox, Form, TextEdit } from 'x4js';

const form = new Form( {
  content: [
    new TextEdit( { label: "Name", name: "name", value: "", required: true } ),
    new TextEdit( { label: "Age", name: "age", type: "number", value: 30 } ),
    new Checkbox( { label: "Active", name: "active", checked: true } ),
  ]
});

Trois méthodes font l’essentiel du travail :

Méthode	Rôle
setValues( values )	Remplit les champs à partir d’un objet.
getValues( )	Renvoie un objet avec la valeur de chaque champ.
validate( )	Vérifie les champs et renvoie les valeurs, ou null si le formulaire est invalide.

TextEdit convient aux champs courants avec libellé. Utilisez Input quand vous avez besoin du champ seul.

Vous pouvez mettre vos propres contrôles dans un formulaire : il suffit qu’ils aient un name et qu’ils répondent à l’interface form-element.

Dialog

Un Dialog est une fenêtre avec un titre, un contenu et des boutons. Dans le cas courant, on le compose plutôt que d’en dériver une classe : un dialogue, un formulaire, des boutons.

import { Checkbox, Dialog, Form, TextEdit } from 'x4js';

async function editUser( ) {
  const dlg = new Dialog( {
    title: "User",
    modal: true,
    movable: true,
    form: new Form( {
      content: [
        new TextEdit( { label: "Name", name: "name", value: "", required: true } ),
        new TextEdit( { label: "Age", name: "age", type: "number", value: 30 } ),
        new Checkbox( { label: "Active", name: "active", checked: true } ),
      ]
    }),
    buttons: [ "ok.outline.default", "cancel.outline" ],
  });

  // attend que l'utilisateur ferme le dialogue
  if( await dlg.showAsync( )=="ok" ) {
    const values = dlg.getValues( );
    console.log( values.name, values.age, values.active );
  }
}

showAsync renvoie le nom du bouton qui a fermé le dialogue.

Les boutons

Les boutons se déclarent par leur nom. Les noms prédéfinis sont ok, cancel, yes, no, retry, abort et save, et leur texte suit la langue courante. Des options s’ajoutent après un point :

Écriture	Résultat
"ok"	Bouton OK.
"ok.default"	Bouton OK, marqué comme bouton par défaut.
"cancel.outline"	Bouton Annuler, en style contour.
"ok.disabled"	Bouton OK, désactivé au départ.
"-"	Espace flexible entre deux groupes de boutons.

Chaque option devient aussi une classe CSS du bouton, ce qui permet d’en ajouter pour vos propres styles.

Vous pouvez aussi passer vos propres Button dans la liste.

Poser une question

Pour un message ou une confirmation, il n’y a pas de dialogue à construire :

import { MessageBox } from 'x4js';

const answer = await MessageBox.showAsync( "Delete this user?", [ "yes", "no" ] );
if( answer=="yes" ) {
  // ...
}

Classe	Usage
MessageBox	Afficher un message, demander une confirmation.
InputBox	Demander une valeur.
PromptBox	Demander une valeur avec l’éditeur de votre choix.
ProgressionBox	Suivre une opération longue, avec ses textes et ses erreurs.

Avant d’inventer un mécanisme de suivi pour une opération longue, regardez ProgressionBox : il fournit déjà l’affichage du texte, du pourcentage et des erreurs.