Documentation: Latest, All Versions
React package: Latest, All Versions
JavaScript modules: Latest, All Versions

The SemLookP Widgets project, derived from the SemLookP project and now hosted on GitHub under the TS4NFDI repository, is a collection of interactive widgets designed to ease the integration of terminology service functions into third-party applications.

In this Storybook, you will find an interactive documentation of the widget component library.

The widgets are built using React and TypeScript and can be used in both React and plain HTML applications. The functionality and arguments are the same for the React and plain HTML versions. Only the code snippet you get when you click "Show code" in the Storybook is different.

Click here for detailed instructions on how to use the package.

• Node v16.13.1
• NPM v8.19.2
• ElasticUI <88.0.0

If your React consumer project uses ElasticUI v> 88.0.0., it might get a conflict in dependencies.

To install the package for development, it may be necessary to move the peerDependencies in the package.json to the devDependencies section, if the corresponding modules are not present on your machine.

IMPORTANT NOTE: To build the package, they must be defined as peerDependencies to avoid dependency conflicts in the consumer projects.

You will need access to a sub-widget repository to run the HierarchyWidget (and the entire project) in development mode. Please contact the SemLookP or TS4NFDI teams. We are working on avoiding this hurdle in the future.

Add the following two lines to your local npm configuraiton ~/.npmrc. Replace TOKEN with your personal access token (classic). You need to have access to a ZB MED project for developing the widgets - please contact the development team.

@zbmed:registry=https://npm.pkg.github.com
@ts4nfdi:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=TOKEN

This project uses Storybook to develop independent React components. To start the development server, install the dependencies with npm install and start Storybook with this command npm run storybook:react. The interactive documentation is available via http://localhost:6006. For more information, please visit https://storybook.js.org/docs/react/get-started/install/

The project also features a Storybook for HTML versions of the components. To start this Storybook, you have to install the HTML widgets as a local module in the project ( see Build widgets for non-React projects). After that, run npm install and start the Storybook with npm run storybook:html. The interactive documentation is available via http://localhost:6007.

The React and HTML components can be combined in one Storybook using npm run storybook. Notice that, for this to work, the React Storybook has to be running at http://localhost:6006 and the HTML Storybook at http://localhost:6007.

Before running the storybook via docker, make sure that you provide the needed authentication file ~/.npmrc.

First, build (name is arbitrary)

 docker build --tag 'storybook' .

Then, run

$ docker run \
    -p 6006:6006 -p 6007:6007 -p 6008:6008 \
    --name story \    
    storybook

Hint: if you want to run the docker for development, you can use the docker bind mount to link the scripts inside the container to your local ones to check the changes immediately without re-building. Look at: https://docs.docker.com/storage/bind-mounts/#start-a-container-with-a-bind-mount

 $ docker run \
    -p 6006:6006 -p 6007:6007 -p 6008:6008 \
    --name story \    
    --mount type=bind,source=$(pwd)/src,target=/usr/storybook/src \
    storybook

Note that the bind only works for the React version. For the HTML version, you need to re-build the storybook.

npm run build builds the standard React widgets. It uses rollup and the output can be found in dist/esm/.

npm run build:plainJS (WIP) builds the widgets for non-React projects. It uses esbuild and the output can be found in dist_plainjs/. This process uses a forked and adapted version of the community plugin esbuild-dynamic-import.

For further information on the usage of the HTML widgets, please visit the interactive documentation in the HTML Storybook.

If the environment features npm, a local module can be created from the output file. To do this, place all the files generated inside dist_plainjs/ in local_modules/terminology-service-suite/ in your consumer project. Now add "terminology-service-suite": "file:local_modules/terminology-service-suite" as a dependency in package.json and run npm install.

This project uses Semantic Release, i.e. the CI/CD pipeline analyzes the commit messages and automatically performs a release depending on the format. Therefore, please format your commit messages according to https://www.conventionalcommits.org/en/v1.0.0/

In short:

HINT: Parameter renaming is a BREAKING CHANGE! Type changes of parameter functions are BREAKING CHANGES!

HINT 2: Don't use Emoji in commit messages (e.g. 🐛), because it breaks semantic versioning!

When developing a new version of widgets, it might be helpful to include the current locally developed version in another consumer project. Changes in the widgets can be tested before publishing a new release. Two methods are described in the following.

Build the package locally in the widgets project and install it in the consumer project for testing:

To prevent unexpected behaviour remove the node_modules folder and package-lock.json file in the widgets project before using

npm install

npm run build

npm pack

A .tgz folder will be created with the bundled module. Add "@ts4nfdi/terminology-service-suite": "file:../path/to/ts4nfdi-terminology-service-suite-1.17.4.tgz", (adapt path and file name) to your package.json of the consumer project and do npm install.

Link the widgets project to the consumer project for testing/development:

Run the following commands in the widgets project:

Build the widgets: npm run build --if-present

Link the peer dependencies from the consumer project: npm link path/to/consumer/node_modules/react path/to/consumer/node_modules/react-query path/to/consumer/node_modules/@emotion/react path/to/consumer/node_modules/axios

Run the following command in the consumer project: npm link path/to/widgets-project-root

Start the application: npm start

This project is developed by the Terminology Services for NFDI (TS4NFDI) project (as part of the Base4NFDI consortium), and the NFDI4Health Consortium.

The NFDI4Health Consortium gratefully acknowledges the financial support of the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) – project number 442326535.

The project is derived from the Semantic Lookup Platform SemLookP which was also developed in part by ZB MED - Information Centre for Life Sciences.