ServerManager

core ServerManager

This manager handles all communications between the experiment running in the participant's browser and the pavlovia.org server, in an asynchronous manner.

It is responsible for reading the configuration file of an experiment, for opening and closing a session, for listing and downloading resources, and for uploading results, logs, and audio recordings.

Constructor

new ServerManager(options)

Source:
Parameters:
Name Type Description
options Object
Properties
Name Type Attributes Default Description
psychoJS module:core.PsychoJS

the PsychoJS instance
autoLog boolean <optional>
 false

whether or not to log

Extends

  • PsychObject

Members

(static, readonly) Event :Symbol

Source:
Properties:
Name Type Description
RESOURCE Symbol

Event type: resource event
DOWNLOADING_RESOURCES Symbol

Event: resources have started to download
DOWNLOADING_RESOURCE Symbol

Event: a specific resource download has started
RESOURCE_DOWNLOADED Symbol

Event: a specific resource has been downloaded
DOWNLOAD_COMPLETED Symbol

Event: resources have all downloaded
STATUS Symbol

Event type: status event

Server event

A server event is emitted by the manager to inform its listeners of either a change of status, or of a resource related event (e.g. download started, download is completed).

Type:
  • Symbol

(static, readonly) ResourceStatus :Symbol

Source:
Properties:
Name Type Description
ERROR Symbol

There was an error during downloading, or the resource is in an unknown state.
REGISTERED Symbol

The resource has been registered.
DOWNLOADING Symbol

The resource is currently downloading.
DOWNLOADED Symbol

The resource has been downloaded.

Resource status

Type:
  • Symbol

(static, readonly) Status :Symbol

Source:
Properties:
Name Type Description
READY Symbol

The manager is ready.
BUSY Symbol

The manager is busy, e.g. it is downloaded resources.
ERROR Symbol

The manager has encountered an error, e.g. it was unable to download a resource.

Server status

Type:
  • Symbol

(readonly) ALL_RESOURCES :Symbol

Source:

Used to indicate to the ServerManager that all resources must be registered (and subsequently downloaded)

Type:
  • Symbol

Methods

(async, protected) _downloadResources(resources)

Source:

Download the specified resources.

Note: we use the preloadjs library.

Parameters:
Name Type Description
resources Set

a set of names of previously registered resources

(protected) _listResources()

Source:

List the resources available to the experiment.

(protected) _queryServerAPI(method, path, data, contentTypeopt)

Source:

Query the pavlovia server API.

Parameters:
Name Type Attributes Default Description
method

the HTTP method, i.e. GET, PUT, POST, or DELETE
path

the resource path, without the server address
data

the data to be sent
contentType string <optional>
 "JSON"

the content type, either JSON or FORM

(protected) _setupPreloadQueue()

Source:

Setup the preload.js queue, and the associated callbacks.

(async) closeSession(isCompletedopt, syncopt) → {Promise.<ServerManager.CloseSessionPromise>|void}

Source:

Close the session for this experiment on the remote PsychoJS manager.

Parameters:
Name Type Attributes Default Description
isCompleted boolean <optional>
 false

whether or not the experiment was completed
sync boolean <optional>
 false

whether or not to communicate with the server in a synchronous manner
Returns:

the response

Type
Promise.<ServerManager.CloseSessionPromise> | void

getConfiguration(configURL) → {Promise.<ServerManager.GetConfigurationPromise>}

Source:

Read the configuration file for the experiment.

Parameters:
Name Type Description
configURL string

the URL of the configuration file
Returns:

the response

Type
Promise.<ServerManager.GetConfigurationPromise>

getResource(name, errorIfNotDownloadedopt) → {Object}

Source:

Get the value of a resource.

Parameters:
Name Type Attributes Default Description
name string

name of the requested resource
errorIfNotDownloaded boolean <optional>
 false

whether or not to throw an exception if the resource status is not DOWNLOADED
Throws:

exception if no resource with that name has previously been registered

Type
Object.<string, *>
Returns:

value of the resource, or undefined if the resource has been registered but not downloaded yet.

Type
Object

getResourceStatus(names) → {module:core.ServerManager.ResourceStatus}

Source:

Get the status of a single resource or the reduced status of an array of resources.

If an array of resources is given, getResourceStatus returns a single, reduced status that is the status furthest away from DOWNLOADED, with the status ordered as follow: ERROR (furthest from DOWNLOADED), REGISTERED, DOWNLOADING, and DOWNLOADED

