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

Merge pull request #2784 from jadeddelta/cloze-checkblank

Browse Source 
Cloze `allow_blanks` functionality
This commit is contained in:
Josh de Leeuw 2022-10-01 14:17:21 -04:00 committed by GitHub
commit 52827bd552
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 151 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.changeset/violet-hairs-tap.md Normal file
View File

@ -0,0 +1,5 @@
---
"@jspsych/plugin-cloze": minor
---
added `allow_blanks` as a field, allowing for completion checking of answers

31
docs/demos/jspsych-cloze-demo3.html Normal file
View File

@ -0,0 +1,31 @@
<!DOCTYPE html>
<html>
<head>
<script src="docs-demo-timeline.js"></script>
<script src="https://unpkg.com/jspsych@7.3.0"></script>
<script src="https://unpkg.com/@jspsych/plugin-cloze@1.1.1"></script>
<script src="https://unpkg.com/@jspsych/plugin-html-button-response@1.1.1"></script>
<link rel="stylesheet" href="https://unpkg.com/jspsych@7.3.0/css/jspsych.css" />
<link rel="stylesheet" href="docs-demo.css" type="text/css">
</head>
<body></body>
<script>
const jsPsych = initJsPsych();
var trial = {
type: jsPsychCloze,
text: 'Science notebooks have a %%-colored front cover. Math notebooks have a %%-colored front cover.',
allow_blanks: false,
mistake_fn: function() { alert('Please fill in all blanks.'); }
};
const timeline = [trial];
if (typeof jsPsych !== "undefined") {
jsPsych.run(generateDocsDemoTimeline(timeline));
} else {
document.body.innerHTML = '<div style="text-align:center; margin-top:50%; transform:translate(0,-50%);">You must be online to view the plugin demo.</div>';
}
</script>
</html>

22
docs/plugins/cloze.md
View File

