Products
Contact Support Additional Learning Monthly Product Updates
Menu

Forsta Survey Designer Support

All the topics, resources needed for Forsta Survey Designer.

Creating and Using Custom Questions

  • Last updated:

Articles in this section

In this article

    Creating a New Custom Question from scratch

    1. Go to the "Custom Questions" client app:

      2. image

      Figure 1 - Entering Custom Questions

    2. Click the New Custom Question button:

      3. image

      Figure 2 - The New Custom Question Button

    3. In the modal dialog specify the name (for example, "My custom single question"), base question type (for example, "Single Choice") and template type (for example, "Nodejs pipeline (Advanced)"). See nodejs pipeline template details herehere

    image

    Figure 3 - The New Custom Question Dialog

    • Enable default rendering - (off by default) the original question (the one the custom question is based on) will not normally be rendered, so you will need to build custom question markup and behavior from scratch. Toggle this on to preserve the original html and behavior of a question so you can extend it where needed rather than having to rebuild the entire question.

    1. Click Create & Download Source Code and wait until the task is finished. On completion a "successful operation" banner is displayed and a zip file in the format cq_\{uniqiue id\}_src.zip is downloaded. The zip file contains the source code for your custom question.

      2. image

      Figure 4 - New custom question successfully created

    2. Click View custom question. You are redirected to the new custom question’s Overview page.

    Custom question in SurveyDesigner and surveys

    1. Go to SurveyDesigner (if SurveyDesigner is already opened, then reload the page in the browser).

      2. image

      Figure 5 - Entering Survey Designer

    2. Create a new test survey with responsive layout (for example, "Public Responsive Whitespace Layout") or use an existing survey. Custom questions appear at the bottom of the "Add question" view:

      3. image

      Figure 6 - Custom Questions in the Add Questions view

    3. Choose My custom single question.

    You now have a survey containing a single custom question. The question has a settings page (Question details → Custom settings tab), and you can see the custom question in the survey using preview/quicktest etc. The screenshot below shows the settings page and preview.

    image

    Figure 7 - Settings Page and Preview

    When you launch the survey you’ll see the same question as in the preview.

    Development

    1. Create a new folder "My custom question", and extract the downloaded zip file (from Creation topic above) to that folder. The default file structure for "nodejs pipeline" template is as follows:

      2. image

      Figure 8 - Default File Structure for "nodejs pipline"

      metadata.json contains the custom question configuration (see Getting Started), the design folder contains the settings page (see Settings Page), and the runtime folder contains the runtime component (see Runtime Component).

    2. Open the terminal app and go to the folder containing the custom question files.
    3. Run npm install to install the nodejs dependencies for your project to the node_modules folder. It must be done only once.
    4. To run a local webserver for development, run npm start and wait until the "Server running" message appears. The Default server is available on the https://localhost:1234 address:

      5. image

      Figure 9 - Running a local webserver for development

    5. To enable the custom question DevMode (see Dev Mode), go the the Overview page and enter your running webserver address (in this case https://localhost:1234) to the "DevServer URL Override". Then click Enable Dev Mode.

      6. image

      Figure 10 - Enabling Dev Mode

      When DevMode is enabled, your custom question resources will be hosted from your local machine instead of Forsta servers. This is to simplify development.

    6. Open the survey in which you have created your custom question in Survey Designer, and open the "Custom settings" tab. If you have not yet accepted the HTTPS certificate, an empty iframe is loaded because a self-signed certificate is not valid for the browser:

      7. image

      Figure 11 - An Empty iframe

    7. You must therefore allow the browser to accept it. Open the link to any valid resource from your local webserver in a separate browser tab (for example, https://localhost:1234/design/index.html). For Chrome-based browsers you will see a "Your connection is not private" warning. Click the Advanced button, then click Proceed to localhost (unsafe) to allow the the browser to use the developer certificate.

      8. image

      Figure 12 - Proceeding to localhost

    8. Accept it once per browser, or allow the specific certificate globally. After certificate access has changed, reload the Survey Designer window. See Dev ModeCertificates for details.

    We will now make some changes in a settings page.

    1. Open design/index.html in your favorite code editor and make some changes (in this example, add "<h1>Hello from DevMode</h1>" before the "Input 1 label" label element). When you save the file the changes will immediately be visible in the SurveyDesigner’s "Custom settings" tab:

      2. image

      Figure 13 - Custom settings tab

    2. A similar process is required for the runtime in-survey component. Run Preview in Survey Designer, the page will show the "hello world" caption for the custom question. Open runtime/component.js in your editor and change "hello world" to "hello devmode". Once you have saved the file, re-open Preview (or re-run QuickTest) to see the changes.

    image

    Figure 14 - Previewing changes

    Deploy

    1. When your custom question is ready to be released, disable DevMode (go to the Overview page and click Disable Dev Mode), stop the local webserver and reload the Survey Designer window.
    2. To build the custom question bundle, run npm run build. This will generate the bundle as a zip file located in /dist-bundle/bundle.zip.
    3. Upload the created zip file from the Overview page by clicking Update zip file.

    Examples

    Youtube Videoplayer CustomQuestion example: https://github.com/ForstaGlobal/CustomQuestionVideoPlayer

    Features:

    • runtime implementation is in vanilla js (without dependencies) and design implementation is in react using material-ui components

    • common folder code is shared between design and runtime

    • fallback to the same default CQ settings in both design and runtime

    • css styles as part of parcel pipeline

    • custom react components with its own state and debouncer

    • render some code conditionally only in devmode session (debug)

    • uses onInit instead of onSettingsReceived with manual state handling

    • optional multi language support