# Client - developer documentation

## File tree

```
./client/
    components/...          <-- See section Components
    cssFiles/...            <-- Contains some CSS files for the MHTL files at the root of the folder
    externalFiles/...       <-- Contains some CSS and JS files for external libraries
    jsFiles/...             <-- Contains the main JS files for the app (except the components)
    res/...                 <-- Contains the images used in the client
```

## Initialization/navigation

For a selected instrument, there is a single HTML file that holds the application : the `SEAWebClient.html` file, which is served as the main route. It includes all the JS files needed, meaning all the JS files located in the `client/jsFiles` folder excepted `SeaWebClientStart.js`, plus the external librairies (`client/externalFiles/`) and the components (`client/components/`).

The entry point is the `SEAWebClientMain.js`, which has a `window.onload` function. First, the grid that holds the different parts (graphics, console...) is computed depending on the screen size. Then, the connection with the server is initiated with the `buildUpdateConnection` function, located in `SeaWebClientCommunication.js`.

This function calls the /update route, which will initiate the SSE connection, retrieving an id, the name of the instrument and the device currently running to the client. The id will be used for all the API calls. When all this information is received, the `loadFirstBlocks()` function is called (`SeaWebClientMain.js`) to populate an array of routes to call, so we can get the content of each block sequentially. Its content is defined by the global variables defined in `SeaWebClientMain.js`, more precisely in the calling cascade of the `treat()` method on the `Settings` function (still in the same file).

The calling cascade is initiated with the `nextInitCommand()` function (`SeaWebClientMain.js`), called just after the `loadFirstBlocks()` function. Every response of each command will be treated in the switch statement of the `successHandler()` function (in `SeaWebClientCommunication.js`). Specifically, the content of each block is dynamically created in JS when the response of the different init commands are received.

## Components

A component is composed of a JS file and its CSS file. They are grouped in the folder `client/components`. A component is basically a class that inherits from `HTMLELement`, and implement the method connectedCallback, where the HTML of the component has to be defined. Then, it has to be added to the customElements via the line `customElements.define("<component-name>", <ComponentClass>)`. The component's name has to contain dash, otherwise an error is thrown.

The export popup, the dates popup and the curves settings popup are considered as components just to separate their code from the rest.

## Miscellaneous

### About instrument and device name

There is a difference between what is displayed in the top left hand corner of the left part (in the grey box) and the right part ("main" block).

In the right part, with a server started : 
- with `sea` or `influxsea` type, only the instrument name is displayed. This information is taken from SEA.

The behavior is not known for a server started with `secop` type.

In the left part, with a server started : 
- with `influxsea` or `influx` type, the instrument is taken from the command that was used to launch the server, and the device is taken from InfluxDB. More specifically, it takes the value out of the `value` field in the measurements `nicos/se_main`, `nicos/se_stick` and `nicos/se_addons`. For each of these measurements, we take the last entry in the database until the end of the visualization window. It has to be mentionned that the device name is updated at each jump in time via the dates popup (go to now or jump). The device name is formatted as `<main>[/<stick>][/<addons>]`. An url can be shown for one of these component. 
- with `sea` type, the instrument is taken from the command line used to launch the server, and device is taken from SEA (device is got with the request `samenv name`).

The behavior is not known for a server started with `dummy` type.

### 

### About updating graphics

- When the server is pushing data, the newly received data is appened to the current curves (on livemode).
- When zooming in the x direction, when the zoom is complete (for e.g. meaning that there are no longer enough mouse wheel step in a certain range of time), then the resolution is computed, the client asks for the data within the new viewing window with the given resolution, and then sets (overwrites) the data for the curves. This process is done only when zooming out, and we have zoomed in by at least 50% of the previous viewing window.

### About livemode

- A user is in livemode when the "now" date is in the viewing window. When the last point gets more recent than the right most value, the viewing window is shrinked, keeping the left mose value.
- Every plain minute, all the curves are synchronized. For the curve that have not receive any new data, their last known point is retreived at the "now" date.

### About the user configuration for the graphs

The local storage is used to save the user configuration. The key in an integer, and the value is a stringified JSON object, which looks like the following :
`{"variable":<variable>, "parameter":<parameter> [, "cat":<cat>] [, "color":<color>] [, "unit":<unit>]}`
The indicated optionnal options are saved only if a value was provided for them.

When it is sent to the server, an entry from the local storage is transformed in this way :
`{"<variable>.<parameter>":{["cat":<cat>] [[,] "color":<color>] [[,] "unit":<unit>]}}`
The indicated optionnal options are sent only if a value was provided for them.


## External libraries

| Name                       | Version   | Website                                |
| -------------------------- | -------   | -------------------------------------- |
| AlertifyJS                 | v1.8.0    | http://alertifyjs.com                  |
| ChartJS                    | v2.9.4    | https://www.chartjs.org                |
| \+ Zoom plugin for ChartJS | v0.7.3    | https://www.chartjs.org                |
| EventSource                | unknown   | https://github.com/Yaffle/EventSource/ |
| Hammer.JS                  | v2.0.7    | http://hammerjs.github.io/             |
| Swipper                    | v11.1.12  | https://swiperjs.com                   |