For example, given three resources:

  • if at least one of the resource status is ERROR, the reduced status is ERROR
  • if at least one of the resource status is DOWNLOADING, the reduced status is DOWNLOADING
  • if the status of all three resources is REGISTERED, the reduced status is REGISTERED
  • if the status of all three resources is DOWNLOADED, the reduced status is DOWNLOADED

Parameters:
Name Type Description
names string | Array.<string>

names of the resources whose statuses are requested
Throws:

if at least one of the names is not that of a previously registered resource

Type
Object.<string, *>
Returns:

status of the resource if there is only one, or reduced status otherwise

Type
module:core.ServerManager.ResourceStatus

openSession() → {Promise.<ServerManager.OpenSessionPromise>}

Source:

Open a session for this experiment on the remote PsychoJS manager.

Returns:

the response

Type
Promise.<ServerManager.OpenSessionPromise>

(async) prepareResources(resourcesopt)

Source:

Prepare resources for the experiment: register them with the server manager and possibly start downloading them right away.

  • For an experiment running locally: the root directory for the specified resources is that of index.html unless they are prepended with a protocol, such as http:// or https://.
  • For an experiment running on the server: if no resources are specified, all files in the resources directory of the experiment are downloaded, otherwise we only download the specified resources. All resources are assumed local to index.html unless they are prepended with a protocol.
  • If resources is null, then we do not download any resources
Parameters:
Name Type Attributes Default Description
resources String | Array.<({name: string, path: string, download: boolean}|String|Symbol)> <optional>
 []

the list of resources or a single resource

resetStatus() → {ServerManager.Status.READY}

Source:

Reset the resource manager status to ServerManager.Status.READY.

Returns:

the new status

Type
ServerManager.Status.READY

setStatus()

Source:

Set the resource manager status.

(async) uploadAudioVideo(@param) → {Promise.<ServerManager.UploadDataPromise>}

Source:

Synchronously or asynchronously upload audio data to the pavlovia server.

Parameters:
Name Type Attributes Default Description
@param Object

options
options.mediaBlob Blob

the audio or video blob to be uploaded
options.tag string

additional tag
options.waitForCompletion boolean <optional>
 false

whether or not to wait for completion before returning
options.showDialog boolean <optional>
 false

whether or not to open a dialog box to inform the participant to wait for the data to be uploaded to the server
options.dialogMsg string <optional>
 "Please wait a few moments while the data is uploading to the server"

default message informing the participant to wait for the data to be uploaded to the server
Returns:

the response

Type
Promise.<ServerManager.UploadDataPromise>

uploadData(key, value, syncopt) → {Promise.<ServerManager.UploadDataPromise>}

Source:

Asynchronously upload experiment data to the pavlovia server.

Parameters:
Name Type Attributes Default Description
key string

the data key (e.g. the name of .csv file)
value string

the data value (e.g. a string containing the .csv header and records)
sync boolean <optional>
 false

whether or not to communicate with the server in a synchronous manner
Returns:

the response

Type
Promise.<ServerManager.UploadDataPromise>

uploadLog(logs, compressedopt) → {Promise.<ServerManager.UploadDataPromise>}

Source:

Asynchronously upload experiment logs to the pavlovia server.

Parameters:
Name Type Attributes Default Description
logs string

the base64 encoded, compressed, formatted logs
compressed boolean <optional>
 false

whether or not the logs are compressed
Returns:

the response

Type
Promise.<ServerManager.UploadDataPromise>

waitForResources(resourcesopt)

Source:

Block the experiment until the specified resources have been downloaded.

Parameters:
Name Type Attributes Default Description
resources Array.<{name: string, path: string}> <optional>
 []

the list of resources

Type Definitions

CloseSessionPromise

Source:
Properties:
Name Type Attributes Description
origin string

the calling method
context string

the context
error Object.<string, *> <optional>

an error message if we could not close the session (e.g. if it has not previously been opened)

GetConfigurationPromise

Source:
Properties:
Name Type Attributes Description
origin string

the calling method
context string

the context
config Object.<string, *> <optional>

the configuration
error Object.<string, *> <optional>

an error message if we could not read the configuration file

OpenSessionPromise

Source:
Properties:
Name Type Attributes Description
origin string

the calling method
context string

the context
token string <optional>

the session token
error Object.<string, *> <optional>

an error message if we could not open the session

UploadDataPromise

Source:
Properties:
Name Type Attributes Description
origin string

the calling method
context string

the context
error Object.<string, *> <optional>

an error message if we could not upload the data