vsm-dictionary-remote-demo is a tiny, partial example-implementation
of the 'VsmDictionary' parent-class/interface (from the package
vsm-dictionary),
to demonstrate communication with a hypothetical server API.
A demo of this demo connects to a real server (see at end).
- VSM-sentences are built from terms that are linked to identifiers.
- The '
vsm-dictionary' package defines a standardized interface, for VSM-related tools to communicate with services that provide terms+IDs (e.g. a webserver API). - It also includes the small 'VsmDictionary' parent class (/interface) that provides shared functionality for concrete subclasses (like this package).
This is VsmDictionaryRemoteDemo:
- The name 'VsmDictionary-Remote-Demo' is meant to contrast with the name of the sibling package 'VsmDictionary-Local'.
- Unlike VsmDictionaryLocal which stores the data locally (=in-memory), VsmDictionaryRemoteDemo communicates with a remote (=online) webserver that stores the data and makes it accessible through an API.
- VsmDictionaryRemoteDemo extends the VsmDictionary parent class, and provides
a bare-minimum implementation that follows the vsm-dictionary
specification.
- It simply makes the assumption that the webserver has a REST API that literally supports all the spec options, and that the server returns data in the exact same way as a VsmDictionary is supposed to pass it onwards.
- It has tests:
these shows how to make automated tests, based on mocking how the webserver's API would respond, using a fake-server module. - It has a demo:
see the interactive demo section.
Because of the above,
- VsmDictionaryRemoteDemo should only be used as inspiration for developing a VsmDictionary-subclass that interfaces with a real server API,
- and for creating automated tests for it.
- The demo (see at end) gives a live impression of how the returned string-search match-objects look like.
Like all VsmDictionary subclass implementations, this package follows
the parent class
specification,
although only a fraction of it, without adding much more.
•
(Note: we simply use the name 'DictionaryRemoteDemo' for VsmDictionaryRemoteDemo,
in the source code).
Be advised to read the comments at the _getReqObj() method, near the end of
src/DictionaryRemoteDemo.js.
It explains how to make API requests in a way that works under Node.js,
as well as in the browser (where XMLHttpRequest isn't/is available, resp.).
Run npm test, which runs tests with Mocha.
Run npm run testw, which automatically reruns tests on any file change.
The demo makes a further subclass of VsmDictionaryRemoteDemo,
and adds code to parse the specific data that the dictionary-webservice
'PubDictionaries.org' returns.
The demo includes only string-search functionality, on a single
dictionary of PubDictionaries at a time, and without support for any options.
Run npm run demo to start the interactive demo.
This opens a browser page with an input-field to search on PubDictionaries data,
plus a field to choose one of its ('sub'-)dictionaries.
The demo works by making a Webpack dev-server bundle all source code (VsmDictionaryRemoteDemo and its dependencies) and serve it to the browser.
This is useful during development, to see immediate effects of changes to the source code (excl. the demo code).
To use a VsmDictionary in Node.js, one can simply run npm install and then
use require().
But it is also convenient to have a version of the code that can just
be loaded via a <script>-tag in the browser.
Therefore, we included webpack.config.js (note: the one in the root folder,
not the one in the 'demo' folder), which is a Webpack configuration file for
generating such a browser-ready package.
By running npm build, the built file will appear in a 'dist' subfolder.
A demo-use of this file can then be seen by opening demo-build.html
(in the 'demo' folder). (It includes a
<script src="../dist/vsm-dictionary-remote-demo.min.js"></script> tag).
So after the build step, demo-build.html does not need Webpack to run.
Note: at the time of writing (Feb. 2019), there seems to be an issue
with conflicting Webpack-dependencies when running a fresh npm install.
Therefore, in order to build your own VsmDictionary, it is recommended that
you copy the package-lock.json and package.json files from this package
and use them as a starting point for your own project, because these files refer
to a set of non-conflicting versions of the dependencies.
This project is licensed under the AGPL license - see LICENSE.md.