Wizard’s Toolkit Emailing
Websites often need to send emails for registrations, forgotten passwords, automated reminders and all sorts of other
reasons. Since emailing is so critical, Wizard’s Toolkit has several functions and pages to make this easier
for the developer.
Table of Contents
-
Setting Up Emailing
-
Functions in PHP
-
HTML Form Emailing
-
JavaScript Functions
Setting Up Emailing
All server-specific PHP Global variables are defined in wtk/wtkServerInfo.php. The easiest way to
verify your email setup is correct is to use /testWTKEmail.php in
your localhost environment. There you can easily test different configurations until you find
what works.
Wizard’s Toolkit has functions written which work well with PHPMailer and with PostmarkApp.
Configuration Variables
- $gloEmailFromAddress : email address used for sending emails
- $gloTechSupport : the tech support email address for website
- $gloEmailMethod : PostmarkApp, sendMail, smtp, qmail, mail
- $gloPostmarkToken : only applicable if using service and Email Method "PostmarkApp"
- $gloEmailHost : this variable and below are not necessary if using PostmarkApp
- $gloEmailPassword : password for email account if necessary to send
- $gloEmailSMTPAuth : PHPMailer uses for $mail->SMTPAuth
- $gloEmailPort : port used for emailing
Most emails you send with Wizard’s Toolkit will use the default email HTML template which
is located in /wtk/htm/ folder. There you will find two HTML files: emailLight.htm and
emailDark.htm. Which one is used is determined by the global PHP variable $gloDarkLight;
if you want the "Light" theme then this variable should be set to 'Light' and if you want the "Dark" theme
this variable should be set to 'Dark'.
Functions in PHP
All emailing related functions are in the /wtk/lib/Email.php file. As with everything in
Wizard’s Toolkit, there is one function which can be called by passing some variables and
it will make a lot of assumptions then call more low-level functions. You, as the developer decide
whether you want the high-level or low-level function when sending an email. Of course you have access
to the code so you can modify these for your own specific needs.
wtkNotifyViaEmail()
You can pass as little as just the Subject and Email Body to this function
and it will default the rest. More functionality can be handled by filling in the optional parameters.
wtkNotifyViaEmail($fncSubject, $fncMessage, $fncToEmail = '', $fncSaveArray = [], $fncCC = '')
This sends email using HTML template, adding log to database
and making so will know when/if email is opened. It defaults to sending email to $gloTechSupport
defined in wtkServerInfo.php but you can pass both a To and a CC email address.
See full functional specifications here .
wtkSendMail()
This calls either wtkSendPHPMail
or wtkPostmarkApp depending on $gloEmailMethod value.
See full functional specifications here .
wtkSendPHPMail()
Uses PHPMailer to send email.
See full functional specifications here .
wtkPostmarkApp()
Uses PostmarkApp to send email.
See full functional specifications here .
wtkSaveEmailSent()
This is called by wtkSendPHPMail and wtkPostmarkApp to log the email into the wtkEmailsSent data table.
See full functional specifications here .
HTML Syntax
The HTML generated by WTK is built for MaterializeCSS.
This of course can be modified for any HTML framework. The only thing that Wizard’s Toolkit relies on
is the form must have a unique ID, the from "email" must use name and id of 'email', and calling the JavaScript
function wtkSendEmail processes the emailing.
Example HTML Form
The below HTML form will validate the email address then AJAX post
to ajxSendEmail.php which will email form contents to the person designated.
JavaScript Functions
wtkSendEmail()
Validate email address and email all form fields.
wtkSendEmail(fncModalId, fncURL, fncFormName, fncEmailBtn)
This sends all form fields to the designated email address.
File Containing Function
/wtk/js/wtkUtils.js
Parameters
-
fncModalId
: string
- Defaults to blank. If form is in modal window pass
in the ID of the modal window and this will close upon successful emailing.
-
fncFormName
: string
- Defaults to 'emailForm'. All form field values
will be sent. Checkbox values are only sent if the checkbox is checked.
-
fncEmailBtn
: string
- Defaults to 'emailBtn'. If the email address is valid,
the button with this id will be disabled for 3.6 seconds to prevent double-click issues.
Action
First this JavaScript function checks the value
in the 'email' field to verify it is a valid email address. Below is sample HTML code.
<button id="emailBtn" onclick="JavaScript:wtkSendEmail('submitWebsite')" class="btn waves-effect waves-light" type="button">Submit</button>
Above is all that is needed to have email sent to
tech support email address as defined in wtkServerInfo.php $gloTechSupport
isValidEmail()
Verifies an email address is valid - returns true if valid and false if not valid.
if (isValidEmail(fncEmail)) {
// valid email - do something
}else{ // not valid email
wtkAlert("Please enter a valid email address.");
}
Pass in a value and this function will return true if value is
in proper format for an email address.
File Containing Function
/wtk/js/wtkUtils.js
Parameters
-
fncEmail
: string
- If format of value passed does not contain the following,
a false will be returned. char@char.char