Allow to have a web-based GUI for controllers

[sapetnioc]

First, the base web elements defined in Capsul 3.0 must be moved in soma-base. Then a controller specific extension must be done. This extension would be developed first for serverless QtWebEngine implementation because it natively supports a runJavaScript() method (via QWebEnginePage class) allowing execute JavaScript code in the browser from Python application. This method makes it possible to update web view as a result of some controller events. For a real web server implementation, this Python -> browser permanent link will require the use of a WebSocket. This starts to be complex enough to provide a production ready web server for GUI. For this a Python web framework supporting WebSockets must be chosen (for instance Sanic or Django).

[sapetnioc]

The web interface start to work quite well but I am facing an important problem for the creation of new list items for complex types (i.e. anything except str, int and float). Creation of new items required to add new elements in the web page. But such elements are being created via HTML produced in Python (through Jinja2 templating). I need to be able to do the same from javascript. I could do it by calling the Python server who would return a piece of HTML that would be interpreted by the client Javascript before being inserted in the DOM. But I had an idea for a much more clean solution that could also allow to completely get rid of Jinja2.

The problem is that Javascript client can only read/modify controller values (via calls to Python backend) but has no access to controller types. If we can serialize the whole tree of controller data types, we could completely separate the HTML rendering in Javascript from the Python backend that would only serve controller values and types. For this, we need a Javascript and Python compatible language allowing to represent the whole complexity of a controller type. Fortunately, such a language exists: JSON Schema. Therefore, I will start to work on exporting a controller type to a JSON Schema compliant structure.

Here is an example of what this schema could look like. I took the example controller I am being working on:

class SubController(Controller):
    s: str = 'a string'
    i: int = 42
    n: float = 42.42
    bt: bool = True
    bf: bool = False
    e: Literal['one', 'two', 'three'] = 'two'
    f: File = '/somewhere/a_file'
    d: Directory = '/elsewhere/a_directory'
    ls: field(type_=list[str], default_factory=lambda: ['a string', 'another string'])
    li: field(type_=list[int], default_factory=lambda: [42, 24])
    ln: field(type_=list[float], default_factory=lambda: [42.24, 24.42])
    lb: field(type_=list[bool], default_factory=lambda: [True, False])
    le: field(type_=list[Literal['one', 'two', 'three']], default_factory=lambda: ['one', 'two'])
    lf: field(type_=list[File], default_factory=lambda: ['/somewhere/a_file', '/elsewhere/another_file'])
    ld: field(type_=list[Directory], default_factory=lambda: ['/somewhere/a_directory', '/elsewhere/another_directory'])
    ok: field(type_=OpenKeyController[str], default_factory=lambda: OpenKeyController[str]())

class VisibleController(SubController):
    o: field(type_=SubController, default_factory=lambda: SubController())
    lo: field(type_=list[SubController], default_factory=lambda: [SubController(), SubController()])

After a manual attempt to convert it to JSON Schema, I ended with the following JSON object:

{
    "$id": "http://localhost:8080/schemas/id_of_a_controller",
    "$schema": "https://json-schema.org/draft/2020-12/schema",

    "$defs": {
        "file": { "type": "string", "brainvisa": { "path_type": "file" }},
        "directory": { "type": "string", "brainvisa": { "path_type": "directory" }},

        "SubController": {
            "type": "object",
            "properties": {
                "s": { "type": "string" },
                "i": { "type": "integer" },
                "n": { "type": "number" },
                "bt": { "type": "boolean" },
                "bf": { "type": "boolean" },
                "e": { "enum": ["one", "two", "three"] },
                "f": { "$ref": "#/$defs/file" },
                "d": { "$ref": "#/$defs/directory" },
                "ls": { "type": "array", "items": { "type": "string" }},
                "li": { "type": "array", "items": { "type": "integer" }},
                "ln": { "type": "array", "items": { "type": "number" }},
                "lb": { "type": "array", "items": { "type": "boolean" }},
                "le": { "type": "array", "items": { "enum": ["one", "two", "three"] }},
                "lf": { "$ref": "#/$defs/file" },
                "ld": { "$ref": "#/$defs/directory" },
                "ok": { "type": "object",
                    "brainvisa": {
                        "new_items": { "type": "string" }
                    }
                }
            }
        },

        "VisibleController": {
            "allOf": [{ "$ref": "#/$defs/SubController" }],
            "o": { "$ref": "#/$defs/SubController"},
            "lo": {
                "type": "array",
                "items": { "$ref": "#/$defs/SubController" }
            }
        }
    },
    
    "allOf": [{ "$ref": "#/$defs/VisibleController" }]
}

I had to include some custom properties for some types that, AFAIK, are not covered by JSON schema: File, Directory and OpenKeyController. For these type, I chose to put any custom information in a single brainvisa attribute. The result is not very human friendly but is relatively easy to parse to allow a fully dynamic generation of controller GUI in Javascript.