Bump to 3.10.1

Author: kristian-lange

docusaurus.config.js

@@ -28,16 +28,21 @@ const config = {
           routeBasePath: '/',
           showLastUpdateAuthor: true,
           showLastUpdateTime: true,
-          lastVersion: '3.9.1',
+          lastVersion: '3.10.1',
           versions: {
             current: {
               label: 'next',
               path: 'next',
               banner: 'unreleased',
             },
+            '3.10.1': {
+              label: '3.10.x',
+              path: '',
+              banner: 'none',
+            },
             '3.9.1': {
               label: '3.9.x',
-              path: '',
+              path: '3.9.x',
               banner: 'none',
             },
             '3.8.1': {

versioned_docs/version-3.10.1/Group_studies/Example-Group-Studies.md

@@ -0,0 +1,33 @@
+---
+title: Example Group Studies
+slug: /Example-Group-Studies.html
+sidebar_position: 1
+---
+
+In group studies, workers who are part of the same group can communicate with each other. JATOS supports various types of groups. For example, a group can have a fixed set of workers, as seen in the [Prisoner's Dilemma](Example-Studies) where exactly two workers play together. On the other end of the spectrum is the [Snake game](Example-Studies), which utilizes an open, multi-worker approach.
+
+### How to Simulate Multiple Workers in a Group Study
+
+**How can you try out a group study if you're alone but want to simulate multiple workers?**
+
+JATOS allows for [multiple study runs](Tips-and-Tricks.html#run-studies-simultaneously-in-the-same-browser) simultaneously within the same browser (there is no limit for different browsers). This means you can easily simulate multiple workers by simply starting the same (group) study multiple times in your browser.
+
+As an example, let's walk through the Snake Game group study in detail:
+
+1.  Download and import the [Snake game](Example-Studies).
+2.  Open the [Study Links](Run-your-Study-with-Study-Links.html) page for the Snake Game study.
+3.  **Get a study link to start the first Snake game:**
+      * Click on the **Study Links** button in the "Personal Multiple" row (other study link types can also work).
+      * In the pop-up window, click the top-left button '<span class="glyphicon glyphicon-plus"></span><span class="glyphicon glyphicon-link"></span>' to generate a new link.
+      * Then, click the <FAIcon icon="fa-regular fa-clipboard" /> button in the link's row to copy it to your clipboard.
+4.  Open a new tab in your browser and paste the study link into the address bar. Press 'Enter' to start the study.
+5.  Repeat the last step to start a second Snake game in another new tab.
+6.  Now, in both tabs, navigate through the introduction until you reach the waiting room. Click **Join** and then **Ready**.
+7.  Voilà\! You'll see two snakes moving around. Each tab is running the Snake Game, and both are communicating within the same group.
+8.  **Optional:** Take a look at your [Group in the Study Links page](Run-your-Study-with-Study-Links.html#groups) to see the member workers.
+
+![Snake example](/img/example-studies/Screenshot_snakeGame.png)
+
+There's a lot happening behind the scenes of a group study. All members of a group can communicate in real-time with each other directly or broadcast messages to the entire group.
+
+Next step: [Write Your Own Group Studies](Write-Group-Studies-I-Setup.html).

versioned_docs/version-3.10.1/Group_studies/Write-Group-Studies-I-Setup.md

@@ -0,0 +1,53 @@
+---
+title: Write Group Studies I - Setup
+slug: /Write-Group-Studies-I-Setup.html
+sidebar_position: 2
+---
+
+## Set Up Group Studies
+
+To enable group studies, first check the **Group study** switch in your study properties.
+
+![Group's property](/img/v39x/study-properties-group-study.png)
+
+When the Group property is enabled, JATOS will assign workers into groups. You can adjust several group properties to control how workers are assigned—either keeping full control yourself or letting JATOS handle it automatically.
+
+### Group Settings in Each Batch's Properties
+
+You can have multiple batches in JATOS, each with its own group settings. There are three key properties for group studies:
+
+![Study Links screenshot](/img/v39x/batch_properties_groups.png)
+
+1. **Max total workers**: Limits the total number of workers allowed to participate in this batch. (This is not exclusive to group studies.)
+2. **Max total members**: Limits the number of members in a single group. Multiple groups can exist in a batch, and this value applies to each group individually.
+3. **Max active members**: Limits the number of active members in a group at any one time. An active member is currently in the group, as opposed to a past member who has already left. For example, in the Prisoner's Dilemma study, you would set this to 2.
+
+By default, all these properties are unlimited.
+
+## Group Assignment
+
+You can let JATOS assign workers to groups automatically, assign them yourself, or use a combination of both. The following scenarios illustrate how group assignment works:
+
+### Scenario 1: One Group, Manual Assignment
+
+If you set _Max total workers_ to 2 and leave the other two fields empty, only 2 workers can join, and both will be placed in the same group. If you [add two Personal Single study links](Run-your-Study-with-Study-Links.html) (other link types also work) and send them to your two participants, you can be sure they will interact with each other. To create more groups, simply add another batch with two more workers.
+
+![Prisoners example](/img/prisoners_example.png)
+
+The first two scenarios are relevant for the [Prisoner's Dilemma Example Study](/Example-Studies).
+
+### Scenario 2: Several Groups, Automatic Assignment
+
+Suppose you want 3 groups with 2 workers each and want JATOS to pair workers automatically. Set _Max total workers_ to 6, and both _Max total members_ and _Max active members_ to 2 (these limits apply per group). Then [add 6 Personal Single study links](Run-your-Study-with-Study-Links.html) (other link types also work) and distribute them to your 6 participants.
+
+### Scenario 3: One Open World
+
+This is the opposite of Scenario 1. If you leave _Max total workers_, _Max total members_, and _Max active members_ unlimited, JATOS will place all workers into a single, potentially unlimited group. To keep it fully open, [add a General Single study link](Run-your-Study-with-Study-Links.html) (other link types also work) and share it (e.g., via a mailing list or website).
+
+![Snake example](/img/snake_example.png)
+
+Scenarios 3 and 4 are relevant for the [Snake Example Study](/Example-Studies).
+
+### Scenario 4: Multiple Open Worlds with Limited Active Members
+
+Suppose you want groups with up to 3 members interacting at the same time, but you don’t want to limit the total number of members per group. New workers can join a group if someone leaves, allowing a flow of participants. The only constraint is the maximum number of active members per group at any time. JATOS will determine the number of groups based on available workers. To set this up, use one batch, set _Max active members_ to 3, and leave _Max total workers_ and _Max total members_ unlimited.

versioned_docs/version-3.10.1/Group_studies/Write-Group-Studies-II-JavaScript-and-Messaging.md

@@ -0,0 +1,70 @@
+---
+title: Write Group Studies II - JavaScript and Messaging
+slug: /Write-Group-Studies-II-JavaScript-and-Messaging.html
+sidebar_position: 3
+---
+
+## Writing JavaScript for Group Studies
+
+Group studies differ from single-worker studies in that the JavaScript must handle groups and communication between members. The _jatos.js_ library provides several useful functions for this purpose.
+
+If you want to dive right into the _jatos.js_ reference:
+
+* [_jatos.js_ functions for group studies](jatos.js-Reference.html#group-functions)
+* [_jatos.js_ group variables](jatos.js-Reference.html#group-variables)
+* [_jatos.js_ Group Session functions](jatos.js-Reference.html#functions-to-access-the-group-session)
+
+---
+
+### Joining a Group and Opening Group Channels
+
+Workers can only communicate with members of their own group, so all interacting workers must join the same group.  
+**A worker remains in a group until _jatos.js_ is explicitly told to leave (or the study run finishes). This means that if a worker moves between components or reloads a page, they will still remain in the same group.** This feature makes groups much more robust.
+
+A typical JATOS group study might have three components:
+
+**Component 1**
+- `jatos.joinGroup` → joins group and opens group channel
+- `jatos.nextComponent` → closes group channel and moves to the next component
+
+**Component 2**
+- `jatos.joinGroup` → opens group channel in the **same group**
+- `jatos.nextComponent` → closes group channel and moves to the next component
+
+**Component 3**
+- `jatos.joinGroup` → opens group channel in the **same group**
+- `jatos.endStudy` → closes group channel, leaves group, ends component, and ends study
+
+Notice that calling [`jatos.joinGroup`](jatos.js-Reference.html#jatosjoingroup) in the second and third components does not let workers join a new group, but simply opens a group channel in the already joined group. To make a worker leave a group, use [`jatos.leaveGroup`](jatos.js-Reference.html#jatosleavegroup).
+
+If you want to see who the members of your groups are, or get other stats, click your batch's [Groups button in the Study Links page](Run-your-Study-with-Study-Links.html#groups).
+
+---
+
+### Reassigning to a Different Group
+
+To move a worker from one group to another, use [`jatos.reassignGroup`](jatos.js-Reference.html#jatosreassigngroup). This function will make a worker leave their current group and join a different one. JATOS can only reassign to another group if one is available; if not, the worker will remain in their original group.
+
+---
+
+### Fixing a Group
+
+Sometimes you want to "lock" a group so no new members can join, even if the group properties would allow it. For example, in the [Prisoner's Dilemma Example Study](/Example-Studies), after the group is assembled in the waiting room, you want to keep the two members fixed—even if one leaves during the game, JATOS should not assign a new member. To do this, call [`jatos.setGroupFixed`](jatos.js-Reference.html#jatossetgroupfixed). Alternatively, you can fix a group in the JATOS GUI, in the [Groups table on the Study Links page](Run-your-Study-with-Study-Links.html#groups).
+
+---
+
+## Communication Between Group Members
+
+JATOS provides three ways for group members to communicate: direct messaging, broadcast messaging, and the Group Session.
+
+### Direct Messaging
+
+Members can send direct messages to a single other member of the same group using [`jatos.sendGroupMsgTo`](jatos.js-Reference.html#jatossendgroupmsgto). Like broadcast messaging, this method is fast but can be unreliable if the network connection is unstable. For example, in the [Snake Example](/Example-Studies), direct messaging is used to send the coordinates of the snakes at every step. Here, speed is more important than reliability, since a few dropped frames will likely go unnoticed.
+
+### Broadcast Messaging
+
+Members can send messages to all other members of the same group using [`jatos.sendGroupMsg`](jatos.js-Reference.html#jatossendgroupmsg). Like direct messaging, this method is fast but can be unreliable on unstable networks.
+
+### Group Session
+
+The Group Session is one of the [three types of session that JATOS provides](Session-Data-Three-Types.html). Members can access Group Session data with the [Group Session functions](jatos.js-Reference.html#functions-to-access-the-group-session). Group Session data is stored in JATOS' database **only while the group is active** and is deleted when the group finishes. Communication via Group Session is slower but more reliable than group messaging. If a member has an unstable internet connection or reloads the page, the Group Session will be automatically restored when the group channel is reopened. In the [Prisoner's Dilemma Example Study](/Example-Studies), workers communicate via Group Session data, since a dropped message (direct or broadcast messaging) could result in important information loss.

versioned_docs/version-3.10.1/Group_studies/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Group Studies",
+  "position": 5
+}

versioned_docs/version-3.10.1/Manage_your_JATOS/Administration.md

@@ -0,0 +1,33 @@
+---
+title: Administration
+slug: /Administration.html
+sidebar_position: 1
+---
+
+On the Administration page, [users with admin rights](/User-Manager.html) can get an overview of the studies and users in a JATOS installation. You can view the **logs**, **system info**, or go to the **test page** to check if JATOS is running correctly. This is also where **update notifications** appear when a new JATOS version is available, and where [admins can trigger an update](/Update-JATOS.html#automatic-updates).
+
+![Administration screenshot](/img/v39x/administration.png)
+
+### User Manager
+
+Manage users, passwords, and rights from here. Find more details on [the documentation page](/User-Manager.html).
+
+### Study Manager
+
+By clicking the **Study Manager** button, you'll see an overview of all studies on the JATOS instance. For each study, you can see who it belongs to (the study members), how much disk space it uses, and when it was last active.
+
+**In larger JATOS installations, it can take up to a couple of minutes to gather all data for this page.**
+
+![Study Manager](/img/v39x/study_manager.png)
+
+The information is displayed in a table with the following columns:
+
+* **Active** – If a study uses too many server resources, an admin can **deactivate** (or activate) it by clicking the switch in the 'Active' column. A deactivated study cannot be started by new participants (workers), but an already started study run can be continued. This means an admin will not interrupt a participant who has already started a study, but no new participants will be able to start it. Study members can still view and edit the study, as well as export its result data.
+* **ID** – The study ID.
+* **Title** – The study title.
+* **Members** – The users who are members of this study.
+* **Study assets size** – The disk size of all asset files associated with this study (HTML, JS, CSS, images, videos, etc.).
+* **Result count** – The number of study results collected so far on this JATOS instance.
+* **Result data size** – The size of all result data stored in the database. The average size per result is shown in brackets.
+* **Result file size** – The size of all result files stored in the server's file system. The average size per result is shown in brackets.
+* **Last started** – The last time this study was started by a participant.

versioned_docs/version-3.10.1/Manage_your_JATOS/Customize-JATOS-Home-Page.md

@@ -0,0 +1,54 @@
+---
+title: Customize JATOS' Home Page
+slug: /Customize-JATOS-Home-Page.html
+sidebar_position: 5
+---
+
+## Link to Terms of Use
+
+You can configure JATOS to show a link to your 'Terms of Use' in an info box on the home page.
+
+In your JATOS installation folder, edit `conf/jatos.conf` and add the URL under `jatos.termsOfUseUrl`. If left empty, the info box is not shown.
+
+## Welcome Block
+
+You can customize JATOS' home page to, for example:
+* show your university's logo,
+* add some introduction text, or
+* announce an upcoming event.
+
+This is done by configuring JATOS with a URL that points to some static HTML describing your individual welcome block. This HTML block will then be loaded and displayed on every home page.
+
+Have a look at this [example welcome block](https://github.com/JATOS/customized-home-page-template/blob/main/foobar-university-welcome.html).
+
+![template customized home page](/img/v39x/screenshot-branding.png)
+
+You can update your welcome block at any time to add new information (e.g., announcement of JATOS maintenance work). However, since the HTML is cached, it can take **up to an hour to be visible to your users**. If you want to see it right away for testing, you can disable caching in your browser.
+
+This welcome block can be fetched from **any HTTP server** that is able to serve HTML. One way is to do it via GitHub.
+
+### With GitHub
+
+1. Go to [https://github.com/JATOS/customized-home-page-template](https://github.com/JATOS/customized-home-page-template)
+2. Click the 'Use this template' button to create a copy of this repository.
+3. Change the content of `foobar-university-welcome.html` to your needs.
+4. Add necessary files (e.g., logo images) to your repository.
+5. Configure JATOS: In your JATOS installation folder, edit `conf/jatos.conf` and add `jatos.brandingUrl`:
+
+   1. Easy but with rate limit (from GitHub):
+
+      ```
+      jatos.brandingUrl = "https://raw.githubusercontent.com/my-user/my-repo/main/foobar-university-welcome.html"
+      ```
+
+      Remember to change `my-user`, `my-repo`, and `foobar-university-welcome.html`.
+
+   2. Better: use [GitHub Pages](https://docs.github.com/en/github/working-with-github-pages/creating-a-github-pages-site):
+
+      ```
+      jatos.brandingUrl = "https://my-user.github.io/my-repo/foobar-university-welcome.html"
+      ```
+
+      Remember to change `my-user`, `my-repo`, and `foobar-university-welcome.html`.
+
+6. Restart JATOS.