GUI - Web UI
Introduction
CDP supports Web UI in multiple ways. One way is to use our Web UI wizard that will make the native GUI possible to load in web browser using WebAssembly. For non-GUI application it will first add the GUI that you can then edit in Design mode. This is the easiest way as it has all the GUI widgets available and works out-of-box, no coding involved. This solution is better suited for industrial UIs on larger screen. See How To Show Existing GUI in Web Browser, How To Add Web UI to an Application or How To Create New Web UI Application for more information.
Another way is to use our HTML5 UI wizard that will generate a demo GUI, using our JavaScript client, possible to load in web browser. This is a more standard way for creating web UIs, but leaves most of the work to the user as it doesn't provide ready-made widgets. It also fits better for mobile targets due to better responsiveness and virtual keyboard support. See How to Use JavaScript in Web HMI GUI for more information.
WebAssembly
Most new web browsers support WebAssembly, meaning it is possible to load code generated with C++. This makes it possible to run the same native GUI, that you are used to run on local PC, in a web browser. All setup is done by our CDP Studio wizard to allow CDP application to act as a web server.
- How To Show Existing GUI in Web Browser
- How To Add Web UI to an Application
- How To Create New Web UI Application
Customization
When opening the web page, initially a loading screen is displayed while in the background the page is connecting to the CDP system. The loading screen (including the CDP Studio logo) can be modified in Code mode. In the project tree, expand the application you added the web UI and under Other files find the exact folder where you added the web UI. There you will find the index.html and logo.svg files. The logo can simply be replaced with the logo of your own company. The index.html however allows for more customizations, for example:
- Modify the progress and error messages displayed to the user. Look for the line
status.innerHTML = loaderStatus + "...";
- Embed the CDP web UI in your custom frame. This can be done as whole drag-and-drop web UI is rendered in a single HTML
canvas
element.
Global Variables
The WebAssembly UI loader looks for some global variables to customize the loading process. The variables can be defined in two ways:
- In the URL query string, e.g. http://127.0.0.1:8000?cdpUrl=10.0.2.65:7689
- As a Javascript variable in the global scope, e.g.
var cdpUrl = "10.0.2.65:7689";
These variables are:
- cdpUrl (e.g. "10.0.2.65:7689") - the address of the CDP application to connect to (look for something like "StudioAPIServer: listening on 10.0.2.65:7689" in the Application Output pane to find the value for
cdpUrl
). Normally, this is not needed as when the CDP application serves the Web UI, the address is auto-detected. However, it is necessary to specify thecdpUrl
when using a custom web server to host the web UI. - cdpResourceUrl (e.g. "localhost:8000/www/wasm") - this will load the GUI resources (including "/mainwidget.ui" and "/Models/Models.tar.gz") from the specified URL instead of the CDP application. This can be useful when embedding the CDP web UI in your custom frame. Note, beware of the same-origin policy when using this variable, cross-domain requests will not work unless allowed in the HTTP headers sent by the web server.
- cdpCredentials (e.g. "Username=user;Password=goodpass") - this will automatically log in to the CDP application with the specified credentials. The format is a semicolon-separated
<key>=<value>
list. Note, as the credentials are publicly visible, this is most useful for providing a read-only access to some public data in a CDP application. Refer to the Security Configuration manual for setting up user accounts and permissions. - cdpGuiPropertyOverrides (e.g. "label_1.cdpRouting=MyApp.MemUsed;label_2.text=Some text") - this will override the GUI properties of the mainwidget.ui file. The format is
<widget>.<property>=<value>
, multiple overrides can be separated by a semicolon. This will allow to use a single GUI file for multiple components, just override the properties that are different.
Note: The semicolon-separated list used in the cdpCredentials
and cdpGuiPropertyOverrides
variables requires quoting the value if it contains a semicolon. If the value also contains a quote, it must be escaped with a backslash. In addition, remember that when using the URL query string, the string must be URL-encoded or when using a Javascript variable, the string must be properly escaped.
For example, here is how to set the cdpCredentials
when the username is User&="'
and the password is passw&=;"'
- URL query string:
?cdpCredentials=Username="User%26=\"\'";Password="passw%26=;\"\'"
- Javascript variable:
var cdpCredentials = String.raw`Username="User&=\"\'";Password="passw&=;\"\'"`;
Limitations and Known Issues
- Virtual keyboard does not work properly on iOS and Android. The workaround is to use our integrated keypad by enabling PadType on any input widget.
- Custom graphics referenced in the mainwidget.ui file is loaded from next to the mainwidget.ui file.
- No support for custom widgets and resource files.
- Export functionality in graph widgets is not available.
- No screen reader support.
- QuickWidget widget is not working.
- QML is not supported.
HTML5 + Javascript
Web UIs for CDP Applications are supported by built-in web server in the StudioAPIServer component and the reflection API for CDP called StudioAPI, provided by the same StudioAPIServer component.
StudioAPI is a protocol that uses HTML5 web-sockets for transport and Google Protocol Buffers for serializing structured data. It provides an API to interrogate CDP Application structure, get any value in the structure, set any writable value in the structure, subscribe to receive all value changes for any value and subscribe to receive changes to the structure.
For Web UIs the HTML5 web-sockets is provided by all modern browsers and StudioAPI client is provided by JavaScript implementation. The client implementation has a single direct dependency in decodeIO's protobuf.js.
Web UI Implementation
Web UIs can be implemented with various JavaScript web frameworks. The demo is provided as an API demonstration only and is not intended for production use.
No specific web development tools are provided by CDP Technologies AS. It is recommended to use industry standard tools for this purpose.
JavaScript Client Limitations
Currently the JavaScript client implementation provided in the demo, supports connecting to a single CDP Application. Multi application Web UIs are still possible but a separate client object is needed for each application that is created and maintained in user code.
Common Issues
Here are some of the common problems people may encounter when developing web interfaces for CDP applications.
The Web UI Doesn't Load or Loads Partially
WebFilesToServe
Using CDP Studio Configure mode, check the WebFilesToServe property of your application. Verify that the property lists all files or folders required by the Web UI.
If it still does not work, use your browser's debugging functionality (usually opens with F12) to try to resolve the issue. The browser Console log often gives some insight.
Content Security Policy
When your web application shows empty page in browsers it can be that the web application utilizes some Cross Site Scripting (XSS) or inline scripting or styling techniques that are not allowed by the Content Security Policy (CSP). CDP web server applies restricting and secure CSP HTTP header to every response to mitigate XSS and other cybersecurity risks on modern browsers.
The case can be verified by looking at the browser console, by pressing F12 in the browser and choosing Console tab.
When the web browser console contains CSP errors (like the ones shown in the example screenshot above), then you should:
- first try to refactor the web application not to use XSS (for example by downloading the needed files and loading them locally), or if that is not possible, then
- adjust (relax) the CSP policy to match your web application need. This can be done by adding a <meta http-equiv="Content-Security-Policy" ...> header into the application html file, between the <head> and </head> tags. When this meta tag is existing in the html file, then the CDP web server is not sending a default restricting and most secure Content-Security-Policy HTTP header any more for this html file and the page is therefore using the policy you added into the <meta> tag.
For a start, you can add the following quite non-restricting meta tag to the application html:
<meta http-equiv="Content-Security-Policy" content="default-src * 'unsafe-inline' 'unsafe-eval' data:; base-uri 'self'; form-action 'self'">
Then re-start the web application and verify if the CSP errors are gone and web application is now showing up correctly. After that you should adjust the CSP to be more matching with the application actual need.
Note: Relaxing the security-requirements for your web-application causes it to be less secure and more easily exploitable. You should not use the non-restricting meta tag provided here in production or mission-critical web applications. Instead you should try to refactor the application not to use XSS or inline scripting and styling or if this is not possible allow cross loading of scripts or styles only from the sites that are actually needed by the web application. See Content Security Policy Quick Reference Guide for options and examples.
Samsung Internet Fails to Connect
On Samsung Android phones, when using the Samsung Internet as the web browser, the Web UI appears but fails to connect to the running CDP application meaning that values do not change. The reason is Samsung Internet blocks unsecured websocket connections and the solution is to enable Use Encryption in the CDP Studio Security tab. Refer to the Security Configuration for a description of how to do that.
Multi-app Connection Fails When Encryption is Enabled
When Use Encryption (https) is enabled in the CDP Studio Security tab, by default a self-signed certificate is used. If you open the Web UI now, the browser will give a security warning and ask if you trust the self-signed certificate. If you accept the certificate, the Web UI will appear and connection to the application that hosts the Web UI will work. However, when trying to access values from other CDP applications in the network, the browser security model will silently deny the connections without asking the user to accept these certificates as well.
There are several possible solutions to this problem:
- Use a trusted certificate instead of the default self-signed one.
- When creating your CDP system, forward all values to the application that hosts the Web UI. For example when App1 hosts the Web UI but needs to show CPULoad signal of App2, add a new CDPSignal to App1 with Routing set to "App2.CPULoad" and make the Web UI refer to the new App1 signal which is forwarding the value. This workaround is also useful to get around the JavaScript client limitation that there is no automatic multi-app connection.
- Manually accept the certificate of each CDP application by opening the CDP Browser Web UI of every application in your web browser. This solution is recommended just for testing and debugging.
Get started with CDP Studio today
Let us help you take your great ideas and turn them into the products your customer will love.