Finding your way around the code¶
The source code underlying the
lab.js library is contained in the
packages/library/src folder of the repository. For ease of development, the code is split across several files.
core.js· Core user-facing classes
If you are looking to understand the internals of the library, this is the place to start – all the core functionality is defined here. We strive to keep this code especially well-commented and understandable, please do let us know if we can explain something better!
html.js· HTML-based components
- All elements that use
HTMLfor showing content:
html.Frame(). These are probably most commonly used in studies.
canvas.js· Canvas-based components
- Components in this file rely on the
Canvasfor showing content, for extra performance:
flow.js· Flow control
- These components are not so much for displaying information, but for controlling the overall flow of the experiment. In particular, this file includes the source for
data.js· Data handling
- The code contained in this file takes care of data storage and export. It defines the
data.Store()class that logs and formats the experiments’ output.
The library also contains a range of utility functions and classes for internal use. These are generally not exposed to end-users, but are used extensively throughout the library code.
util/eventAPI.js· Low-level helpers and event handlers
This file defines the
EventHandler()class that provides a very basic publish-subscribe architecture to all other classes in the library.
This is really the backbone of the library, which relies heavily on this design for everything that happens. This is the place to dig deepest into the inner machinations of
util/domEvents.js· Document event handling
- The code in this file deals with assigning handlers to document events, and establishing and removing the links between both. The resulting
DomConnection()class encapsulates this functionality, and is used within each component to handle document events.
util/fromObject.js· Construct studies from serialized representations
- Many of the studies built with
util/fullscreen.js· Fullscreen helpers
- This file provides functions to enter and leave fullscreen mode across all browsers.
util/options.js· Option parsing
- The code in this file helps with substituting component
parametersin the content and options of components.
util/preload.js· Media preloading
- Preloading images and other static assets.
util/random.js· Random number generation
- Anything that needs to be sampled, drawn, suffled or generated randomly goes through this code.
util/tree.js· Tree traversal
- A more complex study built with
lab.jswill often resemble a tree structure, in that there is a central
sequenceas a stem, which contains other components. These child components may, in turn, contain others nested inside them. This nested, or tree-like structure, frequently needs to be navigated, and the utilities in this file help with that.
The graphical builder interface resides in the repository’s
builder/src directory. It is structured as a React application, building on the create-react-app template. The internal state is managed using Redux.
components· User interface components
- The application is broken down into distinct components, for example the editor or the sidebar, each of which contain their own logic and styles. If you are looking for a specific part of the user interface to improve, this is where you’ll find it.
logic· Application logic
- Besides the user interface, the builder contains a substantial amount of application logic that governs how studies are put together, saved into and loaded from files, and exported to a local preview mode as well as publishable study bundles.