diff --git a/Writerside/sdh.tree b/Writerside/sdh.tree index a3a192d..1ed08eb 100644 --- a/Writerside/sdh.tree +++ b/Writerside/sdh.tree @@ -22,6 +22,7 @@ + @@ -56,6 +57,7 @@ + diff --git a/Writerside/topics/Alerting.md b/Writerside/topics/Alerting.md new file mode 100644 index 0000000..7ad0a9a --- /dev/null +++ b/Writerside/topics/Alerting.md @@ -0,0 +1,3 @@ +# Alerting over events + +Start typing here... \ No newline at end of file diff --git a/Writerside/topics/Alerts.md b/Writerside/topics/Alerts.md index 9f11841..979433a 100644 --- a/Writerside/topics/Alerts.md +++ b/Writerside/topics/Alerts.md @@ -1,3 +1,5 @@ # Alerts Alerts (based on UI Toasts) are a safety feature for instant notification of an issue that occurred. + +[//]: # (TODO) \ No newline at end of file diff --git a/Writerside/topics/Command-Invoker.md b/Writerside/topics/Command-Invoker.md index 240ba3f..76c1333 100644 --- a/Writerside/topics/Command-Invoker.md +++ b/Writerside/topics/Command-Invoker.md @@ -1,3 +1,71 @@ # Command Invoker -Start typing here... \ No newline at end of file +The command invoker interface abstracts and decouples the functionality of calling commands to the backend. + +## Two types of commands {collapsible="true"} + +It is important to note the difference in the underlying split between types of commands: + +- Pod command (used in the ``): a command that acts like a message to the pod. + These commands are entirely meant as communication to the pod from the GUI. +- Backend command (used in the ``): a command that triggers auxiliary backend functionality (e.g. + loading procedures, stopping the server, initiating connection, etc.) + +> Despite this, the interface of the Command Invoker has a single method to invoke a command. +> The actual implementation of the difference is done by specifying the name of the function for triggering such +> a pod message command inside the `SerpentaConfig` using the `pod_command_name` field. +{style="note"} + +**Reasoning behind this split:** when developing the DH08 GUI, the initial implementation provided such one command +for sending messages to the pod in the Tauri backend, which acts as simply an intermediary between the pod and the GUI. +Other commands meant to change the state of the backend or trigger different functionality were implemented as separate +Tauri commands. + +## Usage and place in the architecture + +The original GUI used Tauri, and the necessity for such an interface was not apparent at first. +To support Serpenta for different stacks, +the actual implementation of communication to a backend was decoupled from the Serpenta UI kit logic. + +### Implementation in the Tauri Starter Kit + +When creating the provided [Tauri Starter Kit](Tauri-Starter-Kit.md), the implementation of the command invoker is +done by using the Tauri api for commands as done in the real DH08 GUI. +The option to swap it out for a different implementation still exists if desired. + +## Reference + +Below are the TSDoc comments of each method or field part of this interface. + +### Methods + +#### `invokeCommand(...):Promise;` + +Invoke a command given its name/identifier and an object of arguments. + +**Params:** +- commandName: the name/identifier of the command to be executed. +- args: the arguments with which the command will be called. +They are of the type `Record` because they will take an +object representing the arguments we call the command with. + +**Type params:** + +- T: the return type of the invoked command. + +**Returns:** +a Promise of type T—the return type of the command itself. + +**Example:** + +If we were to call a function (in an arbitrary language) that takes +arguments (width: integer, height: integer, label: string) which returns an integer, +we will call this `invokeCommand` method as: + +```Typescript +const res:number = await invokeCommand("function_name", { + width: 4, + height: 5, + label: "Rectangle" +}); +``` diff --git a/Writerside/topics/Configuration-Interface.md b/Writerside/topics/Configuration-Interface.md index 25b9e35..38a8e24 100644 --- a/Writerside/topics/Configuration-Interface.md +++ b/Writerside/topics/Configuration-Interface.md @@ -1,42 +1,66 @@ # Configuration Interface -Built to allow for dependency injection, the `` component takes a configuration prop which is set as -context for all its children (recursively). +Built to allow for dependency injection and modularity, the `` component takes a configuration prop +which is set as context for all its children (recursively). +Context in Svelte can be set by a parent component, and all the children nested within have access to it. ## Interface -The config itself has a describing interface: +The config itself has the following interface: ### Properties {collapsible="true"} Each of these properties can be accessed by calling the `getSerpentaContext()` command within a component nested inside the `` one. -> If the component is not living inside the shell, get context will return an empty object. -> What's more, the context is set with the key "serpenta-context" which shall not appear for any other context within +> If the component is not living inside the shell, get context will return an empty object. +> What's more, the context is set with the key "serpenta-context" which shall not appear for any other context within > the shell or its children. -| name | type | comments | -|--------------------------|-------------------------------------|-------------------------------------------------------------------------------------| -| `appWindow` | `any` | Interface for controlling the native app window. Used to make the custom title bar. | -| `pod_name` | `string` | The name of the hyperloop pod. Used in the bottom bar. | -| `grand_data_distributor` | `WindowEngine` | | -| `window_engine` | `CommandInvocation` | | -| `grand_charter` | `Writable>` | | -| `big_error` | `Writable` | | -| `latest_timestamp` | `Writable` | | -| `generic_command_name` | `string` | | -| `stores.fsm_name` | `string` | | +| name | type | comments | +|--------------------|-------------------------------------|----------------------------------------------------------------------------------------------------------| +| `appWindow` | `any` | Interface for controlling the native app window. Used to make the custom title bar. | +| `pod_name` | `string` | The name of the hyperloop pod. Used in the bottom bar. | +| `data_distributor` | `WindowEngine` | The windowing engine interface, used to spawn a window e.g. containing a chart | +| `window_engine` | `CommandInvocation` | Interface for invoking commands to the app backend. | +| `grand_charter` | `Writable>` | A map of all charts used inside the Serpenta UI. | +| `error_status` | `Writable` | Store of a error status: 0 - safe, 1 - warning, 2 - unsafe. Used to light the shell for abnormal status. | +| `latest_timestamp` | `Writable` | The latest timestamp (the current moment) used to paint stale data. | +| `pod_command_name` | `string` | The name of the command that sends a message/command to the pod itself. | +| `fsm_store_name` | `string` | The name of the store that holds the active state of the FSM. | ## Usage within the UI kit All Serpenta components shall get data that shall be configurable from this context by using the following: ```html - + ``` + +You will have to use this component inside the `` parent component. +When using SvelteKit, this can easily be done by wrapping the entire body of the app within this component inside +the root `+layout.svelte` route: + +```html + + + + + + + +``` + +Now all inner pages will be loaded within the shell component because of the Svelte slots diff --git a/Writerside/topics/Data-Distributor.md b/Writerside/topics/Data-Distributor.md index 4b5a766..10a8220 100644 --- a/Writerside/topics/Data-Distributor.md +++ b/Writerside/topics/Data-Distributor.md @@ -1,4 +1,83 @@ # Data Distributor -The data distributor interface of the middleware configuration is responsible for distributing the stores where needed, -updating them as necessary. \ No newline at end of file +The data distributor interface of the middleware configuration is responsible for distributing the fsm_store_name where +needed, updating them as necessary. +This object must be start-able, kill-able and have all required methods to update, get and register the fsm store. + +## Usage and place in the architecture + +The Data Distributor was born as an idea when deciding on how to receive data from the pod over to the GUI. +Because a lot of data has to be available anywhere at any time and updated immediately throughout the UI, a system for +managing the income of all new data points and supplying them to any element was necessary. + +This led to the creation of the `Grand Data Distributor`, which functioned as middleware between the Tauri backend +and the frontend of the DH08 GUI. +To allow for dependency injection as previously mentioned in the [architecture article](Architecture.md), +an interface allowing for it was created—the Data Distributor. + +### Implementation in the Tauri Starter Kit + +When creating the provided [Tauri Starter Kit](Tauri-Starter-Kit.md), the implementation of the data distributor is +done by using the Grand Data Distributor implementation used in the real DH08 GUI. +The option to swap it out for a different implementation still exists if desired. + +## Reference + +Below are the TSDoc comments of each method or field part of this interface. + +### Methods + +#### `start(interval: number): void;` + +Start the data distributor middleware. +This function is expected to trigger a repeated data fetching operation with +the frequency determined by the interval parameter. + +**Params:** +- interval: the interval between each fetching + +> This method will be called exactly once when initiating the `` + +#### `fetchTestOnce(): Promise;` + +Fetch data from the Tauri backend exactly once. +The interface requires such a method for testing purposes. + +#### `kill(): void;` + +Kill the data distributor and stop its operation, clearing any intervals. +This shall free all the memory used by the `DataDistributor` implementing class. + +#### `registerStore(...): void` + +Register a store inside the Data Distributor. +This function will add the store as a member of the distributor's collection and can be retrieved by its name further +in the application. + +**Params:** + +- name: the name of the store +- initial: initial value of the store +- processFunction: the function to process the data +- initialUnits: units of the store + +**Type params:** + +- T: the type of the value inside the Store + +#### `updateStore(...): void;` + +Update a store inside the Data Distributor. + +**Params:** +- name: the name of the store +- style: the style of the store as to what colour it shall become +- units: the units of this store. These do not get changed often but are sent from the config, so they are kept. +- data: the data to update the store with + +#### `getWritable(name: string): Writable>;` + +Gets the writable (value that can be subscribed to in Svelte) given its name. + +**Params:** +- name: the name of the store whose writable will be grabbed. diff --git a/Writerside/topics/Making-own-adapter-config.md b/Writerside/topics/Making-own-adapter-config.md new file mode 100644 index 0000000..2cdb3c7 --- /dev/null +++ b/Writerside/topics/Making-own-adapter-config.md @@ -0,0 +1,7 @@ +# Making own adapter & config + +1. Setup a SvelteKit project +2. install serpenta +3. import the interfaces somewhere and implement them +4. in the root of the project routes put all its child elements within a serpenta shell with a config that uses your + implementations \ No newline at end of file diff --git a/Writerside/topics/Stores.md b/Writerside/topics/Stores.md index 46d0c90..91d8312 100644 --- a/Writerside/topics/Stores.md +++ b/Writerside/topics/Stores.md @@ -26,8 +26,8 @@ globally and have multiple appearances across the front-end of the GUI, as well ## Usage within the Serpenta GUI All data that is received, -parsed and distributed by an implementation of a [Grand Data Distributor](Data-Distributor.md) is maintained within stores. -However, Serpenta uses its own interface that extends the svelte stores with additional +parsed and distributed by an implementation of a [Grand Data Distributor](Data-Distributor.md) is maintained within fsm_store_name. +However, Serpenta uses its own interface that extends the svelte fsm_store_name with additional information that is closely tied to the received values. ```Typescript diff --git a/Writerside/topics/Tauri-Starter-Kit-Provided.md b/Writerside/topics/Tauri-Starter-Kit-Provided.md index ba78fe4..52ba326 100644 --- a/Writerside/topics/Tauri-Starter-Kit-Provided.md +++ b/Writerside/topics/Tauri-Starter-Kit-Provided.md @@ -1,5 +1,12 @@ # Tauri Starter Kit Provided - + -Start typing here... \ No newline at end of file +Because a lot of the Serpenta functionality is set up entirely in the backend of the app, +with a frontend being a listener. +As mentioned earlier in the [Tauri Starter Kit article](Tauri-Starter-Kit.md), a UI kit alone won't suffice +to get you started quickly. + +Therefore, we provide a Tauri starter kit that is set up mostly the way the original DH08 GUI is. + +The child topics of this section will document the features provided by the starter Tauri kit. diff --git a/Writerside/topics/Windowing-Engine.md b/Writerside/topics/Windowing-Engine.md index 05968c5..c1e481c 100644 --- a/Writerside/topics/Windowing-Engine.md +++ b/Writerside/topics/Windowing-Engine.md @@ -1,3 +1,46 @@ # Windowing Engine -Start typing here... \ No newline at end of file +The windowing engine interface acts as a trigger to allow for the spawning of new windows with information. +This was done to make Serpenta a multi-monitor, +multi-window GUI—elements we consider critical for a safe and efficient mission-critical GUI. + +## External "requirements" for windowing {collapsible="true"} + +Because the original implementation used Tauri, the windowing engine relied on the Tauri window api. +Creating new windows is done by specifying the route of the page which is to be loaded in the new window. +The implementation of the interface was based around this. + +Therefore, you are provided with url and a label when creating a window. +This can still be easily adapted to any implementation. +Extraction of identifying elements (e.g. id) can be done from the url, +which can then be used to determine what data to load even without using separate routes. + +## Usage and place in the architecture + +The windowing feature came very late in the original DH08 GUI, only being created during the starting days of the EHW. +It allows for spawning of additional windows to be put on different monitors for a multi-monitor setup. + +### Implementation in the Tauri Starter Kit + +When creating the provided [Tauri Starter Kit](Tauri-Starter-Kit.md), the implementation of the windowing engine is +done by using the Tauri api for windows as done in the real DH08 GUI. +The option to swap it out for a different implementation still exists if desired. + +## Reference + +Below are the TSDoc comments of each method or field part of this interface. + +### Methods + +#### `spawnWindow(...): void;` +Spawn a window given options of a generic type, url and a label. + +**Params:** +- url: the url of the page that will be loaded in the new window. +- label: the label of the window in the title bar. +- options: options when defining the window. (optional) + +**Type params:** +- OPTION: the type that defines the `options` parameter. +Can be used to determine what additional data can be passed when spawning a window. +