Add form fields

Form fields can be added to any Riddle type (Poll, Quiz, Form, Predictor, Personality, Minigame, Story).

You can choose between two options:

1. Add a form builder to this Riddle
2. Add a single standalone form field block to this Riddle
3. Embed an already published Riddle form from your (personal) project

Embedding another form allows you to reuse a form you have already created (= central data collection) but also allows you to build more complex forms than with the builder API.

Add a form builder

Like any other block you might add, such as SingleChoice, you can add form fields to the Riddle build by adding a FormBuilder block item to the blocks array.

Properties

The form fields / builder block consists of:

Example

The FormBuilder block isolated:

{
    "title": "My form builder",
    "type": "FormBuilder",
    "fields": [
        { "title": "Your email", "type": "Email" },
        { "title": "Your name", "type": "Name" }
    ]
}

Used in a poll build:

{
    "type": "Poll",
    "build": {
        "title": "My new poll",
        "blocks": [
            {
                "title": "The best noodles?",
                "type": "SingleChoice",
                "items": [
                    { "title": "Spaghetti" },
                    { "title": "Fusilli" }
                ]
            },
            {
                "title": "My form builder",
                "type": "FormBuilder",
                "fields": [
                    { "title": "Your email", "type": "Email" },
                    { "title": "Your name", "type": "Name" }
                ]
            }
        ],
        "result": {
            "title": "Thank you!",
            "description": "We are happy to have you here"
        }
    }
}

Note: You can add as many form builders as you like as long as you stay within the 500 blocks limit.

The fields format

fields follows the shared item formats: an array of objects, one per field. What is specific here is that a field carries two values of its own - its label, which is its title, and its type:

"fields": [
    { "title": "Your email", "type": "Email" },
    { "title": "Your name", "type": "Name", "isRequired": true }
]

Every other option of a field is a key of the same object - see the property table below.

Available form fields

The field type you send to the API is case-sensitive, and the names above are the Builder API names - reading a Riddle back with riddle_get returns the same names, even though the internal storage uses slightly different ones (e.g. Dropdown is stored as DropDown).

Customizing form fields

Beyond title and type, a field object takes the options of its type - this is where you customize the field and how it behaves.

Here is an example how an Email field can be customized inside a FormBuilder block:

{
    "title": "My form builder",
    "type": "FormBuilder",
    "fields": [
        {
            "title": "Your email",
            "type": "Email",
            "placeholder": "Enter your email address",
            "isRequired": true,
            "requiredMessage": "We will never share your email with anyone else."
        }
    ]
}

Form field properties

Each form field supports different options. Unlike other blocks, a form field rejects a property its type does not support - you get a Property "x" not available in form field type "y" error rather than a silently ignored value. This table illustrates what options are available for which type:

The three is...Enabled flags follow the general feature toggle rule: supplying the content switches the feature on, and an explicit flag always wins.

Two properties depend on another one:

• requiredMessage may only be set on a field that is also isRequired: true - otherwise the build fails.
• regexValidationMessage may only be set together with regex.

Media, Content, Privacy and Captcha are not input fields and have their own, separate property sets - see the sections below.

Adding radio buttons and dropdowns

The RadioButtons and Dropdown field types can be used to create a list of options. You can add as many options as you like in the items array, which follows the shared item formats: an object per option, its text in title. Unlike the surrounding fields, an option needs no type.

Note: On the public API, the fields array of a FormBuilder block (and the items array of a Dropdown or RadioButtons field) is limited to a maximum of 100 entries.

Example FormBuilder object:

{
    "title": "My form builder",
    "type": "FormBuilder",
    "fields": [
        {
            "title": "Your favorite color",
            "type": "RadioButtons",
            "items": [
                { "title": "Red" },
                { "title": "Green" },
                { "title": "Blue" }
            ]
        },
        {
            "title": "Your favorite animal",
            "type": "Dropdown",
            "items": [
                { "title": "Dog" },
                { "title": "Cat" },
                { "title": "Fish" }
            ]
        }
    ]
}

An option object also takes a stable id of your own:

"items": [
    { "id": 10, "title": "Red" },
    { "id": 20, "title": "Green" }
]

