Survey Item Types

---

There are a lot of item types, in the beginning you will probably only need a few though. To see them in action, try using the following Google spreadsheet or fill it out yourself. It contains example uses of nearly every item there is.

Plain display types

note

display text. Notes are only displayed once, you can think of them as being "answered" simple by submitting.

note_iframe

If you want to render complex rmarkdown htmlwidgets, use this.

submit timeout

display a submit button. No items are displayed after the submit button, until all of the ones preceding it have been answered. This is useful for pagination and to ensure that answers required for showif or for dynamically generating item text have been given.
You can specify an optional timeout/delay (in milliseconds).
Negative values mean that the user has to wait that long until they can click submit.
Positive values mean the submit button will automatically submit after that time has passed. However, if not all items are answered or optional, the user will end up on the same page and the timer will restart. To avoid that, you have to use it together with optional items. Then, it's a way to use timed submissions. The data in the item display table can be used to check how long an item was displayed and whether this matches with the server's time for when it sent the item and received the response.

Simple input family

text max_length

allows you to enter a text in a single-line input field. Adding a number text 100 defines the maximum number of characters that may be entered.

textarea max_length

displays a multi-line input field

number min, max, step

for numbers. step defaults to 1, using any will allow any decimals.

letters max_length

like text, allows only letters (A-Za-züäöß.;,!: ), no numbers.

email

for email addresses. They will be validated for syntax, but they won't be verified unless you say so in the run.

Sliders

range min,max,step

these are sliders. The numeric value chosen is not displayed. Text to be shown to the left and right of the slider can be defined using the choice1 and choice2 fields. Defaults are 1,100,1.

range_ticks min,max,step

like range but the individual steps are visually indicated using ticks and the chosen number is shown to the right.

Datetime family

date min,max

for dates (displays a date picker). Input can be constrained using the min,max parameters. Allowed values would e.g. be 2013-01-01,2014-01-01 or -2years,now.

time min,max

for times (displays an input with hours and minutes). Input can also be constrained using min,max, e.g. 12:00,17:00

Fancy family

geopoint

displays a button next to a text field. If you press the button (which has the location icon on it) and agree to share your location, the GPS coordinates will be saved. If you deny access or if GPS positioning fails, you can enter a location manually.

color

allows you to pick a color, using the operating system color picker (or one polyfilled by Webshims)

Multiple choice family

The, by far, biggest family of items. Please note, that there is some variability in how the answers are stored. You need to know about this, if you (a) intend to analyse the data in a certain way, for example you will want to store numbers for Likert scale choices, but text for timezones and cities (b) if you plan to use conditions in the run or in showif or somewhere else where R is executed. (b) is especially important, because you might not notice if demographics$sex == 'male' never turns true because sex is stored as 0/1 and you're testing as female.

mc choice_list

multipe choice (radio buttons), you can choose only one.

mc_button choice_list

like mc but instead of the text appearing next to a small button, a big button contains each choice label

mc_multiple choice_list

multiple multiple choice (check boxes), you can choose several. Choices defined as above.

mc_multiple_button

like mc_multiple and mc_button

check

a single check box for confirmation of a statement.

check_button

a bigger button to check.

rating_button
min, max, step

This shows the choice1 label to the left, the choice2 label to the right and a series of numbered buttons as defined by min,max,step in between. Defaults to 1,5,1.

sex

shorthand for mc_button with the ♂, ♀ symbols as choices

select_one choice_list

a dropdown, you can choose only one

select_multiple choice_list

a list in which, you can choose several options

select_or_add_one
choice_list, maxType

like select_one, but it allows users to choose an option not given. Uses Select2. maxType can be used to set an upper limit on the length of the user-added option. Defaults to 255.

select_or_add_multiple
choice_list, maxType,
maxChoose

like select_multiple and select_or_add_one, allows users to add options not given. maxChoose can be used to place an upper limit on the number of chooseable options.

mc_heading choice_list

This type permits you to show the labels for mc or mc_multiple choices only once.
To get the necessary tabular look, assign a constant width to the choices (using e.g. mc-width100), give the heading the same choices as the mcs, and give the following mcs (or mc_multiples) the same classes + hide_label.
On small screens the mc_heading will be hidden and labels will automatically be displayed again, because the tabular layout would otherwise break down.

