The project repository contains the code underlying the lab.js
library and the builder interface. To condense both into a single library file for distribution with studies, and an uploadable version of the builder, please follow these additional steps after downloading. You'll need a local installation of node.js and yarn.
You'll notice that many of the commands start with yarn
-- that's because we use scripts as shortcuts for most build steps.
The easiest way to create a local copy is by cloning the repository. If you use git, you can copy the following command:
git clone https://github.com/FelixHenninger/lab.js.git
If you'd prefer a direct download, that's available too!
The library and builder interface are contained in the same repository because they share several pieces of code. Both are coordinated by Lerna, which can initialize all parts at once by running the following commands in the project directory:
yarn && yarn run bootstrap
Changing to the packages/library
directory and running
yarn
will install all dependencies for the lab.js
library, whereafter
yarn run build:js
will output a transpiled version in the packages/library/dist
directory. If you would like the transpiled output to be updated automatically as you make changes, yarn run watch:js
will do that for you.
yarn run build:starterkit
will build the library with all its components (the basic HTML
template, the stylesheet, and several other useful files), and assemble the result into a zip
file for easier distribution. This is the bundle that is included with every release.
There are a few more commands available, which you can see by typing yarn run
in the packages/library
folder.
The builder interface is created using Facebook's create-react-app template, and follows the conventions instituted there. If you're looking for details, their documentation provides more information than we ever could.
The main code is found in the packages/builder/src
folder, where the components
subdirectories contain all user-facing interface code, and logic
holds the main application logic.
Please note that the builder requires a copy of the library to work, so please compile the library starterkit as described above before modifying the builder. With the library in place, please then navigate into the packages/builder
directory. From there, typing
yarn start
will run the builder application in a local development server, and open it in a browser.
yarn run build
bundles all files necessary for deployment, and creates an optimized version of the application code in the packages/builder/build
folder for you to upload to a local server.
Important
For the lab.js
builder to work on a public server, it must be served over an encrypted connection (via HTTPS); please make sure that encryption is set up on the server you're using.
During the build step, you can set several environment variables that customize the builder's behavior.
PUBLIC_URL
provides the URL at which the builder will run, e.g.https://labjs.felixhenninger.com
REACT_APP_EXAMPLE_PATH
sets the URL from which the builder loads its repository of example studies. By default, this points to the tasks directory in the project repository, and thus the builder loads the example collection metadata from therein.REACT_APP_TEMPLATE_PATH
works just like theEXAMPLE_PATH
above, but instead of loading examples, it loads the templates offered to users when they add new components. This path, too, is expected to contain a metadataJSON
file that provides further information about the templates, like the one in the project repository.
The library's documentation is built using Sphinx, using the fabulous Read the Docs Theme. Both require a local python
installation, as well as the pip
package manager.
If you don't have python
on your system, please consider the Anaconda python distribution; if you're only missing pip
, you can install it on your system. Equipped with both, install the required Python modules:
pip install -r docs/requirements.txt
With everything at hand, you can run the following command from the project's root directory:
yarn run build:docs
This will output the html documentation in the docs/_build
subdirectory. Running yarn run watch:docs
will update the documentation whenever you save changes.