Tutorial - Managing data in a WINDEV application

• sender, recipients,
• outgoing date, subject, message,
• attachments, etc.

In this lesson, we are going to create a window allowing the user to send an email from the "WD Full Application" application. This window is as follows:

WINDEV offers several methods for sending and receiving emails. For more details, see Sending and receiving emails.

Warning
This lesson is based on the example developed in lesson 1.

Creating the window

1. Click in the quick access buttons.
2. Click "Window" then "Window". The window creation wizard opens.
3. Click "Based on a template", select "Use: WINTPL_Template" and confirm.

Creating the controls to send emails

• SMTP server,
• SMTP server port,
• Username,
• User password.

1. On the "Creation" tab, in the "Usual controls" group, click .
2. The control shape appears under the cursor.
3. Click the upper-left corner of the window to create Edit control.
4. Select the control and press Enter. The text switches to edit mode. Enter "SMTP server" and validate. The control name automatically changes to EDT_SMTP_Server.

1. On the "Creation" tab, in the "Usual controls" group, expand "Edit".
2. Select "Password edit".
3. The control shape appears under the cursor.
4. Click below the "User" control to create the new control.
   
   

   The "Password" edit control appears in the editor with a bullet and an eye.
   At runtime, when users enter their passwords, the characters will be replaced with bullets. Users will be able to click the eye icon to toggle the visibility of the password.

1. Select the four controls.
2. On the "Alignment" tab, in the "Inside and outside" group, click "Justify (Ins. and Out.)".
   
   
3. Save the window ( or Ctrl + S).

Creating the controls to enter the email characteristics

• A control to enter the sender's address.
• A control to enter or select the recipient address.
• A control to enter the email subject.
• A control to enter the email text. The user must have the ability to format the email text.
• A control to add attachments.

1. On the "Creation" tab, in the "Usual controls" group, expand "Edit".
2. Enter "Email" in the search box at the top of the list of preset controls. Select "eMail edit". The control shape appears under the cursor.
3. Click below the "Password" control to create the new control.
4. Select the control and press Enter. The text switches to edit mode. Enter "Sender" and confirm.

1. On the "Creation" tab, in the "Usual controls" group, click "Combo Box". The control shape appears under the cursor.
2. Click below the "Sender" control. The Combo Box control creation wizard opens automatically.
3. Select "Display data from a file or existing query". Go to the next step.
4. Select the Customer data file. Go to the next step.
5. The email addresses of the customers will be displayed in the control:
   • Uncheck the "CustomerID" item.
   • Check the "Email" item.
   Go to the next step.
6. The sort item is the "Email" item. Go to the next step.
7. The return value is the "Email" item. Go to the next step.
8. Keep the default options. Go to the next step.
9. In the "Additional settings" screen, check "Allow input". The user must have the possibility to enter a new email address. Go to the next step.
10. Change the name and caption of the Combo Box control:
    • Enter "COMBO_Recipient" in the name field.
    • Enter "Recipient" in the caption field.
11. Finish the wizard. The control is automatically created in the window.

1. On the "Creation" tab, in the "Usual controls" group, click . The control shape appears under the cursor.
2. Click below the "Recipient" control to create the new control.
3. Select the control and press Enter. The text switches to edit mode. Enter "Subject" and validate.

1. On the "Creation" tab, in the "Other controls" group, expand "HTML" and select "HTML Email Editor".
2. The control shape appears under the cursor.
3. Click below the "Subject" control. The HTML Editor control will be automatically created.
4. Enlarge the window using the sizing handles, then enlarge the control vertically and horizontally so that the ribbon of the control and some text lines are visible.

1. Select the HTML Editor control and open the control description window (Alt + Enter).
2. Change the control name. Name the control "HTMEDT_Email".
3. Select "Mini toolbar".
   
   

   The HTML Editor control lets you choose between two types of toolbars: a standard ribbon or a mini toolbar, which is more convenient for writing emails.
4. Confirm.

1. On the "Creation" tab, in the "Usual controls" group, expand "Edit". The list of preset controls is displayed.
2. Select the "File path edit" control and place it below the "HTML Editor" control. The file picker is immediately created.

Align all controls in the window.

We will now create the Button control to send emails.

1. On the "Creation" tab, in the "Usual controls" group, click .
2. Click the location where you want to create the control (e.g., at the bottom of the window).
3. Select the control and change its text (press Enter for example). Enter "Send".

