Lesson 1: Zephyr Basics

Welcome to our newly overhauled Zephyr pages! See our new Overview, Examples, and Index.
Feedback is welcome at bottom of each page.

This tutorial is a new feature on our site. If you have any comments or questions, we would be happy to hear from you. Please write us at SailthruAcademy@sailthru.com. Also, be sure to revisit the index page soon for additional advanced Zephyr tutorials, which are on the way.

Zephyr is Sailthru’s powerful template language, which enables automation and the creation of dynamic templates that intelligently display content. It is used to personalize emails, pull relevant content or merchandise from your data feeds, set up email triggers, and more!

This lesson focuses on the fundamentals of Zephyr. A foundation is important, so lets get started!

1.1 Zephyr Fundamentals

Zephyr consists of written code surrounded by curly brackets. { } These brackets let our system know you are writing in Zephyr.

Text Strings

Read the following two lines, then submit them. They are both lines of text, but one is being processed by Zephyr. Notice the subtle difference that makes.


    <pre><code></code></pre>

The brackets in the examples above are telling Sailthru to do something with the code you provided inside them. Yes, even plain text can be code.

The first line, without brackets, was left alone, and included in the resulting HTML code as-is. On the second line, you used Zephyr to ‘render’ that plain text, which is a coder’s way of saying you had the result of the Zephyr code inserted into the HTML.

Math

You will use Zephyr to perform lots of actions for you, from rendering user information, URLs, or content to calculating a discount price or deciding a user’s price point. Lets try a bit of basic math with Zephyr.


    <pre><code></code></pre>        Why not make that look better?<form method="POST" class="previewText" id="zephyr-text-1-4">            <textarea form="zephyr-text-1-4" name="preview_text" rows="1">4 + 3 = {4+3}</textarea>            <input type="hidden" name="display-id" value="zephyr-display-1-4"/>            <br><input type="submit" name="previewSubmit" value="Submit" style="margin: 5px 0px 5px 0px;">        </form>        <pre><code></code></pre>

Commenting

You may also want to leave a comment to yourself but not want others to see it in the rendered result. Like HTML, Zephyr offers commenting. Just surround the text inside your brackets with asterisks.


    <pre><code></code></pre>

If you had to input all the information yourself, that wouldn’t save you any time and certainly wouldn’t allow personalization. The next two sections will introduce some of Zephyr’s key features for automation and personalization.

Exercises:

Complete the following with Zephyr

  • “Turn this into a Zephyr comment.”
  • Try uncommenting this one too:
    {*If you can see this, it’s no longer a Zephyr comment. Don’t forget to add quotes if you want the text to be rendered in the HTML output.*}
  • We see price as a number and a currency/denomination, but to computers they are just numbers until you assign a currency/denomination. You can start with the math, and add the rest later.
    • What does 5 dollars times 5 dollars equal? (5 * 5)
    • What does 10 percent of 30 dollars equal? (30 * .10)

    <pre><code></code></pre>

1.2 Control Statements

A core Sailthru functionality is personalizing the content displayed to your users. This section gives you the single best tool to extend user-specific differentiation into every aspect of your templates, from a segment-specific greeting (and default fallback welcome) to showing or hiding full HTML sections. Control statements allow the code to make those decisions.

There are many different forms of control statements but we are starting with the most ubiquitous and useful: The “if condition” statement.

Relational Operators

You will use the if statement to show content or assign variables only IF a certain condition is true.

Lets see how you create a condition that is true. A common case is a comparison. Is ‘a’ equal to ‘b’? Is ‘a’ greater than ‘b’? We can translate that comparison into the Zephyr langauge with the greater than symbol.


    <pre><code></code></pre>                Try changing the greater than sign to a less than sign. Then change the 4 to a 2.        <br>

Conditional Statements

    Notice how the previous result is always "true" or "false". The true/false values are called booleans, which are key to using "if" statements. If statements always need a value of true or false to decide what to do. Let's look at the simplest if statement. <form method="POST" class="previewText" id="zephyr-text-2-2">            <textarea form="zephyr-text-2-2" name="preview_text" rows="4">{*We know 4 > 2 returns true, so we are skipping directly to the boolean to help demonstrate the if statement*}
{if true}
    {"SHOW THIS!"}
{/if}</textarea>            <input type="hidden" name="display-id" value="zephyr-display-2-2"/>            <br><input type="submit" name="previewSubmit" value="Submit" style="margin: 5px 0px 5px 0px;">        </form>        <pre><code></code></pre>                Now, go back and change "true" to "false" and submit again.         <br><br>          That is the essense of the if statement. The code between the first "if" and the second "if" will run and show (render) only if the comparison after the first "if" is true. It will skip the whole "if" section when the value is false.         <br><br>        This example was simple to make the concept clearer, but in the next section we will start using vars and the information stored in Sailthru to make powerful "if" conditionals. First we need to introduce the other comparisons like "equals", to create other boolean true/false values as well as learning the "if else" variation for doing related comparisons.

Additional Relational Operators

