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 in a Quarto shiny document.

Overview

In surveydown, your entire survey is designed using markdown and R code in a single Quarto document (a .qmd file). 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.

You can add content to your survey using markdown formatting, or in RStudio you can edit with the visual editor. Survey questions are defined in R code chunks with the sd_question() function. Pages are defined using fences (:::), and navigation buttons handled with the sd_next() function. You can modify the configuration options in the server code chunk (the last code chunk at the bottom of the .qmd file) with the sd_config() function, and you can configure the database with the sd_database(). Details on each of these steps are provided in separate guides in the documentation.

This introduction covers the basic steps to get started with surveydown.

1. Install

See the installation documentation.

2. Start with a template

In the R console, run the following to to setup a template survey:

surveydown::sd_create_survey("path/to/folder")

This will create a folder located at "path/to/folder" with the following files:

  • example.qmd: a template survey you should edit.
  • example.Rproj: An RStudio project file (helpful if you’re working in RStudio)
  • _extensions: A folder with the surveydown Quarto extension needed to make everything work (don’t modify this).

3. Add content

See the Survey Components documentation for details on adding content to your survey, like text, images, etc. with markdown and / or code chunks. As a quick overview:

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

Page 1 content here

:::
  • Add questions with the sd_question() function in code chunks (see vignette("questions") for supported question types). For example:
```{r}
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 configuration options

In the server chunk (bottom of qmd file), add control logic to your survey with the sd_config() function. See the Configuration Options documentation for more details.

5. Setup your database

Also in the server chunk, setup your database with the sd_database() function, or leave it blank to preview / edit your survey without database connected. See the Store Data documentation for more details.

6. Locally preview

Preview your survey by clicking the “Run Document” button in RStudio or in your terminal running the command quarto serve survey_file_name.qmd.

7. Deploy

Deploy your survey by hosting it on your favorite server, like shinyapps.io, huggingface, etc. See the Deployment documentation for more details.