Wizard’s Toolkit Documentation

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 .

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.

<div id="submitWebsite" class="modal container grey darken-4 content"> <div class="modal-content"> <a class="btn btn-mini grey darken-2 waves-effect modal-close right">X</a> <form method="post" id="emailForm" name="submitForm"> <div class="row"> <div class="input-field col m6 s12"> <input id="yourWebsite" name="yourWebsite" type="text" class="validate deep-purple-text text-lighten-4"> <label for="yourWebsite">URL for your website using Wizards Toolkit</label> </div> <div class="input-field col m6 s12"> <input id="email" name="email" type="email" class="validate deep-purple-text text-lighten-4"> <label for="email">Your email address</label> </div> <div class="input-field col m9 s12"> <textarea id="note" name="note" class="materialize-textarea deep-purple-text text-lighten-4"></textarea> <label for="note">Editorial Text you would like displayed about your website or app</label> </div> <div class="input-field col m3 s12"> <button id="emailBtn" onclick="JavaScript:wtkSendEmail('submitWebsite')" class="btn waves-effect waves-light" type="button">Submit</button> </div> </div> </form> </div> </div>

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

Search results