Arethusa Widget
This library provides an embedded version of the Arethusa Annotation Environment. For more information, see the Arethusa GitHub repository,
Demo
https://perseids-tools.github.io/arethusa-widget/
Installation
yarn add arethusa-widget
or
npm install arethusa-widget
(See project on npm)
How to use
Setup
Running the Arethusa widget requires serving some static JavaScript and CSS files.
The easiest way to do this is to link the files from node_modules to a directory in your application
that serves static files:
cd path/to/static/files
ln -s path/to/node_modules/arethusa-widget/dist/arethusa ./arethusa
In the <head> of the HTML file on the page that will contain Arethusa
(or for a single page app, the public HTML page) add the following:
<script type="text/javascript" src="/public/url/arethusa/arethusa.packages.min.js"></script>
<script type="text/javascript" src="/public/url/arethusa/arethusa.min.js"></script>
<script type="text/javascript" src="/public/url/arethusa/arethusa.widget.loader.js"></script>
<script type="text/javascript">
window.i18npath = "/public/url/arethusa/i18n/";
window.dagred3path = "vendor/dagre-d3/dagre-d3.min.js";
</script>
<link rel="stylesheet" type="text/css" href="/public/url/arethusa/css/arethusa.min.css">
<link rel="stylesheet" type="text/css" href="/public/url/arethusa/css/colorpicker.css">
<link rel="stylesheet" type="text/css" href="/public/url/arethusa/css/font-awesome.min.css">
<link rel="stylesheet" type="text/css" href="/public/url/arethusa/css/foundation-icons.css">
<link rel="stylesheet" type="text/css" href="/public/url/arethusa/css/widget.css">The /public/url is the base path of the page.
For most applications you will probably want to change /public/url to /.
If embedding in a React app, change /public/url to %PUBLIC_URL%.
Usage
In the JavaScript file where you would like to use Arethusa, import the ArethusaWrapper.
The ArethusaWrapper requires an elementId,
which is the id of the HTML element that will hold the treebank,
a remoteUrl, which is the equivalent of /public/url/arethusa mentioned above,
and a doc which is the URL of a treebank XML file.
Rendering Arethusa requires a configuration. Two ready-to-go configs are provided: defaultConfig and sidepanelConfig. You will also need to provide a sentence and (optionally) a list of words to select.
import { ArethusaWrapper, defaultConfig, sidepanelConfig } from 'arethusa-widget';
const wrapper = new ArethusaWrapper({
elementId: 'treebank_container', // `id` of the HTML element containing the widget
remoteUrl: `/arethusa`, // the `/public/url/arethusa`; for React it would be `process.env.PUBLIC_URL + '/arethusa'`
doc: 'https://www.example.com/treebanks/some_treebank.xml', // URL of the treebank
});
wrapper.render({
chunk: '1', // sentence of the treebank to display
config: defaultConfig, // this can be `defaultConfig`, `sidepanelConfig`, or a custom configuration object
words: [1], // (optional) words to highlight; `1` highlights the first word, `2` the second word, etc.
});The HTML of the page should contain a <div> with class __artsa which should itself
contain a <div>. The id of this second <div> should match the elementId argument passed
to new ArethusaWrapper().
<div class="__artsa">
<div id="treebank_container" />
</div>The following functions can be used with the instantiated wrapper once it has been rendered:
// Go to another sentence and/or highlight other words
wrapper.gotoSentence({
chunk: '2', // sentence of the treebank to display
words: [2,3], // (optional) words to highlight; `1` highlights the first word, `2` the second word, etc.
});
// Return the subdoc (string) of the current sentence
wrapper.getSubdoc();
// Return the morphology (object) of a particular sentence and word
// See https://github.com/alpheios-project/arethusa/blob/widget/app/js/arethusa.core/services/api.js#L59
wrapper.getMorph({
chunk: '4', // sentence of the treebank to display
wordId, // a word to select; `1` highlights the first word, `2` the second word, etc.
});
// Refresh the Arethusa view
wrapper.refreshView();
// Given a chunk, word, prefix (optional), and suffix (optional), moves to the
// specified sentence and returns a list of matching words
// See https://github.com/alpheios-project/arethusa/blob/widget/app/js/arethusa.core/services/api.js#L121
wrapper.findWord({
chunk: '2', // sentence of the treebank to display
word: 'χαῖρε', // the word to find
prefix: 'ἀλλὰ', // (optional) prefix the preceding word or words
suffix: 'ὦ', // (optional) suffix the following word or words
});(This package is designed to be used with ES6 modules and Webpack.
If you do not have that set up for your project you will need to replace the imports
with the equivalent requires.)
Development
Requirements
- Node 14.2.0
- Yarn
- Docker
- Docker Compose
Setup
git clone --recurse-submodules git@github.com:perseids-tools/arethusa-widget.git
or if the repository is already initialized
git pull --recurse-submodules
then install development dependencies
yarn install
Tests
yarn build
yarn test
Linting the code
yarn lint
Updating libraries
git submodule update --remote
Updating GitHub Pages
yarn build
yarn deploy
To run locally before publishing:
yarn demo
Publishing
- Update the version in
package.jsonaccording to SemVer - Commit and push to GitHub
- Add a new release with
vfollowed by the version number as the tag and a title of the version preceded byRelease. For example, if theversioninpackage.jsonis2.0.0, then the tag for the release should bev2.0.0and the title should beRelease v2.0.0. The description of the release should contain a list of changes followed by the commit of the Arethusa and Arethusa Configs repositories. - Run
yarn buildand thennpm publish