ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

New WINDEV 2024 feature!
Help / WINDEV Tutorial / Tutorial - WINDEV application: Managing data
  • Lesson 7 - Sending an email
  • Overview
  • New window to send emails
  • Creating the window
  • Creating the controls to send emails
  • Creating the controls to enter the email characteristics
  • WLanguage code for sending the email
  • Window improvements
  • Closing the window
  • Formatting
  • Opening the window from the drop-down menu
  • To sum up

Tutorial - WINDEV application: Managing data

Lesson 7 - Sending an email
We will cover the following topics:
  • How to send an email from a WINDEV application.
  • How to include a supercontrol in a window.
  • How to define the tab order in a window.
  • How to open a non-modal window.
Durée de la leçon 20 mn
Overview
Multiple WLanguage functions allow you to manage incoming and outgoing emails. You also have the ability to access the email characteristics:
  • 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:
Window for sending emails
We will use SMTP to send the email.
WINDEV offers several methods for sending and receiving emails. For more details, see Sending and receiving emails.
First, we will create the window with the different controls for entering the characteristics of the email. Then, we will write the code to send the email.
Warning
This lesson is based on the example developed in lesson 1.
New window to send emails
This window will contain all controls allowing the user to type the different email elements. A "Send" Button control will group all processes used to send the email.

Creating the window

Create a new window:
  1. Click Create an element in the quick access buttons.
  2. Click "Window" then "Window". The window creation wizard opens.
  3. In the "Based on a template" tab pane, select "Use: WINTPL_Template" and finish the wizard.
The save window appears. Enter "Sending an email" in the title field, the name is automatically completed: "WIN_Sending_an_email". Validate the default information.

Creating the controls to send emails

First, we will create all controls for configuring the SMTP server used to send messages. Four edit controls are required:
  • SMTP server,
  • SMTP server port,
  • Username,
  • User password.
To create the Edit control that corresponds to the name of the SMTP server:
  1. On the "Creation" tab, in the "Usual controls" group, click Create an Edit control.
  2. The control shape appears under the cursor.
  3. Click in the upper-left area of the window: the Edit control is automatically created.
  4. Select the control and press Enter. The text becomes editable. Enter "SMTP server" and validate. The control name automatically changes to EDT_SMTP_Server.
It's your turn:
Similarly, create two Edit controls:
  • An EDT_Port control to enter the port of the SMTP server. Enter "Port" for the caption of this control.
  • An EDT_User control to enter the username.
We will create a new Edit control to allow users to enter their password. To do so, we will use one of the preset controls available in WINDEV:
  1. On the "Creation" tab, in the "Usual controls" group, expand "Edit".
  2. Select a preset "Password" edit control.
  3. The control shape appears under the cursor.
  4. Click below the "User" control: the Edit control is automatically created.
    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: this allows users to check their passwords.
Align the controls you have just created:
  1. Select the four controls.
  2. On the "Alignment" tab, in the "Inside and outside" group, click "Justify (Ins. and Out.)".
    'Alignment' tab
    Interface of the window to create
  3. Save the window (Save an element or Ctrl + S).

Creating the controls to enter the email characteristics

To write an email, the user needs:
  • 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.
We will create these controls in our window.

1. Sender's address:
To create the Edit control for the sender's address, we will use a preset control:
  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: the Edit control is automatically created.
  4. Select the control and press Enter. The text becomes editable. Enter "Sender" and validate.
2. Recipient's address:
The control used to type the recipient's address should list the addresses of the customers from the database, but should also allow the user to type another address. To do so, we will use an "Editable combo box" control linked to the Customer data file.
  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 starts 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.
3. Email subject:
To create the Edit control that corresponds to the email subject:
  1. On the "Creation" tab, in the "Usual controls" group, click Create an Edit control. The control shape appears under the cursor.
  2. Click below the "Recipient" control: the Edit control is automatically created.
  3. Select the control and press Enter. The text becomes editable. Enter "Subject" and validate.
4. Message body:
For the message body, we will use an HTML Email Editor control: the user will be able to easily format the email text via a specific ribbon.
  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 is 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.
Let's change the control characteristics via its description window:
  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. Validate.
5. Attachments:
We will create a file picker to allow users to add attachments. Instead of creating it from scratch, we will use a preset Edit control for files. The user will be able to select the file to attach by clicking "Browse" in the context menu of the control.
  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 drag it to the "WIN_Sending_an_email" window: drop the control below the "HTML Editor" control. The file picker is immediately created.
Align all controls in the window.
Window for writing emails
We will now create the Button control to send emails.
WLanguage code for sending the email
The email will be sent by clicking a button. We will create the button in the window and write the corresponding code in WLanguage.
First of all, enlarge the window to have enough space to add a button below the HTML Editor control: use the bottom-right resizing handle of the window.
To create the Button control to send emails:
  1. On the "Creation" tab, in the "Usual controls" group, click Create a Button control.
  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".
Let's move on to the WLanguage code for this button:
  1. Edit the WLanguage code associated with the Button control: right-click and select "Code" in the context menu.
  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 (Save element or Ctrl + S).
Window improvements
We are going to improve our window:
  • 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

To add a Button control to close the window:
  1. On the "Creation" tab, in the "Usual controls" group, expand "Button": the list of preset buttons appears.
  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

To define the anchors:
  • Select the "Sender", "Recipient" and "Subject" controls: anchor these controls horizontally.
  • Select the "HTML Editor" control: anchor this control vertically and horizontally.
  • Select the Button controls: anchor these controls to the right and to the bottom.
  • Select the file selection control: anchor this control horizontally and to the bottom.
Now let's see if the tab order of the controls in the page is consistent.
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.
To define the tab order:
  1. Display the tab order by pressing F5.
  2. Define the automatic tab order: on the "Window" tab, in the "Order" group, expand "Tab order" and select "Define automatically".
  3. The numbers change and appear in order.
    Tab order
  4. Press F5 again to hide the numbers.
  5. Save the window (Save an element or Ctrl + S).

Opening the window from the drop-down menu

The window will be opened directly from a drop-down menu option in "WIN_Menu".
We created the drop-down menu in lesson 5 of this tutorial.
First, let's create the menu option:
  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 to open the context menu of the "Exit" option and select "Add before".
  4. Type the option caption ("Send an email") and validate.
  5. Select the "Exit" option again.
  6. Right-click to open the context menu of the "Exit" option and select "Insert a separator".
Let's look at the code for this option:
  1. Right-click to open the context menu of the "Send an email" option 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 is used to open the window in "non-modal" mode: the user will be able to write an email and to see the information displayed in the main window at the same time.
Save the window and its code (Save an element or Ctrl + S).
Test the project (click Test project in the quick access buttons) and open the window for sending emails via "Menu .. Send an email".
Email send test
To sum up
Completed project
Do you want to check the end result of the steps described here?
A completed project is available. This project contains the different windows created in this lesson. To open the completed project, go to the home page and click "Tutorial", then in "Tutorial - WINDEV application: Manage data", double-click "Full application - Answers".
In this lesson, we discovered how to send an email from a WINDEV application. WINDEV applications can also allow users to read incoming emails. For more details, see Reading an email.
This tutorial, which focuses on developing a management application, is now complete. We recommend you follow the Deploying the application tutorial to learn how to create and distribute the executable file of your application.
Previous LessonTable of contents
Minimum version required
  • Version 2024
Comments
Click [Add] to post a comment

Last update: 12/04/2023

Send a report | Local help