Survey Settings

All survey settings are configured in the YAML header of the survey.qmd file. If you wish to use the default settings, no YAML header is required.

Default settings

There are three categories of settings:

• The theme-settings control the visual appearance of the survey. You can customize the theme, position of the progress bar, and footer text.
• The survey-settings includes various options to customize the survey behavior, such as enabling cookies, enabling auto-scrolling, changing the system language, highlighting unanswered questions, and specifying required questions.
• The system-messages section allows you to customize the text for various buttons and messages displayed throughout the survey.

This is the comprehensive list of all default survey configuration settings:

---
theme-settings:
  theme: default
  barposition: top
  barcolor: ~
  footer-left: ''
  footer-center: ''
  footer-right: ''

survey-settings:
  show-previous: no
  use-cookies: yes
  auto-scroll: no
  rate-survey: no
  all-questions-required: no
  start-page: initial_page
  system-language: en
  highlight-unanswered: yes
  highlight-color: gray
  capture-metadata: yes
  required-questions: []

system-messages:
  cancel: Cancel
  confirm-exit: Confirm Exit
  sure-exit: Are you sure you want to exit the survey?
  submit-exit: Submit and Exit
  warning: Warning
  required: Please answer all required questions before proceeding.
  rating-title: Before you go...
  rating-text: 'Rate your survey experience:'
  rating-scale: from 1-poor to 5-excellent
  previous: Previous
  next: Next
  exit: Exit Survey
  close-tab: Please close this tab manually to exit the survey.
  choose-option: Choose an option...
  click: Click here
  redirect: Redirecting in
  seconds: seconds
  new-tab: Opens in a new tab
  redirect-error: "Error: This text won't trigger any redirection..."
---

Note

• All YAML keys can be written with underscores (_) or hyphens (-), so both use-cookies and use_cookies are valid.
• In YAML keys, you have 2 ways to represent boolean values: true/false or yes/no. Both are acceptable. For true/false, you can also use capitalized versions: True/False.

settings.yml file

When you render your surveydown survey, a _survey folder is generated that contains all files needed to run the survey. In that folder, there is a settings.yml file that contains all survey settings in YAML format. This file is automatically generated based on the YAML header in your survey.qmd file. You can open and inspect this file to see how your survey settings are stored.

Warning

Do not manually edit the settings.yml file, as any changes you make will be overwritten the next time you render your survey.

Theme settings

Overall theme

Because the survey.qmd is a Quarto document, you can use any of the Quarto formatting options to change the appearance of your survey.

For example, you can change the overall survey theme using the theme key:

theme: united # Any bootswatch theme 

There are 25 bootswatch themes to choose from. You can also provide a custom.scss file to further modify the theme, or even combine the two, e.g.:

theme: [united, custom.scss]

Progress bar

You can modify the survey progress bar with the barcolor and barposition keys, e.g.:

barcolor: "#768692"
barposition: top 

The barcolor key defines the color of the progress bar. It defaults to the primary theme color, but you can change it to text color names (over 140 supported by browser CSS) and hex color codes in 3 or 6 digits, e.g. #FF5733 or #F53.

The barposition key defines the position of the progress bar. It defaults to top, but can also be changed to bottom or none (to remove the bar). The progress bar updates on every question the user clicks on, not pages.

Footer

You can customize the footer text using the footer, footer-left, footer-center, and footer-right keys.

If you only want to set a centered footer text, use the footer key, like this:

footer: This is your centered footer text.

Or, you can customize the left, center, and right footer texts separately using the footer-left, footer-center, and footer-right keys, like this:

footer-left: Footer Left Test
footer-center: Footer Center Test
footer-right: Footer Right Test

Survey settings

Cookies

Cookies are used to store user sessions, including their session ID, survey data storage (backend), and their survey progress (frontend).

Define your cookies like this in YAML:

use-cookies: true

By default, the cookies are enabled. You can disable the cookies by changing the YAML key to false.

Auto scroll

The auto scroll feature allows the page to automatically scroll according to the user’s working progress.

Define auto scroll like this in YAML:

