Build the resource file specification from a directory path

build_resources(
from,
audio = c(".mp3", ".wav", ".aif", ".mid"),
video = c(".mp4", ".mpg", ".mov", ".wmv", ".webm", ".ogg"),
image = c(".jpg", ".png", ".bmp", ".svg", ".tiff"),
script = c(".js"),
style = c(".css")
)

## Arguments

from The paths to files/directories File extensions assumed to be audio File extensions assumed to be video File extensions assumed to be images File extensions assumed to be scripts File extensions assumed to be stylesheets

## Value

The build_resources() function returns a tibble with four columns, called "name", "type", "from", and "to". The "name" column lists the name of every resource file discovered in the from folder and the "type" column lists the kind of resource file (image, audio, video, script, style or other file). Finally, the "from" column specifies the full path to the existing location of the resource file, while the "to" column specifies the relative path to which a copy of the resource file should be copied (relative to the "index.html" file for the experiment)

## Details

Because jsPsych experiments are designed to run through the browser rather than within R, the jaysire package incorporates "resource files" in a slightly complicated way. Resource files here are divided into several categories because the experiment has to incorporate them in different ways: the code for handling images is different to the code for handling audio files or video files, and both are different to how scripts and style files are loaded. As a consequence, the build_experiment() function needs to know what kind of file each resource corresponds to in order to construct the experiment properly. One part of what the build_resources() function does is make this a little easier for the user, by scanning all files that belong to a "resource folder" (located at the path specified by the from argument) and using the file extension to guess the type of each resource file.

The second peculiarity is that the build_experiment() function will make copies of all resource files. Regardless of where the original files are taken from, a separate copy will be placed in an appropriate subfolder within the experiment. For example, if the primary experiment file is saved to "experiment/index.html" and it requires an image file called "picture.png", it will be copied to "experiment/resource/image/picture.png". The reason for this is to ensure that the "experiment" folder is entirely self contained, and includes all source files necessary to run the experiment. This is important if the experiment is designed to be deployed to a remote server (e.g., using Google App Engine), as is very often the case if one wishes to run an online experiment.

It is for this reason that the build_experiment() function creates copies of resource files: jaysire is designed on the presumption that the user may wish to keep the "original" versions of resource files somewhere else, and makes copies of them that can be deployed in the experiment. Viewed from this perspective, the build_resources() function is a helper function: as long as all the resource files your experiment requires are (at least temporarily) stored in the from folder, it will construct a tibble that contains all the information that build_experiment() needs to organise the experimental files appropriately.

There are two important details to note. First, the from folder should be flat: it should not contain subfolders. Second, there are various arguments (e.g., audio, video, script etc) that specify the file extensions that are associated with each resource type. The default values are likely to change in future as the current lists are quite restrictive.

insert_resource, build_experiment