Server logic for a surveydown survey

This function defines the server-side logic for a 'shiny' application used in surveydown. It handles various operations such as conditional display, progress tracking, page navigation, database updates for survey responses, and exit survey functionality.

Usage

sd_server(
  db = NULL,
  required_questions = NULL,
  all_questions_required = FALSE,
  start_page = NULL,
  admin_page = FALSE,
  auto_scroll = FALSE,
  rate_survey = FALSE,
  language = "en",
  use_cookies = TRUE
)

Arguments

db: A list containing database connection information created using sd_database() function. Defaults to NULL.
required_questions: Vector of character strings. The IDs of questions that must be answered. Defaults to NULL.
all_questions_required: Logical. If TRUE, all questions in the survey will be required. Defaults to FALSE.
start_page: Character string. The ID of the page to start on. Defaults to NULL.
admin_page: Logical. Whether to include an admin page for viewing and downloading survey data. Defaults to FALSE.
auto_scroll: Logical. Whether to enable auto-scrolling to the next question after answering. Defaults to FALSE.
rate_survey: Logical. If TRUE, shows a rating question when exiting the survey. If FALSE, shows a simple confirmation dialog. Defaults to FALSE.
language: Set the language for the survey system messages. Include your own in a translations.yml file, or choose a built in one from the following list: English ("en"), German ("de"), Spanish ("es"), French ("fr"), Italian ("it"). Simplified Chinese ("zh-CN"). Defaults to "en".
use_cookies: Logical. If TRUE, enables cookie-based session management for storing and restoring survey progress. Defaults to TRUE.

Value

This function does not return a value; it sets up the server-side logic for the 'shiny' application.

Details

The function performs the following tasks:

Initializes variables and reactive values.
Implements conditional display logic for questions.
Tracks answered questions and updates the progress bar.
Handles page navigation and skip logic.
Manages required questions.
Performs database operation.
Sets up admin functionality if enabled with the admin_page argument.
Controls auto-scrolling behavior based on the auto_scroll argument.
Uses sweetalert for warning messages when required questions are not answered.
Handles the exit survey process based on the rate_survey argument.

Progress Bar

The progress bar is updated based on the last answered question. It will jump to the percentage corresponding to the last answered question and will never decrease, even if earlier questions are answered later. The progress is calculated as the ratio of the last answered question's index to the total number of questions.

Database Operations

If db is provided, the function will update the database with survey responses. If db is NULL (ignore mode), responses will be saved to a local CSV file.

Auto-Scrolling

When auto_scroll is TRUE, the survey will automatically scroll to the next question after the current question is answered. This behavior can be disabled by setting auto_scroll = FALSE.

Exit Survey

When rate_survey = TRUE, the function will show a rating question when the user attempts to exit the survey. When FALSE, it will show a simple confirmation dialog. The rating, if provided, is saved with the survey data.

Examples

if (interactive()) {
  library(surveydown)

  # Get path to example survey file
  survey_path <- system.file("examples", "basic_survey.qmd",
                             package = "surveydown")

  # Copy to a temporary directory
  temp_dir <- tempdir()
  file.copy(survey_path, file.path(temp_dir, "survey.qmd"))
  orig_dir <- getwd()
  setwd(temp_dir)

  # Define a minimal server
  server <- function(input, output, session) {

    # sd_server() accepts these following parameters
    sd_server(
      db = NULL,
      required_questions = NULL,
      all_questions_required = FALSE,
      start_page = NULL,
      admin_page = FALSE,
      auto_scroll = FALSE,
      rate_survey = FALSE,
      language = "en",
      use_cookies = TRUE
    )
  }

  # Run the app
  shiny::shinyApp(ui = sd_ui(), server = server)

  # Clean up
  setwd(orig_dir)
}