|
| 1 | +## Example: Controller Mail |
| 2 | + |
| 3 | +This example shows how to create a URL that generates an email and then redirect to another page to display a confirmation message. |
| 4 | + |
| 5 | +> **Note** |
| 6 | +> 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. |
| 7 | + |
| 8 | +Features covered by this example: |
| 9 | + |
| 10 | +* Controllers - route URL requests to code |
| 11 | +* Views - HTML template engine |
| 12 | +* Config - settings (mail server) used by the framework |
| 13 | +* `F.route()` - define a route |
| 14 | +* `controller.view()` - render a HTML template |
| 15 | +* `controller.mail()` - send an email |
| 16 | +* `controller.redirect()` - redirect a request |
| 17 | +* `@{layout`, `@{if}`, `@{fi}` and `{@model.key}` template tags |
| 18 | + |
| 19 | +### Overview |
| 20 | + |
| 21 | +This example will perform the following sequence of events: |
| 22 | + |
| 23 | +1. Requests to the site homepage (`/`) route to the `view_homepage()` function |
| 24 | + * `view_homepage()` renders the `homepage.html` "view" back to the browser |
| 25 | + * the page contains a link (`/mail/`) to send email |
| 26 | +2. Requests to `/mail/` route to the `redirect_mail()` function |
| 27 | + * `redirect_mail()` renders the `email.html` view and sends it in an email |
| 28 | + * the user is then redirected back to the home page |
| 29 | +3. The homepage template detects a `?success` query string on the URL and outputs a success message |
| 30 | + |
| 31 | +### Routing (Controller) |
| 32 | + |
| 33 | +The routing from URL path to handler function is done by the controller (`/controllers/default.js`): |
| 34 | + |
| 35 | +```javascript |
| 36 | +exports.install = function() { |
| 37 | + F.route( '/' , view_homepage ); |
| 38 | + F.route( '/mail/', redirect_mail ); |
| 39 | +}; |
| 40 | +``` |
| 41 | + |
| 42 | +The first handler function renders `homepage.html` back to the browser: |
| 43 | + |
| 44 | +```javascript |
| 45 | +function view_homepage() { |
| 46 | + this.view('homepage'); |
| 47 | +} |
| 48 | +``` |
| 49 | + |
| 50 | +> **Note:** |
| 51 | +> The path and extension are automatically added if not specified, so `'homepage'` becomes `../views/homepage.html`. |
| 52 | + |
| 53 | +The second handler function renders `email.html` to an SMTP server, and then redirects back to the homepage: |
| 54 | + |
| 55 | +```javascript |
| 56 | +function redirect_mail() { |
| 57 | + |
| 58 | + // send email template '~email' --> '../views/email.html' |
| 59 | + // the object in the last parameter is the "model"; it can be accessed in the template |
| 60 | + this.mail( 'petersirka@gmail.com', 'Test e-mail', '~email', { name: 'MODEL NAME' } ); |
| 61 | + |
| 62 | + // redirect to home page |
| 63 | + this.redirect('/?success=1'); // <-- note 'success' query string |
| 64 | + |
| 65 | +} |
| 66 | +``` |
| 67 | + |
| 68 | +### Settings (Config) |
| 69 | + |
| 70 | +The mail server used by `.mail()` is defined by `key : vlaue` pairs in the `/config` file: |
| 71 | + |
| 72 | +``` |
| 73 | +// Mail settings |
| 74 | +mail.smtp : smtp.gmail.com |
| 75 | +mail.smtp.options : {"secure":true,"port":465,"user":"YOUR-GMAIL-EMAIL","password":"YOUR-GMAIL-PASSWORD","timeout":10000} |
| 76 | +mail.address.from : petersirka@gmail.com |
| 77 | +mail.address.reply : petersirka@gmail.com |
| 78 | +mail.address.bcc : |
| 79 | +``` |
| 80 | + |
| 81 | +### Templates (Views) |
| 82 | + |
| 83 | +Now let's take a look at the HTML templates. First, the `/views/homepage.html`: |
| 84 | + |
| 85 | +```html |
| 86 | +@{layout('')} |
| 87 | + |
| 88 | +@{if query.success} |
| 89 | + <div style="background-color:#E0E0E0;padding:10px">E-mail was sent.</div> |
| 90 | + <br /> |
| 91 | +@{fi} |
| 92 | + |
| 93 | +<a href="/mail/">Send e-mail</a> |
| 94 | +``` |
| 95 | + |
| 96 | +The `@{layout('')}` sets the layout for the view, in this case there isn't one. |
| 97 | + |
| 98 | +> When the homepage is first displayed, the rendered output will be: |
| 99 | +> |
| 100 | +> ```html |
| 101 | +> <a href="/mail/">Send e-mail</a> |
| 102 | +> ``` |
| 103 | +> |
| 104 | +> If the `?success` query string is detected, the rendered output will be: |
| 105 | +> |
| 106 | +> ```html |
| 107 | +> <div style="background-color:#E0E0E0;padding:10px">E-mail was sent.</div> |
| 108 | +> <br /> |
| 109 | +> <a href="/mail/">Send e-mail</a> |
| 110 | +> ``` |
| 111 | + |
| 112 | +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. |
| 113 | + |
| 114 | +Next, let's look at the HTML template used for the email, `/views/email.html`: |
| 115 | + |
| 116 | +```html |
| 117 | +@{layout('')} |
| 118 | + |
| 119 | +<h1>@{model.name}</h1> |
| 120 | +<div>This is message.</div> |
| 121 | +``` |
| 122 | + |
| 123 | +You'll notice the `@{model.name}` tag - it outputs the `.name` property of the "model" defined earlier in the `redirect_mail()` function. |
| 124 | + |
| 125 | +> The rendered output of this template will be: |
| 126 | +> |
| 127 | +> ```html |
| 128 | +> <h1>MODEL NAME</h1> |
| 129 | +> <div>This is message.</div |
| 130 | +> ``` |
0 commit comments