diff --git a/docs/overview/browser-device-support.md b/docs/overview/browser-device-support.md new file mode 100644 index 00000000..05ec995b --- /dev/null +++ b/docs/overview/browser-device-support.md @@ -0,0 +1,34 @@ +# Browser and Device Support + +## Desktop and Laptop Browsers + +**Supported** + +jsPsych supports recent versions of the four most commonly-used web browsers: +* Chrome +* Firefox +* Safari +* Edge + +This means that jsPsych _should_ work on these browsers. If something doesn't work as you expect on one of the browsers above, it might be a bug that should be fixed. You can search for and report bugs on the [jsPsych GitHub Issues page](https://github.com/jspsych/jsPsych/issues). We're very grateful for anyone who takes the time to report bugs - it helps improve the library for everyone! + +**Unsupported** + +There are many other web browsers that are available, but that are not commonly used. The most well-known of these are Internet Explorer and Opera. jsPsych is not tested on these and other browsers not listed in the Supported section above. jsPsych experiments _might_ work in these browsers, but they _might not_. If you want to give participants the option to use unsupported browsers, then we recommend carefully testing your experiment to make sure that everything works as expected. Otherwise, we suggest asking your participants to only use a supported browser, or incorporating browser, device, and/or feature checks at the start of your experiment. jsPsych offers built-in methods for [exclusion based on minimum browser size and WebAudio API compatibility](overview/exclude-browser.md). You can incorporate other browser/device/feature checks into your experiment by adding custom JavaScript code. + +## Mobile Devices + +In general, jsPsych experiments can be run on mobile devices (smartphones and tablets). However, certain plugins will not work on mobile. For instance, any plugin that requires a keyboard response without a text input box, such as the *-keyboard-response plugins, will not work. Even plugins that do work on mobile might work differently than they do on desktop and laptop computers. For instance, on mobile devices, a text input box will cause an on-screen keyboard to pop up, which affects the visible content on the screen. + +If you plan to run an experiment that allows people to use mobile devices, we recommend doing some extra testing to make sure that everything works as expected. In particular, you may want to check that: +* Font sizes are readable on smaller screens +* Stimuli sizes are large enough and appropriate for the task +* Page is laid out as intended (e.g. elements are centered and do not overlap) +* Response options are touchscreen-friendly (e.g. buttons rather than key presses) +* Response options (e.g. buttons, text boxes, radio buttons) are large enough and far enough apart to be easily selected with a finger tap + +It's possible to use your browser's developer tools to emulate mobile devices ([this page shows how to do it in Chrome](https://developers.google.com/web/tools/chrome-devtools/device-mode)), which is useful for getting a sense of how your experiment will look on mobile devices. Just be aware that there are limitations to emulator tools, and there are some aspects of mobile devices/browsers that a desktop browser will not be able to simulate. + +## Mobile Browsers + +The browser options for mobile phones and tablets are slightly different than those for desktop and laptop computers. In addition to mobile versions of Chrome, Firefox, Safari, and Edge, other notable mobile browsers include Opera Mobile, Samsung Internet, UC Browser, and Dolphin. Because of the greater diversity of mobile browsers and volatility in their usage statistics, jsPsych does not officially support any particular set of mobile browsers. However, we do anticipate that most experiments should work in most mobile browsers, especially the mobile versions of browsers that we do support in Desktop mode. If you run into a problem using jsPsych in mobile browsers, please report it on the [jsPsych GitHub Issues page](https://github.com/jspsych/jsPsych/issues)! We do our best to fix browser incompatibilities that are not specific to a single experiment. diff --git a/docs/overview/collecting-data.md b/docs/overview/collecting-data.md new file mode 100644 index 00000000..665cc47a --- /dev/null +++ b/docs/overview/collecting-data.md @@ -0,0 +1,25 @@ +# Collecting Data from Online Participants + +## Hosting the Experiment and Saving the Data + +jsPsych is a front-end JavaScript library that runs entirely on the participant's computer. To run a jsPsych experiment over the internet, the files need to be hosted on a public web server so that participants can access the experiment using a web browser. When the participant completes the experiment in the browser, all of the data that jsPsych collects is stored on the participant's computer in the browser's memory. To get access to this data, it needs to be sent from the participant's browser back to the web server and stored in a database or a file. + +To be maximally flexible, jsPsych doesn't provide a single built-in solution for the web server component of your experiment. This makes jsPsych compatible with a wide range of hosting services and tools, allowing researchers to choose the web server option that best suit their needs. Some options for hosting jsPsych experiments include: + +* [Cognition.run](https://www.cognition.run/) - A free service designed specifically for hosting jsPsych experiments, with an easy-to-use interface. +* [JATOS](https://www.jatos.org/Whats-JATOS.html) - A free program that runs on your own server and provides a GUI for setting up experiments and accessing the data. Offers lots of features for creating more complex experiments and managing multiple researchers. +* [Pavlovia](https://pavlovia.org/) - A paid hosting service for web-based experiments, run by the PsychoPy team. Experiment files are managed on a GitLab repository. Participants will access the experiment through a link to Pavlovia. +* [PsiTurk](https://psiturk.org/) - Python-based program to help you host your experiment on your own computer and collect data from MTurk (see Recruiting Participants below). Relatively easy for a DIY option. +* [Pushkin](https://languagelearninglab.gitbook.io/pushkin/) - A set of tools to help you set up your own virtual laboratory for online experiments. This option differs from the others in that it helps you set up a complete website that may contain many different experiments, information about the laboratory, participant logins, and other features that are targeted at hosting large-scale data collection efforts. +* Full DIY - You can setup your own web server and database and handle the communication yourself. Traditional web server 'stacks' include [LAMP](https://www.digitalocean.com/community/tutorial_collections/how-to-install-lamp)/[LEMP](https://www.digitalocean.com/community/tutorials/how-to-install-linux-nginx-mysql-php-lemp-stack-on-ubuntu-20-04) (Linux operating system, Apache or Nginx server application, MySQL database, and PHP programming language). Other common web server frameworks include [Flask](https://flask.palletsprojects.com/) (Python) and [Node.js](https://nodejs.org/) (JavaScript). + +## Recruiting Participants + +Once your experiment is hosted on a web server, you could recruit participants in the same way that you would for lab-based studies. For instance, if your institution uses SONA, you can advertise your web-based study link on SONA. SONA allows you to automactically embed a unique ID in online study URLs, which you can then save in your data using [jsPsych's URL query parameters function](core_library/jspsych-data/#jspsychdatageturlvariable). SONA will also generate a completion URL that you can redirect participants to at the end of the study, and this will mark them as having completed the study in SONA. + +To take full advanage of hosting an experiment online, many researchers advertise their experiments more widely. Social media and other media outlets provide one option for reaching a large number of potential participants. There are also some commercial platforms that you can use to advertise your study and pay anonymous online participants. These recruitment platforms charge a fee for use. The advantages of these platforms are that they handle the participant payments and allow you to specify pre-screening criteria. The most commonly used recruitment platforms in online behavioral research are: + +* [Prolific](https://www.prolific.co/): An online labor market designed specifically for web-based research. +* [Amazon Mechanical Turk (MTurk)](https://www.mturk.com/): An online labor market designed for advertising paid 'human intelligence tasks'. This service was designed for use by commercial businesses but has been used by behavioral researchers for many years. + +Like SONA, Prolific and MTurk use URL query parameters to get participant information, and redirection to specific URLs to mark participants as having finished the study. jsPsych includes [convenience functions for interacting with MTurk participants](core_library/jspsych-turk/). Information about integrating with Prolific can be found in the researcher support section of their website. diff --git a/docs/plugins/jspsych-instructions.md b/docs/plugins/jspsych-instructions.md index ed66b0b3..4b3f5b9f 100644 --- a/docs/plugins/jspsych-instructions.md +++ b/docs/plugins/jspsych-instructions.md @@ -17,6 +17,7 @@ show_clickable_nav | boolean | false | If true, then a `Previous` and `Next` but button_label_previous | string | 'Previous' | The text that appears on the button to go backwards. button_label_next | string | 'Next' | The text that appears on the button to go forwards. show_page_number | boolean | false | If true, and clickable navigation is enabled, then Page x/y will be shown between the nav buttons. +page_label | string | 'Page' | The text that appears before x/y pages displayed when show_page_number is true. ## Data Generated diff --git a/docs/plugins/jspsych-survey-html-form.md b/docs/plugins/jspsych-survey-html-form.md index 11cb7ec1..5a164646 100644 --- a/docs/plugins/jspsych-survey-html-form.md +++ b/docs/plugins/jspsych-survey-html-form.md @@ -12,6 +12,8 @@ html | string | *undefined* | HTML formatted string containing all the input ele preamble | string | empty string | HTML formatted string to display at the top of the page above all the questions. button_label | string | 'Continue' | The text that appears on the button to finish the trial. dataAsArray | boolean | false | Retrieve the data as an array e.g. [{name: "INPUT_NAME", value: "INPUT_VALUE"}, ...] instead of an object e.g. {INPUT_NAME: INPUT_VALUE, ...}. This might be useful if you omit naming your inputs. +autofocus | string | empty string | The HTML element ID of a form field to autofocus on. The focused element is the element that will receive keyboard events. For elements like `` or ``, autofocus means that the cursor will appear in the text input area when the trial loads. +autocomplete | boolean | false | This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. ## Data Generated @@ -33,3 +35,16 @@ var form_trial = { html: '

