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
sframeobject.- output_path
Character. File path for the output HTML. When
NULL, a<survey_title>.htmlfile is written intempdir().- 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 toFALSE.- preview
Logical.
TRUEexports 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. Supplyingendpoint_urlalongside it is an error. Defaults toFALSE.
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.
See also
launch_studio(), launch_builder(), run_survey()
Other Collect functions:
export_google_sheet(),
sframe_survey_server(),
sframe_survey_ui()
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"))
# }