Template Management
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.
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.
Currently there are three possible operations on templates. You can list uploaded ones, download them or upload new ones with these skycli commands.
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.
​
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.htmlwelcome_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.
{{ .appname }}{{ .email }}{{ .user }}{{ .url_prefix }}
​
This template will be used to generate forgot password emails. Again there are two available formats:
forgot_password_email.htmlforgot_password_email.txt
{{ .appname }}{{ .link }}{{ .email }}{{ .user }}{{ .user_id }}{{ .url_prefix }}{{ .code }}{{ .expire_at }}
​
Allow customization on the password reset page:
forgot_password_reset.html
{{ .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>
​
HTML-based templates that are responsible for reset password success and failure page respectively:
forgot_password_success.htmlforgot_password_error.html
Only the error one has variables:
{{ .error }}
​
Two templates are available to customize the appearance of emails carrying the Out of Band (OOB) code for MFA:
mfa_oob_code_email.htmlmfa_obb_code_email.txt
SMS content can also be altered with:
mfa_oob_code_sms.txt
{{ .appname }}{{ .code }}
​
Emails sent to verify user can be modified with the use of these:
user_verification_email.htmluser_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.
Both the email or SMS templates are eligible to use these:
{{ .appname }}{{ .login_id_key }}{{ .login_id }}{{ .user }}{{ .user_id }}{{ .code }}{{ .link }}
​
Templates to customize the appearance of user verification success and error pages:
user_verification_success.htmluser_verification_error.html
Again, has to be in a login-id-named directory.
Only the error one has variables:
{{ .error }}
​Here is a step-by-step tutorial on how can templates be uploaded to Skygear.
​
