Skip to content

Commit 811eba5

Browse files
abigailalexanderabigailalexander
authored
Merge pull request #140 from DiamondLightSource/update-installation-docs
Update README
2 parents d915d09 + 62421c0 commit 811eba5

File tree

1 file changed

+221
-54
lines changed

1 file changed

+221
-54
lines changed

‎README.md‎

Lines changed: 221 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,15 @@
11
# cs-web-lib
2-
An npm library for Control Systems web applications
2+
cs-web-lib is a React component library for EPICS Control Systems web applications, based off CSStudio Phoebus.
33

4-
## Installation
5-
6-
:warning: cs-web-lib is **NOT** compatible with projects using create-react-app. Vite should be used instead.
7-
8-
Install via npm:
9-
`npm install @diamondlightsource/cs-web-lib`
10-
11-
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.
12-
13-
- `VITE_PVWS_SOCKET` - point to the server hosting the PVWS application.
14-
- `VITE_PVWS_SSL` - set this to false if running a local PVWS instance e.g. localhost:8080 without SSL, otherwise true
15-
16-
These should be provided in a .env file at the root of your project.
17-
18-
Inside your application, create a screen by passing a .opi, .bob or .json file to the EmbeddedDisplay widget.
19-
20-
## Legacy Installation
21-
22-
PVWS was introduced in version 0.4.0. Versions prior to this used [Coniql](https://github.com/DiamondLightSource/coniql), and the .env variables used were `VITE_CONIQL_SOCKET` and `VITE_CONIQL_SSL`.
23-
24-
React 17 was supported until version < 0.5.0.
4+
- [Features](https://github.com/DiamondLightSource/cs-web-lib#Features)
5+
- [Installation](https://github.com/DiamondLightSource/cs-web-lib#Installation)
6+
- [Development](https://github.com/DiamondLightSource/cs-web-lib#Development)
257

268
## Features
279

2810
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.
2911

30-
#### Widgets
12+
**Widgets**
3113

3214
| Category | Widget | Included | Reason |
3315
| :---------------- | :---------------: | :------: | :-----------------: |
@@ -41,14 +23,14 @@ cs-web-lib does not contain the full suite of features and widgets provided by P
4123
| Monitors | Byte Monitor | &#9989; | |
4224
| | LED | &#9989; | |
4325
| | Multi State LED | &#10060; | Add later |
44-
| | Meter | &#10060; | Add later (date unknown, low priority) |
26+
| | Meter | &#9989; | |
4527
| | Progress Bar | &#9989; | |
4628
| | Symbol | &#9989; | |
4729
| | Table | &#9989; | |
48-
| | Tank | &#10060; | Add later (date unknown, low priority) |
30+
| | Tank | &#9989; | |
4931
| | Text Symbol | &#10060; | Add later |
5032
| | Text Update | &#9989; | |
51-
| | Thermometer | &#10060; | Add later (date unknown, low priority) |
33+
| | Thermometer | &#9989; | |
5234
| Controls | Action Button | &#9989; | |
5335
| | Boolean Button | &#9989; | |
5436
| | Check Box | &#9989; | |
@@ -62,9 +44,9 @@ cs-web-lib does not contain the full suite of features and widgets provided by P
6244
| | Spinner | &#10060; | Add later (date unknown, low priority) |
6345
| | Text Entry | &#9989; | |
6446
| | Thumbwheel | &#10060; | Add later (date unknown, low priority) |
65-
| Plots | Data Browser | &#10060; | Add later (date unknown, low priority) |
47+
| Plots | Data Browser | &#9989; | Basic Implementation |
6648
| | Image | &#10060; | Unknown |
67-
| | Stripchart | &#10060; | Unknown |
49+
| | Stripchart | &#9989; | |
6850
| | XY Plot | &#9989; | |
6951
| Structure | Array | &#10060; | Add later |
7052
| | Embedded Display | &#9989; | |
@@ -73,51 +55,236 @@ cs-web-lib does not contain the full suite of features and widgets provided by P
7355
| | Tabs | &#9989; | |
7456
| | Template/Instance | &#10060; | Unknown |
7557

76-
#### Features
58+
**Methods**
7759

7860
| Widget | Included | Reason |
7961
| :---------: | :------: | :---------------------: |
8062
| Actions | &#9989; | Some actions may not be supported. Please open an issue for any issues noticed. |
81-
| Formulas | &#10060; | `sim://` PVs are supported, but not `eq://`. This will be added in future. |
82-
| Rules | &#9989; | 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.|
83-
| Scripts | &#10060; | The use of scripting is recommended against in general by CS Studio Developers. Formulae should be able to handle most use cases. |
63+
| Formulas | &#9989; | `sim://`, `eq://` and `loc://` PVs are supported. |
64+
| Rules | &#9989; | Partial support. Please open an issue for any issues noticed.|
65+
| Scripts | &#10060; | Basic PoC for scripting is currently implemented, which works for background colour and position ONLY. |
66+
67+
## Installation
68+
69+
Install via npm:
70+
71+
`npm install @diamondlightsource/cs-web-lib`
72+
73+
To use cs-web-lib in a client project, you will need:
74+
- React 18
75+
- Vite
76+
- A separate running instance of [PVWS](https://github.com/ornl-epics/pvws)
77+
78+
**Configuring PVWS**
79+
80+
To make use of PVs in cs-web-lib widgets, you need to connect to PVWS. The basic configuration parameters for this will be loaded at runtime from a JSON file. This should be located somewhere accessible at runtime such as `/public` directory. The schema/structure of the configuration file is:
81+
82+
```
83+
{
84+
PVWS_SOCKET: string
85+
PVWS_SSL: boolean,
86+
THROTTLE_PERIOD: integer
87+
}
88+
```
89+
90+
The configuration parameters are:
91+
92+
| Parameter | type | Description |
93+
|- | -| - |
94+
| PVWS_SOCKET | string | The fully qualified hostname and port of the instance of the PVWS web service |
95+
| PVWS_SSL | boolean | If true use https, if false use http for connecting to the PVWS web service |
96+
| THROTTLE_PERIOD | integer | The period in milliseconds between updates of the PV state variables |
97+
98+
At the root of your client app, create a `config.ts` file to load the config from this file.
99+
100+
```
101+
import { CsWebLibConfig } from "@diamondlightsource/cs-web-lib";
102+
103+
export const loadConfig = async (): Promise<CsWebLibConfig> => {
104+
if (config) {
105+
return config;
106+
}
107+
108+
try {
109+
// Point towards your file location
110+
const response = await fetch("/config/config.json");
111+
config = await response.json();
112+
} catch (error) {
113+
console.warn("Configuration not found falling back to defaults", error);
114+
// Set defaults here if necessary
115+
config = {
116+
PVWS_SOCKET: undefined,
117+
PVWS_SSL: undefined,
118+
THROTTLE_PERIOD: undefined
119+
};
120+
}
121+
122+
return config as CsWebLibConfig;
123+
};
124+
```
125+
126+
The final step is to wrap your application in a Redux Provider and pass in the loaded config and cs-web-lib PV store. This allows your application to access the store which handles subscribing to PVs and storing updates to values.
127+
128+
```
129+
import { store, CsWebLibConfig } from "@diamondlightsource/cs-web-lib";
130+
import { Provider } from "react-redux";
131+
import { loadConfig } from "./config";
132+
133+
function App({}) {
134+
const [config, setConfig] = useState<CsWebLibConfig | null>(null);
135+
useEffect(() => {
136+
loadConfig().then(config => {
137+
setConfig(config);
138+
});
139+
}, []);
140+
141+
return (
142+
<Provider store={store(config)}>
143+
// Your app goes here
144+
</Provider>
145+
);
146+
}
147+
148+
export default App;
149+
```
150+
151+
Now you can use cs-web-lib to display .bob files and see updates to PV values.
152+
153+
**Displaying a .bob file**
154+
155+
To view a file in the client application, make use of the display components. These are:
156+
157+
- **Embedded Display**
158+
This displays a single screen, passed in via a filepath.
159+
```
160+
<EmbeddedDisplay
161+
file={{
162+
path: "/my/file.bob",
163+
defaultProtocol: "ca" // Or "pva",
164+
macros: {}
165+
}}
166+
position={new RelativePosition("0", "0", "100%", "100%")}
167+
scroll={false}
168+
resize={"scroll-content"}
169+
/>
170+
171+
```
172+
- **Dynamic Page**
173+
This component allows dynamic loading of different files, using a FileContext to store which file is currently displayed. The application must be wrapped in the FileProvider to access this context. The executeAction function can be called to trigger changes in displayed files.
174+
```
175+
import { FileProvider } from "@diamondlightsource/cs-web-lib";
176+
177+
const INITIAL_SCREEN_STATE = {
178+
main: {
179+
path: "/my/file.bob",
180+
macros: {},
181+
defaultProtocol: "ca"
182+
}
183+
};
184+
185+
function DemoDynamicPage() {
186+
const fileContext = useContext(FileContext);
187+
188+
// Use executeAction to update the displayed file
189+
const handleClick = () => {
190+
executeAction(
191+
{
192+
type: "OPEN_PAGE",
193+
dynamicInfo: {
194+
name: "new",
195+
location: "main",
196+
description: undefined,
197+
file: {
198+
path: "/my/new_file.bob
199+
macros: {},
200+
defaultProtocol: "ca"
201+
}
202+
}
203+
},
204+
fileContext,
205+
undefined,
206+
{},
207+
"
208+
);
209+
};
210+
211+
return (
212+
<FileProvider initialPageState={INITIAL_SCREEN_STATE}>
213+
<Button onClick={handleClick}>
214+
<DynamicPageWidget
215+
location={"main"}
216+
position={new RelativePosition()}
217+
scroll={false}
218+
showCloseButton={false}
219+
/>
220+
</FileProvider>
221+
);
222+
}
223+
```
224+
225+
226+
**Using Standalone widgets**
227+
228+
cs-web-lib widgets can also be used independently of an Embedded Display or Dynamic Page widget, simply by treating them as any other React component. These must be initialised with a position, using either an `AbsolutePosition` or a `RelativePosition` object, and can be passed other properties.
84229
85230
## Development
86-
To develop on the library code first clone this repo, install the npm package dependencies and then make changes:
87231
88-
cd cs-web-lib/
89-
npm install
232+
**Install Node**
233+
234+
Install Node.js version 22+, if it is not already installed on your machine.
235+
236+
**Clone the repository**
237+
```
238+
git clone https://github.com/DiamondLightSource/cs-web-lib.git
239+
```
90240
91-
### Pushing changes
92-
Before pushing any changes check that the update code conforms to the formatter checks and that the unit tests all pass:
241+
**Install the dependencies, from the root folder of the repo run:**
242+
```
243+
npm ci
244+
```
93245
94-
npm run all-checks
95-
npm run tests
96-
97-
If making changes to the build process, check that the package is built correctly with:
246+
**To run the unit tests:**
247+
```
248+
npm run test
249+
```
98250
99-
npm run rollup
100-
npm pack
251+
**To run the static analysis and code style checks:**
252+
```
253+
npm run all-checks
254+
```
101255
102-
You can then install the generated tar.gz file into another project and check that all functionality expected is there.
256+
**To test your development version**
103257
104-
### Publishing to NPM (PREFERRED METHOD)
258+
You can install a local version of cs-web-lib into a project to test out any changes:
259+
```
260+
npm run rollup
261+
npm pack
262+
cd <PROJECT_REPO_DIR>
263+
npm install <CS_WEB_LIB_REPO_DIR>/cs-web-lib/diamondlightsource-cs-web-lib-*.*.*.tar.gz
264+
```
265+
266+
267+
### Publishing to NPM
268+
**Workflow**
105269
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.
106-
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):
270+
1. Increment the package version in package.json
271+
`npm version <major|minor|patch> -no-git-tag-version`
107272
108-
npm version <major|minor|patch> -no-git-tag-version
109273
2. Commit and push this to GitHub:
274+
```
275+
git add package.json
276+
git commit -m "..." package.json
277+
git push <remote> <branch>
278+
```
110279
111-
git add package.json
112-
git commit -m "..." package.json
113-
git push <remote> <branch>
114280
3. Create a new tag and push to GitHub
115-
116-
git tag -a vX.XX.xx -m "..."
117-
git push <remote> vX.XX.xx
281+
```
282+
git tag -a vX.XX.xx -m "..."
283+
git push tag <remote> vX.XX.xx
284+
```
118285
This will trigger a job on GitHub to publish a new version of the cs-web-lib to NPM. Check that this job passes.
119286
120-
### Publishing to NPM locally
287+
**Locally**
121288
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:
122289
1. Update the package version in package.json (follow the major.minor.patch versioning terminology).
123290
2. Run the rollup command to package the library: `npm run rollup`.

0 commit comments

Comments
 (0)