Update WebDisplay.md file

linev · linev · commit 394a1112efed · 2025-04-02T12:47:36.000+02:00
diff --git a/documentation/users-guide/WebDisplay.md b/documentation/users-guide/WebDisplay.md
@@ -7,6 +7,8 @@ In this chapter discussed how web-based display can be created in the ROOT.
 Idea of web displays is implementation of user interface, which can run remotely
 or locally in the web-browsers, fully decoupled from the application code.
 For the communication between application and browser websockets are used.
+On the server side ROOT application runs THttpServer instance which serves one or
+several clients. Client is any web browser
 
 
 ## Creating web-window
@@ -46,44 +48,21 @@ win->SetDataCallBack([](unsigned connid, const std::string &msg) {
 ```
 
 Here **connid** is unique identifier, which assign to each connection when it is established.
-There are several predefined messages kinds: **"CONN_READY"** when new connection established and
-**"CONN_CLOSED"** when connection is closed by client.
 The connection identifier should be used when sending message to the client:
 
 ```{.cpp}
 
-// get connection id for the first connection in the list
-
-if (win->NumConnections() > 0) {
-   unsigned connid = win->GetConnectionId();
-   std::string msg = "Hello, world";
-   win->Send(msg, connid);
-}
+unsigned connid = win->GetConnectionId(); // first connection
+std::string msg = "Hello, world";
+win->Send(connid, msg);
 
 ```
 
-## Display window
-
-To display window in the browser, one should call `win->Show()` method.
-This will starts new window (or new tab) in the default browser and show content of HTML page,
-configured for the window. As argument of `Show()` method one can specify browser kind like
-"chromium" or "firefox" or just full path to the program which should be invoked.
-With the method `win->GetUrl()` one obtains URL string, which can be typed in the browser address string directly.
-
-Same window can be displayed several times in different browsers or different browser tabs - one only
-must allow appropriate number of connections calling `win->SetConnLimit(3)`
-
-For the local displays **Chromium Embeded Framework (CEF)** is used. It provides functionality
-of Chrome web browser in ROOT application without need to create and start real http server.
-If CEF was configured correctly, it is enough to call `win->Show("cef")` to display window in CEF.
-
-
 ## Client code
 
-There is no limitations which framework should be used on the client side.
 The minimal HTML/JavaScript code, which establish connection with the server, looks like:
 
-``` {.html}
+```{html}
 <!DOCTYPE HTML>
 <html>
    <head>
@@ -116,3 +95,65 @@ The minimal HTML/JavaScript code, which establish connection with the server, lo
 </html>
 
 ```
+
+Here `jsroot/webwindow` module is loaded to let establish connection with ROOT application.
+It includes all necessary initialization and authentication of websocket connection with the server.
+Beside this part there is no limitations which HTML/JS framework should be used to organize layout and code on the client side.
+
+
+## Display window
+
+To configure web display one uses `--web=<kind>` argument when starting ROOT.
+Typical values are:
+
+- "chrome": select Google Chrome browser for interactive web display
+- "firefox": select Mozilla Firefox browser for interactive web display
+- "edge": select Microsoft Edge browser for interactive web display
+- "qt6": uses QWebEngine from Qt6, no real http server started (requires `qt6web` component build for ROOT)
+- "cef": uses Chromium Embeded Framework, no real http server started (requires `cefweb` component build for ROOT)
+- "default": system default web browser, invoked with `xdg-open` on Linux, `start` on Mac or `open` on Windows
+- "off": turns off the web display and comes back to normal graphics in  interactive mode.
+
+Alternatively one can call `gROOT->SetWebDisplay("<kind>")` to specify display kind.
+Same argument can be provided directly to the `RWebWindow::Show()`.
+
+With the method `win->GetUrl()` one obtains URL string, which can be typed in the browser address string directly.
+
+
+## Use ROOT web widgets on the remote nodes
+
+It is advised to use the `rootssh` script with built-in port forwarding and run
+the user interface on the local host with the default web browser. Like:
+
+    [localhost] rootssh username@remotenode
+
+As with regular `ssh`, one can specify command which should be run on remote node:
+
+    [localhost] rootssh username@remotenode "root --web -e 'new TBrowser'"
+
+Script automatically creates tunnel and configures several shell variables in remote session. These are:
+
+- `ROOT_WEBGUI_SOCKET` - unix socket which will be used by ROOT `THttpServer` in webgui
+- `ROOT_LISTENER_SOCKET` - unix socket which gets messages from ROOT when new web widgets are started
+
+When on remote node in ROOT session new web widget is created, default web browser will be started on the local node and display created widget.
+
+It is highly recommended to use `rootssh` script on public nodes like `lxplus`. Unix sockets, which are created on
+the remote session, are configured with `0700` file mode - means only user allowed to access them.
+
+One can provide `--port number` parameter to configure port number on local node and `--browser <name>` to specify
+web browser executable to display web widgets. Like:
+
+    [localhost] rootssh --port 8877 --browser chromium username@remotenode
+
+Also any kind of normal `ssh` arguments can be specified:
+
+    [localhost] rootssh -Y -E file.log username@remotenode
+
+On remote node root session should be started with `root --web` argument to advise ROOT use web widgets. Like:
+
+    [remotehost] root --web hsimple.C
+
+[`rootssh` script](https://raw.githubusercontent.com/root-project/root/master/config/rootssh) can be download and used independently from ROOT installation - it is only required that supported ROOT version installed on remote node.
+
+
