Getting started with surveydown

]

<br><br>
# .font150[.fancy[Getting started with surveydown]]

]

---

# Meet your instructor!

]]

### John Helveston, Ph.D.

Associate Professor, Engineering Management & Systems Engineering

- 2016-2018 Postdoc at [Institute for Sustainable Energy](https://www.bu.edu/ise/), Boston University
- 2016 PhD in Engineering & Public Policy at Carnegie Mellon University
- 2015 MS in Engineering & Public Policy at Carnegie Mellon University
- 2010 BS in Engineering Science & Mechanics at Virginia Tech
- Website: [www.jhelvy.com](http://www.jhelvy.com/)

]]

---

# Meet the dev team!

<center>
<img src="images/john_helveston_square.png" width=90%>
<br>
<b>John Paul Helveston</b>
</center>

]]

<center>
<img src="images/pingfan_hu.jpg" width=90%>
<br>
<b>Pingfan Hu</b>
</center>

]]

<center>
<img src="images/bogdan_bunea.jpg" width=90%>
<br>
<b>Bogdan Bunea</b>
</center>

]]

---

# Before we start...

<br>

## 1. Be sure to [install everything](https://jhelvy.github.io/2025-qux-surveydown-workshop/install.html)

## 2. Download the [examples](https://jhelvy.github.io/2025-qux-surveydown-workshop/examples.zip)

---

# .font150[.fancy[Getting started with surveydown]]

---

---

---

]

# Limitations

<br>

## .font80[❌] .font90[Reproducibility]

]

---

]

# Limitations

<br>

## .font80[❌] .font90[Reproducibility]

## .font80[❌] .font90[Version control]

]

---

---

]

# Limitations

<br>

## .font80[❌] .font90[Reproducibility]

## .font80[❌] .font90[Version control]

## .font80[❌] .font90[Limited features]

]

---

]

# Limitations

<br>

## .font80[❌] .font90[Reproducibility]

## .font80[❌] .font90[Version control]

## .font80[❌] .font90[Limited features]

## .font80[❌] .font90[Open source]

]

---

# .center[Why not make surveys from code?]

---

# .center[Why not make surveys from code?]

]

<br>

# ~~Limitations~~ Features

## ✅ Reproducibility

## ✅ Version control

## ✅ Lots of features

## ✅ Open source

]

---

# .font130[.center[Introducing surveydown!]]

---

# .fancy[Getting started with surveydown]

### 1. .orange[What is surveydown?]
### 2. Adding survey content

---

---

# .font140[.center[What is Quarto?]]

---

# Quarto is a publishing system that blends **markdown-formatted text** & **code**

---

```` markdown
---
format: html
title: "HTML Page with R Code"
---

# Hello, World!

This is a simple **HTML** page with *R* code.

```{r}
library(ggplot2)

df <- data.frame(x = rnorm(100))
ggplot(df, aes(x = x)) +
  geom_histogram()
```
````

]]

]

---

```` markdown
---
format: html
echo: false
warning: false
---

```{r}
library(surveydown)
```

--- welcome

# Welcome to our survey!

```{r}
sd_question(
  type  = "mc",
  id    = "penguins",
  label = "What's your favorite penguin?",
  option = c(
    "Adélie"    = "adelie",
    "Chinstrap" = "chinstrap",
    "Gentoo"    = "gentoo"
  )
)

sd_next()
```

--- end

This is the last page of the survey.

```{r}
sd_close()
```

````

]]

# .center[survey.qmd]

]

---

```` markdown
*---
*format: html
*echo: false
*warning: false
*---

*```{r}
*library(surveydown)
*```

--- welcome

# Welcome to our survey!

sd_next()
```

--- end

This is the last page of the survey.

```{r}
sd_close()
```

````

]]

YAML Header

<br>
Load `surveydown` package

]

---

```` markdown
---
format: html
echo: false
warning: false
---

```{r}
library(surveydown)
```

*--- welcome

# Welcome to our survey!

sd_next()
```

*--- end

This is the last page of the survey.

```{r}
sd_close()
```

````

]]

Define page breaks like this:

``` markdown
--- page_id

Page content

```

]

---

```` markdown
---
format: html
echo: false
warning: false
---

```{r}
library(surveydown)
```

--- welcome

*# Welcome to our survey!

*```{r}
*sd_question(
* type  = "mc",
* id    = "penguins",
* label = "What's your favorite penguin?",
* option = c(
*   "Adélie"    = "adelie",
*   "Chinstrap" = "chinstrap",
*   "Gentoo"    = "gentoo"
* )
*)

*sd_next()
*```

--- end

This is the last page of the survey.

```{r}
sd_close()
```

````

]]

<br><br><br><br><br><br>Use markdown for page content

Use `sd_question()` in code chunk for survey questions

<br><br>Use `sd_next()` for next button

]

---

```` markdown
---
format: html
echo: false
warning: false
---

```{r}
library(surveydown)
```

--- welcome

*# Welcome to our survey!

*sd_next()
*```

--- end

This is the last page of the survey.

```{r}
sd_close()
```

````

]]

<br>

]

---

# .font120[.center[Use Shiny to drive the web app]]

<br>

---

# Survey Components

<br>

### `survey.qmd`

A **Quarto doc** defining the main survey content (pages, text, images, questions, etc).

]

### `app.R`

An **R script** defining the survey Shiny app. It sets up the database and server, and launches the survey.

]

---

``` r
library(surveydown)

