Version Change

docusaurus.config.js

@@ -31,13 +31,18 @@ const config = {
           showLastUpdateTime: true,
           versions: {
             current: {
-              label: '3.7.1-alpha',
-              path: '3.7.1',
+              label: 'next',
+              path: 'next',
               banner: 'unreleased',
             },
+            '3.7.1': {
+              label: '3.7.1',
+              path: '',
+              banner: 'none',
+            },
             '3.6.1': {
               label: '3.6.1 and earlier',
-              path: '',
+              path: '3.6.1',
               banner: 'none',
             },
           },

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

@@ -0,0 +1,28 @@
+---
+title: Example Group Studies
+slug: /Example-Group-Studies.html
+sidebar_position: 1
+---
+
+In group studies, the workers that are part of a group can communicate with each other. JATOS supports different kinds of groups. A group can e.g. have a fixed set of workers like this [Prisoner's Dilemma](/Example-Studies) where exactly two workers play with each other. On the other side of the spectrum is this [Snake game](/Example-Studies) with an on open, multi-worker approach.
+
+**How can you try-out a group-study if you're alone but want to simulate multiple workers?**
+
+JATOS allows [up to 10 study runs](Tips-and-Tricks.html#run-up-to-10-studies-in-the-same-browser-at-the-same-time) at the same time in the same browser (JATOS has no limit for different browsers). So you can just start the same (group) study multiple times in your browser and pretend you're multiple workers.
+
+As an example of this, let's go through the Snake Game group study in detail:
+
+1. Download and import the [Snake game](/Example-Studies)
+1. Open the [Study Links](Run-your-Study-with-Study-Links.html) page
+1. Now get a study link to start the first Snake game: Click on the Study Links button in line Personal Multiple (other study link types are fine too). In the opened pop-up window click on the top-left button <span class="glyphicon glyphicon-plus"></span><span class="glyphicon glyphicon-link"></span> to get a new link and then on <span class="glyphicon glyphicon-duplicate"></span> in the link's row to copy it to the clipboard.
+1. Open a new tab in your browser and paste the study link into the address field. Press 'Enter' and the study should start.
+1. Repeat the last step to start a second Snake game.
+1. Now, in both tabs: click through the introduction until you arrive in the waiting room. Click **Join** and then **Ready**.
+1. Voilà! You'll see two snakes moving around: each tab is running the Snake Game - but they are in the same group.
+1. Optional: Have a look at your [Group in the Study Links page](Run-your-Study-with-Study-Links.html#groups) add see who the member workers are.
+
+![Snake example](/img/example-studies/Screenshot_snakeGame.png)
+
+There's actually a lot going on behind the curtain of a group study. All members of a group are able to communicate in real-time with each other directly or broadcast messages to the whole group.
+
+Next step: [Write Your Own Group Studies](Write-Group-Studies-I-Setup.html).

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

@@ -0,0 +1,55 @@
+---
+title: Write Group Studies I - Setup
+slug: /Write-Group-Studies-I-Setup.html
+sidebar_position: 2
+---
+
+## Set up group studies
+
+First and common to all group setups is to check the Group study checkbox in the study properties. 
+
+![Group's property](/img/study-properties-group-study.png)
+
+If the Group property is checked, JATOS will assign workers into groups. We'll describe some group properties that you can use to tweak according to whether you want to keep control over worker assignment, or you give JATOS full control.
+
+
+### Group settings in each batch's properties
+
+You can have multiple batches in JATOS, each one with different group settings. There are three important bits of information for a group study:
+
+![Study Links screenshot](/img/batch_properties_groups.png)
+
+1. **Max total workers**: This isn't just a properties of group studies. It simply limits the total amount of workers who are allowed to run in this batch.
+1. **Max total members**:  This limits the number of members a single group can have. While there can be multiple groups in a batch, the _Max total members_ field applies to each separate group. 
+1. **Max active members**: This limits the number of active members a single group can have. An active member is in the group at this time - in opposite to a past member who already left the group. This number applies to each group separately. Example: In the Prisoner's Dilemma study, you would limit the active members to 2.
+
+By default, all properties have no upper limit.
+
+
+## Group assignment
+
+You can either tell JATOS to assign workers to different groups, or you can keep full control and do it yourself (or something in between). We'll use some example scenarios to explain how this assignment works.
+
+### Scenario 1: One group, assign workers manually
+
+If in a batch you set the _Max total worker_ to 2 and leave the other two Max parameters empty, JATOS has no other choice than to allow only 2 workers and sort them into the same group. If you then [create two Personal Single study links](Run-your-Study-with-Study-Links.html) (but other study link types are fine too) and send the links to your two participants, you can be sure that they will interact with each other. If you need more groups, just create a second batch with two other workers.
+
+![Prisoners example](/img/prisoners_example.png)
+
+The first two scenarios may apply to the [Prisoner's Dilemma Example Study](/Example-Studies).
+
+### Scenario 2: Several groups, let JATOS assign workers
+
+Say you want to have 3 groups with 2 workers each. You want to leave it to JATOS which workers are paired together. Then, set _Max total workers_ to 6 and both _Max active members_ and _Max total members_ to 2 (remember that these numbers apply to each group separately). Then [create 6 Personal Single study links](Run-your-Study-with-Study-Links.html) (but other study link types are fine too) and send them to your 6 participants.
+
+### Scenario 3: One open world
+
+This scenario is basically the opposite of the first one. By limiting neither the _Max total worker_ nor the _Max total members_, nor the _Max active members_ JATOS will sort all workers into one single group that is potentially of unlimited size. Now --to keep it completely open-- just [create one study link type General Single](Run-your-Study-with-Study-Links.html) (but other study link types are fine too) and publish it (e.g. via a mailing list or on a website).
+
+![Snake example](/img/snake_example.png)
+
+The third and fourth scenario may apply to the [Snake Example Study](/Example-Studies).
+
+### Scenario 4: Multiple open worlds with limited active members
+
+Say you want to have groups with up to 3 members, interacting _at the same time_. But you don't want to actually limit the total number of members per group: you want to allow new workers to join a group if one of its members left. This way each group can have a flow of workers joining and leaving - the only constraint is the maximum members per group at any given time. You also want to let JATOS set the number of groups depending on the available workers. To set up this just use one batch, set the _Max active members_ to 3, and leave _Max total worker_ and _Max total members_ unlimited.  

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

@@ -0,0 +1,66 @@
+---
+title: Write Group Studies II - JavaScript and Messaging
+slug: /Write-Group-Studies-II-JavaScript-and-Messaging.html
+sidebar_position: 3
+---
+
+## Writing JavaScripts for group studies
+
+Group studies differ from single-worker studies simply in that the JavaScript needs to handle groups and communications between members. The _jatos.js_ library provides some useful functions for this.
+
+If you like to dive right into _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, interacting workers must all join the same group. 
+**A worker will remain in a group until _jatos.js_ is explicitly told to leave the group (or the study run is finished). 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. 
+
+So here's how a typical JATOS group study run would look like. This study has three components.
+
+Component 1
+
+  * `jatos.joinGroup` -> joins group and opens group channel
+  * `jatos.nextComponent` -> closes group channel and jumps to next component
+
+Component 2
+
+  * `jatos.joinGroup` -> opens group channel in the **same group**
+  * `jatos.nextComponent` -> closes group channel and jumps to next component
+
+Component 3
+
+  * `jatos.joinGroup` -> opens group channel **same group**
+  * `jatos.endStudy` -> closes group channel, leaves group, ends component, and ends study
+
+Notice that by calling [`jatos.joinGroup`](jatos.js-Reference.html#jatosjoingroup) in the second and third component JATOS does not let workers join a new group but just  opens a group channel in the already joined group. To make a worker leave a group,  use the function [`jatos.leaveGroup`](jatos.js-Reference.html#jatosleavegroup).
+
+Every know and then you probably would like to know who the members of your groups are. This and other stats you can get by clicking on 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 a different one, use [`jatos.reassignGroup`](jatos.js-Reference.html#jatosreassigngroup). This function will make a worker leave their group and join a different one. JATOS can only reassign to a different group if there is another group available. If there is no other group JATOS will not start a new one but put the worker into the same old group again.  
+
+### Fixing a group
+
+Sometimes you want to stay with the group like it is in this moment and don't let new members join - although it would be allowed according to the group properties. For example in the [Prisoner's Example study](/Example-Studies) after the group is assembled in the waiting room component it is necessary to keep the two members as it is. Even if one of the members leaves in the middle of the game, JATOS shouldn't just assign a new member. To do this you can call _jatos.js_' function [`jatos.setGroupFixed`](jatos.js-Reference.html#jatossetgroupfixed). Alternatively you can fix a group in JATOS' GUI, in the 
+[Groups table in the Study Links page](Run-your-Study-with-Study-Links.html#groups).
+
+
+## Communication between group members
+
+JATOS provides three ways for communicating within the group: direct messaging, broadcast messaging and with the Group Session.
+
+### Direct messaging
+Members can send direct messages to a single other member of the same group with the [`jatos.sendGroupMsgTo`](jatos.js-Reference.html#jatossendgroupmsgto) function. Like broadcast messaging this way of group communication is fast but can be unreliable in case of an unstable network connection. We use direct messaging in the [Snake example](/Example-Studies) to send the coordinates of the snakes on every step. Here, speed is more critical than reliability in the messages, because a few dropped frames will probably go unnoticed. 
+
+### Broadcast messaging
+Members can send messages to all other members of the same group with the [`jatos.sendGroupMsg`](jatos.js-Reference.html#jatossendgroupmsg) function. Like direct messaging this way of group communication is fast but can be unreliable in case of an unstable network connection.
+
+### Group session
+The Group Session is one of the [three types of session that JATOS provides](Session-Data-Three-Types.html). Members can access the Group Session data with the [Group Session functions](jatos.js-Reference.html#functions-to-access-the-group-session). The Group Session data are stored in JATOS' database **only while the group is active. It is deleted when the group is finished.** Communication via Group Session is slower, but more reliable than group messaging. If one member has an unstable internet connection or does a page reload, the Group Session will be automatically restored after the member reopens the group channel. Workers communicate via the Group Session data in the [Prisoner's Example study](/Example-Studies), because here one dropped message would lead to important information loss.

versioned_docs/version-3.7.1/Group_studies/_category_.json

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

versioned_docs/version-3.7.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 of a JATOS installation. You can see the **logs**, **system info**, or go to the **test page** to check if JATOS runs correctly. It is also the place 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/Screenshot_Administration_371.png)
+
+On the menu you will find links to two additional administration pages: 
+
+### User Manager
+
+Manage users, passwords, and rights from here. Find more details on [its documentation page](/User-Manager.html)
+
+
+### Study Administration
+
+By clicking the _Studies_ button you'll get to an overview about all studies that are on the JATOS instance. You'll also see, for each study: whom it belongs to (the study members), how much disk space it takes, and when it was active last.
+
+**For larger JATOS installation it can take up to a couple minutes to gather all data for this page**
+
+![Studies Administration](/img/Screenshot_Study_Admin_371.png)
+
+The information is displayed in a table with the columns:
+
+* **Active** - In cases where e.g. a study uses to many server resources, an admin can **deactivate** (or activate again) it by clicking the checkbox in the 'Active' column. A deactivated study cannot be started by participants (workers) anymore, but an already started study run can be continued. That means, an admin will not interrupt a participant if they already started doing a study, but no new participants will be able to start it. The study members can still see and edit the study, as well as export its result data. 
+* **Study Assets Size** - The disk size of all asset files associated to 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 that are stored in the database. In brackets is the average size per result count.
+* **Result File Size** - The size of all result files that are stored in the server's file system. In brackets is the average size per result count.
+* **Last Started** - When was this study last started by a participant.

versioned_docs/version-3.7.1/Manage_your_JATOS/Troubleshooting.md

@@ -0,0 +1,44 @@
+---
+title: Troubleshooting
+slug: /Troubleshooting.html
+sidebar_position: 4
+---
+
+### JATOS test page
+
+JATOS comes with build in tests (e.g. WebSockets connections and database connection), but they are only accessible for users with admin rights: go to _Administration_ ⇒ _Tests_ and check that all tests are 'OK'.
+
+
+### Downloading a study / exporting a study fails (e.g. in Safari browsers)
+
+As a default, Safari (and some other browsers) automatically unzips every archive file after downloading it. When you export a study, JATOS zips your study together (study properties, all components, and all files like HTML, JavaScripts, images) and delivers it to your browser, who should save it in your local computer. Safari's default unzipping interferes with this. Follow [these instructions](https://discussions.apple.com/thread/1958374?start=0&tstart=0) to prevent Safari's automatic unzip.
+
+
+### Read log files in the browser
+
+In a perfect world, JATOS always works smoothly and, when it doesn't, it describes the problem in an error message. Unfortunately we aren't in a perfect world: every now and then something will go wrong and you might not get any clear error messages, or no message at all. In these (rare) cases, you can look into JATOS' log files (not to be confused with the [study log](Study-Log.html)) to try to find what the problem might be. You can see and download all log files in the _Administration_ page => _Logs_ (for security reasons, you must be logged in as a user with admin rights). 
+
+* _application.log_ - all JATOS logging
+* _loader.log_ - logging during startup with loader
+* _update.log_ - logging during updates
+
+Alternatively you can read the log files directly on the server. You'll find your logs in `jatos_directory/logs/`.
+
+
+### A file (library, image, ...) included in the HTML fails to load?
+
+There is a common mistake Windows users make that might prevent files from loading: Any URL or file path in a HTML or JS file should only use '/' as a file path separator - even on Windows systems. So it should always be e.g. `<script src="subfolder/myscript.js"></script>` and **not** `<script src="subfolder\myscript.js"></script>`.
+
+
+### Database is corrupted?
+
+If you get an error that reads something like: `Error in custom provider, Configuration error: Configuration error[Cannot connect to database [default]]`, your database might be corrupted. By default JATOS comes with an H2 database and the H2 database doesn't handle [copying its files while running](http://stackoverflow.com/questions/2036117/how-to-back-up-the-embedded-h2-database-engine-while-it-is-running) too well. 
+
+There are two reasons why this might be the case: you moved your JATOS folder while it was running or you installed JATOS in a synced folder. To prevent this, be sure to always be careful with the following:
+
+1. **Don't copy or move while JATOS is running** - Always **stop JATOS** (type `./loader.sh stop` in your Linux / Mac OS terminal or close the window on Windows) before moving it.  
+1. **Don't sync while JATOS is running** - As we mentioned in the [Installation page](Installation.html), you can run JATOS from pretty much anywhere **except** from a folder that syncs across devices, like Dropbox or Google Drive. Doing so might lead to database corruption, because while the files might be synced between computers, the running processes aren't. This will lead to havoc and destruction and, in extreme cases, to the implosion of the known Universe. You can find in our [blog post](http://blog.jatos.org/Database_Recovery/) a description of an attempt to recover a corrupted database. Didn't work.
+
+**Of course, this brings us to an important point: back up your result data (i.e., simply download and save your text files) regularly if you're running a study!**
+
+