Logic and Personalization

Liquid Templates and Variables

3 min readUpdated Oct 24, 2026

Use Liquid template syntax to show variable values inside widget text and prompts.

Berdee supports Liquid templating inside text-based widget content. This lets you pull runtime variables into the learner experience without duplicating copy across scenes.

Liquid templates are most useful when a scene should adapt to:

A learner choice
A running score
A retry count
A selected topic
A piece of state that changes during the lesson

Where templating is useful

You will most often use Liquid templates in places that display text, such as:

Text blocks
Button labels
Input labels and placeholders
Fill-in-the-blank prompts
Matching labels
Flashcard text
Passages and prompt copy

If a setting displays text to the learner, there is a good chance templating can help.

The two access patterns

Berdee supports two practical ways to reference a variable.

Direct variable access

Use the variable name directly:

You have {{ score }} points.

Every variable is one you create in the lesson. Berdee doesn't fill in the student's name or any other built-in value for you.

Nested variable access

You can also access the same value through the variables object:

Score: {{ variables.score }} / {{ variables.total }}

Both patterns are valid. If your team wants one convention, pick it and stay consistent.

Renaming a variable updates both kinds of tag for you, everywhere in the lesson. See Renaming a variable.

Good practical examples

Count what a student found

Nice work, you found {{ stars_found }} stars.

The tutorial Show a live count of what students discover builds this step by step: each tap adds 1 to a number variable, and a line like Creatures found: {{ found }} of 4 counts up as the student goes.

Show current score

You have {{ variables.score }} points so far.

Reflect a learner choice

You chose the {{ selected_topic }} pathway.

The tutorial Build a silly story from words students pick saves three dropdown choices in variables and tells a story with them: Once upon a time, a {{ adjective }} {{ animal }} decided to {{ action }} all the way to the moon.

Show a number a student typed

You estimated {{ estimate }}.

The tutorial Reveal how close a student's estimate was copies a Number Input's Current value into a number variable when a button is pressed, shows it on the next scene, and uses the same variable in visibility rules to say "So close!" only for estimates within 20 of the answer.

Scene-level feedback

Attempt {{ variables.attempts }}: Read the passage again and try one more time.

How this works with variables

Templating does not create state by itself. It reads the current value of a variable that is already being managed elsewhere.

That usually means:

Create the variable in the variable manager
Update it with an interaction or action
Reference it in widget text with Liquid syntax

This division is useful:

Variables store the state
Actions change the state
Liquid templates display the state.

What you see while editing

The studio doesn't know what a student will choose, so the canvas and the scene thumbnails in the Scenes tab show each placeholder exactly as you typed it, braces and all: Next stop: {{ planet }}!. Students never see the braces. Each one sees their own value in that spot. To check the real wording, open Preview and play through the step that sets the variable.

Common patterns

Branching recap

Store a learner choice in a variable, then reuse that choice in later scenes so the lesson feels connected.

Score messaging

Update a score variable during the lesson, then show the learner a running or final result in text.

Retry coaching

Increment a variable on each unsuccessful attempt, then change the feedback text to become more supportive or more specific.

When to use Liquid instead of duplicate text

Use Liquid when the wording should stay mostly the same but one part needs to change.

Good fit:

Nice work on {{ selected_topic }}.

Bad fit:

Building a huge branching script inside one paragraph when separate scenes or visibility rules would be clearer

If the lesson flow changes significantly, scene logic is usually better than trying to force everything into a single template.

Best practices

Keep variable names readable so templates are easy to scan.
Use templates for small dynamic fragments, not for hiding confusing lesson structure.
Preview scenes after editing templates so you can confirm the runtime values are actually present.
If the text should still make sense before the variable is set, design for that intentionally.