@ -2,7 +2,7 @@
Current version: 1.1.2. [See version history](https://github.com/jspsych/jsPsych/blob/main/packages/plugin-cloze/CHANGELOG.md). Current version: 1.1.2. [See version history](https://github.com/jspsych/jsPsych/blob/main/packages/plugin-cloze/CHANGELOG.md).
This plugin displays a text with certain words removed. Participants are asked to replace the missing items. Responses are recorded when clicking a button. Optionally, responses are evaluated and a function is called in case of differences, making it possible to inform participants about mistakes. This plugin displays a text with certain words omitted. Participants are asked to replace the missing items. Responses are recorded when clicking a button. Responses can be evaluated and a function is called in case of either differences or incomplete answers, making it possible to inform participants about mistakes before proceeding.
## Parameters ## Parameters
@ -13,7 +13,8 @@ In addition to the [parameters available in all plugins](../overview/plugins.md#
| text | string | *undefined* | The cloze text to be displayed. Blanks are indicated by %% signs and automatically replaced by input fields. If there is a correct answer you want the system to check against, it must be typed between the two percentage signs (i.e. % correct solution %). | | text | string | *undefined* | The cloze text to be displayed. Blanks are indicated by %% signs and automatically replaced by input fields. If there is a correct answer you want the system to check against, it must be typed between the two percentage signs (i.e. % correct solution %). |
| button_text | string | OK | Text of the button participants have to press for finishing the cloze test. | | button_text | string | OK | Text of the button participants have to press for finishing the cloze test. |
| check_answers | boolean | false | Boolean value indicating if the answers given by participants should be compared against a correct solution given in the text (between % signs) after the button was clicked. If ```true```, answers are checked and in case of differences, the ```mistake_fn``` is called. In this case, the trial does not automatically finish. If ```false```, no checks are performed and the trial automatically ends when clicking the button. | | check_answers | boolean | false | Boolean value indicating if the answers given by participants should be compared against a correct solution given in the text (between % signs) after the button was clicked. If ```true```, answers are checked and in case of differences, the ```mistake_fn``` is called. In this case, the trial does not automatically finish. If ```false```, no checks are performed and the trial automatically ends when clicking the button. |
| mistake_fn | function | ```function(){}``` | Function called if ```check_answers``` is set to ```true``` and there is a difference between the participants answers and the correct solution provided in the text. | | allow_blanks | boolean | true | Boolean value indicating if the answers given by participants should be checked for completion after the button was clicked. If ```true```, answers are not checked for completion and blank answers are allowed. The trial will then automatically finish upon the clicking the button. If ```false```, answers are checked for completion, and in case there are some fields with missing answers, the ```mistake_fn``` is called. In this case, the trial does not automatically finish. |
| mistake_fn | function | ```function(){}``` | Function called if ```check_answers``` is set to ```true``` or ```allow_blanks``` is set to false and there is a difference between the participants answers and the correct solution provided in the text, or if there is at least one field with a blank answer respectively. |
## Data Generated ## Data Generated
@ -63,6 +64,23 @@ import cloze from '@jspsych/plugin-cloze';
<a target="_blank" rel="noopener noreferrer" href="../../demos/jspsych-cloze-demo1.html">Open demo in new tab</a> <a target="_blank" rel="noopener noreferrer" href="../../demos/jspsych-cloze-demo1.html">Open demo in new tab</a>
???+ example "Cloze example using default settings with completion checking and custom error handling"
=== "Code"
```javascript
var cloze_trial = {
type: jsPsychCloze,
text: 'Science notebooks have a %%-colored front cover. Math notebooks have a %%-colored front cover.',
allow_blanks: false,
mistake_fn: function() { alert('Please fill in all blanks.'); }
};
```
=== "Demo"
<div style="text-align:center;">
<iframe src="../../demos/jspsych-cloze-demo3.html" width="90%;" height="500px;" frameBorder="0"></iframe>
</div>
<a target="_blank" rel="noopener noreferrer" href="../../demos/jspsych-cloze-demo3.html">Open demo in new tab</a>
???+ example "More elaborate example (with check against correct solution, custom error handling and modified button text)" ???+ example "More elaborate example (with check against correct solution, custom error handling and modified button text)"
=== "Code" === "Code"

11
examples/jspsych-cloze.html
View File

@ -3,7 +3,7 @@
<head> <head>
<script src="../packages/jspsych/dist/index.browser.js"></script> <script src="../packages/jspsych/dist/index.browser.js"></script>
<script src="../packages/plugin-cloze/dist/index.browser.js"></script> <script src="../packages/plugin-cloze/dist/index.browser.js"></script>
<link rel="stylesheet" href="../packages/jspsych/css/jspsych.css"> <link rel="stylesheet" href="../packages/jspsych/css/jspsych.css" />
</head> </head>
<body></body> <body></body>
<script> <script>
@ -22,6 +22,14 @@
text: 'The %% is the largest terrestrial mammal. It lives in both %% and %%.' text: 'The %% is the largest terrestrial mammal. It lives in both %% and %%.'
}); });
// another example with checking if all the blanks are filled in
timeline.push({
type: jsPsychCloze,
text: 'Science notebooks have a %%-colored front cover. Math notebooks have a %%-colored front cover.',
allow_blanks: false,
mistake_fn: function () { alert("You have not filled in all the blanks!"); }
});
// more elaborate example (with check against correct solution, custom error handling and modified button text) // more elaborate example (with check against correct solution, custom error handling and modified button text)
timeline.push({ timeline.push({
type: jsPsychCloze, type: jsPsychCloze,
@ -32,6 +40,5 @@
}); });
jsPsych.run(timeline); jsPsych.run(timeline);
</script> </script>
</html> </html>

2
packages/plugin-cloze/README.md
View File

@ -4,7 +4,7 @@ jsPsych is a JavaScript framework for creating behavioral experiments that run i
## Plugin Description ## Plugin Description
The cloze plugin displays a text with certain words omitted. Participants are asked to replace the missing words, and are recorded upon clicking a button. Optionally, the responses can be evaluated and a function can be called in the case of differences, making it possible to provide feedback to the participant. The cloze plugin displays a text with certain words omitted. Participants are asked to replace the missing words, and are recorded upon clicking a button. Responses can be evaluated and a function is called in case of either differences or incomplete answers, making it possible to inform participants about mistakes before proceeding.
## Examples ## Examples

62
packages/plugin-cloze/src/index.spec.ts
View File

