Directory Structure

This project directory is organized to be modular and composable. In general, files and functions should be relatively small and self-contained, global scope should not be used, and only the pieces of code needed for any given file should be imported.

assets/

This folder contains static files that are used by the application. Honeycomb uses a few images as icons for the installed applications.

caution

Assets that pertain to your specific task should be added to the public/assets/ folder, not here!

build/

The build scripts automatically create a build folder at the root of the repository and update it on subsequent builds.

caution

build/ should be left alone! It is in Honeycomb's .gitignore and should never be added to git.

emulator_data/

This folder contains starter data for the Firebase Emulators to use while developing locally. The Firebase Scripts detail how to use this data.

caution

emulator_data/ is written to when running npm run firebase:emulators:save and should never be edited.

env/

This folder contains different files used to pass environment variables (settings) into Honeycomb. Honeycomb starts with presets for common use cases and is explained in greater detail in the Environment Variables section.

node_modules/

caution

node_modules/ is written to when running npm install and should never be edited. It is in Honeycomb's .gitignore and should never be added to git.

psiturkit/

The file psiturk-it inside psiturkit/ is a bash script used to instal PsiTurk locally - see PsiTurk for more information.

caution

This folder involves a Honeycomb deployment. The files do not need to be edited.

public/

The public directory contains files that are used as assets in the built app.

• index.html is the entry point of the website
  • Changing <title>Honeycomb</title> will update the text in the browser tab!
• favicon.ico is the small (16x16px) icon you can see in the browser tab
• manifest.json contains metadata about the web app

caution

manifest.json involves project metadata and does not need to be edited.

assets/

The public/assets/ directory contains all of the audio, images, and videos needed to run your task.

electron/

The public/electron/ directory contains the files needed to run Honeycomb as an Electron app.

• main.js sets up Electron itself
• preload.js sets up the communication between the main and renderer processes.

caution

This folder involves a Honeycomb deployment, the files do not need to be edited.

lib/

The public/lib/ directory contains the files PsiTurk needs to run. Note that index.html references these files inside the <script> tags.

caution

This folder involves dependencies for a Honeycomb deployment, the files should not be edited.

src/

This folder contains the source code for the Honeycomb application.

• index.js is the entry point for React in our application. Note that the id 'root' corresponds with a tag in public/index.html:

  <div id="root"></div>
  caution

  index.js runs Honeycomb itself and should not be edited.

App/

Files relating to the React application.

caution

This folder holds the code that runs the jsPsych task, the files do not need to be edited.

components/

The React components that make up Honeycomb are located here.

• App.jsx initializes and maintains the state of the application.
• Error.jsx displays a small error message. It is rendered when the App.jsx detects an issue in state.
• JsPsychExperiment.jsx initializes the jsPsych experiment.
• Login.jsx handles user authentication based on the environment variables passed to Honeycomb.

deployments/

Custom code used by the various deployments such as Firebase.

caution

This folder involves Honeycomb deployments, the files do not need to be edited.

config/

Each file in the config directory contains settings for a different part of the task.

• language.json contains the language used in your task. This file allows for easy internationalization of the task (e.g. English and Spanish) and mturk-specific language. Common phrases can be written once and re-used throughout the task.

• main.js contains the global settings (e.g., whether Honeycomb is running online or in the clinic) passed from env variables and logic for loading the appropriate files.

• settings.json contains the settings for your task. Usage of the config file allows for easy updating of task settings. Common settings can be written once and re-used throughout the task.

• trigger.js contains equipment-related settings for a trigger box. The eventCodes are especially important for marking the types of given trials.

experiment/

tip

This is where you'll spend most of your time while developing your task!

• index.js contains the outermost logic for running the experiment. It loads experiment's styling and exports the main timeline and options for the experiment.
  caution

  The experiment will not run correctly if the names jsPsychOptions or buildTimeline are changed.

