OJS Integration Guide¶

This guide covers what you need to embed the SciFlow editor in an OJS plugin. It assumes familiarity with OJS plugin development.

1. Load the Bundle¶

npm install @sciflow/editor-start
cp node_modules/@sciflow/editor-start/dist/bundle/sciflow-editor.js vendor/sciflow-editor.js
# or resolve via the package export:
#   import '@sciflow/editor-start/bundle';

$templateMgr->addJavaScript(
    'sciflow-editor',
    $request->getBaseUrl() . '/plugins/generic/myPlugin/vendor/sciflow-editor.js',
    ['type' => 'module', 'priority' => STYLE_SEQUENCE_LATE]
);

Icons are bundled as inline SVGs — no external fonts or CDN links required.

2. Self-host MathJax¶

Many institutional OJS hosts enforce CSP policies that block CDN scripts. Self-host MathJax alongside your plugin:

npm install mathjax@4
cp -r node_modules/mathjax/es5 vendor/mathjax/

Register vendor/mathjax/tex-svg.js the same way. Copy the entire es5/ directory — MathJax loads sub-resources dynamically at runtime.

3. Map References¶

OJS uses rawCitation for what SciFlow calls rawReference — the bibliography string (the full entry in a reference list, not an in-text citation). Both may contain lightweight HTML such as <i>. Map between them when loading and saving:

// OJS → SciFlow
const sciflowRef = { id: ojsCitation.id, rawReference: ojsCitation.rawCitation };

// SciFlow → OJS
const ojsCitation = { id: sciflowRef.id, rawCitation: sciflowRef.rawReference };

See the Reference Integration guide for full wiring (events, highlighting, drag-and-drop).

4. Connect Figure Uploads¶

Wire your OJS file API into the figure feature. See the Figure File API guide for the full handler interface.

5. Fullscreen¶

If you offer fullscreen editing, use CSS (position: fixed; inset: 0) instead of the browser's native Fullscreen API. The native API captures Escape, which breaks ProseMirror's selectParentNode and the math editor's cancel action.

6. Troubleshooting¶

Symptom	Fix
Equations show raw TeX	Check browser console for CSP errors; verify the MathJax script path
MathJax sub-resources 404	Copy the full `es5/` directory, not just `tex-svg.js`
`sciflow-editor` is undefined	Ensure `type` is set to `module` in `addJavaScript`
MathJax loads from CDN	Search templates for `cdn.jsdelivr.net/npm/mathjax` and remove