auto-scroll: true

By default, auto scroll is disabled.

Survey rating

You may want to add a survey rating question by the end of the survey to collect user reflections. Simply set rate-survey to true (Default to false) in YAML:

rate-survey: true

By default, survey rating is disabled.

Survey rating is triggered by the “Exit Survey” button by the end of the survey. If you want to implement the survey rating, make sure you define the Exit Button by the end of the survey using the sd_close() function.

Below are the true and false cases for rate-survey:

TRUE

If rate-survey is true, a survey rating question will pop up:

FALSE

If rate-survey is false, a confirm exit dialog box will pop up:

System language

To systematically display the preset system messages and button text elements in a different language, change the system language using a different country code.

By default, the system language is set to English (en):

system-language: en

Six languages are internally supported by surveydown:

1. English (en)
2. German (de)
3. Spanish (es)
4. French (fr)
5. Italian (it)
6. Chinese (zh-CN)

Below is an example of the system language set to Spanish (es):

You can also customize any system message beyond these default values (see the System Messages section below).

Highlight unanswered questions

You can highlight unanswered questions to help respondents identify which questions they have not answered yet:

highlight-unanswered: true
highlight-color: gray

By default, highlighting unanswered questions is enabled. You can disable this feature by setting highlight-unanswered to false.

By default, the highlight color is set to gray (equivalent to grey). We also provide 4 other colors: blue, orange, green, and purple.

Below is an example of unanswered questions being highlighted in gray:

Changed to blue:

Note

We auto-trigger red highlighting for required questions that are not answered, if the respondent attempts to click on the “Next” button without answering them, regardless of the highlight-unanswered setting.

Capture metadata

surveydown supports metadata capturing. If enabled, the data sheet will show columns of browser and ip_address, in which browser contains information of the respondent’s browser name, version, and operating system, and ip_address shows the respondent’s IP address. To enable metadata capturing, set capture-metadata to true in YAML:

capture-metadata: true

By default, metadata capturing is enabled.

Start page

When editing your survey, it can be helpful to start the survey at a specific page. You can define the start page in YAML like this:

start-page: page_1

By default, the survey starts at the first page.

Required questions

By default, no questions are required. We provide 2 YAML keys to define required questions:

Firstly, set all-questions-required to true to make all questions required:

all-questions-required: true

By default, all-questions-required is set to false.

Secondly, use required-questions to provide a list of question IDs to make specific questions required:

required-questions:
  - question_1
  - question_2

The questions set to required will make the respondent unable to proceed until they have answered all of them on the current page. It will also place a red asterisk (*) next to the question label to indicate that the question is required.

System messages

You can customize all system messages and button text elements displayed throughout the survey by modifying the system-messages section in YAML. By default, all system messages are in English, though you can set the default language to one of six supported languages by changing the system-language setting.

Any customizations you make in the system-messages section will override the default messages, regardless of the system language setting.

Here is a description of each system message key and its default value:

• cancel: Text for the cancel button in dialog boxes.
• confirm-exit: Title text for the confirm exit dialog box (when using sd_close() to insert a closing button).
• sure-exit: Message text asking if the user is sure they want to exit the survey (when using sd_close() to insert a closing button).
• submit-exit: Text for the submit and exit button in the confirm exit dialog box.
• warning: Title text for warning dialog boxes.
• required: Message text prompting the user to answer all required questions before proceeding.
• rating-title: Title text for the survey rating dialog box.
• rating-text: Message text prompting the user to rate their survey experience.
• rating-scale: Description of the rating scale used in the survey rating question.
• previous: Text for all previous navigation buttons.
• next: Text for all next navigation buttons.
• exit: Text for the exit survey button.
• close-tab: Message prompting the user to close the tab manually to exit the survey.
• choose-option: Placeholder text for dropdown menus.
• click: Text for clickable links.
• redirect: Text indicating that the user is being redirected.
• seconds: Text indicating the number of seconds remaining before redirection.
• new-tab: Text indicating that a link opens in a new tab.
• redirect-error: Error message displayed if redirection fails.