PC SOFT

ONLINE HELP
 WINDEVWEBDEV AND WINDEV MOBILE

Home | Sign in | English EN
New WINDEV 26 feature!
  • In this lesson you will learn the following concepts
  • Overview
  • A window for sending emails
  • Creating the window
  • Creating the controls to send emails
  • Creating the controls to enter the email characteristics
  • Sending the email
  • Window improvements
  • Closing the window
  • Formatting
  • Non-modal opening of window
Lesson 4.8. Sending an email
In this lesson you will learn the following concepts
  • 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.
Lesson duration

Estimated time: 20 mn
Previous LessonTable of contentsNext Lesson
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...
WINDEV proposes several methods for managing emails:
  • Management via Lotus Notes, Outloook or MS Exchange:
    • Lotus Notes or Outlook messaging software: these programs allow you to send and receive emails.
    • "Simple Mail API" (also called SMAPI or Simple MAPI): this management mode of emails is used by most of the Microsoft applications, especially by Microsoft Exchange.
  • Management via the POP3, IMAP and SMTP protocols:
    • POP3 protocol: this protocol for receiving emails is recognized by all service providers. It is used to communicate with the server directly, available at your ISP. This protocol is used to list and read incoming messages.
    • IMAP protocol: this protocol for receiving emails is used to leave the emails on the server so that they can be consulted from different emails clients or webmails.
    • SMTP protocol: this protocol for sending emails is recognized by all service providers.
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 an email
We are going to use the SMTP protocol. Indeed, this mode is commonly used all over the world.
For more details on the other methods, see Communicating by emails.

  • Open the project you worked on in the previous lesson if necessary.
    1. Go to the WINDEV home page (Ctrl + <).
    2. On the home page, click "Tutorial", then in "Part 4 - Full application with data", double-click "Full application (Exercise)".
    3. A dialogue box prompts you to open the project you worked on in the previous lesson. You can open the local copy or the original project. Select "Open the local copy".

Answer

A corrected project is available. This project contains the different elements created in this lesson. To open the corrected project, go to the home page and click "Tutorial", then in "Part 4 - Full application with data", double-click "Full application (Answers)".

Example

See the "WD Mail" example (full example supplied with WINDEV) for more details. This example is accessible from the WINDEV home page (Ctrl + <).
A window for sending 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. Open the "WD Full Application" project if necessary.
    2. Create a new blank window.
      • Click Create an element among the quick access buttons.
      • The element creation window appears: click "Window" then "Window".
      • The window creation wizard starts.
      • In the "Based on a template" tab pane, select "Use: WINTPL_Template" and validate the wizard.
    3. The save window appears. Enter "Sending an email" in the title field, the name is automatically proposed: "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 corresponding to the name of the SMTP server:
    1. On the "Creation" pane, 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 can be edited. Enter "SMTP server" and validate. The control name automatically corresponds to EDT_SMTP_Server.
  • To create the edit control corresponding to the port:
    1. On the "Creation" pane, in the "Usual controls" group, expand "Edit".
    2. Select a preset Integer edit control.
    3. The control shape appears under the cursor.
    4. Click below the "SMTP server" control: the edit control is automatically created.
    5. Select the control and press Enter. The text can be edited. Enter "Port" and validate. The control name automatically corresponds to EDT_Port.
  • To create the edit control corresponding to the user name:
    1. On the "Creation" pane, in the "Usual controls" group, click Create an edit control.
    2. The control shape appears under the cursor.
    3. Click below the "Port" control: the edit control is automatically created.
    4. Select the control and press Enter. The text can be edited. Enter "User" and validate. The control name automatically corresponds to EDT_User.
  • To create the edit control corresponding to the user password:
    1. On the "Creation" pane, 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.

      Tip

      The "Password" edit control appears in the editor with a bullet and an eye.
      At runtime, when the user enters their password, the characters will be replaced by bullets. Users will be able to click the eye icon to toggle the visibility of the password: this allows users to check their passwords.
      This feature can be disabled by programming if necessary. For more details, see Showing the password.
  • Align the created controls:
    1. Select the four controls.
    2. On the "Alignment" pane, in the "Inside and outside" group, click "Justify (Ins. and Out.)".
      'Alignment' pane
      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 must have:
  • A control to enter the sender 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 are now going to create these controls in our window.

  • To create the edit control corresponding to the sender address:
    1. On the "Creation" pane, 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".
    3. The control shape appears under the cursor.
    4. Click below the "Password" control: the edit control is automatically created.
    5. Select the control and press Enter. The text can be edited. Enter "Sender" and validate.
  • The control used to type the recipient address must list the addresses of the customers found in the database but it must 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" pane, in the "Usual controls" group, click "Combo Box".
    2. The control shape appears under the cursor.
    3. Click below the "Sender" control: the Combo Box control creation wizard starts automatically.
    4. Select "Display the data found in a file or in an existing query". Go to the next step.
    5. Select the Customer data file. Go to the next step.
    6. The email addresses of the customers must be displayed in the control:
      • Uncheck the "CustomerID" item.
      • Check the "Email" item.
      Go to the next step.
    7. The sort item is the "Email" item. Go to the next step.
    8. The return value is the "Email" item. Go to the next step.
    9. Keep the default options. Go to the next step.
    10. In the "Additional settings" screen, check "Allow input". Indeed, the user must have the ability to type a new email address. Go to the next step.
    11. Modify the name and caption of the Combo Box control:
      • Enter "COMBO_Recipient" in the name field.
      • Enter "Recipient" in the caption field.
    12. Validate the wizard. The control is automatically created in the window.
  • To create the edit control corresponding to the email subject:
    1. On the "Creation" pane, in the "Usual controls" group, click Create an edit control.
    2. The control shape appears under the cursor.
    3. Click below the "Recipient" control: the edit control is automatically created.
    4. Select the control and press Enter. The text can be edited. Enter "Subject" and validate.
  • 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" pane, 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 lines are visible.
    5. Select the HTML Editor control and open the control description window (Alt + Enter).
    6. Modify the control name. Enter "HTMEDT_Email" in the "Name" field.
  • We are going to create a file picker allowing the user to add an attachment. Instead of creating it from scratch, we will use a file preset edit control. 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" pane, 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.

