Open Sander3003 opened 1 year ago
General architecture can uploaded to .github
This is the original architecture proposal (not exactly what was implemented) from summer of 2020, converted to markdown format. Please feel free to use this as you wish.
Any comment is welcome!!!
The web platform is the most ubiquitous and battle-tested technology available for user interface implementation today. Because its user interfaces may be declared using dialects of XML
, it runs in browser environments containing the world's most reliable and optimized XML
parser and DOM
API implementations.
We propose to use this readily available technology throughout the next version of the OpenSCD
XML
editor.
This is a cartoon representation of the proposed architecture of each individual WebComponent representing a part (e.g. editor pane, editable element, user interface element, plugin etc.) of the OpenSCD
app, which is at the top level itself a WebComponent making use of (i.e. rendering as parts and delegating updates to) its WebComponent children:
. ----- action : Event <----
/ \
| |
v |
update(action) : void render(model) : HTML Node
| ^
| |
\ /
---> model : XML Node ----
The proposed architecture is inspired by Flux
, the Elm
architecture, cycle.js
's "Model, View, Intent" architecture, and reactive user interface design in general (React
, RxJS
etc.) . Of these, it is closest to Elm
's "Model, View, Update" functional architecture, the major caveat being our effectful manipulation (update
) of the mutable state (model
) encapsulated in WebComponent properties and attributes instead of functionally producing new immutable state as a function of old immutable state and incoming action.
The view (represented above by
render,
a function of themodel
) represents the "query" part of CQRS, presenting relevant parts of the model to the user without modifying anything in the model.The
update
function above represents the "command" part of CQRS, modifying the model in response to user triggered events without modifying anything about the view.
OpenSCD
would achieve modularity and encapsulation through pervasive use of LitElement
WebComponents. Each WebComponent consists of an entire model
-> render
-> action
-> update
cycle -- importing, containing, and using other web components as needed (1 to n
"has-a" relationships). The top level container element is the <open-scd>
LitElement
.
We store the model of each WebComponent entirely in the component's properties and attributes.
Our top level (<open-scd>
) model is at its core just a regular XMLDocument
we get from the browser's DOMParser
Web API by parsing the SCL
file to be edited upon opening it, decorated with a bit of extra user interface state like:
undo
/redo
history) ?Models of individual editor components (e.g. editor panes, modules, plugins) similarly consist chiefly of collections of XML
Node
s representing parts of the parent element's model.
render
)The view of each WebComponent is defined in its LitElement
render()
method depending exclusively on the element's attributes and properties (what would otherwise be function parameters in an Elm-like FRP
approach). It gets called automatically whenever relevant attributes or properties change and returns the updated view in the form of pure HTML
and CSS
.
A user action is a semantic event representing some user intention (e.g. "change bay name") that is emitted by the WebComponent upon any one of a set of browser events (e.g. click
, keydown
, touch
) and handled by the element's update
event handler (or selection of event handlers).
Each user action Event
is handled by an event handler appropriate to the event type (e.g. onnamechange
handling NameChangeEvent
s). These event handlers defined on each WebComponent with the corresponding faculty are represented in above architecture cartoon by the update
function.
These patterns promoted by the team behind LitElement
should prove helpful in development:
currentView
property in the top level component keeping track of the view currently being rendered.lazyLoad
directive for importing both "internal" editor modules (e.g. views) and "external" plugins dynamically when needed.WASM
schema validator) to enable synchronous rendering of components upon completion.Thanks @ca-d!
As a (potentail) developer I would like to know the exsisting architecure decissions So I can understand why choices are made and base my decision on these choices or challenge them.
Acceptance criteria: Upload existing documentation of @ca-d to a docs folder in this repository.