The ontotext-yasgui project contains the ontotext-yasgui-web-component wrapper around the YASGUI library allowing easy reusing by simply embedding the custom html tag in any web project be it vanilla javascript or based on any of the popular SPA frameworks. This component also extends the YASGUI API and serves as a facade behind which customizations can be implemented without affecting the client projects.
The component is heavily used in the Ontotext's GraphDB Workbench. All extensions and customizations made on top of the original YASGUI library came as requirements during integration of the library in the GraphDB Workbench UI.
This project is composed by following sub-projects:
- Yasgui;
- ontotext-yasgui-web-component;
- cypress. - An automated testing project.
- shared-conformance-utils -Shared utilities for the conformance tests. The utilities are used by both the conformance-tests and cypress conformance tests.
- conformance-tests - Contains tests for the SPARQL syntax and semantics conformance. The tests are executed against the grammar and tokenizer directly.
- test-files - A collection of test files used by the conformance tests. The test files are based on the W3C SPARQL test suite.
A workspace with the latest version of the original source code of the
Yasgui library with all needed customizations.
After a build, the yasgui.min.js and yasgui.min.css artefacts are copied into
ontotext-yasgui-web-component.
A workspace with the implementation of a custom web component which wraps the Yasgui library and
provides a common interface for unobtrusive customizations via configurations and hooks;
A project with automated e2e tests for the ontotext-yasgui-web-component.
Shared utilities for the conformance tests. The utilities are used by both the conformance-tests and cypress conformance tests. The utilities parse the SPARQL test manifests from the W3C SPARQL test suite and provide a common interface for executing the tests.
A project with tests for the SPARQL syntax and semantics conformance. The tests are executed against the grammar and tokenizer directly. The tests are based on the W3C SPARQL test suite. The test suite is parsed with the shared utilities from the shared-conformance-utils project
A collection of test files used by the conformance tests. The test files are based on the W3C SPARQL test suite. The test collection is automatically updated with the latest version of the W3C SPARQL test suite.
Read Development guide before starting any development in this project. Below are some first steps helping to get started:
git clone https://github.com/Ontotext-AD/ontotext-yasgui.git
npm install
Node.js 16.20.2 is required for this project to be built succesfully!
Execute the npm run build command. The command executes the following tasks:
- Builds the Yasgui component;
- Copies the built yasgui.min.js and yasgui.min.css artefacts into ontotext-yasgui-web-component
project;
- Builds the ontotext-yasgui-web-component project. The component is built in the dist
folder in the ontotext-yasgui-web-component.
-
A development server can be run by executing the
npm run startcommand. This will run a simple web server and deploy a sample web page with theontotext-yasgui-web-componentinside. The server supports a watch mode, and a live reload of the web browser.
-
Running the Cypress tests
The automated tests can be run by executing one of the following commands:
npm run cy:runfor headless tests execution.
npm run cy:openfor opening the cypress dashboard.
npm run cy:run-conformancefor headless execution of the cypress conformance tests.
npm run cy:open-conformancefor opening the cypress dashboard for the conformance tests.The development web server must be started before running the automated cypress tests.
-
Running the syntax conformance tests
The syntax conformance tests can be run by executing the
npm run test:conformancecommand. This will execute the tests in theconformance-testsproject. The tests are executed against the grammar and tokenizer directly.
-
The test files collection is based on the W3C SPARQL test suite.
To update the test files collection with the latest version of the W3C SPARQL test suite, execute the
npm run test:updatecommand. This will download the latest version of the W3C SPARQL test suite and update the test files collection in thetest-filesproject. -
The code quality is monitored with eslint. Executing the
npm run lintcommand will perform a code lint check. And running thenpm run lint:fixcommand will execute a code lint check as well as an automatic problems fixing where possible and reporting the rest. -
The
ontotext-yasgui-web-componentis regularly published as a package in the NPM registry. This is done via automated CI.
Execute the npm run clean command. This command will delete:
- Parent project
- node_modules of parent project
- ontotext-yasgui-web-component project
- ontotext-yasgui-web-component/dist
- ontotext-yasgui-web-component/loader
- ontotext-yasgui-web-component/node_modules
- ontotext-yasgui-web-component/www
- Yasgui project
- Yasgui/node_modules
- Yasgui/build
- Yasgui/packages/utils/node_modules
- Yasgui/packages/utils/build
- Yasgui/packages/yasgui/node_modules
- Yasgui/packages/yasgui/build
- Yasgui/packages/yasqe/node_modules
- Yasgui/packages/yasqe/build
- Yasgui/packages/yasr/node_modules
- Yasgui/packages/yasr/build
After execution of this command the project will be in a state same as it was just cloned from the repository.
For development purposes the minification of the yasgui can be skipped by setting the
minimizeproperty tofalseof the optimization configuration in Yasgui/webpack/config.ts file.
After the ontotext-yasgui-web-component is built, then it can be used in every supported by
stenciljs framework or in vanilla javascript applications. Read
Usage guide for details how to use it.
TODO: Describe the process in details