# Connects to database
db <- sd_db_connect()

# Main UI
ui <- sd_ui()

server <- function(input, output, session) {

# Main server
  sd_server(db)
  
}

shiny::shinyApp(
  ui = ui, 
  server = server
)
```

]]

# .center[app.R]

]

---

``` r
*library(surveydown)

# Connects to database
*db <- sd_db_connect()

# Main UI
*ui <- sd_ui()

server <- function(input, output, session) {
  
  # Main server
* sd_server(db)

}

shiny::shinyApp(
  ui = ui,
  server = server
)
```

]]

Load package

Connect to database

Make standard UI

<br>Run surveydown server

]

---

# Your turn - start with a [template](https://surveydown.org/templates)

**Step 1:** In R console, run:

``` r
surveydown::sd_create_survey()
```

*Optional*: Specify a `path` and / or a `template`:

``` r
surveydown::sd_create_survey(
  template = "question_types",
  path     = "path/to/folder"
)
```

**Step 2:** In your IDE, open the `app.R` file, click "Run App", or in R console run:

``` r
shiny::runApp('app.R')
```

---

# .fancy[Getting started with surveydown]

### 1. What is surveydown?
### 2. .orange[Adding survey content]

---

## YAML Header

The YAML header is at the top of the `.qmd` file:

``` yaml
---
format: html
echo: false
warning: false
---
```

---

## Change the survey theme

Pick a different [bootswatch theme](https://bootswatch.com) with the `theme` key:

``` markdown
---
format: html
echo: false
warning: false
*theme: united
---
```

Make a custom theme with a `custom.scss` file

``` markdown
---
format: html
echo: false
warning: false
*theme: [united, custom.scss]
---
```

---

## Progress bar

You can modify the survey progress bar with the `barcolor` and `barposition` keys:

Change to any color with `barcolor`:

``` markdown
---
format: html
echo: false
warning: false
*barcolor: #768692
---
```

]

Change position: `top`, `bottom`, or `none`

``` markdown
---
format: html
echo: false
warning: false
*barposition: bottom
---
```

]

---

# Inserting pages

Insert new pages with the shorthand syntax using three dashes `---` followed by the page ID:

``` r
--- page1

Page 1 content here

--- page2

Page 2 content here
```

---

# Inserting next buttons

Insert buttons with the `sd_next()` function to go to the next page:

````markdown
```{r}
sd_next()
```
````

Specify a specific page to go to:

````markdown
```{r}
sd_next('next_page_id')
```
````

---

# Inserting questions

Insert questions using the `sd_question()` function, like this:

**Code**

``` r
sd_question(
  type   = 'mc',
  id     = 'fruit',
  label  = "1. Do you like fruit?",
  option = c(
    'Yes!'    = 'yes',
    'Kind of' = 'kind_of',
    'No :('   = 'no'
  )
)
```

Format is `"Label = value"`

]

**Output**

<div id="container-fruit" data-question-id="fruit" class="question-container" style="width: 100%;" oninput="Shiny.setInputValue('fruit_interacted', true, {priority: 'event'});" onclick="Shiny.setInputValue('fruit_interacted', true, {priority: 'event'});">
<div id="fruit" class="form-group shiny-input-radiogroup shiny-input-container" role="radiogroup" aria-labelledby="fruit-label">
<label class="control-label" id="fruit-label" for="fruit"><ol>
<li>Do you like fruit?</li>
</ol>
</label>
<div class="shiny-options-group">
<div class="radio">
<label>
<input type="radio" name="fruit" value="yes"/>
<span>Yes!</span>
</label>
</div>
<div class="radio">
<label>
<input type="radio" name="fruit" value="kind_of"/>
<span>Kind of</span>
</label>
</div>
<div class="radio">
<label>
<input type="radio" name="fruit" value="no"/>
<span>No :(</span>
</label>
</div>
</div>
</div>
<span class="hidden-asterisk">*</span>
</div>

**Data**

`yes`, `kind_of`, or `no`

]

---

## surveydown supports lots of [question types](https://surveydown.org/docs/question-types)

Some common types you may want to use:

Type | Description
-----|---------------------
`mc` | Multiple choice question (single choice) 
`mc_multiple` | Multiple choice question (multiple choices) 
`mc_buttons` | Multiple choice question (large buttons)
`select` | Drop down menu (choose one)
`text` | Open text, single row
`textarea` | Open text, block

---

# Embed images with html

I recommend just writing html code, like this

``` html
<center>
<img src="https://surveydown.org/images/logo.png" width=250>
</center>
```

---

# Embed images with markdown

``` html
![](https://surveydown.org/images/logo.png){fig-align="center" width="250"}
```

---

# Try out the surveydown [studio app](https://github.com/surveydown-dev/sdstudio)

## `sdstudio::launch()`

---

## Your turn

- Open and edit the `survey.qmd` file that you previously made.
- Pick a topic for your survey (a food, an animal, a sports team...whatever).
- Draft a survey about that topic. Include the following:
    - Page 1: A welcome message in large font ("Welcome to a survey about [topic]") and an image about the topic (find an image somewhere).
    - Pages 2 to N: Add different questions about the topic using several different question types.
- Try out different themes to change the look and feel.

## OR:

Open and play with the examples:

- `part-1-question-types`
- `part-1-question-yml`