plugin-capture-url-params

packages/plugin-capture-url-params/CITATION.cff

@@ -0,0 +1,41 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+- family-names: "Courtney B. Hilton"  # Replace with last name
+  given-names: "Courtney B. Hilton"   # Replace with first name
+  name-particle: "Courtney B. Hilton" # Replace with name particle(s)
+  orcid: "https://orcid.org/0000-0000-0000-0000"  # Replace with ORCID
+# More  authors can be listed here in the same format as above
+contact:  # Contact person for this extension
+- family-names: "Courtney B. Hilton"
+  given-names: "Courtney B. Hilton"
+  email: "{email}"          # Replace with contact person's email
+  orcid: "https://orcid.org/0000-0000-0000-0000"  # Replace with contact person's ORCID
+title: "jsPsychPluginCaptureUrlParams"
+version: 0.0.0
+doi: 10.5281/zenodo.1234    # Replace with DOI
+date-released: 2000-01-01
+url: "{softwareUrl}"        # Replace with URL to this extension
+
+# If you wish to cite a paper on this extension instead, you can use the following template:
+preferred-citation:
+  authors:
+  - family-names: "Courtney B. Hilton"
+    given-names: "Courtney B. Hilton"
+    name-particle: "Courtney B. Hilton"
+    orcid: "https://orcid.org/0000-0000-0000-0000"
+  # More authors can be listed here in the same format as above
+  date-published: 2023-05-11
+  doi: 10.21105/joss.12345 
+  issn: 1234-5678
+  issue: 01
+  journal: Journal for Open Source Software
+  publisher:
+    name: Open Journals
+  start: 0001
+  title: "{title}"
+  type: article               # Other options include: book, pamphlet, conference-paper...
+  url: "{linkToPublicationInJournal}"
+  volume: 1
+
+# More information on the preffered-citation CFF format can be found at https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files#citing-something-other-than-software

packages/plugin-capture-url-params/README.md