Learn more about setting custom ids here.

Adding content and media fields

The Content and Media field types can be used to add additional information to your form.

Example FormBuilder with Content and Media fields:

{
    "title": "My form builder",
    "type": "FormBuilder",
    "fields": [
        {
            "type": "Content",
            "text": "<h2>Welcome to the survey!</h2><p>Please fill out the form below.</p>"
        },
        {
            "type": "Media",
            "media": "https://httpbin.io/image/jpeg",
            "mediaOrientation": "Wide"
        }
    ]
}

Note: Neither field carries a title - a Content field is its text and a Media field is its media. This is the one place in fields where title is not part of the field.

Adding a privacy / GDPR consent field

The Privacy field holds your privacy notice plus the two consent checkboxes a lead capture form needs to be legally usable in the EU. There are always exactly these two checkboxes - you cannot add your own.

Both consent objects take the same properties:

{
    "title": "My form builder",
    "type": "FormBuilder",
    "fields": [
        { "title": "Your email", "type": "Email" },
        {
            "type": "Privacy",
            "privacyText": "<p>We store your email to send you the results. See our privacy policy.</p>",
            "requiredConsentForAddRiddleData": {
                "isEnabled": true,
                "isRequired": true,
                "label": "<p>May we combine your answers with your email?</p>",
                "checkboxText": "<p>Yes, you may</p>"
            },
            "requiredConsentForTracking": {
                "isEnabled": false
            }
        }
    ]
}

Double opt-in (DOI) confirmation is not part of this field - it is a Riddle-wide publish setting, see publish settings.

Adding a captcha field

A google or cloudflare captcha is rejected unless both key and secret are set (empty strings do not count) - a vendor captcha cannot work without them.

Note: secret is write-only. It is never returned when you read a Riddle back as a build configuration, so a credential is not handed out to anyone who can read the Riddle's structure. key is returned - it is the public site key the widget renders into the page anyway. Because a read never returns the secret, re-sending a fetched configuration as an edit keeps the stored one; only a create has to supply it.

{
    "type": "Captcha",
    "captchaType": "cloudflare",
    "key": "0x4AAA...",
    "secret": "0x4AAA..."
}

Adding single standalone form field blocks

If you want to add a single form field instead of a full form builder, you can do so by adding the respective form field type directly to the blocks array.

In addition to the common properties, each form field type supports the same options as described in the Customizing form fields section.

Embed an already published form

You can embed a form from your (personal) project by adding a block of the FormSelect type to the blocks array.

Properties

The form select block consists of:

The referenced Riddle must exist, must be of type Form, and must be accessible to you - otherwise the build fails.

Example

The FormSelect block isolated:

{
    "type": "FormSelect",
    "form": "hQ3SYWur"
}

Used in a poll build:

{
    "type": "Poll",
    "build": {
        "title": "My new poll",
        "blocks": [
            {
                "title": "The best noodles?",
                "type": "SingleChoice",
                "items": [
                    { "title": "Spaghetti" },
                    { "title": "Fusilli" }
                ]
            },
            {
                "type": "FormSelect",
                "form": "hQ3SYWur"
            }
        ],
        "result": {
            "title": "Thank you!",
            "description": "We are happy to have you here"
        }
    }
}

Referencing form fields later

Form fields are what leaderboards and dynamic variables refer back to. You can either reference a field by its label (e.g. "Your email") or by the canonical field key that reading the Riddle back reports (e.g. email1). You can also pin your own id on a field - see custom IDs.

Full example

A complete Form request body with the standalone field blocks from this page built into it.

{
    "type": "Form",
    "build": {
        "title": "Form example (Builder API)",
        "blocks": [
            {
                "title": "Your favorite animal",
                "type": "FormField",
                "fieldType": "Dropdown",
                "items": [
                    { "title": "Dog" },
                    { "title": "Cat" },
                    { "title": "Fish" }
                ]
            },
            {
                "title": "Your email",
                "type": "FormField",
                "fieldType": "Email",
                "placeholder": "Enter your email address",
                "isRequired": true,
                "requiredMessage": "We will never share your email with anyone else."
            }
        ]
    }
}