HoshinoKoji/jsPsych
1
0
Fork 0
mirror of https://github.com/jspsych/jsPsych.git synced 2025-05-10 19:20:55 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

first draft of new hello world tutorial

Browse Source
This commit is contained in:
Josh de Leeuw 2021-09-15 12:54:36 -04:00
parent 64e7ff0b46
commit 9d74f9223c
1 changed files with 376 additions and 122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

496
docs/tutorials/hello-world.md
View File

@ -2,174 +2,428 @@
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. 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.
## Step 1: Choose your own (setup) adventure ## 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. 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**. 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 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.**. 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 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.** Great! 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 - [**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.
!!! info ## Option 1: Using CDN-hosted scripts
If you would like to use modern web development tools (e.g. ES6 modules, Node/NPM, webpack, Babel), you may want to check out the [jsPsych Builder](https://github.com/bjoluc/jspsych-builder) CLI utility. jsPsych Builder allows you to automate the experiment setup, spin up a development server, and transpile and bundle scripts and styles. Using jsPsych Builder will automate some of the steps in this tutorial, so if you prefer that option, you may want to switch to the getting started instructions on the jsPsych Builder GitHub page.
## Step 1: Download the jsPsych library ### Step 1: Create an HTML file
Start by downloading the jsPsych library. The most recent version can always be found on the [GitHub releases page](https://github.com/jspsych/jsPsych/releases). !!! 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).
*Note: the image below shows version 4.2, but the process is the same for the most recent version.* Create a new file called `experiment.html`.
![releasespage](/img/githubreleases.jpg)
!!! warning
We strongly recommend downloading the latest release of the code rather than downloading the zip file of the code via the *Big Green Button* on the GitHub site. Downloading the code via the *Big Green Button* may give you a copy of the library that is in development and contains bugs.
## Step 2: Create a folder to store your experiment files
Create a folder on your computer to put the experiment files in. Once you've created the folder, open the downloaded archive from step 1, and move the extracted folder (called `jspsych-6.3.0` if using v6.3.0 of jsPsych) into the experiment folder.
```
📂 My Experiment
-- 📂 jspsych-6.3.0
```
If you open up the `jspsych-6.3.0` folder you should see this structure.
```
📂 My Experiment
-- 📂 jspsych-6.3.0
---- 📂 css
---- 📂 examples
---- 📂 plugins
---- 📄 jspsych.js
```
## Step 3: Create a new HTML file
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).
Once you've got a text editor that you like, create a new file in the experiment folder called `experiment.html`
```
📂 My Experiment
-- 📂 jspsych-6.3.0
-- 📄 experiment.html
```
## Step 4: Add the bare-minimum HTML code
There's some basic code that (nearly) all HTML documents have in common. Here's a typical bare-bones HTML document. There's some basic code that (nearly) all HTML documents have in common. Here's a typical bare-bones HTML document.
```html ```html
<!DOCTYPE html> <!DOCTYPE html>
<html> <html>
<head> <head>
<title>My experiment</title> <title>My experiment</title>
</head> </head>
<body></body> <body></body>
</html> </html>
``` ```
Add the above code to the experiment.html file and save it. If you then open the file in a web browser, you should see a blank page and the title of the page will be '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 5: Import the jsPsych library ### Step 2: Load the jsPsych library
To use jsPsych, add a `<script>` tag to import the library. To use jsPsych, add a `<script>` tag to load the library. We'll load the library from a [CDN](https://www.jsdelivr.com/), which means that the library is hosted on another server and can be loaded without having your own copy.
```html ```html hl_lines="5"
<!DOCTYPE html> <!DOCTYPE html>
<html> <html>
<head> <head>
<title>My experiment</title> <title>My experiment</title>
<script src="jspsych-6.3.0/jspsych.js"></script> <script src="https://cdn.jsdelivr.net/npm/jspsych@7.0/dist/index.browser.min.js"></script>
</head> </head>
<body></body> <body></body>
</html> </html>
``` ```
You may also want to import the jsPsych stylesheet, which applies a basic set of visual styles to the experiment to make it visually pleasing. This requires adding a `<link>` tag to the `<head>` section of the document. 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.
```html You may also want to import the jsPsych stylesheet, which applies a basic set of visual styles to the experiment. This requires adding a `<link>` tag to the `<head>` section of the document.
```html hl_lines="6"
<!DOCTYPE html> <!DOCTYPE html>
<html> <html>
<head> <head>
<title>My experiment</title> <title>My experiment</title>
<script src="jspsych-6.3.0/jspsych.js"></script> <script src="https://cdn.jsdelivr.net/npm/jspsych@7.0/dist/index.browser.min.js"></script>
<link href="jspsych-6.3.0/css/jspsych.css" rel="stylesheet" type="text/css"> <link href="https://cdn.jsdelivr.net/npm/jspsych@7.0/css/jspsych.css" rel="stylesheet" type="text/css" />
</head> </head>
<body></body> <body></body>
</html> </html>
``` ```
## Step 6: Use the jspsych-html-keyboard-response plugin to print a message ### Step 3: Create a script element and initialize jsPsych
For the 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 `<script>` tag.
```html
<!DOCTYPE html>
<html>
<head>
<title>My experiment</title>
<script src="jspsych-6.3.0/jspsych.js"></script>
<script src="jspsych-6.3.0/plugins/jspsych-html-keyboard-response.js"></script>
<link href="jspsych-6.3.0/css/jspsych.css" rel="stylesheet" type="text/css">
</head>
<body></body>
</html>
```
Once the plugin is loaded, we can create an experiment using the plugin. To declare a trial that uses the html-keyboard-response plugin, we create a JavaScript object with the property `type` equal to `'html-keyboard-response'`. Then we can specify the other parameters of the plugin in the same object.
To add JavaScript code directly to the webpage we need to add a set of `<script>` tags after the `<body>` tags. To add JavaScript code directly to the webpage we need to add a set of `<script>` tags after the `<body>` tags.
```html ```html hl_lines="9 10"
<!DOCTYPE html> <!DOCTYPE html>
<html> <html>
<head> <head>
<title>My experiment</title> <title>My experiment</title>
<script src="jspsych-6.3.0/jspsych.js"></script> <script src="https://cdn.jsdelivr.net/npm/jspsych@7.0/dist/index.browser.min.js"></script>
<script src="jspsych-6.3.0/plugins/jspsych-html-keyboard-response.js"></script> <link href="https://cdn.jsdelivr.net/npm/jspsych@7.0/css/jspsych.css" rel="stylesheet" type="text/css" />
<link href="jspsych-6.3.0/css/jspsych.css" rel="stylesheet" type="text/css"> </head>
</head> <body></body>
<body></body> <script>
<script> </script>
var hello_trial = {
type: 'html-keyboard-response',
stimulus: 'Hello world!'
}
</script>
</html> </html>
``` ```
Now that we have the trial defined we just need to tell jsPsych to run an experiment consisting of this trial. This requires using the `jsPsych.init` function and specifying the `timeline` parameter. To initialize jsPsych we use the `initJsPsych()` function and assign the output to a new variable.
```html ```html hl_lines="10"
<!DOCTYPE html> <!DOCTYPE html>
<html> <html>
<head> <head>
<title>My experiment</title> <title>My experiment</title>
<script src="jspsych-6.3.0/jspsych.js"></script> <script src="https://cdn.jsdelivr.net/npm/jspsych@7.0/dist/index.browser.min.js"></script>
<script src="jspsych-6.3.0/plugins/jspsych-html-keyboard-response.js"></script> <link href="https://cdn.jsdelivr.net/npm/jspsych@7.0/css/jspsych.css" rel="stylesheet" type="text/css" />
<link href="jspsych-6.3.0/css/jspsych.css" rel="stylesheet" type="text/css"> </head>
</head> <body></body>
<body></body> <script>
<script> const jsPsych = initJsPsych();
</script>
</html>
```
var hello_trial = { ### Step 4: Use a plugin to print a message
type: 'html-keyboard-response',
stimulus: 'Hello world!'
}
jsPsych.init({ 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 `<script>` tag.
timeline: [hello_trial]
})
</script> ```html hl_lines="6"
<!DOCTYPE html>
<html>
<head>
<title>My experiment</title>
<script src="https://cdn.jsdelivr.net/npm/jspsych@7.0/dist/index.browser.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@jspsych/plugin-html-keyboard-response@1.0/dist/index.browser.min.js"></script>
<link href="https://cdn.jsdelivr.net/npm/jspsych@7.0/css/jspsych.css" rel="stylesheet" type="text/css" />
</head>
<body></body>
<script>
const jspsych = initJsPsych();
</script>
</html>
```
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 `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).
```html hl_lines="13 14 15 16"
<!DOCTYPE html>
<html>
<head>
<title>My experiment</title>
<script src="https://cdn.jsdelivr.net/npm/jspsych@7.0/dist/index.browser.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@jspsych/plugin-html-keyboard-response@1.0/dist/index.browser.min.js"></script>
<link href="https://cdn.jsdelivr.net/npm/jspsych@7.0/css/jspsych.css" rel="stylesheet" type="text/css" />
</head>
<body></body>
<script>
const jsPsych = initJsPsych();
const hello_trial = {
type: htmlKeyboardResponse,
stimulus: 'Hello world!'
}
</script>
</html>
```
### 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"
<!DOCTYPE html>
<html>
<head>
<title>My experiment</title>
<script src="https://cdn.jsdelivr.net/npm/jspsych@7.0/dist/index.browser.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@jspsych/plugin-html-keyboard-response@1.0/dist/index.browser.min.js"></script>
<link href="https://cdn.jsdelivr.net/npm/jspsych@7.0/css/jspsych.css" rel="stylesheet" type="text/css" />
</head>
<body></body>
<script>
const jsPsych = initJsPsych();
const hello_trial = {
type: htmlKeyboardResponse,
stimulus: 'Hello world!'
}
jsPsych.run([hello_trial]);
</script>
</html> </html>
``` ```
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). 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
<!DOCTYPE html>
<html>
<head>
<title>My experiment</title>
</head>
<body></body>
</html>
```
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 `<script>` tag to load the library. Set the `src` attribute to the path to the `jspsych.js` file.
```html hl_lines="5"
<!DOCTYPE html>
<html>
<head>
<title>My experiment</title>
<script src="jspsych/jspsych.js"></script>
</head>
<body></body>
</html>
```
You may also want to import the jsPsych stylesheet, which applies a basic set of visual styles to the experiment. This requires adding a `<link>` tag to the `<head>` section of the document.
```html hl_lines="6"
<!DOCTYPE html>
<html>
<head>
<title>My experiment</title>
<script src="jspsych/jspsych.js"></script>
<link href="jspsych/jspsych.css" rel="stylesheet" type="text/css" />
</head>
<body></body>
</html>
```
### Step 5: Create a script element and initialize jsPsych
To add JavaScript code directly to the webpage we need to add a set of `<script>` tags after the `<body>` tags.
```html hl_lines="9 10"
<!DOCTYPE html>
<html>
<head>
<title>My experiment</title>
<script src="jspsych/jspsych.js"></script>
<link href="jspsych/jspsych.css" rel="stylesheet" type="text/css" />
</head>
<body></body>
<script>
</script>
</html>
```
To initialize jsPsych we use the `initJsPsych()` function and assign the output to a new variable.
```html hl_lines="10"
<!DOCTYPE html>
<html>
<head>
<title>My experiment</title>
<script src="jspsych/jspsych.js"></script>
<link href="jspsych/jspsych.css" rel="stylesheet" type="text/css" />
</head>
<body></body>
<script>
const jsPsych = initJsPsych();
</script>
</html>
```
### 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 `<script>` tag.
```html hl_lines="6"
<!DOCTYPE html>
<html>
<head>
<title>My experiment</title>
<script src="jspsych/jspsych.js"></script>
<script src="jspsych/plugin-html-keyboard-response.js"></script>
<link href="jspsych/jspsych.css" rel="stylesheet" type="text/css" />
</head>
<body></body>
<script>
const jspsych = initJsPsych();
</script>
</html>
```
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 `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).
```html hl_lines="13 14 15 16"
<!DOCTYPE html>
<html>
<head>
<title>My experiment</title>
<script src="jspsych/jspsych.js"></script>
<script src="jspsych/plugin-html-keyboard-response.js"></script>
<link href="jspsych/jspsych.css" rel="stylesheet" type="text/css" />
</head>
<body></body>
<script>
const jsPsych = initJsPsych();
const hello_trial = {
type: htmlKeyboardResponse,
stimulus: 'Hello world!'
}
</script>
</html>
```
### 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"
<!DOCTYPE html>
<html>
<head>
<title>My experiment</title>
<script src="jspsych/jspsych.js"></script>
<script src="jspsych/plugin-html-keyboard-response.js"></script>
<link href="jspsych/jspsych.css" rel="stylesheet" type="text/css" />
</head>
<body></body>
<script>
const jsPsych = initJsPsych();
const hello_trial = {
type: htmlKeyboardResponse,
stimulus: 'Hello world!'
}
jsPsych.run([hello_trial]);
</script>
</html>
```
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](/core_library/jspsych-core/#jspsychinit), 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` 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]);
```