Dynamic variables

In the Riddle Creator you can use dynamic variables to personalize / dynamically display any Riddle / form data.

You can do the same when building a Riddle via the API - all title and description properties can be personalized with dynamic variables.

Syntax

The following syntax is used to embed dynamic variables into a property:

%riddleVariable

Example:

Welcome back, %name!

riddleVariable then needs to be replaced with the variable you want to use. Keep reading to learn which variables you can use.

Rules for the syntax:

• A variable name consists of letters, digits and dots, and is matched case-insensitively (%Name works just as well as %name). A dot at the very end is not part of the variable, so Welcome back, %name. works as expected.
• A variable is only accepted if it exists for this Riddle - see the two sections below. An unknown variable that stands on its own (i.e. is preceded by whitespace) fails the build with Invalid variable found in rich text: %<name> (original text: ...).
• A %something that is not preceded by whitespace is treated as literal text and left untouched, so texts like 50%off do not break the build.

Dynamic Riddle variables

Available variables

Variables that do not exist for the Riddle type you are building are rejected - e.g. %score.number in a Poll.

Example

You could personalize the result page by using the variables result.title, score.number, and score.max:

{
    "result": {
        "title": "Your result: %result.title",
        "description": "You scored %score.number out of %score.max"
    }
}

Dynamic form variables

Added form fields can be used in any following blocks as dynamic variables.

A form field's variable is its field type in lowercase, followed by the position of that field among all fields of the same type: %name1, %name2, %email1, %phone1, %dropdown1, and so on. The first field of a type is additionally available without the number.

For example, adding a FormBuilder with two Name fields and one Email field makes the following variables available:

• %name (this will always be the first Name field)
• %name1
• %name2
• %email (this will always be the first Email field)
• %email1

Here's how you could integrate the variables into a SingleChoice quiz question:

{
    "title": "What's the capital of Germany, %name1 %name2?",
    "type": "SingleChoice",
    "items": [
        { "title": "Berlin", "isCorrect": true },
        { "title": "Lissabon", "isCorrect": false },
        { "title": "Leipzig", "isCorrect": false }
    ]
}

Reading variables back

When you read a Riddle back as a build configuration, variables are turned back into the very %shortcode you would send, so the text can be rebuilt unchanged. For the first field of a type the short form is preferred, i.e. %email rather than %email1.

Two cases cannot be expressed as a shortcode and are therefore returned as the raw variable markup, with a warning for that property:

• a variable that was given a fallback value in the Creator (the API's %shortcode syntax has no way to express a fallback), and
• a variable whose source no longer exists, e.g. because its form field was deleted.