@ -73,6 +73,20 @@ describe("cloze", () => {
await expectFinished(); await expectFinished();
}); });
test("ends trial on button click when all answers are checked for completion and are complete", async () => {
const { expectFinished } = await startTimeline([
{
type: cloze,
text: "This is a %cloze% text.",
allow_blanks: false,
},
]);
getInputElementById("input0").value = "filler";
clickTarget(document.querySelector("#finish_cloze_button"));
await expectFinished();
});
test("does not end trial on button click when answers are checked and not correct", async () => { test("does not end trial on button click when answers are checked and not correct", async () => {
const { expectRunning } = await startTimeline([ const { expectRunning } = await startTimeline([
{ {
@ -87,6 +101,20 @@ describe("cloze", () => {
await expectRunning(); await expectRunning();
}); });
test("does not end trial on button click when answers are checked for completion and some are missing", async () => {
const { expectRunning } = await startTimeline([
{
type: cloze,
text: "This is a %cloze% text.",
allow_blanks: false,
},
]);
getInputElementById("input0").value = "";
clickTarget(document.querySelector("#finish_cloze_button"));
await expectRunning();
});
test("does not call mistake function on button click when answers are checked and correct", async () => { test("does not call mistake function on button click when answers are checked and correct", async () => {
const mistakeFn = jest.fn(); const mistakeFn = jest.fn();
@ -104,6 +132,23 @@ describe("cloze", () => {
expect(mistakeFn).not.toHaveBeenCalled(); expect(mistakeFn).not.toHaveBeenCalled();
}); });
test("does not call mistake function on button click when answers are checked for completion and are complete", async () => {
const mistakeFn = jest.fn();
await startTimeline([
{
type: cloze,
text: "This is a %cloze% text.",
allow_blanks: false,
mistake_fn: mistakeFn,
},
]);
getInputElementById("input0").value = "cloze";
clickTarget(document.querySelector("#finish_cloze_button"));
expect(mistakeFn).not.toHaveBeenCalled();
});
test("calls mistake function on button click when answers are checked and not correct", async () => { test("calls mistake function on button click when answers are checked and not correct", async () => {
const mistakeFn = jest.fn(); const mistakeFn = jest.fn();
@ -121,6 +166,23 @@ describe("cloze", () => {
expect(mistakeFn).toHaveBeenCalled(); expect(mistakeFn).toHaveBeenCalled();
}); });
test("calls mistake function on button click when answers are checked for completion and are not complete", async () => {
const mistakeFn = jest.fn();
await startTimeline([
{
type: cloze,
text: "This is a %cloze% text.",
check_answers: true,
mistake_fn: mistakeFn,
},
]);
getInputElementById("input0").value = "";
clickTarget(document.querySelector("#finish_cloze_button"));
expect(mistakeFn).toHaveBeenCalled();
});
test("response data is stored as an array", async () => { test("response data is stored as an array", async () => {
const { getData, getHTML } = await startTimeline([ const { getData, getHTML } = await startTimeline([
{ {

24
packages/plugin-cloze/src/index.ts
View File

@ -21,7 +21,13 @@ const info = <const>{
pretty_name: "Check answers", pretty_name: "Check answers",
default: false, default: false,
}, },
/** Function called if check_answers is set to TRUE and there is a difference between the participants answers and the correct solution provided in the text. */ /** Boolean value indicating if the participant may leave answers blank. */
allow_blanks: {
type: ParameterType.BOOL,
pretty_name: "Allow blanks",
default: true,
},
/** Function called if either the check_answers is set to TRUE or the allow_blanks is set to FALSE and there is a discrepancy between the set answers and the answers provide or if all input fields aren't filled out, respectively. */
mistake_fn: { mistake_fn: {
type: ParameterType.FUNCTION, type: ParameterType.FUNCTION,
pretty_name: "Mistake function", pretty_name: "Mistake function",
@ -47,6 +53,7 @@ class ClozePlugin implements JsPsychPlugin<Info> {
trial(display_element: HTMLElement, trial: TrialType<Info>) { trial(display_element: HTMLElement, trial: TrialType<Info>) {
var html = '<div class="cloze">'; var html = '<div class="cloze">';
// odd elements are text, even elements are the blanks
var elements = trial.text.split("%"); var elements = trial.text.split("%");
const solutions = this.getSolutions(trial.text); const solutions = this.getSolutions(trial.text);
@ -59,13 +66,15 @@ class ClozePlugin implements JsPsychPlugin<Info> {
solution_counter++; solution_counter++;
} }
} }
html += "</div>"; html += "</div>";
display_element.innerHTML = html; display_element.innerHTML = html;
const check = () => { const check = () => {
var answers = []; var answers: String[] = [];
var answers_correct = true; var answers_correct = true;
var answers_filled = true;
for (var i = 0; i < solutions.length; i++) { for (var i = 0; i < solutions.length; i++) {
var field = document.getElementById("input" + i) as HTMLInputElement; var field = document.getElementById("input" + i) as HTMLInputElement;
@ -79,17 +88,22 @@ class ClozePlugin implements JsPsychPlugin<Info> {
field.style.color = "black"; field.style.color = "black";
} }
} }
if (!trial.allow_blanks) {
if (answers[i] === "") {
answers_filled = false;
}
}
} }
if (!trial.check_answers || (trial.check_answers && answers_correct)) { if ((trial.check_answers && !answers_correct) || (!trial.allow_blanks && !answers_filled)) {
trial.mistake_fn();
} else {
var trial_data = { var trial_data = {
response: answers, response: answers,
}; };
display_element.innerHTML = ""; display_element.innerHTML = "";
this.jsPsych.finishTrial(trial_data); this.jsPsych.finishTrial(trial_data);
} else {
trial.mistake_fn();
} }
}; };