Hidden family

These items don't require the user to do anything, so including them simply means that the relevant value will be stored. If you have exclusively hidden items in a form, things will wrap up immediately and move to the next element in the run. This can be useful for hooking up with other software which sends data over the query string i.e. https://formr.org/run_name?param1=10&user_id=29

calculate

in the value column you can specify an R expression, the result of which will be saved into this variable. Useful to pull in external data or to forestall recalculating something repeatedly that you want to refer to later. If the calculation is based on values from the same module, you can insert the calculate item in the last line of the sheet behind the last submit button and its result will be stored in the database for use in further modules.

ip

saves your IP address. You should probably not do this covertly but explicitly announce it.

referrer

saves the last outside referrer (if any), ie. from which website you came to formr

server var

saves the $_SERVER value with the index given by var. Can be used to store one of 'HTTP_USER_AGENT', 'HTTP_ACCEPT', 'HTTP_ACCEPT_CHARSET', 'HTTP_ACCEPT_ENCODING', 'HTTP_ACCEPT_LANGUAGE', 'HTTP_CONNECTION', 'HTTP_HOST', 'QUERY_STRING', 'REQUEST_TIME', 'REQUEST_TIME_FLOAT'. In English: the browser, some stuff about browser language information, some server stuff, and access time.

get var

saves the var from the query string, so in the example above get param1 would lead to 10 being stored.

random min,max

generates a random number for later use (e.g. randomisation in experiments). Minimum and maximum default to 0 and 1 respectively. If you specify them, you have to specify both.

hidden

you can use this item with a pre-set value, if you need to use data from previous pages together with data on the same page for a showif

block

Blocks progress. You can give this item a showif such as (item1 + item2) > 100 to add further requirements.

File uploads

You can ask study participants to upload image, audio, video, text, and PDF files in formr. Server-side limits for the maximal file sizes apply, you can also set lower limits per item.

file max_size_in_bytes

Permits all of the file types allowed by audio, video, image plus PDFs and some text files.

audio max_size_in_bytes

Upload audio files. If you assign the class "record_audio" in the class column, a little recording interface will be shown. It will use the device microphone.

video max_size_in_bytes

Upload video files.

image max_size_in_bytes

Upload image files. On smartphones, this can trigger the camera app.

Knit R & Markdown

---

This section gives some guidance on how to format and customise text in formr. In many cases you'll do it right by default. You'll also see how to access the data you just collected in formr in R — for example to score an assessment, give feedback, or customise the study in other ways.

Markdown

You can format text/feedback everywhere (i.e. item labels, choice labels, the feedback shown in pauses, stops, in emails) in a natural fashion using Github-flavoured Markdown.
The philosophy is that you write like you would in a plain-text email and Markdown turns it nice.
In most cases, characters with special meaning won't entail unintended side effects if you use them normally, but if you ever need to specify that they shouldn't have side effects, escape it with a backslash: \*10\* doesn't turn italic.

* list item 1
* list item 2

will turn into a nice bulleted list.

• list item 1
• list item 2

# at the beginning of a line turns it into a large headline, ## up to ###### turn it into smaller ones.

*italics* and __bold__ are also easy to do.

