Template Management

Introduction

Almost every software application that requires users to log in comes with the ability to send password reset and welcome emails. Landing pages for user verification have also become an essential for a secure and complete user registration flow.

In Skygear, these features are all implemented and brought to users out of the box. At the same time one can customize the appearance and behaviours of these emails and landing pages through the use of templates.

Requirements

All user-defined templates must reside in a folder called templates next to skygear.yaml.

Some of them must be placed within a sub-folder named by corresponding Login ID:

templates[/<login_id>]/<template>

Say you have a self-defined Login ID calledcompany_email whose type is a email address and you would like to upload a user_verification_email.html template for it. You will have to place this template under the pathtemplates/company_email/user_verification_email.html, otherwise it will be marked as invalid and the upload will fail.

Operations on Templates

Currently there are three possible operations on templates. You can list uploaded ones, download them or upload new ones with these skycli commands.

Available Templates

All currently available templates on Skygear are listed here.

Each section covers a type of templates, the purpose of them, and the available variables you can put in. App or user specific information is provided via these variables, so that you can tailor make the templates.

Say you would like to include the user's email and app name in the welcome mail, the template can look like:

<html>
<body>
<p>Hello {{ .email }},</p>
<p>Welcome to {{ .appname }}.</p>
<p>Thanks.</p>
</body>
</html>

where {{ .email }} and {{ .appname }} are variables of the welcome email template.

Welcome Email

The template that decides how the welcome email looks like. Since email can come in two formats: HTML and plain text, there exist two types of templates for this:

  • welcome_email.html

  • welcome_email.txt

Note that you will have to turn on "send welcome email" first in either the Web Portal or your app's configuration file. Otherwise welcome emails no matter they are customized or not will not be sent upon new user registration.

Available Variables

  • {{ .appname }}

  • {{ .email }}

  • {{ .user }}

  • {{ .url_prefix }}

Forgot Password Email

This template will be used to generate forgot password emails. Again there are two available formats:

  • forgot_password_email.html

  • forgot_password_email.txt

Available Variables

  • {{ .appname }}

  • {{ .link }}

  • {{ .email }}

  • {{ .user }}

  • {{ .user_id }}

  • {{ .url_prefix }}

  • {{ .code }}

  • {{ .expire_at }}

Forgot Password Reset Page

Allow customization on the password reset page:

  • forgot_password_reset.html

Available Variables

  • {{ .action_url }}

  • {{ .code }}

  • {{ .user_id }}

  • {{ .expire_at }}

These variables are different from those in other templates - they are closely related to the password reset <form> submission while the others are for information displaying purposes only. Here's the default content of the this template to give you an idea on how the variables work:

<!DOCTYPE html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
{{ if .error }}
<p>{{ .error.Message }}</p>
{{ end }}
<form method="POST" action="{{ .action_url }}">
<label for="password">New Password</label>
<input type="password" name="password"><br>
<label for="confirm">Confirm Password</label>
<input type="password" name="confirm"><br>
<input type="hidden" name="code" value="{{ .code }}">
<input type="hidden" name="user_id" value="{{ .user_id }}">
<input type="hidden" name="expire_at" value="{{ .expire_at }}">
<input type="submit" value="Submit">
</form>

Forgot Password Reset Result Pages

HTML-based templates that are responsible for reset password success and failure page respectively:

  • forgot_password_success.html

  • forgot_password_error.html

Available Variables

Only the error one has variables:

  • {{ .error }}

MFA OOB Code Email and SMS

Two templates are available to customize the appearance of emails carrying the Out of Band (OOB) code for MFA:

  • mfa_oob_code_email.html

  • mfa_obb_code_email.txt

SMS content can also be altered with:

  • mfa_oob_code_sms.txt

Available Variables

  • {{ .appname }}

  • {{ .code }}

User Verification Email and SMS

Emails sent to verify user can be modified with the use of these:

  • user_verification_email.html

  • user_verification_email.txt

User verification SMS can also be personalized with:

  • user_verification_sms.txt

Note that they all have to be put under the sub-directory with a valid Login ID name whose type is email.

Available Variables

Both the email or SMS templates are eligible to use these:

  • {{ .appname }}

  • {{ .login_id_key }}

  • {{ .login_id }}

  • {{ .user }}

  • {{ .user_id }}

  • {{ .code }}

  • {{ .link }}

User Verification Result Pages

Templates to customize the appearance of user verification success and error pages:

  • user_verification_success.html

  • user_verification_error.html

Again, has to be in a login-id-named directory.

Available Variables

Only the error one has variables:

  • {{ .error }}

Tutorial on Uploading Templates

Here is a step-by-step tutorial on how can templates be uploaded to Skygear.