@@ -0,0 +1,65 @@
+# plugin-capture-url-params
+
+## Overview
+
+The `plugin-capture-url-params` plugin saves data embedded in the URL parameters into the jsPsych data object. This is useful when working with external participant platforms like Prolific, which use URL parameters to pass unique identifiers such as `PROLIFIC_PID`, `STUDY_ID`, or `SESSION_ID`.
+
+By default, the plugin captures all available URL parameters. You can also specify a subset of required parameters using the `url_params` option. If any of these required parameters are missing, the plugin can optionally show an error message to participants and either allow the experiment to continue (`soft_fail = true`) or stop the experiment (`soft_fail = false`).
+
+## Loading (Note: these CDN resources don't currently exist... but maybe will eventually?)
+
+Using the CDN-hosted JavaScript file:
+
+```js
+<script src="https://unpkg.com/@jspsych/plugin-capture-url-params@VERSION_HERE"></script>
+```
+
+Using the JavaScript file downloaded from a GitHub release dist archive:
+
+```js
+<script src="jspsych/plugin-capture-url-params.js"></script>
+```
+
+Using NPM:
+
+```
+npm install @jspsych/plugin-capture-url-params
+```
+
+```js
+import jsPsychPluginCaptureUrlParams from "@jspsych/plugin-capture-url-params";
+```
+
+## Compatibility
+
+`plugin-capture-url-params` requires jsPsych v8.0.0 or later.
+
+## Parameters
+
+| Name            | Type             | Default                                    | Description                                                                                                                             |
+| --------------- | ---------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `url_params`    | array of strings | `[]`                                       | A list of specific URL parameter keys to extract (e.g., `["PROLIFIC_PID", "STUDY_ID"]`). If empty, all URL parameters will be captured. |
+| `show_error`    | boolean          | `false`                                    | Whether to display an error message to the participant if any of the specified parameters are missing.                                  |
+| `error_message` | string           | `"URL parameters could not be retrieved."` | The message shown to participants if required parameters are missing.                                                                   |
+| `soft_fail`     | boolean          | `true`                                     | If set to `false`, the experiment will abort when required parameters are missing. If `true`, the experiment will continue.             |
+
+## Data
+
+The plugin saves the captured parameters as an object in the `response` field of the trial data.
+
+```json
+{
+  "response": {
+    "PROLIFIC_PID": "abc123",
+    "STUDY_ID": "def456"
+  }
+}
+```
+
+## Documentation
+
+See [documentation](https://github.com/themusiclab/pose/tree/main/test/plugin-capture-url-params/README.md)
+
+## Author / Citation
+
+[Courtney B. Hilton](https://github.com/courtney-bryce-hilton)

packages/plugin-capture-url-params/docs/plugin-capture-url-params.md

@@ -0,0 +1,61 @@
+# plugin-capture-url-params
+
+## Overview
+
+The `plugin-capture-url-params` plugin saves data embedded in the URL parameters into the jsPsych data object. This is useful when working with external participant platforms like Prolific, which use URL parameters to pass unique identifiers such as `PROLIFIC_PID`, `STUDY_ID`, or `SESSION_ID`.
+
+By default, the plugin captures all available URL parameters. You can also specify a subset of required parameters using the `url_params` option. If any of these required parameters are missing, the plugin can optionally show an error message to participants and either allow the experiment to continue (`soft_fail = true`) or stop the experiment (`soft_fail = false`).
+
+## Loading (Note: these CDN resources don't currently exist... but maybe will eventually?)
+
+Using the CDN-hosted JavaScript file:
+
+```js
+<script src="https://unpkg.com/@jspsych/plugin-capture-url-params@VERSION_HERE"></script>
+```
+
+Using the JavaScript file downloaded from a GitHub release dist archive:
+
+```js
+<script src="jspsych/plugin-capture-url-params.js"></script>
+```
+
+Using NPM:
+
+```
+npm install @jspsych/plugin-capture-url-params
+```
+
+```js
+import jsPsychPluginCaptureUrlParams from "@jspsych/plugin-capture-url-params";
+```
+
+## Parameters
+
+| Name            | Type             | Default                                    | Description                                                                                                                             |
+| --------------- | ---------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `url_params`    | array of strings | `[]`                                       | A list of specific URL parameter keys to extract (e.g., `["PROLIFIC_PID", "STUDY_ID"]`). If empty, all URL parameters will be captured. |
+| `show_error`    | boolean          | `false`                                    | Whether to display an error message to the participant if any of the specified parameters are missing.                                  |
+| `error_message` | string           | `"URL parameters could not be retrieved."` | The message shown to participants if required parameters are missing.                                                                   |
+| `soft_fail`     | boolean          | `true`                                     | If set to `false`, the experiment will abort when required parameters are missing. If `true`, the experiment will continue.             |
+
+## Data
+
+The plugin saves the captured parameters as an object in the `response` field of the trial data.
+
+```json
+{
+  "response": {
+    "PROLIFIC_PID": "abc123",
+    "STUDY_ID": "def456"
+  }
+}
+```
+
+## Documentation
+
+See [documentation](https://github.com/themusiclab/pose/tree/main/test/plugin-capture-url-params/README.md)
+
+## Author / Citation
+
+[Courtney B. Hilton](https://github.com/courtney-bryce-hilton)

packages/plugin-capture-url-params/examples/index.html

@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>jsPsychPluginCaptureUrlParams Example</title>
+    <script src="https://unpkg.com/jspsych@8"></script>
+    <!-- Load the published plugin package here, e.g.
+    <script src="https://unpkg.com/plugin-capture-url-params"></script> -->
+    <script src="../dist/index.browser.js"></script>
+    <script src="https://unpkg.com/@jspsych/[email protected]"></script>
+    <link rel="stylesheet" href="https://unpkg.com/jspsych@8/css/jspsych.css" />
+  </head>
+
+  <body></body>
+  <script>
+    const jsPsych = initJsPsych({
+      on_finish: () => {
+        jsPsych.data.displayData();
+      },
+    });
+
+    const placeholder = {
+      type: jsPsychHtmlButtonResponse,
+      stimulus:
+        "<p>Type Some URL parameters into your browser window before continuing.</p>" +
+        "<p>For example add to the end of the URL '?key1=value1&key2=value2'</p>",
+      choices: ["Next"],
+    };
+
+    const trial = {
+      type: jsPsychPluginCaptureUrlParams,
+    };
+
+    jsPsych.run([placeholder, trial]);
+  </script>
+</html>

packages/plugin-capture-url-params/jest.config.cjs

@@ -0,0 +1 @@
+module.exports = require("@jspsych/config/jest").makePackageConfig(__dirname);