cs-web-lib

An npm library for Control Systems web applications

Installation

⚠️ cs-web-lib is NOT compatible with projects using create-react-app. Vite should be used instead.

Install via npm: npm install @diamondlightsource/cs-web-lib

We use React 18. cs-web-lib requires several environment variables to be set in order to connect to PVWS and fetch PV value updates.

• VITE_PVWS_SOCKET - point to the server hosting the PVWS application.
• VITE_PVWS_SSL - set this to false if running a local PVWS instance e.g. localhost:8080 without SSL, otherwise true

These should be provided in a .env file at the root of your project.

Inside your application, create a screen by passing a .opi, .bob or .json file to the EmbeddedDisplay widget.

Legacy Installation

PVWS was introduced in version 0.4.0. Versions prior to this used Coniql, and the .env variables used were VITE_CONIQL_SOCKET and VITE_CONIQL_SSL.

React 17 was supported until version < 0.5.0.

Features

cs-web-lib does not contain the full suite of features and widgets provided by Phoebus. The tables below describes which features are currently included, are planned to be added, and which will not be added.

Widgets

Category	Widget	Included	Reason
Graphics	Arc	✅
	Ellipse	✅
	Label	✅
	Picture	✅
	Polygon	✅
	Polyline	✅
	Rectangle	✅
Monitors	Byte Monitor	✅
	LED	✅
	Multi State LED	❌	Add later
	Meter	❌	Add later (date unknown, low priority)
	Progress Bar	✅
	Symbol	✅
	Table	✅
	Tank	❌	Add later (date unknown, low priority)
	Text Symbol	❌	Add later
	Text Update	✅
	Thermometer	❌	Add later (date unknown, low priority)
Controls	Action Button	✅
	Boolean Button	✅
	Check Box	✅
	Choice Button	✅
	Combo Box	✅
	File Selector	❌	Add later
	Radio Button	✅
	Scaled Slider	✅
	Scrollbar	❌	Add later
	Slide Button	❌	Add later (date unknown, low priority)
	Spinner	❌	Add later (date unknown, low priority)
	Text Entry	✅
	Thumbwheel	❌	Add later (date unknown, low priority)
Plots	Data Browser	❌	Add later (date unknown, low priority)
	Image	❌	Unknown
	Stripchart	❌	Unknown
	XY Plot	✅
Structure	Array	❌	Add later
	Embedded Display	✅
	Group	✅
	Navigation Tabs	✅
	Tabs	✅
	Template/Instance	❌	Unknown

Features

Widget	Included	Reason
Actions	✅	Some actions may not be supported. Please open an issue for any issues noticed.
Formulas	❌	sim:// PVs are supported, but not eq://. This will be added in future.
Rules	✅	Partial support. x, y and Font rules are currently not supported. This will be added in future. Please open an issue for any issues noticed.
Scripts	❌	The use of scripting is recommended against in general by CS Studio Developers. Formulae should be able to handle most use cases.

Development

To develop on the library code first clone this repo, install the npm package dependencies and then make changes:

cd cs-web-lib/
npm install

Pushing changes

Before pushing any changes check that the update code conforms to the formatter checks and that the unit tests all pass:

npm run all-checks
npm run tests

If making changes to the build process, check that the package is built correctly with:

npm run rollup
npm pack

You can then install the generated tar.gz file into another project and check that all functionality expected is there.

Publishing to NPM (PREFERRED METHOD)

A GitHub workflow has been setup to automatically publish a new package version to the NPM registry on the push of a new tag. This should be used as the preferred method of release a new package.

1. Update/increase the package version in package.json (see https://docs.npmjs.com/cli/v8/commands/npm-version for further details on this npm command):

    npm version <major|minor|patch> -no-git-tag-version
   

2. Commit and push this to GitHub:

    git add package.json
    git commit -m "..." package.json
    git push <remote> <branch>
   

3. Create a new tag and push to GitHub

    git tag -a vX.XX.xx -m "..."
    git push <remote> vX.XX.xx 
   

This will trigger a job on GitHub to publish a new version of the cs-web-lib to NPM. Check that this job passes.

Publishing to NPM locally

To publish a new version of the @diamondlightsource/cs-web-lib package you must first have an npm account and be a member of the DiamondLightSource organisation. Then:

1. Update the package version in package.json (follow the major.minor.patch versioning terminology).
2. Run the rollup command to package the library: npm run rollup.
3. Login to your npm account: npm adduser
4. Publish as a public-scoped packages: npm publish --access public --registry=https://registry.npmjs.org