• honeycomb.js contains the options and timeline for the jsPsych tutorial's "Simple React Time Task". It serves as an example for the experiment timeline for your task.
  tip

  This is just an example experiment! Be sure to write your experiment in its own file. {/ TODO: Link to this in the quick_start guide once it's ready /}

procedures/

A procedure is a tested timeline of trials in jsPsych. Common parameters can be used across trials, and the trials within a procedure can be ordered and repeated as desired. Check out the JsPsych documentation for more information on creating a custom procedure.

• startProcedure.js contains the procedure for the start of the experiment. It uses the environment and task settings from config.json to create a nested timeline that correctly starts the experiment.
• honeycombProcedure.js contains the procedure for the Honeycomb task. It displays a fixation dot and presents the stimulus of the example task.
  tip

  This is just an example procedure! Be sure to write your procedures in their own files.

• endProcedure.js contains the procedure for the end of the experiment. It uses the environment and task settings from config.json to create a nested timeline that correctly end the experiment.

trials/

A trial is the base unit of an experiment. These trials are ordered into procedures and timelines to create the task itself.

• adjustVolume.js prompts the user to adjust the volume on their tablet.

• camera.js contains trials for beginning and ending a camera recording.

• conclusion.js displays a message to the user indicating that the experiment has concluded.

• fixation.js displays a fixation dot in the center of the screen. It contains additional logic for flashing a photodiode spot and emitting an event code based on the environment settings.

• fullscreen.js contains trials for entering and exiting fullscreen mode.

• holdUpMarker.js prompts the user to connect their event marker and hold it up to the camera.

• honeycombTrials.js contains the individual trials used in the Honeycomb task. These trials are imported into experiment/procedures/honeycombProcedure.js and experiment/honeycomb.js.

  tip

  These trials are for the example experiment! Be sure to write trials pertaining to your task in their own file(s).

• introduction.js displays a message to the user welcoming them to the experiment. They must click on a button to continue.

• name.js displays the name of the task to the user.

• startCode.js emits a start code to a photodiode spot and audible beep.

• survey.js contains trials pertaining to a survey/quiz for the user to complete.

lib/

A library of utility and markup functions are located here. This allows for functions and html to be re-used wherever needed.

• utils.js contains utility functions that can be used across a variety of trials. Be sure to look for functions you might be able to use in your task!

markup/

Markup files contain HTML templates used throughout the task.

• photodiode.js contains the markup for the photodiode box and spot displayed in the bottom right corner of the screen
• tags.js contains functions for wrapping language in common html tags. You should always wrap your language in a tag to ensure it is displayed correctly.
  • For example: p('Hello World') will return <p>Hello World</p>.

tip

The tag function inside tags.js can be used to wrap language in any html tag you need.

Other Folders/Files

• .nvmrc determines which version of node that Honeycomb is designed to be run on.

• .github/workflows/ contains .yaml files used for CI/CD with GitHub Actions.

• package.json contains metadata about your project, a list of the dependencies needed for the project, and scripts to run tasks related to your task. The Quick Start lists which metadata should be changed.

• cli.mjs is the script used to download and delete data stored in Firestore.

• version.js is the script used to keep track of which version of the task a given experiment is using.

caution

cli.mjs and version.js are automated scripts and should not be edited.

package-lock.json is written to when running npm install and should never be edited.

Firebase Files

• .firebaserc contains the name of the project Firebase should connect to. Be sure to update the default project to the one you created!
• firebase.json contains the Firebase settings for Honeycomb.
• firestore.indexes.json contains the Firestore index settings for Honeycomb.
• firestore.rules contains the Firestore rules for creating/editing data.

caution

firebase.json and firestore.indexes.json are default configs and shouldn't need to be edited.

Git Files

• .gitignore lists the folders and files that should be excluded from Git.

caution

Any secrets and/or tokens must be added to .gitignore or they will be visible to anyone with access to the repository!

Eslint Files

• .eslintrc.js contains the Eslint settings for Honeycomb. We recommend it's left alone but can be adjusted for personal preference.
• .eslintignore lists the folders and files that eslint shouldn't touch, similar to .gitignore.

Prettier Files

.prettierrc.js contains the Prettier settings for Honeycomb. We recommend it's left alone but can be adjusted for personal preference.