1. Right-click the Button control to open the context menu, and select "Code".
2. Write the following lines of code in the "Click" event:
   • WLanguage code for opening the connection and starting the SMTP session:
     

     MySession is emailSMTPSession
     MySession.Name = EDT_User
     MySession.Password = EDT_Password
     MySession.ServerAddress = EDT_SMTP_Server
     MySession.Port = EDT_Port
     // Starts the SMTP session
     IF NOT MySession.StartSession() THEN
     	Error("Unable to connect to the SMTP server.", ErrorInfo())
     	RETURN
     END

     This code uses an advanced emailSMTPSession variable. The different properties of this variable define the characteristics of the SMTP session. Then, the <Session>.StartSession function is used to start the session.
   • WLanguage code for preparing the email:
     

     MyMessage is Email
     
     MyMessage.Sender = EDT_Sender
     MyMessage.Subject = EDT_Subject
     
     HTMEDT_Email.ToEmail(MyMessage)
     
     // Adds a recipient
     MyMessage.Recipient.Add(COMBO_Recipient.DisplayedValue)
     
     // Adds the attachment if necessary
     IF EDT_File <> "" THEN
     	MyMessage.LoadAttachment(EDT_File)
     END

     This code uses a variable of type Email. The different properties of this variable define the characteristics of the email to be sent. This code associates the content of the different window controls to the properties of the Email variable.
     In this code:
     • <HTML Editor control>.ToEmail directly associates the contents of the email with the corresponding properties of the Email variable. If images are included in the text of the email, they will be automatically added as attachments.
     • <Email>.LoadAttachment integrates the attached file if it exists in the Email variable.
   • WLanguage code for sending the email:
     

     // Sends the email
     IF MySession.SendMessage(MyMessage) = False THEN
     	Error("Message not sent.", ErrorInfo())
     ELSE
     	// Message sent
     	ToastDisplay("Message sent", toastShort, vaMiddle, haCenter)
     END

     The email is sent by <Email>.SendMessage. Simply pass as parameters: the variable that contains the characteristics of the SMTP session, and the variable that contains the characteristics of the email to send.
     If the email is sent, a Toast message is displayed, indicating that the email was sent. A Toast message is a small message that appears for a few seconds.
   • WLanguage code for closing the SMTP session:
     
     // Closes the SMTP session
     MySession.CloseSession()
     
     This code closes the session with <Session>.CloseSession.

Save the window and its code ( or Ctrl + S).

• Add a Button control to close the window.
• Format the window by setting the anchors and the tab order.
• Open the window from the "WIN_Menu" window.

Closing the window

1. Go to the "Creation" tab, "Usual controls" group, and expand "Button" to see the list of preset buttons.
2. Click the "Close" button.
3. Click the position in the window where the control must be created (for example at the bottom, to the right of the "Send" Button control).

Formatting

• Select the "Sender", "Recipient" and "Subject" controls and set their anchor mode to "Width".
• Select the "HTML Editor" control and set its anchor mode to "Width and height".
• Select the Button controls and set their anchor mode to "Right and bottom".
• Select the file picker and set its anchor mode to "Width and bottom".

The tab order of the controls is the order in which the user will be able to enter the values in the different controls of the window. At runtime, the Tab key allows switching from one control to another. The default tab order is the order in which the controls have been created.

1. Display the tab order by pressing F5.
2. Set the tab order to automatic. To do so, go to the "Window" tab, "Order" group, expand "Tab order" and select "Define automatically".
3. The numbers change and appear in order.
   
4. Press F5 again to hide the numbers.
5. Save the window ( or Ctrl + S).

Opening the window from the drop-down menu

We created the drop-down menu in lesson 5 of this tutorial.

1. Open "WIN_Menu" in the editor (double-click its name in the "Project explorer" pane, for example).
2. In the editor, expand the "Menu" option and select "Exit".
3. Right-click the "Exit" option to open the context menu and select "Add option before".
4. Type the option caption ("Send an email") and confirm.
5. Select the "Exit" option again.
6. Right-click the "Exit" option to open the context menu and select "Insert a separator".

1. Right-click the "Send an email" option to open the context menu and select "Code".
2. Write the following WLanguage code:
   
   // Opens the window for sending emails
   WIN_Sending_an_email.OpenChild()
   
   In this WLanguage code, <Window>.OpenChild opens the window in "non-modal" mode. This means the user can both write an email and see the information in the main window.

Save the window and its code ( or Ctrl + S).

Test the project (click in the quick access buttons) and open the window for sending emails via "Menu .. Send an email".