Pular para o conteúdo principal
Base de Conhecimento da FocusVision

Suspend Tag: Add a Page Break

1:  Overview

The <suspend/> tag is a control element used to create page breaks in your survey.

<radio label="S1" optional="0">
  <title>Are you...</title>
  <row label="r1">Male</row>
  <row label="r2">Female</row>
</radio>
<suspend/>

<number label="S2" size="3" verify="range(1, 125)" optional="0">
  <title>Please enter your age below.</title>
</number>
<suspend/>

<exec cond="S2.ival gt 30">
setMarker('cannot_be_trusted')
</exec>

In the example above, both questions S1 and S2 are shown on separate pages.

A <suspend/> tag must be used before referencing another question. In other words, you cannot reference data at another question that exists on the same page. Why? Because data is not stored until the page is submitted -- and pages can only be submitted when a <suspend/> tag (or the end of the survey) is reached.

For example, the <exec> condition in the code above, cond="S2.ival gt 65", would have generated the following error if a <suspend/> didn't exist after question S2.

Error: Data reference to S2 which does not have data yet

Anytime you need to reference selections made or data supplied at a particular question, there must be a <suspend/> tag between the logic and the question it's referencing.

2:  Attributes

There are two attributes applicable to <suspend/> tags:

2.1:  cond - Set When to Display the Page Break

The cond attribute can be applied to the <suspend/> tag to conditionally execute the <suspend/> element. If the condition evaluates to False, it will not execute.

For example:

<radio label="Q1" optional="0">
  <title>Would you like to show the rest of the survey on a single page?</title>
  <row label="r1">Yes</row>
  <row label="r2">No</row>
</radio>
<suspend/>

<text label="Q2" optional="0" title="How do you feel about driving?" />
<suspend cond="Q1.r2"/>

<text label="Q3" optional="0" title="How do you feel about flying?" />
<suspend cond="Q1.r2"/>

<text label="Q4" optional="0" title="How do you feel about swimming?" />
<suspend cond="Q1.r2"/>

<text label="Q5" optional="0" title="How do you feel about the suffix, -ing?" />
<suspend cond="Q1.r2"/>

In the example above, each question will be displayed on their own page only if "No" is selected at question Q1.

2.2:  url - Redirect to an External URL

The url attribute can be set to a URL address to redirect respondents out of the survey.

When a respondent reaches a page with <suspend url="..."/> specified, they will immediately redirect out of the survey to whatever link/URL is provided. A variable, state, is automatically appended to the URL that can be used to link the respondent back to the survey where they left off.

The state variable is unique and generated automatically on each page of the survey.

This is often used to force respondents to an external page where they can answer additional questions on a different system (e.g. Sawtooth), view a concept hosted somewhere else, or take a break and come back later.

There must be at least one labelled element before the suspend url element, otherwise the redirect will not work.

For example:

<radio label="Q1" optional="0">
  <title>Would you like to take a break from this survey?</title>
  <row label="r1">Yes</row>
  <row label="r2">No</row>
</radio>
<suspend/>

<html label="placeholderredirect" where="none">Redirect placeholder so that the redirect executes</html>

<suspend sst="0" cond ="Q1.r1" url="http://SOME_URL.com"/>

<html label="Welcome_Back" where="survey" cond="Q1.r1">
  <p>Welcome back! Please click "Continue".</p>
</html>
<suspend cond="Q1.r1"/>

Using the suspend URL attribute to redirect respondents outside of the survey will prevent simulated test data from successfully completing the survey. To ensure that this does not happen, please make sure to add the sst="0" attribute to any suspend tags that use the URL attribute.

In the example above, if a respondent selects "Yes" at Q1, they will be redirected the following URL:

http://SOME_URL.com?state=50m3n07S0j...h57aT3v4r14Bl3

The respondent can return to the survey using the original survey URL and their unique state variable appended to the end:

http://.../survey/selfserve
/9d3/proj1234?state=50m3n07S0j1b83r15h57aT3v4r14Bl3

If you redirect respondents to your website, make sure to capture the state variable and provide them with a full link to return to the survey.

3:  Advanced Suspended Redirects

Similar to the <suspend url="..."/> method mentioned above, you can use the suspendExternal(URL) function to manually redirect respondents.

There must be at least one labelled element before the suspendExternal function call, otherwise the redirect may not work properly.

For example:

<exec sst="0">
if Q999.r1:
suspendExternal("http://SOME_URL.com?return-url=[return]")
</exec>

Using the suspendExternal attribute to redirect respondents outside of the survey will prevent simulated test data from successfully completing the survey. To ensure that this does not happen, please make sure to add the sst="0" attribute to any exec tags that use the suspendExternal attribute.

Using this method, you can append the variable, return, to the URL which contains the full link back to the survey. Use this return URL to redirect respondents back to the survey and continue where they left off.

The return variable automatically appends the state variable to the link.

If you need to execute special code when a respondent returns to the survey, use an <exec when="returning"> tag. For example:

<exec when="returning">
setMarker('RETURNED_FROM_REDIRECT')
</exec>

If you need to access any additional data that was also passed into the returning URL, use gv.request.get("VAR") to access these variables.

For example, if a respondent re-entered the survey using the following URL:

/proj1234?state=...&extraInfo=approved

We can use gv.request.get("VAR") to grab the "extraInfo" data and store it inside a question:

<exec when="returning">
vOtherData.val = gv.request.get("extraInfo") or "NO DATA"
</exec>

In this example, vOtherData is set to "approved".

4:  What's Next?

Using the survey builder? Learn about Adding or Removing a Page.

Learn more about the Exec Tag and Adding Condition/Skip Logic.