Custom Templates & Merge Tags

Use your own HTML templates for submission emails instead of our default. Merge tags allow you to build your own templates or merge submission data into our email customization fields.

Using Handlebars

Basin supports Handlebars 4.7.7, a popular templating engine, within custom templates. This provides a powerful way to add dynamic content to your templates.

Basic usage

Handlebars expressions are enclosed by double braces {{}}. They can contain Basin's merge tags that will be replaced with values from your form submissions. For example, {{name}} will output the submitted 'name' field's value.

Builtin Helpers

Handlebars provides several built-in helpers, like {{#if}} and {{#each}}, which provide control structures allowing for more complex templates. For example, the 'if' helper can be used to conditionally render parts of your templates.

Partials

Handlebars partials are reusable pieces of templates. Though Basin doesn't directly support defining your own partials, the concept of using reusable HTML chunks can be achieved by setting up standard sections of your custom templates and copying them where needed.

Block Helpers

Handlebars also offers block helpers. These are more advanced and allow you to create sections that can be overridden by child templates. While these are not natively supported in Basin, understanding their functionality can still provide useful insights into Handlebars' templating capabilities.

For more detailed information on working with Handlebars, we recommend reviewing the full Handlebars guide.

Using Handlebars-helpers

In addition to standard Handlebars functionality, Basin also supports the handlebars-helpers library version 0.10.0. This library adds over 130 helper methods, extending Handlebars' built-in capabilities, and providing more powerful and flexible template creation.

Available Helpers

The handlebars-helpers library is divided into a number of categories, including: array, collection, comparison, date, fs, html, i18n, inflection, logging, markdown, match, math, misc, number, object, path, regex, string, url, and utils. Each category includes multiple helpers. For example, the 'string' category includes helpers like 'camelcase', 'capitalize', 'lowercase', and many more.

For a detailed list of all available helpers and their usage, refer to the library's GitHub repository.

Custom Helper: `camelToHuman`

Beyond the built-in Handlebars helpers and the extensive handlebars-helpers library, Basin offers custom helpers to simplify template formatting.

One of these is the camelToHuman helper, which converts camelCase strings into a more readable, human-friendly format. This is especially useful for displaying field names in a cleaner, readable way in your email templates.

{{camelToHuman "firstName"}}

Output:

first name

Example of Helper Usage

To use a helper in your custom template, you would use the following format: {{helperName parameter1 parameter2}}. For example, to capitalize the 'name' field, you could use the 'capitalize' helper as follows: {{capitalize name}}. This would output the name with the first letter capitalized.

Getting Started With Custom Templates

To use custom templates, follow these steps:

Log in to your Basin account
Select your form
Navigate to the Emails page
Scroll down to the 'Custom Template' section and click the radio button for "Use your own HTML template"
Type in, or paste in your HTML template in the box
Click "Save" at the bottom of the page

Warning

Custom templates do not support special characters or spaces in form field names. This includes hyphens, dashes, and quotation marks. If you have form fields that contain a hyphen, we recommend renaming them to use underscore instead.

Simple HTML example

You can use merge tags to fill in data from a submitted form. So if you had a form like this

<form action="https://usebasin.com/f/1a2b3c4d5e6f" method="POST">
  <label for="name">Name</label>
  <input type="text" id="name" name="name" required>
  <label for="email-address">Email Address</label>
  <input type="email" id="email" name="email" required>
  <button type="submit">Submit</button>
</form>

Your form submissions would look something like this

name	email
Elon Musk	ElonMusk@Tesla.com

You could then access the name and email merge tags by typing in the name of the field inside curly brackets

<html>
  ...
  <b>Name: </b> {{name}}<br>
  <b>Phone number: </b> {{phone_number}}<br>
  ...
</html>

You can use these merge tags in your response emails

Custom subject

Thank you, {{name}}

Custom response

Hello, {{name}}. Thank you for providing us with your information.

Using #each

You can use {{#each form_params}} to get all the values from the form. Use {{this.name}} for the name of the field, and {{this.value}} for the values submitted

Here is all the data submitted: <br>
{{#each form_params}}
  <h2>{{this.name}}</h2>
  <div>{{this.value}}</div>
{{/each}}

Attachments:

For attachments, loop through attached files with {{#each attachment}}, then use {{this.name}}, {{this.public_url}}, and {{this.file_size}}

{{#each attachment}}
  <a href="{{this.public_url}}">{{this.name}}</a>
    <!-- OR -->
  <img src="{{this.public_url}}"/>
  <b>File size:</b>{{this.file_size}} bytes
{{/each}}

Other merge tags

These merge tags are also available to you:

Tag	Description
`{{timestamp}}`	Timestamp of when submission was received
`{{self_id}}`	Submission id of submission
`{{form_id}}`	Id of form the submission originated from
`{{form_name}}`	Name of form the submission originated from
`{{project_name}}`	Name of project submission originated in
`{{ip_address}}`	Ip address of submission (if available)
`{{origin}}`	Origin of submission (if available)

Note

For {{timestamp}}, the timezone can be selected under the My Account tab in Account Settings.

Please note

We can't possibly catch all the errors that you may have in your template. If the template throws an error, you will receive the submission email with our default template and a note that your template didn't work. If you need help with your template, feel free to contact us.

Our default template can be found here