Gambas 3/WebFormApp
Web form application modifier
Une Web form application est une application web où tout tient sur une page.
Pour la petite histoire, le composant gb.web.form est présent dans Gambas depuis la version 3.9.0 ; ça date de l'été 2016 et, depuis, il est constamment amélioré.
Ce composant permet de faire des interfaces graphiques pour les applications web depuis l'environnement de développement (IDE).
Presque tout le travail est fait du côté du serveur. Le navigateur (client) est utilisé comme terminal graphique. Côté client, Gambas utilise JavaScript. Toutefois, le but est de minimiser le plus possible l'usage du JavaScript.
La communication des événements et le rafraîchissement des pages web se fait par le biais de requêtes HTML XML.
L'éditeur vous permet d'ajouter les contrôles visuellement de la même façon que lorsque vous créez une application graphique.
Mais attention ! Il y a des différences ! Votre site internet génère du contenu en fonction des requêtes reçues. En testant, vous constaterez que vous ne pouvez pas réutiliser un code provenant d'une application graphique tel quel.
Bien entendu, le nom des contrôles change un peu mais surtout la portée des variables se trouve modifiée car elle n'est valide que le temps d'une requête.
Pour bien débuter avec les applications web, il faut connaître un peu comment fonctionne le protocole HTTP, comment fonctionne un serveur, comment fonctionne un navigateur (le client), ce qu'est un cookie, une session.
La classe statique Session vous permet de stocker les données concernant l'utilisateur qui est en train de surfer sur votre site. C'est important de savoir où nous en sommes entre deux requêtes.
Il faudrait connaître un peu le HTML qui est utilisé dans le texte du contrôle WebHtml pour spécifier le contenu et le CSS qui est utilisé pour le style de la mise en forme de tous les contrôles (pour rendre votre page toute jolie).
Bonne nouvelle ! Vous n'avez pas besoin de toutes ces notions pour suivre le tutoriel. Commençons par faire connaissance avec les contrôles !
Vous avez démarré l'éditeur de code et vous avez créé un projet avec le modèle Web form application.
Contrôles modifier
Faites un double-clic sur Webform1 dans le volet de gauche ! Au centre de l'écran, l'éditeur vous montre un formulaire nommé Webform1. Supprimez tous les contrôles présents par défaut dans le Webform1 ! Pour cela, faites un clic-droit sur chaque contrôle puis choisissez Supprimer !
Webform modifier
Un Webform est l'équivalent d'une page web. C'est un conteneur et vous pouvez ajouter divers contrôles en faisant un glisser-déposer depuis le volet de droite.
Comme pour les applications graphiques, lorsque vous faites un clic-droit sur le contrôle, le menu contextuel s'affiche et vous pouvez placer le curseur de votre souris sur Événements. Un sous-menu s'affiche avec les événements que vous pouvez utiliser.
Vous pouvez créer un ou plusieurs sous-formulaires à l'aide des Webforms et les afficher dans le formulaire principal à l'aide du conteneur WebContainer par formulaire. Pour cela, il faut construire l'objet Webform au runtime en donnant la référence du WebContainer parent. Si vous débutez, sachez que c'est complexe.
Événement(s) modifier
L'événement principal pour le WebForm est l'événement _Open(). De manière identique aux applications graphique, cette événements est déclenché au tout début lorsque votre formulaire est construit. Vous pouvez l'utiliser pour définir les valeurs initiales d'autres contrôles par exemple.
L'événement est déclenché aussi lorsque l'utilisateur rafraîchi avec F5. Utilisez l'objet Session pour savoir si vous avez déjà fait le travail.
Propriété(s) modifier
La propriété Title contient le titre de l'application. Comme pour les autres conteneurs, la propriété Arrangement définit comment les contrôles enfants seront disposés. La valeur Vertical définit que la largeur des contrôles enfants sera étendue sur toute la page. Les contrôles seront placés l'un après l'autre de haut en bas.
WebMenuBar modifier
C'est la barre de menu de votre application. C'est un conteneur qui contient les menus qui sont des contrôles de type WebMenu.
WebMenu modifier
C'est un menu dans la WebMenuBar qui contiendra à son tour des éléments qui sont des éléments de type WebMenuItem. Vous pouvez avoir plusieurs menus comme par exemple : Fichiers, Édition, Aide, etc.
WebMenuItem modifier
C'est l'élément qui sera cliqué au final. C'est l'entrée du menu qui définit l'action.
Événement(s) modifier
L'événement _Click() est déclenché quand l'utilisateur clique sur l'entrée du menu.
Propriété(s) modifier
La propriété Text permet de définir le texte affiché.
WebButton modifier
Le contrôle WebButton est le contrôle principal. C'est le bouton pour déclencher une action.
Événement(s) modifier
L'événement _Click() se produit quand l'utilisateur relâche le bouton gauche de la souris.
Propriété(s) modifier
La propriété Text permet de définir le texte affiché.
WebHtml modifier
Ce contrôle vous permet d'insérer du code HTML5 quelque part dans votre formulaire.
Propriété(s) modifier
La propriété Text vous permet de définir le code HTML5 qui sera utilisé pour afficher l'information.
WebTextBox modifier
C'est le cadre dans lequel l'utilisateur écrit du texte. Ce contrôle est à utiliser pour du texte qui ne contient pas de retour à la ligne.
Événement(s) modifier
L'événement _Change() se produit après chaque modification de texte faite par l'utilisateur.
Propriété(s) modifier
La propriété Text permet de définir ou de retrouver le texte saisi par l'utilisateur.
La propriété ReadOnly est un booléen. Assignez True pour empêcher l'utilisateur de modifier le texte !
WebTextArea modifier
C'est le cadre dans lequel l'utilisateur écrit du texte. Ce contrôle est à utiliser pour du texte qui contient des retours à la ligne.
Événement(s) modifier
L'événement _Change() se produit après chaque modification de texte faite par l'utilisateur.
Propriété(s) modifier
La propriété Text permet de définir ou de retrouver le texte saisi par l'utilisateur.
La propriété Wrap est un booléen. Assignez True pour que le texte passe à la ligne suivante. Sans cela, il faudra scroller horizontalement pour voir le texte.
WebImage modifier
Ce contrôle vous permet d'insérer une image quelque part dans votre formulaire.
Propriété(s) modifier
Height, Width : pour définir la taille de l'image par exemple 32px. La propriété Image permet de sélectionner le fichier par exemple un fichier *.png.
WebLabel modifier
Un WebLabel est une étiquette. Vous l'utilisez pour afficher du texte. Ce texte peut être traduit.
Propriété(s) modifier
La propriété principale et Text pour spécifier le contenu.
WebSeparator modifier
Un contrôle pour dessiner un trait afin de marquer une séparation dans la page.
WebProgressBar modifier
C'est une barre de progression. Ce n'est pas dynamique. Vous spécifier la valeur pour que la barre évolue.
Propriété(s) modifier
La propriété Value accepte un Double entre 0.0 et 1.0 pour définir le pourcentage.
WebContainer modifier
C'est un conteneur. Il peut être utilisé pour disposer les contrôles enfants mais aussi comme spacer c'est à dire comme un espace qui s'étend afin de garder le contrôle lorsque l'utilisateur modifie la taille de la fenêtre par exemple.
C'est utile pour conserver la tailles initiales des contrôles typés WebImage.
Propriété(s) modifier
La propriété Arrangement est essentielle. Mettez Row pour arranger les contrôles comme des mots dans un paragraphe. La propriété Border est un booléen vous permettant de faire apparaître la bordure.
WebHBox modifier
C'est un raccourci pour placer un conteneur qui organise les contrôles enfants horizontalement.
WebVBox modifier
C'est un raccourci pour placer un conteneur qui organise les contrôles enfants verticalement.
WebExpander modifier
Un conteneur qui permet de masquer ou d'afficher son contenu.
Événement(s) modifier
Les événements sont _Hide() et _Show()
Propriété(s) modifier
La propriété importante à connaître est le booléen Hidden. Si la valeur est True, le contenu est masqué.
WebScrollView modifier
Il semble que ce contrôle ne soit pas encore opérationnel. On verra dans le futur.
WebTabPanel modifier
Un conteneur avec des onglets. Lorsque l'utilisateur active un onglet, le contenu des autres onglets est masqué automatiquement.
Événement(s) modifier
L'événement _Click() se produit lorsque l'utilisateur change d'onglet.
Propriété(s) modifier
La propriété Index est un Integer. La valeur 0 correspond au premier onglet sélectionné.
WebDateBox modifier
Un contrôle permettant à l'utilisateur de sélectionner une date ou une date et une heure.
Événement(s) modifier
L'événement _Change() se produit lors d'un changement de valeur.
Propriété(s) modifier
La propriété Date vous donne le moment sélectionné par l'utilisateur. Cette propriété est de type DateTime.
WebDateChooser modifier
Un contrôle permettant à l'utilisateur de sélectionner une date (mais sans spécifier l'heure).
Événement(s) modifier
L'événement _Change() se produit lors d'un changement de valeur.
Propriété(s) modifier
La propriété Value vous donne la date choisie.
WebRadioButton modifier
Un bouton option. Comme dans les autres langage, seul un bouton option peut être activé. Cliquer sur un bouton radio aura pour effet de désactiver tous les autres.
Événement(s) modifier
L'événement est _Click()
Propriété(s) modifier
La propriété Value vous renvoie un booléen. True si l'option a été choisie.
WebCheckBox modifier
C'est le contrôle correspondant a une case à cocher.
Événement(s) modifier
L'événement est _Click()
Propriété(s) modifier
La propriété Checked a la valeur True lorsque c'est coché.
WebSpinBox modifier
Un contrôle pour laisser l'utilisateur choisir une valeur entière avec une borne minimale et une borne maximale.
Événement(s) modifier
L'événement _Change() se produit lors d'un changement de valeur.
Propriété(s) modifier
Les propriétés Min et Max vous permettent de spécifier les bornes. La propriété Value renvoie la sélection actuelle.
WebComboBox modifier
J'ai pu constater que le comportement de ce contrôle n'est pas encore parfait mais il est utilisable comme suit : utilisez d'abord la méthode Clear() pour enlever les anciens éléments. Ajoutez d'abord un texte "Veuillez sélectionner" puis ajouter les autres valeurs avec la méthode Add().
Voici le code pour l'exemple :
WebComboBoxChoice.Clear()
WebComboBoxChoice.Add("veuillez sélectionner", 0)
WebComboBoxChoice.Add("un", 1)
WebComboBoxChoice.Add("deux", 2)
WebComboBoxChoice.Add("trois", 3)
WebComboBoxChoice.Index = 1
Événement(s) modifier
L'événement _Click() se produit lors d'un changement de sélection.
Propriété(s) modifier
La propriété Index vous renvoie un Integer correspondant à l'index sélectionné. Zéro correspond au texte "Veuillez sélectionner".
WebTable modifier
Le contrôle WebTable sert à afficher des données sous forme d'un tableau. Vous décidez si l'utilisateur ne peut que lire les données ou s'il peut sélectionner une ligne ou plusieurs lignes.
Plusieurs astuces sont nécessaires pour utiliser ce contrôle. La première est d'enregistrer les données avant de les afficher. Avec une base de données MySQL, vous pouvez créer une table temporaire comme suit :
DROP TABLE IF EXISTS TempTable SELECT * INTO TempTable FROM Data
Ensuite, vous utiliser la table TempTable pour remplir les données du contrôle et pour retrouver les valeurs du contrôle sélectionné.
La deuxième astuce consiste à n'ajouter les colonnes que si elles ne sont pas déjà présentes.
WebTableData.Clear()
If WebTableData.Columns.Count <> 2 Then
WebTableData.AddColumn("Id")
WebTableData.AddColumn("Description")
Endif
WebTableData.ShowHeader = False
WebTableData.Count = 4
Événement(s) modifier
L'événement _Select() se produit à chaque changement de sélection.
L'événement _Data() permet de fournir au contrôle les données à afficher.
Propriété(s) modifier
La propriété Mode définit si l'utilisateur peut sélectionner. La propriété Selection renvoie un tableau d'entier correspondant aux index des lignes sélectionnées.
WebSlider modifier
Ce contrôle ressemble au WebSpinBox.
Événement(s) modifier
L'événement _Change() se produit lors d'un changement de valeur.
Propriété(s) modifier
MaxValue, MinValue pour définir les bornes et Value pour trouver la valeur choisie.
WebUploader modifier
WebUploader est un contrôle visant à gérer l'ensemble du processus de téléchargement de fichiers. C'est une combinaison d'un WebUploadArea, d'un bouton d'annulation et d'une barre de progression.
Je n'arrive pas à l'utiliser à plusieurs reprises. Votre aide, chers lecteurs, est la bienvenue ... La méthode Reset() semble ne pas fonctionner.
Événement modifier
L'événement _Upload() se produit lorsque le fichier est complètement transféré côté serveur.
Propriétés modifier
La propriété Path vous donne le chemin complet du fichier transféré côté serveur.
La propriété File vous donne le nom du fichier sélectionné côté utilisateur.
WebUploadArea modifier
Ce contrôle permet de téléverser un fichier. C'est un conteneur et la méthode Clear() permet de vider le contenu.
Événement(s) modifier
L'événement _Progress() se produit à une ou plusieurs reprises durant le transfert de fichier du client au serveur. Vous pouvez l'utiliser pour afficher et mettre à jour une barre de progression par exemple.
L'événement _Upload() se produit quand le fichier dans son intégralité a été copié sur le serveur. Uniquement dans le traitement de l'événement _Upload(), les propriétés suivantes permettent de finaliser le téléversement du fichier :
Utilisez la propriété Path pour renvoyer le chemin du fichier sur le serveur par exemple /tmp/gambas.1000/upload/192.168.1.113:1403D51560FF89E98B84FA0B/@1.WebUploadArea1.pdf ! Notez que le nom du fichier correspond au nom du contrôle !
Utilisez la propriété File pour recevoir le nom original du fichier par exemple : ENG everything - curl.pdf !
Un exemple de finalisation serait d'enregistrer le fichier, par exemple une photo, dans la base de données puis de mettre à jour le contenu dans le WebUploadArea.
Propriété(s) modifier
La propriété Path est en lecture seule. Elle renvoie le chemin du fichier sur le serveur.
La propriété File est en lecture seule. Elle renvoie le nom original du fichier.
La propriété Upload renvoie True quand le fichier a été transféré.
WebTimer modifier
Un contrôle invisible pour l'utilisateur. Le timer est sert à exécuter du code régulièrement.
Événement(s) modifier
L'événement _Timer() se prosuit à chaque batement du timer.
Propriété(s) modifier
La propriété Delay permet de définir un Integer qui donne le temps en milisecondes entre deux battements du timer.
La propriété Enabled est un booléen. True pour que le timer fonctionne. False et le timer est arrêté.
Débogage modifier
Comme pour les autres types de projets, cliquez sur le triangle (Démarrer) ou tapez F5 ! Votre navigateur sera démarré. Chez moi, c'est Firefox.
Durant le développement, si vous voulez tester votre site depuis un autre poste de travail sur le même réseau local (chez vous uniquement), il faudra ouvrir le port 8080 avec votre firewall. Chez moi, sur Linux Mint, j'utilise les commandes suivantes sur le serveur et sur le second poste qui sert à tester :
sudo ufw allow 8080 sudo ufw status
Download / Upload modifier
Pour demander au navigateur (côté client) de télécharger un fichier, vous pouvez utiliser la méthode statique WebForm.Download(Path As String).
Pour permettre à l'utilisateur de téléverser un fichier, vous devez utiliser le contrôle WebUploader et gérer le fichier reçu avec l'événement _Upload().
Je vous souhaite beaucoup de fun pour la réalisation de votre site avec Gambas !