---
title: "Introduction to surveydown"
description: >
  Learn how to get started with the basics of surveydown.
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to surveydown}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

```{r setup, include=FALSE, message=FALSE, warning=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  warning = FALSE,
  message = FALSE,
  eval = FALSE,
  fig.retina = 3,
  comment = "#>"
)
```

# Main Documentation

The main documentation for surveydown is at [https://surveydown.org/](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}](https://pkg.surveydown.org) 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](https://surveydown.org/server-options) and [conditional control logic](https://surveydown.org/conditional-control) in the `server()` function in the `app.R` file.
- Store your respondent data in a database (see [Store Data](https://surveydown.org/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

- [R](https://CRAN.R-project.org/)
- [Quarto](https://quarto.org/)

We also recommend working with an IDE that has good support for R, Quarto, and Shiny. [RStudio](https://posit.co/products/open-source/rstudio/) is great, and we also like [VSCode](https://github.com/microsoft/vscode) and [Positron](https://github.com/posit-dev/positron).

### Install the {surveydown} R package

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

```{r}
#| eval: false

install.packages("surveydown")
```

or you can install the development version from [GitHub](https://github.com/surveydown-dev/surveydown):

```{r}
#| eval: false

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

Load the package with:

```{r}
#| eval: false

library(surveydown)
```

You can also check which version you have installed:

```{r}
#| eval: false

surveydown::sd_version()
```

## 2. Start with a template

See the [Template](https://surveydown.org/template) page.

## 3. Add survey content in your `survey.qmd` file

See the [Survey Components](https://surveydown.org/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](https://surveydown.org/question-types) page for more on the types of questions supported). For example, here's a multiple choice question:

```{r}
#| eval: false

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](https://surveydown.org/server-options) and [conditional control logic](https://surveydown.org/conditional-control).

## 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](https://surveydown.org/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](https://connect.posit.cloud/), [Heroku](https://www.heroku.com/), etc. See the [Deployment](https://surveydown.org/deployment) page for more details.