“Equals” can be used on text as well as numbers and is done in Zephyr with two equals signs ==, you will learn why it has to be two equals signs in the next section. Play around with the following. Try to get the following two words equal to each other.


    <pre><code></code></pre>                Strings (text) will normally use the equals sign, but for number comparisons you can also use "greater than or equal to" <em>>=</em> and its opposite <em><=</em>.

Lastly, you can reverse any comparison by using the exclamation mark in front of the comparison.


    <pre><code></code></pre>

If-Else Statements

One last thing before we move on to the other good stuff. You can stack on other “if” statements that will only run when the first if statement is false. Not only that, you can have a default section that will render only when all other “if” statements were false.

Submit the Zephyr example below. Then, switch the first true value to “false” and try again. Then do the same with the second. You’ll get each block to render, including the default “else” case.


    <pre><code></code></pre>

Of course, in your Zephyr code, you won’t be hard-coding the words ‘true’ or ‘false’, but instead using forumulas that will evaluate to true or false.

Imagine how powerful all this will be when you want to conditionally show different aspects of your products or content to a user based on each item’s attributes. Lets go learn about variables so we can start building them into your “if” structures.

1.3 Variables

Variables are containers to hold and give you access to your information. Its how you access and render user names, optout links, content and more in your templates. All of the information you import on your user’s will be held in variables -or vars as we like to shorten them. We have created a lot of useful vars that you will be able to use in your templates. You can and will create your own vars too. Let’s learn how to use them by creating some vars of our own.

Assign Variables

You fill in, or assign, the var with the information through an assignment statement. Here is the basic format.

var_name = information 

It’s the name you want to give the var followed by an equals sign, which is immediately followed by the information you want the var to hold. Remember, that information can be pretty much anything you want. The following example assigns a var.


    <pre><code></code></pre>

Nothing shows up when we look at the preview. That is because all we did was assign the string (text) to that variable.

Render Variables

To actually use the var, we need to ‘call’ it in curly brackets { } so Zephyr will ‘render’ it.
Lets call I_am_a_var by placing its variable name inside inside Zephyr brackets.


    <pre><code></code></pre>

To recap, a var that you create needs to be assigned data. Then, you can ‘call’ the var, and the var’s data value will be ‘rendered’ (used/presented).

In addition to rendering the vars that you have created, you can render default vars that are created by Sailthru. Lets try calling the information you uploaded about your users. Hopefully you uploaded a var like first_name but everyone uploaded their user’s email, so we will access their email address in a welcome greeting.


    <pre><code></code></pre>                 But you don't want to use their email, you want to use their first name! When I onboarded, I uploaded Ms Zephyr Trainer with her name in a var called first_name so lets use that!<form method="POST" class="previewText" id="zephyr-text-3-8">            <textarea form="zephyr-text-3-8" name="preview_text" rows="1">Hello {first_name}</textarea>            <input type="hidden" name="display-id" value="zephyr-display-3-8"/>            <br><input type="submit" name="previewSubmit" value="Submit" style="margin: 5px 0px 5px 0px;">        </form>        <pre><code></code></pre>        But what if it doesn't exist? It turns out that if a var doesn't exist it will return false, so we can use "if" statements from the last section. Let's try using a var called <em>first</em>, this time. <form method="POST" class="previewText" id="zephyr-text-3-4">            <textarea form="zephyr-text-3-4" name="preview_text" rows="5">{if first}
    Hello {first},
{else}
    Hello Valued user,
{/if}</textarea>            <input type="hidden" name="display-id" value="zephyr-display-3-4"/>            <br><input type="submit" name="previewSubmit" value="Submit" style="margin: 5px 0px 5px 0px;">        </form>        <pre><code></code></pre>

The var {first} does not exist, so the first if statement evaluated to false. Therefore, the else statement was run and the default line was rendered.

So far we have only included text in our vars, but they can contain many different kinds of information, including numbers and even other variables.


    <pre><code></code></pre>

Arrays

A var doesn’t even need to be limited to a single piece of information like a number or phrase. In fact, it can hold a collection of information in what is called an array. Think of arrays like a list.

An analogy may help. When you go grocery shopping you need peas, carrots, celery, and lentils so you write a shopping list:
-Peas
-Carrots
-Celery
-Lentils

Then in the store, when you need something you consult your “grocery list”. That grocery list is an array!

To convert it into a Zephyr array you start with a name and an equal sign like before. To indicate this is an array, use a square bracket and include each item separated by a comma.

{grocery_array = ["Peas","Carrots","Celery","Lentils"]}

Each one of those items is called a member of the array, so Lentils is the last member of grocery_array. You can call the variable’s name by itself to see all the values inside of it. To use/see a specific member (item) in the array you will use its position to call it. Although, unlike how you or I would count positions, arrays index the position by counting up from 0, not 1. The position (index) number needs to be in square brackets [ ] after the array variable’s name.


Congratulations! You’ve completed Lesson 1: Zephyr Basics!

When you’re ready, continue to Lesson 2: Sailthru Data Basics.

Top