Survey Settings

surveydown provides 2 ways of configuring survey settings:

  1. (Recommended) Using YAML header in survey.qmd.
  2. Using sd_server() in app.R.

We chose to use YAML header keys in our templates, and we intentionally made them verbose to demonstrate all available options. If you prefer using sd_server(), you can call ?sd_server() to see all available options.

Note

If you define the same setting in both the YAML header and sd_server(), the setting in sd_server() will take precedence.

Option 2: sd_server() in app.R

Alternatively, you can configure survey settings using the sd_server() function in the app.R file, under the server function definition. The server() function is a standard Shiny server function that takes input, output, and session as arguments.

Define your sd_server() like this:

server <- function(input, output, session) {
  sd_server(
    db = db, # Left out from YAML
    use_cookies = TRUE,
    auto_scroll = FALSE,
    rate_survey = FALSE,
    language = "en",
    highlight_unanswered = TRUE,
    highlight_color = "gray",
    capture_metadata = TRUE,
    start_page = "page_1",
    all_questions_required = FALSE,
    required_questions = c("question_1", "question_2")
  )
}

Above are the equivalent settings to those defined in the YAML header example. Note that the db argument is not available in the YAML header and must be specified in sd_server() if you are using a database connection.

Setting explanations

Appearance settings

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 any hex code you wish here to overwrite the theme color.

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.

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:

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

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 the system language. See the System Translations page for more details.

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.

Back to top