Installation

Use this package if you are a customer of SOWISO and would like to integrate your existing platform with us. You should’ve been instructed on the backend integration separately. Continue reading on how to integrate the frontend.

The SOWISO Content Player is published as an npm package in our npm registry hosted on GitLab. Add it to your project by creating (or appending) the .npmrc file in your frontend code directory with the following content:

@sowiso:registry=https://gitlab.com/api/v4/packages/npm/

Afterwards, you can install the SOWISO Player integration like so:

$ npm install @sowiso/player

The installed node_modules/@sowiso/player directory will contain a dist/ folder. You should instruct your build system to copy this folder over to your final bundle directory into the /sowiso subdirectory, so that on the final webserver it is reachable at yourdomain.com/sowiso. Due to the nature of some of the software packages we depend on, it is impossible to bundle the SOWISO integration into a single JS bundle - the entire directory must be copied.

That does not mean that all components must be included on every page. For example, a page that only needs the Formulaeditor input and the Keyboard must not necessary include the Content Player.

Loading the SOWISO bundle

To use any of the SOWISO components, load the SOWISO bundle by adding a <script> tag to your page like so:

<script type="module" src="index.js"></script>

Once the Player has loaded all its dependencies, you can listen to the sowiso-dependencies-loaded event on document. Not however that under normal circumstances, you shouldn’t have any need to do this, as you can simply add our custom elements to the page, and they will be picked up and initialized automatically as soon as the dependencies have loaded.

Configuration

In addition to the component-specific options that you can configure for each component individually, there are also certain options that apply to all SOWISO components. To make it easier to configure those globally so that you don’t have to pass those options to each component manually, there’s one central place where these global options go. You put these options onto the window.sowisoGlobalOptions object before loading the SOWISO bundle:

window.sowisoGlobalOptions = {
  // skip loading SOWISO's bundled version of MathJax, before using see section below!
  skipLoadingMathjax: false,
  // hides attempt labels in replay mode
  hideAttemptsInReplayMode: false,
};

My website already has MathJax on it, and it’s conflicting with the one loaded by the SOWISO bundle

It’s possible to disable the loading of our bundled MathJax by setting the skipLoadingMathjax option to true as shown above. However, there is something to keep in mind. By not loading our bundled MathJax, the MathJax configuration options that we provide in our bundle will also not be loaded. As the SOWISO components were made with a certain set of MathJax options in mind, you should make sure to merge the options that we provide to MathJax, with your own MathJax configuration. Otherwise, some components might behave strangely. You can inspect the options that we provide to MathJax by looking at content-player-mathjax-config.js. (You can skip the sowiso-mathjax-ready event, since you’re loading your own MathJax we won’t be waiting for that event when skipLoadingMathjax is true; however, you should make sure that you only add the SOWISO bundle to the page after you’ve made sure that your own MathJax is fully loaded.)