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

Overview

In addition to the native SurveyToGo question types and renderings, SurveyToGo allows you to write Custom Question Rendering Packages (CQRPs) that allow you to control how the question is rendered. For example, instead of showing the Scale question with its built in rendering:

You can instead create a CQRP that will incorporate a custom slider control and will look different along with some custom behavior if necessary. For example, here is CQRP package that uses a JQuery Mobile slider:

Now while the two sliders might look roughly the same, they are rendered very differently. The first is the default built-in Scale question rendering while the second is a completely custom rendered control using HTML and JQuery Mobile and is interacting with the SurveyToGo Engine to look as if it is a native question type even though it is not. The possibilities using this technique are endless and will allow anybody with basic knowledge of HTML and Javascript to create any custom question rendering that suite your specific project requirements.

In this How-to we will show you how to create a CQRP package that can be used in SurveyToGo. Click here for a guide on how to use the CQRP package (zip file) within SurveyToGo once the zip file is ready.

In this guide we will create a CQRP package for the custom Slider shown above. The full source code of this CQRP package along with inline code documentation can be downloaded from here: http://dblstg.dooblo.net/downloads/MobileSlider-CQRP.zip

Important note: this guide assumes prior knowledge in HTML, Javascript, CSS, JQuery and JQuery Mobile. If you are not familiar with these technologies it is recommended that you first take a moment to familiarize yourself with them before continuing.

Step 1: Starting the project

We will base this guide on the free JQuery mobile slider that can be found here:

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

and a workable demo of it here: http://www.w3schools.com/jquerymobile/tryit.asp?filename=tryjqmob_forms_slider

Our first step would be to download the main HTML file along with any JS files and CSS files it uses to our local computer. For clarity, we downloaded each file(s) to their corresponding folders:

Then we put in the HTML folder a single file called “Page1.html” that has the code of the slider, but modified to reference the local folders instead of the web ones (for JS and CSS). Here is the source of the modified page1.html:

Note how we’ve replaces the “src” and “href” to point locally instead of to the web.

This page creates the JQuery slider and that’s it. Note how we removed the “min” “max” and “value” properties from the configuration of the slider as we will control these later.

At this stage you can test the control in your browser to make sure it works like you want it to:

** Important note: Please at this stage test that you can view the page correctly in your device browser (Phone/Tablet) as sometimes the browser on the tablet/phone will not support all that the PC supports.

Step 2: Adding support for the SurveyToGo Engine

Now that we have the basic control up and running, it is time to integrate it with the SurveyToGo engine. There are 2 integration points with the Engine:

Integration point 1

So in our case, we need to add the “STG_Loaded()” function and in there run our initialization code which consists of:

1. (Mandatory): Setting the previously saved value of the question to be the current position of the slider.
2. (Optional) Setting the min/max values of the slider to the ones that the user set in the SurveyToGo Studio.

Implementing #1: Setting the previously saved value is done by first checking if the question was answered and then retrieving the value and setting it to be the value of the control:

To interact with the SurveyToGo Engine we used the functions:

1. STG.WasAnswered(): returns if the question was previously answered
2. STG.getUL(): returns the UserLogic model of SurveyToGo which grants you access to all the functions of SurveyToGo
3. STG.getCurrQues(): returns the question index of the current question.

(for more information on accessing the engine, please see this link: How-to-Access-Various-Engine-Components-From-Within-a-CQRP)  

We check if the question was answered and if so we retrieve the last value that was set through the “Answer()” function of the user logic.

Implementing #2: To set the min/max values we can reference the options set by the SurveyToGo Studio user for the question that will host this control. If you are using this technique please make sure the scripter of the survey that will use your CQRP package knows which properties to use to dynamically change your control behavior. In our case we will use the “Upper Limit” and “Lower limit” of the Scale question properties of the Studio to allow the user to dynamically control our slider min/max settings:

Here is the code:

We use the “STG.getMinRange()” and “STG.getMaxRange()” to get the settings from the Studio and then use them in the slider. Here is how the full code of the STG_Loaded function looks like:

Integration point 2

So after implementing the code necessary for Integration point 1, we now move to implement the second part of the integration, which is to indicate to the engine once the value is changed. We do this by catching the “slide stopped” event of the slider control and notifying the engine that the value changed and passing the new value:

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

Step 3: Generating the CQRP zip file

Our final step is to create a zip file with all the content. The zip file is then used by the SurveyToGo survey designer (scripter) when configuring the question. It is important that the zip file only contains the folders necessary as it will be downloaded to the tablets / phones when used. To generate our zip file:

And after creating the zip file, we renamed it to “customSlider.zip”:

This is the CQRP package file which can be sent to the users of SurveyToGo to use.

Click here for the guide on how to use the CQRP package file within SurveyToGo.

Final productivity tip: Please note that you can take JQuery controls that do not work on mobile browsers and get them to work correctly using this free utility library:http://touchpunch.furf.com/

That’s it! 

Visit us at: http://www.dooblo.net