Gambas 3/WebFormApp
Web form application
[modifier | modifier le wikicode]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 | modifier le wikicode]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 | modifier le wikicode]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 | modifier le wikicode]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 | modifier le wikicode]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 | modifier le wikicode]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 | modifier le wikicode]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 | modifier le wikicode]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 | modifier le wikicode]L'événement _Click() est déclenché quand l'utilisateur clique sur l'entrée du menu.
Propriété(s)
[modifier | modifier le wikicode]La propriété Text permet de définir le texte affiché.
WebButton
[modifier | modifier le wikicode]Le contrôle WebButton est le contrôle principal. C'est le bouton pour déclencher une action.
Événement(s)
[modifier | modifier le wikicode]L'événement _Click() se produit quand l'utilisateur relâche le bouton gauche de la souris.
Propriété(s)
[modifier | modifier le wikicode]La propriété Text permet de définir le texte affiché.
WebHtml
[modifier | modifier le wikicode]Ce contrôle vous permet d'insérer du code HTML5 quelque part dans votre formulaire.
Propriété(s)
[modifier | modifier le wikicode]La propriété Text vous permet de définir le code HTML5 qui sera utilisé pour afficher l'information.
WebTextBox
[modifier | modifier le wikicode]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 | modifier le wikicode]L'événement _Change() se produit après chaque modification de texte faite par l'utilisateur.
Propriété(s)
[modifier | modifier le wikicode]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 | modifier le wikicode]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 | modifier le wikicode]L'événement _Change() se produit après chaque modification de texte faite par l'utilisateur.
Propriété(s)
[modifier | modifier le wikicode]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 | modifier le wikicode]Ce contrôle vous permet d'insérer une image quelque part dans votre formulaire.
Propriété(s)
[modifier | modifier le wikicode]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 | modifier le wikicode]Un WebLabel est une étiquette. Vous l'utilisez pour afficher du texte. Ce texte peut être traduit.
Propriété(s)
[modifier | modifier le wikicode]La propriété principale et Text pour spécifier le contenu.
WebSeparator
[modifier | modifier le wikicode]Un contrôle pour dessiner un trait afin de marquer une séparation dans la page.
WebProgressBar
[modifier | modifier le wikicode]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 | modifier le wikicode]La propriété Value accepte un Double entre 0.0 et 1.0 pour définir le pourcentage.
WebContainer
[modifier | modifier le wikicode]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 | modifier le wikicode]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 | modifier le wikicode]C'est un raccourci pour placer un conteneur qui organise les contrôles enfants horizontalement.
WebVBox
[modifier | modifier le wikicode]C'est un raccourci pour placer un conteneur qui organise les contrôles enfants verticalement.
WebExpander
[modifier | modifier le wikicode]Un conteneur qui permet de masquer ou d'afficher son contenu.
Événement(s)
[modifier | modifier le wikicode]Les événements sont _Hide() et _Show()
Propriété(s)
[modifier | modifier le wikicode]La propriété importante à connaître est le booléen Hidden. Si la valeur est True, le contenu est masqué.
WebScrollView
[modifier | modifier le wikicode]Il semble que ce contrôle ne soit pas encore opérationnel. On verra dans le futur.
WebTabPanel
[modifier | modifier le wikicode]Un conteneur avec des onglets. Lorsque l'utilisateur active un onglet, le contenu des autres onglets est masqué automatiquement.
Événement(s)
[modifier | modifier le wikicode]L'événement _Click() se produit lorsque l'utilisateur change d'onglet.
Propriété(s)
[modifier | modifier le wikicode]La propriété Index est un Integer. La valeur 0 correspond au premier onglet sélectionné.
WebDateBox
[modifier | modifier le wikicode]Un contrôle permettant à l'utilisateur de sélectionner une date ou une date et une heure.
Événement(s)
[modifier | modifier le wikicode]L'événement _Change() se produit lors d'un changement de valeur.
Propriété(s)
[modifier | modifier le wikicode]La propriété Date vous donne le moment sélectionné par l'utilisateur. Cette propriété est de type DateTime.
WebDateChooser
[modifier | modifier le wikicode]Un contrôle permettant à l'utilisateur de sélectionner une date (mais sans spécifier l'heure).
Événement(s)
[modifier | modifier le wikicode]L'événement _Change() se produit lors d'un changement de valeur.
Propriété(s)
[modifier | modifier le wikicode]La propriété Value vous donne la date choisie.
WebRadioButton
[modifier | modifier le wikicode]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 | modifier le wikicode]L'événement est _Click()
Propriété(s)
[modifier | modifier le wikicode]La propriété Value vous renvoie un booléen. True si l'option a été choisie.
WebCheckBox
[modifier | modifier le wikicode]C'est le contrôle correspondant a une case à cocher.
Événement(s)
[modifier | modifier le wikicode]L'événement est _Click()
Propriété(s)
[modifier | modifier le wikicode]La propriété Checked a la valeur True lorsque c'est coché.
WebSpinBox
[modifier | modifier le wikicode]Un contrôle pour laisser l'utilisateur choisir une valeur entière avec une borne minimale et une borne maximale.
Événement(s)
[modifier | modifier le wikicode]L'événement _Change() se produit lors d'un changement de valeur.
Propriété(s)
[modifier | modifier le wikicode]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 | modifier le wikicode]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 | modifier le wikicode]L'événement _Click() se produit lors d'un changement de sélection.
Propriété(s)
[modifier | modifier le wikicode]La propriété Index vous renvoie un Integer correspondant à l'index sélectionné. Zéro correspond au texte "Veuillez sélectionner".
WebTable
[modifier | modifier le wikicode]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 | modifier le wikicode]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 | modifier le wikicode]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 | modifier le wikicode]Ce contrôle ressemble au WebSpinBox.
Événement(s)
[modifier | modifier le wikicode]L'événement _Change() se produit lors d'un changement de valeur.
Propriété(s)
[modifier | modifier le wikicode]MaxValue, MinValue pour définir les bornes et Value pour trouver la valeur choisie.
WebUploader
[modifier | modifier le wikicode]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 | modifier le wikicode]L'événement _Upload() se produit lorsque le fichier est complètement transféré côté serveur.
Propriétés
[modifier | modifier le wikicode]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 | modifier le wikicode]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 | modifier le wikicode]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 | modifier le wikicode]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 | modifier le wikicode]Un contrôle invisible pour l'utilisateur. Le timer est sert à exécuter du code régulièrement.
Événement(s)
[modifier | modifier le wikicode]L'événement _Timer() se prosuit à chaque batement du timer.
Propriété(s)
[modifier | modifier le wikicode]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 | modifier le wikicode]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 | modifier le wikicode]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 !