[Named links](http://yihui.name/knitr/) and embedded images ![image description](http://imgur.com/imagelink) are easy. If you simply paste a link, it will be clickable automatically too, even easier. Email addresses are a bit special, you need the "mailto:" prefix: [Contact us](mailto:contact_email@example.com).

You can quote something by placing a > at the beginning of the line.

If you're already familiar with HTML you can also use that instead, though it is a little less readable for humans. Or mix it with Markdown! You may for example use it to go beyond Markdown's features and e.g. add icons to your text using <i class="fa fa-smile-o"></i> to get for instance. Check the full set of available icons at Font Awesome.

Knitr

If you want to customise the text or generate custom feedback, including plots, you can use Knitr. Thanks to Knitr you can freely mix Markdown and chunks of R. You can load data using R commands, but the data you just collected for this participant will automatically be made available as R data frames. See R helpers for more information. Some examples:

• Today is `r date()` shows today's date.
  
• Hello `r demographics$name` greets someone using the variable "name" from the survey "demographics".
  
• Dear `r ifelse(demographics$sex == 1, 'Sir', 'Madam')` greets someone differently based on the variable "sex" from the survey "demographics".
  
• You can also plot someone's extraversion on the standard normal distribution.

  ```{r}
  library(formr)
  # build scales automatically
  big5 = formr_aggregate(results = big5)
  # standardise
  big5$extraversion = scale(big5$extraversion, center = 3.2, scale = 2.1)
  
  # plot
  qplot_on_normal(big$extraversion, xlab = "Extraversion")
  ```
          

  yields
  

R Helpers

---

R in formr

In formr, you can use R to write simple and complex code. Various places allow you to specify either R code (e.g., showif column, value column, SkipForward/SkipBackward, External, Pause button conditions) or R code interspersed with Markdown (as in knitr, e.g., labels, Stop button, Pause button texts). The R code you wrote will be automatically enriched with the data objects you name and processed using OpenCPU. By default, your participants cannot view the R code you write.

Automatically enriched data

When you write R code in formr, we try to automatically determine what data you need and supply it. To do so, formr has a look up table of all the available data (the surveys defined in the run, the items defined in these surveys, as well as some metadata about the participant and run progress).

For example, to obtain somebody's age, you need only write demographics$age. formr will then automatically create a data frame named "demographics" containing the variable "age". To give another example, to see whether a participant ever reported a headache in your diary, you might just write any(diary$headache > 1). In this case, formr would create a data frame containing all responses to the headache question. It's important to note that formr simply checks whether the name of the survey exists anywhere in the text and whether the name of the item exists anywhere else. So, demographics$age works, but so does demographics[, 'age']. If an item name exists in multiple surveys that you have named, it will be supplied for all surveys.

Available data

user_id

The unique user code which we use for logging people in, e.g., NqbpASFVlcci5cnVvpMZG4ueILaYvFk39fDND305XvPLh3KW4xzrP0ygJ1phs1gf.

.formr
$login_link $login_code $nr_of_participants $session_last_active

Useful shortcuts to obtain the link to the personalised study link, the login code (currently the same as user_id), the total number of participants in the run (even those who only saw the first page), as well as a date-time when the current participant was last active.

YourSurvey
$YourItem1
$YourItem2

Any of the surveys that are part of the run and any of their items can be requested in this way. In addition, if you have named items belonging to a scale with a numeric suffix and an optional R, you need only name the scale (e.g., extraversion) and all items (e.g., extraversion1, extraversion2R, extraversion3) will be supplied.

survey_users
$created
$modified
$user_code
$email
$email_verified
$mobile_number
$mobile_verified

This data frame contains user account information, such as when the account was created, the user's contact details, and whether they have been verified. This is usually empty, because most study participants don't sign up on formr.

survey_run_sessions
$session
$created
$last_access
$ended
$position
$current_unit_id
$deactivated
$no_email

This data frame tracks user sessions in the run/study, including when they started the study (created), last accessed it, ended it (reached a Stop button), the current position in the run, and whether the user has opted out of email notifications.

survey_unit_sessions
$created
$ended
$expired
$unit_id
$position
$type

This data frame contains metadata about the progression of the user through the run/study, including when they reached each unit (created), left it (ended), and so on.

externals
$created
$ended
$position

Metadata about external units linked to the study, i.e. when users were sent there, whether they returned/completed the external unit (ended) and the position in the run.

survey_items_display
$created
$answered_time
$answered
$displaycount
$item_id

This data frame tracks the display and response behavior for survey items, including timestamps for when they were displayed and answered.

survey_email_log
$email_id
$created
$recipient

This data frame logs email interactions, including when an email was sent and its recipient.

shuffle
$unit_id
$created
$group

This data frame tracks shuffled units and the group they belong to for randomisation purposes.

Packages

Wherever you use R in formr you can also use the functions in its R package. If you want to use the package in a different environment, you'll need to install it using the following code.

install.packages('formr', repos = c('https://rforms.r-universe.dev', 'https://cloud.r-project.org'))

The package currently has the following feature sets

• Some shorthand functions for frequently needed operations on the site:

  first(cars) # first non-missing value
  last(cars) # last non-missing value
  current(cars) # last value, even if missing
  "formr." %contains% "mr." # will yield TRUE
  "formr." %contains_word% "mr" # will yield FALSE
  "12, 15" %contains% "1" # will yield TRUE
  "12, 15" %contains_word% "1" # will yield FALSE

• Some helper functions to make it easier to correctly deal with dates and times:

  time_passed(hours = 7) 
  next_day()
  in_time_window(time1, time2)

• Connecting to formr, importing your data, correctly typing all variables, automatically aggregating scales.
• Easily making feedback plots e.g.

  qplot_on_normal(0.8, "Extraversion")

  The package also has a function to simulate possible data, so you can try to make feedback plots ahead of collecting data.

Further data

Sometimes, you need more than the data that formr auto-enriches your study with. For example, you might have designed a couples' diary study and need the partner's data to synchronize participation. In these cases, you will have to explicitly load the data using formr's API.

Other times, you might want to import data from elsewhere on the web. You can R packages and functions to, for example, read a participant's social media posts or to look up information in an external, online database.

Features

---

The following designs and many more are possible:

• simple surveys with and without feedback
• complex surveys (using skipping logic, personalised text, complex feedback)
• surveys with eligibility limitations
• diary studies including completely flexible automated email/text message reminders
• longitudinal studies (e.g. automatically re-contact participants after they return from their exchange year). The items of later waves need not exist in final form at wave 1.
• longitudinal social networks and other studies that require rating a variable number of things or persons

Core strengths

• generates very pretty feedback live, including ggplot2, and interactive ggvis plots and htmlwidgets. We find that this greatly increases interest and retention in our studies.
• automates complex experience sampling, diary and training studies, including automated reminders via email or text message
• looks nice on a phone (about 30-40% of participants fill out our surveys on a mobile device)
• easily share, swap and combine surveys (they're simply spreadsheets) and runs (you can share complete designs, e.g. "daily diary study")
• you can use R to do basically anything that R can do (i.e. complicated stuff, like using a sentiment analysis of a participant's Twitter feed to decide when the survey happens)
• not jealous at all – feel free to integrate other components (other survey engines, reaction time tasks, whatever you are used to) with formr, we tried our best to make it easy.

Features

• manage access to and eligibility for studies
• longitudinal studies
• send text messages (see the HowTo)
• works on all somewhat modern devices and degrades gracefully where it doesn't
• formats text using Github-flavoured Markdown (a.k.a. the easiest and least bothersome way to mark up text)
• file, image, video, sound uploads for users (as survey items) and admins (to supply study materials)
• complex conditional items
• a dedicated formr R package: makes pretty feedback graphs and complex run logic even simpler. Simplifies data wrangling (importing, aggregating, simulating data from surveys).
• a nice editor, Ace, for editing Markdown & R in runs.

Plans:

• work offline on mobile phones and other devices with intermittent internet access (in the meantime enketo is pretty good and free too, but geared towards humanitarian aid)
• a better API (some basics are there)
• social networks, round robin studies - at the moment they can be implemented, but are a bit bothersome at first. There is a dedicated module already which might also get released as open source if there's time.
• more planned enhancements on Github

formr API

---

The formr API is the primary way to get data/results out of the platform. It's a low-level HTTP-based API that you can use principally to get results of a study for specified participants (sessions)

Resource requests to the formr API require that you have a valid access token which you can obtain by providing API credentials (a client id and a client secret)

API base URL:
https://api.formr.org

Obtaining Client ID and Client Secret

Access to the API is restricted, so only the administrators of formr are able to provide API credentials to formr users. To obtain API credentials, send an email to Cyril and your credentials will be sent to you.

Obtaining An Access Token

An access token is an opaque string that identifies a formr user and can be used to make API calls without further authentication. formr API access tokens are short-lived and have a life span of about an hour.

To generate an access token you need to make an HTTP POST request to the token endpoint of the API

POST /oauth/access_token?
     client_id={client-id}
    &client_secret={client-secret}
    &grant_type=client_credentials

This call will return a JSON object containing an access token which can be used to access the API without further authentication required.
Sample successful response

{
	"access_token":"XXXXXX3635f0dc13d563504b4d",
	"expires_in":3600,
	"token_type":"Bearer",
	"scope":null
}

The attribute expires_in indicates the number of seconds for which is token is valid from its time of creation. If there is an error for example if the client details are not correct, then an error object is returned containing an error_description and sometimes an error_uri where you can read more about the generated error. An example of an error object is

{
	"error":"invalid_client",
	"error_description":"The client credentials are invalid"
}

Making Resource Requests using generated access token

With the generated access token, you are able to make requests to the resource endpoints of the formr API. For now only the results resource endpoint has been implemented

Getting study results over the API

REQUEST

To obtain the results of a particular set of sessions in a particular run, send a GET HTTP request to the get endpoint along side the access_token obtained above together with the necessary parameters as shown below:

GET /get/results?
     access_token={access-token}
    &run[name]={name of the run as it appears on formr}
    &run[sessions]={comma separated list of session codes OR leave empty to get all sessions}
    &surveys[survey_name1]={comma separated list items to get from survey_name1 OR leave empty to get all items}
    &surveys[survey_name2]={comma separated list items to get from survey_name2 OR leave empty to get all items}

Notes:

• survey_name1 and survey_name2 should be the actual survey names
• If you want to get results for all surveys in the run you can omit the survey parameter
• If you want to get all items from a survey, keep the items list empty.

RESPONSE

The response to a results request is a JSON object. The keys of this JSON structure are the names of the survey that were indicated in the requested and the value associated to each survey entry is an array of objects representing the results collected for that survey for all the requested sessions. An example of a response object could be the following:

{
	"survey_1": [{
		"session": "sdaswew434df",
		"survey_1_item_1": "answer1",
		"survey_1_item_2": "answer2",
		"survey_1_item_2": "answer3",
	},
	{
		"session": "fdgdfg4323",
		"survey_1_item_1": "answer4",
		"survey_1_item_2": "answer5",
		"survey_1_item_2": "answer6",
	}],
	"survey_2": [........]
}

Using the formr API in R

# load the httr package
library(httr)

# Login using your client ID and client Secret to get an access token
login <- list( # define login credentials
  client_id = "bb472xxxxxxxxe1918",
  client_secret = "zEfgeyJ0eXXXXXEwYwNGZj",
  grant_type = "client_credentials"
)
request <- POST( # send POST request
  "https://api.formr.org/oauth/access_token",
  body = login, 
  encode = "form"
)
# parse response to get access token
# If there an error then the response object would contain the details of the error in response$error
response <- content(request)
access_token <- response$access_token

#With a valid access token, call API to get the results of a particular study (run)
query <- list(
  access_token = access_token,
  "run[name]" = "/enter run name here/",
  "run[session]" = "/here you can specify a full session code or just a substring(but include the beginning /",
  "surveys[survey_1]" = "item_1, item_2, item_etc.", # comma separated list of items to get from the survey or leave empty string to get all items
  "surveys[survey_2]" = "item_3, item_4, item_etc."
)
request <- GET("https://api.formr.org/get/results", query=query)
results <- content(request)

# With a valid response you can, for example, extract the results of a particular survey say 'survey_1':
survey_1 = results$survey_1
survey_1[, c("item_1","item_2")]

Help

---

Where to get help

If you're a participant in one of the studies implemented in formr, please reach out to the person running the study.

If you're running a study yourself, there's several places to look for help.

• this documentation is a good start, just click on any of the tabs above.
• There is a Wiki on Github. You can find a number of HowTos there and contribute yourself.
  • start with learning to create a simple survey
  • then learn to add feedback
  • and if you're up for more, discover diary studies, peer rating studies, and find out how to send texts.
• You'll find answers to some frequently asked questions there too.
• You can ask (and answer!) questions in our Github Discussions forum for community support. Previously, we used a mailing list, but spam made it unusable. You can still browse it.
• If you find a bug, this is the place to describe it (preferably in a way that allows us to reproduce it, but we're also accepting Yeti reports).
• Please do not email the creators of formr for general support unless you've bought one of our consulting packages. Do reach out if you think sharing your concerns publicly could result in security concerns.