Skip to contents

Introduction to surveydown

Source: vignettes/surveydown.Rmd
surveydown.Rmd

Main Documentation

The main documentation for surveydown is at https://surveydown.org/. We recommend navigating there for more detailed documentation about the R package and how to use it to build dynamic surveys.

Overview

Every surveydown survey is composed of a survey and an app, defined in two separate files:

  • survey.qmd: A Quarto document that contains the survey content (pages, questions, etc), which renders to an HTML file.
  • app.R: An R script defining a Shiny app that contains the global settings (libraries, database configuration, etc.) and server configuration options (e.g., conditional skipping / display, etc.).

These files must be named survey.qmd and app.R.

The {surveydown} R package provides a set of functions for defining the survey content and configuration options. Each function starts with sd_ to make them easy to identify.

The platform is based on some basic principles:

  • Add content to your survey.qmd file using markdown text (or in RStudio use the visual editor).
  • Define survey questions in R code chunks with the sd_question() function.
  • Define pages using fences (:::), with navigation buttons handled using the sd_next() function.
  • Add rich functionality to your survey using a variety of server options and conditional control logic in the server() function in the app.R file.
  • Store your respondent data in a database (see Store Data).

This approach ensures a flexible survey platform that is fully reproducible and easy to customize.

The remaining steps on this page will guide you through the process of creating a surveydown survey.

1. Installation

Install R & Quarto

We also recommend working with an IDE that has good support for R, Quarto, and Shiny. RStudio is great, and we also like VSCode and Positron.

Install the {surveydown} R package

You can install {surveydown} from CRAN in your R console:

install.packages("surveydown")

or you can install the development version from GitHub:

# install.packages("pak")
pak::pak('surveydown-dev/surveydown')

Load the package with:

You can also check which version you have installed:

surveydown::sd_version()

2. Start with a template

See the Template page.

3. Add survey content in your survey.qmd file

See the Survey Components page for details on the main components in a surveydown survey. For a quick overview, here’s how you add pages and questions:

  • Add pages with fences, like this:
::: {#page1 .sd-page}

Page 1 content here

:::
  • Add questions with the sd_question() function in code chunks (see the Question Types page for more on the types of questions supported). For example, here’s a multiple choice question:
sd_question(
  type  = 'mc',
  id    = 'penguins',
  label = "Which is your favorite type of penguin?",
  option = c(
    'Adélie'    = 'adelie',
    'Chinstrap' = 'chinstrap',
    'Gentoo'    = 'gentoo'
  )
)

4. Add control options

In the server() function in the app.R file, add rich functionality to your survey using a variety of server options and conditional control logic.

5. Setup your database

In the global settings at the top of the app.R file, setup your database with the sd_database() function. You can also leave it blank to preview / edit your survey without database connected, or set ignore = TRUE to run the survey without storing data. See the Store Data page for more details.

6. Locally preview

Preview your survey by clicking the “Run App” button in RStudio or in your R console running the runApp() command.

7. Deploy

Deploy your survey by hosting it on your favorite server, like {{< var shinyapps >}}, {{< var huggingface >}}, Posit Connect Cloud, Heroku, etc. See the Deployment page for more details.