Custom

A custom question, hosted by you within an iframe.

Formsort supports dozens of question types out of the box. However, in some cases it makes sense for you to implement a custom question type yourself using the Formsort Custom Question API.

A great example of this would be an airline ticket purchasing flow, which at one point requires picking a seat (or multiple seats).

While you could use select buttons in a grid to achieve this within Formsort, backed by an API to fetch the choice options, maintaining the logic of which planes are in your fleet and which seats are available would be much more easily done as part of your existing technical infrastructure.

Instead of having to custom engineer the entire form flow, you can build just the single question you need and plug it into your existing flow, reusing the Formsort questions and logic for the remainder.

To view various sample implementations of custom questions, check out this repo: https://github.com/formsort/custom-question-examples

Adding read-only content

The simplest custom content is read only. Once a user sees the content, they will be allowed to continue along in the flow.

This is useful if you have something like a privacy policy you need to show a user, and you don't want to link to it or have to keep the content within Formsort.

To add it, set the Source URL to the URL of your content, and enable Is read-only?.

You yourself host custom content and questions (or use something like a headless CMS to do so). During development, it's recommended to point the Source URL to localhost and view the flow in the Live preview.

Setting the size of the container

Within the custom question settings, you can set the Default width and Default height.

If your content or question is larger than this size, the default behavior is to allow it to scroll. If you'd rather disallow scrolling, you can set the behavior in overflow-y.

Dynamic setting of size

The <iframe> security model does not allow the containing frame to access your content directly, so Formsort does not know the size of your content if you don't tell it.

For example, this snippet would set the size of the question within formsort to the size of the body.

import { setQuestionSize } from '@formsort/custom-question-api';

window.addEventListener('load', () => {
  const width = document.body.offsetWidth;
  const height = document.body.offsetHeight;
  setQuestionSize(width, height);
})

Take care to only call this when your content has fully loaded or rendered (eg, if you're using React, then on the componentDidMount() class method or useEffect hook), and not to make it too big so that the rest of the step it is embedded in becomes unusable.

Collecting an answer from within the question

Of course, being able to actually collect data and store it is the essence of form building.

<iframe> elements may communicate with their containing pages (in our case, the Formsort flow) by passing messages. The Formsort Custom Question API faciliates this with a few methods.

Setting an answer value

To set an answer, use the custom question API's setAnswerValue method with the value you want to store. Like answers to other questions in Formsort, this value will be stored at in the answers using the key specified in Answer variable name, you only need to provide the value.

If I just had a simple text input, my setup would look like this:

<input id="my-input" />

import { setAnswerValue } from '@formsort/custom-question-api';

const inputEl = document.querySelector('#my-input'):
inputEl.addEventListener('change', e => {
  setAnswerValue(e.target.value);
})

Formsort is type-aware, make sure to set the Expected answer type to match the type you are returning.

Clearing an answer value

If your custom question has a notion of clearing a value, you can use the clearAnswerValue with no parameters.

Adding a button to clear the input from the previous example, we can add clearing behavior.

<input id="my-input" />
<button id="clear-btn">Clear</button>

import {
  setAnswerValue ,
  clearAnswerValue
} from '@formsort/custom-question-api';

const inputEl = document.querySelector('#my-input'):
inputEl.addEventListener('change', e => {
  setAnswerValue(e.target.value);
})

const clearBtnEl = document.querySelector('#clear-btn'):
clearBtnEl.addEventListener('click', e => {
  inputEl.value = '';
  clearAnswerValue();
})

Getting the existing value in the frame

Sometimes, the user will already have an answer to the question you are asking, either because they are returning to a flow and you have enabled Returning responder behavior to retain their answers, or they have merely clicked back to a previous step when filling out their flow.

To initialize your question with the existing answer, use the getAnswerValue() method. Note that it returns a promise, since <iframe> can only communicate via asynchronous messages.

import { getAnswerValue } from '@formsort/custom-question-api';

getAnswerValue().then(value => {
  // Initialize your question with the existing value.
})

Accessing other answers already collected

If your question needs to know other answers that have already been collected in the flow, you may obtain a promise for the the whole object of answers already collected using getAllAnswerValues(). You can trust that the answers will be of the types configured within Formsort.

import { getAllAnswerValues } from '@formsort/custom-question-api';

getAllAnswerValues().then(answers => {
  // Initialize your question with the existing values

  const birthday = answers['birthday'] // Access answers using their variable names as defined in Formsort.
})

If you're interested in the responder UUID, you may obtain that in a similar way using getResponderUuid(). This can be used for analytics on your end, or to obtain data about this user from your own systems that might not be present within Formsort.

For additional details, see the Custom Question API repo on GitHub.