My experiment

# jsPsych "Hello world" experiment In the long tradition of **"Hello world!"** examples, this tutorial creates an experiment that outputs the phrase "Hello world!" to the browser. Though useless as an actual experiment, the process is helpful for learning the basics of using the jsPsych library. ## Choose your own (setup) adventure With the release of version 7.0 of jsPsych there are now three different ways that you can add jsPsych to your project. Which approach you choose will depend on what your goals are. - [**I want the simplest possible setup**](#option-1-using-cdn-hosted-scripts). This approach involves using scripts that are hosted on a CDN. You do not need to download or install anything to start using jsPsych. The limitation is that you cannot customize the library. For most experiments, this approach will be sufficient. - [**I want to be able to do some customization, but have a simple setup.**](#option-2-download-and-host-jspsych). This approach involves downloading a bundle of scripts that make up jsPsych. _If you used jsPsych prior to version 7.0, this will feel like the most familiar approach_. Having your own copy of the scripts means that you can make modifications to the library such as tweaking plugin behavior. - [**I want to use modern JavaScript tooling, like `npm` and `import` statements.**](#option-3-using-npm) You can install jsPsych, plugins for jsPsych, and extensions for jsPsych from npm. This approach allows you to integrate jsPsych into your favorite JavaScript frameworks and get the benefits of TypeScript, bundlers, and more. ## Option 1: Using CDN-hosted scripts ### Step 1: Create an HTML file !!! tip To edit jsPsych code you'll need a programming-friendly text editor. A great free option is [Visual Studio Code](https://code.visualstudio.com/) (Windows, OSX, Linux). Create a new file called `experiment.html`. There's some basic code that (nearly) all HTML documents have in common. Here's a typical bare-bones HTML document. ```html My experiment ``` Add the above code to the `experiment.html` file and save it. If you open the file in a web browser, you should see a blank page and the title of the page will be 'My experiment'. ### Step 2: Load the jsPsych library To use jsPsych, add a ` ``` Note that the URL for the jsPsych library includes the version number, which ensures that the behavior of your experiment won't change with any future updates to jsPsych. You may also want to import the jsPsych stylesheet, which applies a basic set of visual styles to the experiment. This requires adding a `` tag to the `` section of the document. ```html hl_lines="6" My experiment ``` ### Step 3: Create a script element and initialize jsPsych To add JavaScript code directly to the webpage we need to add a pair of ` ``` To initialize jsPsych we use the `initJsPsych()` function and assign the output to a new variable. ```html hl_lines="10" My experiment ``` ### Step 4: Use a plugin to print a message For this demo we want to show some text on the screen. This is exactly what the [jspsych-html-keyboard-response plugin](../plugins/jspsych-html-keyboard-response.md) is designed to do. To use the plugin, we need to load it with a ` ``` Once the plugin is loaded we can create a trial using the plugin. To declare a trial that uses the `html-keyboard-response` plugin, we create an object with the property `type` equal to `jsPsychHtmlKeyboardResponse`. We can specify the other parameters of the plugin in the same object. Here we use the `stimulus` parameter to include a message. You can see the full set of parameters for each plugin on its [documentation page](/plugins/jspsych-html-keyboard-response). ```html hl_lines="13 14 15 16" My experiment ``` ### Step 5: Run the experiment Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the `jsPsych.run` function and passing in a [timeline](/overview/timeline). For a simple experiment like this one, the timeline is just an array containing the list of trials to run. ```html hl_lines="18" My experiment ``` Once you've saved the file, open it in a browser. You should see "Hello world!" printed on the screen, and if you press a key on the keyboard, the text should disappear (ending the trial). ## Option 2: Download and host jsPsych ### Step 1: Download jsPsych Start by downloading the latest release of jsPsych. The most recent version can always be found at the top of the [GitHub releases page](https://github.com/jspsych/jsPsych/releases). ### Step 2: Create a folder to store your experiment files Create a folder on your computer to put the experiment files in. We'll call this "MyExperiment" for the tutorial. Add a subfolder called `jspsych`. Once you've created the folder, open the downloaded archive from step 1 and copy the contents of the `dist` folder into the `jspsych` folder. It should look like this: ``` 📂 MyExperiment -- 📂 jspsych ---- 📄 jspsych.js ---- 📄 plugin-animation.js ---- 📄 plugin-audio-keyboard-response.js ---- ... ``` ### Step 3: Create an HTML file !!! tip To edit jsPsych code you'll need a programming-friendly text editor. A great free option is [Visual Studio Code](https://code.visualstudio.com/) (Windows, OSX, Linux). Create a new file called `experiment.html` in the `MyExperiment` folder. The directory structure should look like this: ``` 📂 MyExperiment -- 📄 experiment.html -- 📂 jspsych ``` There's some basic code that (nearly) all HTML documents have in common. Here's a typical bare-bones HTML document. ```html My experiment ``` Add the above code to the `experiment.html` file and save it. If you open the file in a web browser, you should see a blank page and the title of the page will be 'My experiment'. ### Step 4: Load the jsPsych library To use jsPsych, add a ` ``` You may also want to import the jsPsych stylesheet, which applies a basic set of visual styles to the experiment. This requires adding a `` tag to the `` section of the document. ```html hl_lines="6" My experiment ``` ### Step 5: Create a script element and initialize jsPsych To add JavaScript code directly to the webpage we need to add a pair of ` ``` To initialize jsPsych we use the `initJsPsych()` function and assign the output to a new variable. ```html hl_lines="10" My experiment ``` ### Step 6: Use a plugin to print a message For this demo we want to show some text on the screen. This is exactly what the [jspsych-html-keyboard-response plugin](../plugins/jspsych-html-keyboard-response.md) is designed to do. To use the plugin, we need to load it with a ` ``` Once the plugin is loaded we can create a trial using the plugin. To declare a trial that uses the `html-keyboard-response` plugin, we create an object with the property `type` equal to `jsPsychHtmlKeyboardResponse`. We can specify the other parameters of the plugin in the same object. Here we use the `stimulus` parameter to include a message. You can see the full set of parameters for each plugin on its [documentation page](/plugins/jspsych-html-keyboard-response). ```html hl_lines="13 14 15 16" My experiment ``` ### Step 7: Run the experiment Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the `jsPsych.run` function and passing in a [timeline](/overview/timeline). For a simple experiment like this one, the timeline is just an array containing the list of trials to run. ```html hl_lines="18" My experiment ``` Once you've saved the file, open it in a browser. You should see "Hello world!" printed on the screen, and if you press a key on the keyboard, the text should disappear (ending the trial). ## Option 3: Using npm If you are electing to use `npm` to install jsPsych we will assume that you already are familiar with Node.js and generally know what you are doing with web development. ### Step 1: Install jspsych Run `npm install jspsych`. This installs the core jsPsych package. Plugins and extensions are installed separately. ### Step 2: Import the JsPsych class and create a new instance We create a new instance of `JsPsych`. The instance can be configured via [a variety of options](/reference/jspsych.md#initjspsych), passed as an object to the constructor. ```js import {JsPsych} from 'jspsych'; const jsPsych = new JsPsych(); ``` ### Step 3: stylesheet?? ### Step 4: Install and import a plugin Install the `html-keyboard-response` plugin with: `npm install @jspsych/plugin-html-keyboard-response` Then import the `htmlKeyboardResponse` plugin class. ```js import {JsPsych} from 'jspsych'; import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response'; const jsPsych = new JsPsych(); ``` ### Step 5: Create a trial Once the plugin is imported we can create a trial using the plugin. To declare a trial that uses the `html-keyboard-response` plugin, we create an object with the property `type` equal to `htmlKeyboardResponse`. We can specify the other parameters of the plugin in the same object. Here we use the `stimulus` parameter to include a message. You can see the full set of parameters for each plugin on its [documentation page](/plugins/jspsych-html-keyboard-response). ```js import {JsPsych} from 'jspsych'; import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response'; const jsPsych = new JsPsych(); const trial = { type: htmlKeyboardResponse, stimulus: 'Hello world!' } ``` ### Step 6: Run Now that we have the trial defined we need to tell jsPsych to run an experiment consisting of this trial. This requires using the `jsPsych.run` function and passing in a [timeline](/overview/timeline). For a simple experiment like this one, the timeline is just an array containing the list of trials to run. ```js import {JsPsych} from 'jspsych'; import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response'; const jsPsych = new JsPsych(); const trial = { type: htmlKeyboardResponse, stimulus: 'Hello world!' } jsPsych.run([trial]); ```