10 More Plugins
- Review how to add new plugins to jsPsych experiments
- Learn to navigate and interpret jsPsych plugin documentation
- Practice implementing the instructions and html-button-response plugins
- Understand how to customize plugin parameters and styling
10.1 Introduction
In this chapter, we’re going to take a closer look at adding plugins to your jsPsych experiments and learning how to read the official documentation. We’ll focus on two specific plugins: the html-button-response plugin, which lets participants click on buttons to respond, and the instructions plugin plugin, which creates multi-page instruction screens.
Since this book can’t cover every single plugin, our main goal here is to teach you how to read and understand the documentation. Once you master this skill, you’ll be able to add any plugin you need to your experiments, even ones we haven’t discussed.
Think of plugin documentation as a recipe book. Each plugin page tells you exactly what ingredients (parameters) you need, which ones are required versus optional, and how to put them together to create the trial you want.
10.2 The Instructions Plugin
10.2.1 Documentation Overview
When you visit the instructions plugin documentation, you’ll see several important sections. Let’s walk through each one so you know what to look for.
10.2.1.1 Parameters
The most important part of any plugin documentation is the parameters table. This table tells you everything you can customize about how the plugin works.
| Parameter | Type | Default Value | Description |
|---|---|---|---|
| pages | array | undefined | Each element of the array is the content for a single page. Each page should be an HTML-formatted string. |
| key_forward | string | ‘ArrowRight’ | This is the key that the participant can press in order to advance to the next page. This key should be specified as a string (e.g., ‘a’, ‘ArrowLeft’, ’ ‘, ’Enter’). |
| key_backward | string | ‘ArrowLeft’ | This is the key that the participant can press to return to the previous page. This key should be specified as a string (e.g., ‘a’, ‘ArrowLeft’, ’ ‘, ’Enter’). |
| allow_backward | boolean | true | If true, the participant can return to previous pages of the instructions. If false, they may only advace to the next page. |
| allow_keys | boolean | true | If true, the participant can use keyboard keys to navigate the pages. If false, they may not. |
| show_clickable_nav | boolean | false | If true, then a Previous and Next button will be displayed beneath the instructions. Participants can click the buttons to navigate. |
| 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. |
| on_page_change | function | function (current_page) {} | The function that is called every time the page changes. This function receives a single argument current_page, which is the index of the current page after page change, and starts at 0. The function is also called when going forward from the last page, i.e., finishing the trial. |
The pages parameter is the most important one. Notice that its default value is listed as undefined. This is a programming way of saying “nothing.” When you see “undefined” as a default value, it means this parameter is required. You must include it, or your trial won’t work. The pages parameter expects an array (a list) of content for each instruction page. Each item in your list becomes one page of instructions.
The show_clickable_nav parameter has a default value of false, which means by default, participants can only use keyboard keys to navigate through instructions. If you want to show “Previous” and “Next” buttons that participants can click, you need to change this to true.
Other parameters like button_label_next and button_label_previous let you customize what text appears on those navigation buttons. The default values are “Next” and “Previous,” but you might want to change them to something like “Continue” and “Back” depending on your experiment.
10.2.1.2 Install
The documentation also shows you how to load the plugin into your experiment. You’ll see a few options: loading it from a local file on your computer, or loading it from the internet using something called a CDN (Content Delivery Network).
Local method:
Using the (online) CDN-hosted file:
The CDN method is often easier because you don’t need to download and manage the plugin files yourself, but it requires an internet connection.
However, for this book, we’re using a local copy to ensure everyone is using the same version of jsPsych.
10.2.1.3 Examples
Further down the page, we can see a couple examples of creating an instructions trial object:
var trial = {
type: jsPsychInstructions,
pages: [
'Welcome to the experiment. Click next to begin.',
'This is the second page of instructions.',
'This is the final page.'
],
show_clickable_nav: true
}Every jsPsych plugin follows the same naming pattern in your code. You take the plugin name (like “instructions”) and convert it to what programmers call “camelCase”. This means you capitalize the first letter of each word except the first, then add “jsPsych” to the beginning.
So the “instructions” plugin becomes jsPsychInstructions in your code. The “html-button-response” plugin becomes jsPsychHtmlButtonResponse. This might seem confusing at first, but once you see the pattern, it becomes automatic.
Also notice how we’re following the parameter requirements from the documentation. We specify the type as jsPsychInstructions, provide the required pages parameter with an array of three text strings, and set show_clickable_nav to true so participants can click buttons to navigate.
Each item in the pages array becomes one screen of instructions. Participants will see the first item first, then can navigate forward to see the second item, and so on.
10.2.2 A Working Example
Ok, let’s load it up and see it in action:
<!DOCTYPE html>
<html>
<head>
<title>My experiment</title>
<!-- Base JsPsych -->
<script src="jspsych/jspsych.js"></script>
<link href="jspsych/jspsych.css" rel="stylesheet" type="text/css" />
<!-- Plugins -->
<script src="jspsych/plugin-instructions.js"></script>
</head>
<body>
<script src="exp.js"></script>
</body>
</html>const jsPsych = initJsPsych();
var trial = {
type: jsPsychInstructions,
pages: [
'Welcome to the experiment. Click next to begin.',
'This is the second page of instructions.',
'This is the final page.'
],
show_clickable_nav: true,
show_page_number: true,
button_label_previous: "Back",
button_label_next: "Next"
}
jsPsych.run([trial])10.2.3 Adding HTML and Styling
Plain text instructions work fine, but sometimes you want more control over how your instructions look. Since the pages parameter accepts HTML, you can include formatting like headers, paragraphs, lists, and even custom styling.
Here’s a more sophisticated example:
<!DOCTYPE html>
<html>
<head>
<title>My experiment</title>
<!-- Base JsPsych -->
<script src="jspsych/jspsych.js"></script>
<link href="jspsych/jspsych.css" rel="stylesheet" type="text/css" />
<!-- Plugins -->
<script src="jspsych/plugin-instructions.js"></script>
<!-- custom CSS -->
<link href="style.css" rel="stylesheet" type="text/css" />
</head>
<body>
<script src="exp.js"></script>
</body>
</html>const jsPsych = initJsPsych();
var trial = {
type: jsPsychInstructions,
pages: [
`<div class="instructions">
<h2>Welcome to the Memory Experiment!</h2>
<p>In this study, you will be testing your working memory capacity using a digit span task. Use the arrow keys or buttons below to navigate through these instructions.</p>
</div>`,
`<div class="instructions">
<h2>How the Task Works</h2>
<p>You will see a sequence of numbers presented one at a time on the screen.</p>
<p>Your job is to remember the numbers in the <strong>exact order</strong> they appeared. After the sequence ends, you will be asked to type the numbers back in the correct order.</p>
</div>`,
`<div class="instructions">
<h2>Example</h2>
<p>If you see the sequence: <code>3 → 7 → 1 → 9</code></p>
<p>You should type: <code>3719</code></p>
<p>The sequences will start short and gradually get longer as you progress through the experiment.</p>
</div>`,
`<div class="instructions">
<h2>Important Guidelines</h2>
<ul>
<li>Pay close attention to each number as it appears</li>
<li>Do not write anything down during the presentation</li>
<li>Type your response as soon as the input box appears</li>
<li>If you're unsure, make your best guess</li>
</ul>
</div>`,
`<div class="instructions">
<h2>Ready to Begin?</h2>
<p>The experiment will take approximately 10-15 minutes to complete.</p>
<p>Make sure you're in a quiet environment where you can concentrate.</p>
<p>Click 'Next' when you're ready to start the practice trials.</p>
</div>`
],
show_clickable_nav: true
}
jsPsych.run([trial]).jspsych-content-wrapper {
background-color: '#DCE2F0';
color: '#50586C';
}
.jspsych-content {
width: 100%;
max-width: 700px;
}
.jspsych-btn {
background-color: #4A5568;
color: #FFFFFF;
border: 1px solid #2D3748;
}
.jspsych-btn:hover {
background-color: #2D3748;
}
.instructions {
margin-left: 1em;
margin-right: 1em;
text-align: left;
}
Notice a few important things about this example. First, I’m using backticks (`) instead of regular quotation marks around the HTML content. Backticks allow you to write text that spans multiple lines and includes quotation marks without causing problems in your code.
Second, I’ve wrapped each page’s content in a <div> with a class called instructions. This gives me a way to apply consistent styling to all my instruction pages using CSS.
Third, I’ve added the show_page_number parameter and set it to true. This will display something like “Page 1/3” to help participants understand how many instruction pages there are.
For the CSS, I’ve added some styling to our external stylesheet called style.css. I decided to change a few things about the jspsych classes, including the colors. This styling will apply to the entire experiment.
Then, I added our custom .instructions class and added some styling that will only apply to the instructions HTML.