Sending the email

  • 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" pane, in the "Usual controls" group, click Create a Button control.
    2. Click the location where the control will be created (at the bottom of the window for example).
    3. Select the control and modify its text (press Enter for example). Enter "Send".
    4. Edit the WLanguage code associated with this Button control: select "Code" in the context menu (right click).
    5. 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 are used to define the characteristics of the SMTP session. Then, <Session>.StartSession associated with this variable 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 an Email variable. The different properties of this variable are used to define the characteristics of the email to send. 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" pane, in the "Usual controls" group, expand "Button": the list of preset buttons is displayed.
    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: these controls must be anchored horizontally.
    • Select the "HTML Editor" control: this control must be anchored vertically and horizontally.
    • Select the Button controls: these controls must be anchored to the right and to the bottom.
    • Select the file selection control: this control must be anchored horizontally and to the bottom.
  • To define the tab order:

    Remark

    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. It can be modified:
    • by specifying an automatic tab order: the first control in the upper-left area of the window will be the first in the tab order, the second control will be the one to its right or below...
    • by specifying a tab order from a selection.
    1. Display the tab order by pressing F5.
    2. Define the automatic tab order: on the "Window" pane, in the "Order" group, expand "Tab order" and select "Define automatically".
    3. The numbers are modified and they now appear in order.
      Tab order
    4. Press F5 again to hide the numbers.
    5. Save the window ( Save an element or Ctrl + S).

Non-modal opening of window

The window for email management will be opened from the "WIN_Menu" window. Its opening mode is specific because this window must not prevent the information displayed in the "WIN_Menu" window from being viewed.
  • To open the "WIN_Sending_an_email" window from the "WIN_MENU" window:
    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. Open the popup menu of the "Exit" option (right click) and select "Add before".
    4. Type the option caption ("Send an email") and validate.
    5. Select the "Exit" option again.
    6. Open the popup menu of the "Exit" option (right click) and select "Insert a separator".
    7. Open the popup menu of the "Send an email" option (right click) and select "Code".
    8. 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 among the quick access buttons) and open the email window via "Menu .. Send an email".
    Email send test
Previous LessonTable of contentsNext Lesson
Minimum version required
  • Version 26
Comments
Click [Add] to post a comment