I am feeling , , and .

' }; ``` + +### Example using the autofocus parameter + +In this example, the browser will focus on the element with the ID `test-resp-box` when the trial loads. For `` elements, this means that the cursor will appear inside the text box. + +```javascript +var autofocus_trial = { + type: 'survey-html-form', + preamble: '

What is your favorite bird?

', + html: '

My favorite bird is

', + autofocus: 'test-resp-box' +}; +``` \ No newline at end of file diff --git a/docs/plugins/jspsych-survey-likert.md b/docs/plugins/jspsych-survey-likert.md index fe89ffbf..65d292d1 100644 --- a/docs/plugins/jspsych-survey-likert.md +++ b/docs/plugins/jspsych-survey-likert.md @@ -13,6 +13,7 @@ randomize_question_order | boolean | `false` | If true, the display order of `qu preamble | string | empty string | HTML formatted string to display at the top of the page above all the questions. scale_width | numeric | null | The width of the likert scale in pixels. If left `null`, then the width of the scale will be equal to the width of the widest content on the page. button_label | string | 'Continue' | Label of the button. +autocomplete | boolean | false | This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. ## Data Generated diff --git a/docs/plugins/jspsych-survey-multi-choice.md b/docs/plugins/jspsych-survey-multi-choice.md index 0ff60896..e9129974 100644 --- a/docs/plugins/jspsych-survey-multi-choice.md +++ b/docs/plugins/jspsych-survey-multi-choice.md @@ -12,6 +12,7 @@ questions | array | *undefined* | An array of objects, each object represents a randomize_question_order | boolean | `false` | If true, the display order of `questions` is randomly determined at the start of the trial. In the data object, `Q0` will still refer to the first question in the array, regardless of where it was presented visually. preamble | string | empty string | HTML formatted string to display at the top of the page above all the questions. button_label | string | 'Continue' | Label of the button. +autocomplete | boolean | false | This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. ## Data Generated diff --git a/docs/plugins/jspsych-survey-multi-select.md b/docs/plugins/jspsych-survey-multi-select.md index 60621a29..10672e10 100644 --- a/docs/plugins/jspsych-survey-multi-select.md +++ b/docs/plugins/jspsych-survey-multi-select.md @@ -13,6 +13,7 @@ randomize_question_order | boolean | `false` | If true, the display order of `qu preamble | string | empty string | HTML formatted string to display at the top of the page above all the questions. button_label | string | 'Continue' | Label of the button. required_message | string | 'You must choose at least one response for this question' | Message to display if required response is not given. +autocomplete | boolean | false | This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. ## Data Generated diff --git a/docs/plugins/jspsych-survey-text.md b/docs/plugins/jspsych-survey-text.md index f43abe38..69d06adc 100644 --- a/docs/plugins/jspsych-survey-text.md +++ b/docs/plugins/jspsych-survey-text.md @@ -12,6 +12,7 @@ questions | array | *undefined* | An array of objects, each object represents a randomize_question_order | boolean | `false` | If true, the display order of `questions` is randomly determined at the start of the trial. In the data object, `Q0` will still refer to the first question in the array, regardless of where it was presented visually. preamble | string | empty string | HTML formatted string to display at the top of the page above all the questions. button_label | string | 'Continue' | The text that appears on the button to finish the trial. +autocomplete | boolean | false | This determines whether or not all of the input elements on the page should allow autocomplete. Setting this to true will enable autocomplete or auto-fill for the form. ## Data Generated