R/build_resources.R
build_resources.RdBuild 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") )
| from | The paths to files/directories |
|---|---|
| audio | File extensions assumed to be audio |
| video | File extensions assumed to be video |
| image | File extensions assumed to be images |
| script | File extensions assumed to be scripts |
| style | File extensions assumed to be stylesheets |
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)
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.