Example: Controller Mail

This example shows how to create a URL that generates an email and then redirect to another page to display a confirmation message.

Note This example is based on the 1.9.x versions of total.js - there are some changes to the mail system in v2.0 and above.

Features covered by this example:

Controllers - route URL requests to code
Views - HTML template engine
Config - settings (mail server) used by the framework
F.route() - define a route
controller.view() - render a HTML template
controller.mail() - send an email
controller.redirect() - redirect a request
@{layout, @{if}, @{fi}, query.success and {@model.key} template tags

Overview

This example will perform the following sequence of events:

Requests to the site homepage (/) route to the view_homepage() function

view_homepage() renders the homepage.html "view" back to the browser
the page contains a link (/mail/) to send email

Requests to /mail/ route to the redirect_mail() function

redirect_mail() renders the email.html view and sends it in an email
the user is then redirected back to the home page

The homepage template detects a ?success query string on the URL and outputs a success message

Routing (Controller)

The routing from URL path to handler function is done by the controller (/controllers/default.js):

exports.install = function() {
  F.route( '/'     , view_homepage );
  F.route( '/mail/', redirect_mail );
};

The first handler function renders homepage.html back to the browser:

function view_homepage() {
	this.view('homepage');
}

Note: The path and extension are automatically added if not specified, so 'homepage' becomes ../views/homepage.html.

The second handler function renders email.html to an SMTP server, and then redirects back to the homepage:

function redirect_mail() {

  // send email template '~email' --> '../views/email.html'
  // the object in the last parameter is the "model"; it can be accessed in the template
  this.mail( 'petersirka@gmail.com', 'Test e-mail', '~email', { name: 'MODEL NAME' } );

  // redirect to home page
  this.redirect('/?success=1'); // <-- note 'success' query string

}

Settings (Config)

The mail server used by .mail() is defined by key : vlaue pairs in the /config file:

// Mail settings
mail.smtp          : smtp.gmail.com
mail.smtp.options  : {"secure":true,"port":465,"user":"YOUR-GMAIL-EMAIL","password":"YOUR-GMAIL-PASSWORD","timeout":10000}
mail.address.from  : petersirka@gmail.com
mail.address.reply : petersirka@gmail.com
mail.address.bcc   :

Templates (Views)

Now let's take a look at the HTML templates. First, the /views/homepage.html:

@{layout('')}

@{if query.success}
    <div style="background-color:#E0E0E0;padding:10px">E-mail was sent.</div>
    <br />
@{fi}

<a href="/mail/">Send e-mail</a>

The @{layout('')} sets the layout for the view, in this case there isn't one.

When the homepage is first displayed, the rendered output will be:
<a href="/mail/">Send e-mail</a>
If the ?success query string is detected, the rendered output will be:
<div style="background-color:#E0E0E0;padding:10px">E-mail was sent.</div>
<br />
<a href="/mail/">Send e-mail</a>

The @{if query.success} checks for the success query string on the URL - if found, the following lines are output up to the {fi} closing tag.

Next, let's look at the HTML template used for the email, /views/email.html:

@{layout('')}

<h1>@{model.name}</h1>
<div>This is message.</div>

You'll notice the @{model.name} tag - it outputs the .name property of the "model" defined earlier in the redirect_mail() function.

The rendered output of this template will be:
<h1>MODEL NAME</h1>
<div>This is message.</div