Skip to contents

Generates a single HTML file that presents the survey instrument in a browser by itself, offline, with the Shiny server left out. Every item type, branching, required-item checks and multi-page navigation run in the browser's own JavaScript.

Usage

export_survey(
  instrument,
  output_path = NULL,
  open = interactive(),
  endpoint_url = NULL,
  overwrite = FALSE,
  preview = FALSE
)

Arguments

instrument

An sframe object.

output_path

Character. File path for the output HTML. When NULL, a <survey_title>.html file is written in tempdir().

open

Logical. If TRUE (default) and the session is interactive, the file is opened in the default browser after writing.

endpoint_url

Character or NULL. A URL to which responses are POSTed as JSON on submission. When NULL, CSV download is the only collection mechanism.

overwrite

Logical. Whether to overwrite an existing file at output_path. Defaults to FALSE.

preview

Logical. TRUE exports a survey that collects nothing: the collector endpoint and the completion redirect are both removed, and the thank-you screen says the response went nowhere, above the study's own message as respondents will read it. This is what SurveyStudio's preview uses, which keeps a test answer away from a live study's collector. Supplying endpoint_url alongside it is an error. Defaults to FALSE.

Value

The output path, invisibly.

Details

When output_path is NULL, the file is written to tempdir(). Supply an explicit output_path for any production export that should be kept.

How a response reaches you

On submission the survey builds a one-row CSV in the browser's memory and shows the thank-you screen. When endpoint_url is supplied, it also sends the response as a POST request to that URL, for example a Google Apps Script web app. The browser reads back none of the reply to that request, so the survey treats it as sent and the respondent sees the thank-you screen either way.

The thank-you screen offers the CSV as a download button, which the respondent chooses to use. It appears when the instrument's thank-you settings ask for it, and whenever there is no endpoint_url, where that file is the only copy of the response.

Plan for both parts. Test the endpoint with a pilot submission and confirm the row arrives before collecting, and treat the download as a route a respondent may decline.

For a host page: confirmed delivery, restarts and drafts

While a response is being sent, the survey shows a sending screen. A host that can confirm delivery, such as a platform embedding the survey, defines window.sframeSendResponse(row) in the page before the survey script runs. The survey then hands each response to that function in place of its own POST. It returns a Promise: resolving to true, or to {confirmed: true}, shows the response as recorded. Resolving to anything else shows it as sent and unconfirmed, and a rejection shows the failure screen with a retry.

The thank-you screen states delivery itself, one line for each outcome: recorded, sent but unconfirmed, not sent, or failed. Write render$thankyou$message as thanks, a debrief or contact details, and do not state delivery in it. It appears below the status line in every case except a failed send, and defaults to "Thank you for participating."

2 settings in the instrument's render block suit a host too. render$thankyou$show_restart = FALSE hides "Submit another response". render$save_draft = TRUE keeps the answers in the browser's local storage as the respondent goes, under a key drawn from the instrument's content, so a respondent who closes the tab is offered to resume on return. The draft is cleared once the response is submitted, and kept when delivery fails.

The exported file works offline. It can be hosted on GitHub Pages, Netlify, any static file server, or e-mailed as an attachment for opening directly from disk.

Examples

cs    <- sframe_choice_set("ag5", 1:5,
           c("Strongly disagree", "Disagree", "Neutral",
             "Agree", "Strongly agree"))
i1    <- sframe_item("sat_1", "Overall I am satisfied with the service.",
                 type = "likert", choice_set = "ag5", required = TRUE)
i2    <- sframe_item("comments", "Any additional comments?", type = "textarea")
instr <- sframe_instrument("Customer Satisfaction Survey",
                       components = list(cs, i1, i2))

# Write to a temp file without opening the browser
out <- export_survey(instr,
                             output_path = file.path(tempdir(), "sat.html"),
                             open = FALSE, overwrite = TRUE)
sframe_show(out)

# \donttest{
# Write to a temp file and open in the default browser
export_survey(instr,
                     output_path = file.path(tempdir(), "sat_browser.html"),
                     overwrite = TRUE)

# Write with a Google Apps Script endpoint for server-side collection
export_survey(
  instr,
  output_path  = file.path(tempdir(), "sat_endpoint.html"),
  endpoint_url = "https://script.google.com/macros/s/XXXXX/exec",
  open         = FALSE,
  overwrite    = TRUE
)
sframe_show(file.path(tempdir(), "sat_endpoint.html"))
# }