How to: Write a Custom Question Rendering Package (CQRP)

 

Overview

In addition to the native SurveyToGo question types and renderings, SurveyToGo allows you to create Custom Question Rendering Packages (CQRPs) that give you complete control over how a question is displayed and behaves.

For example, instead of using the built-in rendering for a Scale question:

[Insert image of the default Scale question]

You can create a CQRP that incorporates a custom slider control with a unique appearance and behavior. For example, the following CQRP uses a jQuery Mobile slider:

[Insert image of the custom jQuery Mobile slider]

Although the two sliders may appear similar, they are rendered very differently. 

The first uses SurveyToGo's built-in Scale question rendering, while the second is a fully custom control built with HTML and jQuery Mobile. It communicates with the SurveyToGo Engine to behave like a native question type, even though it is entirely custom.

The flexibility of CQRPs allows anyone with a basic understanding of HTML, JavaScript, CSS, jQuery, and jQuery Mobile to create custom question renderings tailored to the specific needs of their projects.

This guide walks you through the process of creating a CQRP package that can be used in SurveyToGo.

As an example, you will build the custom slider shown above. The complete source code for this CQRP package, including inline code comments, is provided in the attached file.

Prerequisites: This guide assumes you are familiar with HTML, JavaScript, CSS, jQuery, and jQuery Mobile. If you are not familiar with these technologies, we recommend familiarizing yourself with them before continuing.

The information is based on the free JQuery mobile slider found here:

https://demos.jquerymobile.com/1.2.0/docs/forms/slider/

Below is a workable slider demo:  https://www.w3schools.com/jquerymobile/tryit.asp?filename=tryjqmob_forms_slider

Step 1: Start the Project

Download the main HTML file along with all required JavaScript (JS) and CSS files to your local computer. For better organization, place each file in its corresponding folder.

Next, create a file named Page1.html in the HTML folder. This file contains the slider code, modified to reference the local JS and CSS files instead of the online versions.

The source code for the modified Page1.html is shown below.

Note: The src and href attributes have been updated to reference the local files rather than the web-hosted versions.

This page is responsible for creating the jQuery slider. Notice that the min, max, and value properties have been removed from the slider configuration, as these values will be controlled later.

Once you've completed this step, open Page1.html in your web browser to verify that the slider displays and functions as expected.

Important: Before proceeding, test the page on the target device (phone or tablet) as well as on your computer. Some mobile browsers may not support all the features available in desktop browsers, so it is important to confirm that the page renders and behaves correctly on the device where it will be used.

Step 2: Adding support for the SurveyToGo Engine

There are 2 integration points with the Engine:

Integration Point 1

In this case, we need to add the STG_Loaded() function and run our initialization code inside it.

The initialization code includes:

1. 1. Mandatory: Set the slider’s current position to the question’s previously saved value.

   2. Optional: Set the slider’s minimum and maximum values based on the values defined by the user in SurveyToGo Studio.

Implementing Step 1: Set the Previously Saved Value

To set the previously saved value, first check whether the question was already answered. If it was answered, retrieve the saved value and set it as the current value of the slider.

To interact with the SurveyToGo Engine, use the following functions:

STG.WasAnswered(): Returns whether the question was previously answered.

STG.getUL(): Returns the SurveyToGo UserLogic model, which provides access to SurveyToGo functions.

STG.getCurrQues(): Returns the index of the current question.

For more information about accessing the engine, see: How-to-Access-Various-Engine-Components-From-Within-a-CQRP

We check whether the question was answered. If it was, we retrieve the last value that was set using the Answer() function of the UserLogic model.

Implementing Step 2: Set the Minimum and Maximum Values

To set the minimum and maximum values, reference the options configured by the SurveyToGo Studio user for the question hosting this control.

When using this technique, make sure the survey scripter who will use your CQRP package knows which properties can be used to dynamically change the control’s behavior.

In this example, we use the Upper Limit and Lower Limit properties of the Scale question in SurveyToGo Studio. These properties allow the user to dynamically control the slider’s minimum and maximum values.

Here is the code:

Use STG.getMinRange() and STG.getMaxRange() to retrieve the Lower Limit and Upper Limit values configured in SurveyToGo Studio. These values are then used to set the slider's minimum and maximum range.

The complete implementation of the STG_Loaded() function is shown below.

Integration Point 2

After implementing the code required for Integration Point 1, the next step is to notify the SurveyToGo Engine whenever the slider value changes.

To do this, capture the slider’s slide stopped event. When the event is triggered, notify the engine that the value has changed and pass the new value.

The code uses the STG.AnswerChanged() function to notify the SurveyToGo Engine of the updated value.

 

Step 3: Generate the CQRP ZIP File

The final step is to package the project into a ZIP file. This ZIP file is the CQRP package that SurveyToGo survey designers (scripters) will use when configuring the custom question.

When creating the ZIP file, include only the folders and files required by the control. Since the package is downloaded to the interviewer’s phone or tablet, keeping it as small as possible helps improve download times and storage efficiency.

After creating the ZIP file, rename it to customSlider.zip.

The resulting customSlider.zip file is your CQRP package and can be distributed to SurveyToGo users for use in their surveys.

Productivity Tip: If you are using a jQuery control that does not work correctly on mobile browsers, you can often enable touch support by using the free jQuery UI Touch Punch library:

https://touchpunch.furf.com/