Overview
The Web Browser Display (available since 2016.01) can display URL's that are configured for a topology node of the Interactive Forecast Display in the topology.xml.
Steps to integrate the embedded WebBrowserDisplay (2018.01 and before)
To use the Web Browser Display, do the following.
- Create <explorerTask> placeholder in the Explorer.xml
- Extend the <nodes> in the Topology.xml with URLs to display relevant web content (see examples at 2018.02 and onwards)
Explorer.xml (2018.01 and before)
<explorerTask name="Web Browser Display"> <iconFile>document.png</iconFile> <mnemonic>h</mnemonic> <taskClass>nl.wldelft.fews.gui.plugin.webbrowser.WebBrowserDisplay</taskClass> <toolbarTask>false</toolbarTask> <menubarTask>true</menubarTask> <accelerator>ctrl h</accelerator> <loadAtStartup>false</loadAtStartup> </explorerTask>
Steps to integrate the embedded WebBrowserDisplay (2018.02 and onwards)
To add a new Web Browser Display to your configuration you need to take a few general steps, which are listed here and detailed in the sections below.
If you already have the pre 2018.02 WebBrowserDisplay running, you can skip general steps 2 and 3.
- Download the JCEF package for your Delft-FEWS version
- Create <explorerTask> placeholder in the Explorer.xml
- Extend the <nodes> in the Topology.xml with URLs to display relevant web content
- Add an <autoExportModuleDataSet> to *_clientConfig.xml
- Rename the JCEF package file to jcef.zip and copy it to your ModuleDataSetFiles folder.
For Operator Client:
- Make the configuration changes as in the general steps above
- Upload the following files using the Config Manager:
- Explorer.xml in the SystemConfigFiles (only if needed)
- Topology.xml in the RegionConfigFiles
- JCEF package (jcef.zip) to the ModuleDataSetFiles
- *_clientConfig.xml in the RootConfigFiles
- Start your Delft-FEWS OC application using the (2018.02 way of) clicking the Desktop (or Start Menu) icon.
Download jcef
In Delft-FEWS 2018.02 (and onwards), a new package (Java Chromium Embedded Framework - JCEF) is taking care of launching this display.
By default, this package is NOT installed and available through the Delft-FEWS libraries and need to be installed separately.
Please contact Delft-FEWS Productmanagement by e-mail (fews-pm@deltares.nl) or go directly to the downloads sections at the bottom of the page.
Explorer.xml
Starting with version 2018.02, a predefined display has been added so you can configure it in <explorerTask> in Explorer.xml.as follows::
<explorerTask name="Web Browser Display"> <iconFile>document.png</iconFile> <mnemonic>h</mnemonic> <predefinedDisplay>web browser</predefinedDisplay> <toolbarTask>false</toolbarTask> <menubarTask>true</menubarTask> <accelerator>ctrl h</accelerator> <loadAtStartup>false</loadAtStartup> </explorerTask>
Please be aware that you refer to an existing <iconFile> in your configuration!
Note: You can still use the <taskClass> tag to identify the component by it's class name, but using the <predefinedDisplay> is the preferred way of doing this.
Topology.xml
To display content in the Web Browser Display, topology nodes can be extended with optional URLs. In the following example, a SA test application (FEWS-Swiss was used) to show the potential variety.
The <mainPanel> element is not necessary to give the browser window the focus if it was hidden by some other content window because the <url> element automatically gets the focus regardless of the <mainPanel> element being present. In the following example, both node1 and node2 will give the focus to the browser window.
<nodes id="Web" name="Web"> <node id="node1" name="FOEN Swiss"> <url>https://www.bafu.admin.ch/bafu/en/home.html</url> </node> <node id="node2" name="Meteo Swiss"> <mainPanel>web browser display</mainPanel> <url>https://www.meteoswiss.admin.ch/home.html?tab=overview</url> </node> <node id="node3" name="Energy SFOE Swiss"> <url>https://www.bfe.admin.ch/themen/00490/00491/00494/index.html?lang=en</url> </node> <node id="node4" name="YouTube (to test movies)"> <url>https://www.youtube.com/</url> </node> <node id="node5" name="Deltares"> <url>https://www.deltares.nl/en/</url> </node> <node id="node6" name="Rijksoverheid (to test certificates) and redirect to https"> <url>https://www.rijksoverheid.nl/</url> </node> <node id="node7" name="local html"> <url>file:///PATH_TO_LOCAL_FILE.html</url> </node> </nodes>
After displaying a page, the content can be refreshed using the "F5" shortcut key. This also required when for example images have been changed in the background. The can be refreshed by using the F5 key.
Note: There are restrictions in Google Chrome regarding the loading of files from the local file system; links to files on the local file system (file:///) are allowed only in html documents that have been loaded from the local file system as well. In general best practice is to always use relative paths/urls to images and other files that are referred to in a html document, so if the html page is hosted on a local file system the browser would also look for included images etc. there. This restriction can not possibly be overruled by listing local files in the WebBrowserDisplay.xml white list.
Note: The Web Browser can no longer used for viewing pdf files. This was possible in older versions of JCEF, but is not supported in recent versions.
clientConfig.xml
Add an <autoExportModuleDataSet> for the jcef binaries: <autoExportModuleDataSet name="jcef" exportDir="Modules"/>
In both cases (OC and SA) will extract the jcef.zip automatically under the configured "exportDir". If this directory is not present, it will be created.
In this exportDir a dedicated directory called jcef will be created holding the binaries required for the WebBrowserDisplay.
This 'extraction on startup' will only take place once, unless the ModuleDataSet file has been changed (in the case of the jcef.zip file, this is not likely).
This is the new way of distributing ModuleDataSet files on startup, more info see here.
<?xml version="1.0" encoding="UTF-8"?> <clientConfiguration xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews https://fewsdocs.deltares.nl/schemas/version1.0/clientConfig.xsd"> <clientType>Stand alone</clientType> <autoExportModuleDataSet name="jcef" exportDir="Modules"/> </clientConfiguration>
ModuleDataSetFiles
Add the jcef.zip to your Config/ModuleDataSetFiles folder.
Note: you do not need to declare this moduleDataSet in the ModuleInstanceDescriptors.xml, like you would do normally.
Configuring of WebBrowserDisplay.xml
<defaultBrowser>
By default the web browser is linked to items (segments) in the topology tree (IFD) which have a url field assigned. To use the display for all web pages that can be opened within the UI (for example from hyperlinks in tooltips or the forecaster document panel) you can add a <defaultBrowser> element to the config file as shown above. If you do so, you may also want to add the <bringToFront> element to make the browser display activate itself whenever a new web page is loaded.
<bringToFront>
When set to true, the webBrowserDisplay will come to the front when a new webpage is loaded.
<chromiumSwitch>
For specific troubleshooting or configuration purposes, you can use one or more <chromiumSwitch> elements to add add standard chromium command line switches to the WebBrowserDisplay.xml configuration, like in the example configuration given above, a proxy server is configured using the --proxy-server option.
<lazyLoading>
To postpone the loading of the webBrowserDisplay until it is acutally needed (e.g. when a URL is selected through the Topology).
Default is true for Windows, false for linux.
Note: The webBrowserDisplay can hijack the focus when the config option lazyLoading is set to false. This behavior has been found in combination with the 34 What-If Templates - What-If Editor display.
Ensure that lazyLoading=true to prevent erratic behavior of the Scenario editor not allowing you create a scenario as your typing is not arriving in the text field.
<domainWhiteList>
For security reasons, an extra display configuration file named WebBrowserDisplay.xml has been added where you should list domains on the internet that are considered safe for the embedded web browser so it will allow users to navigate to web pages hosted in these domains.
For example, in Topology.xml a node is linked to the url of the Deltares homepage: https://www.deltares.nl
Given this url, the embedded web browser will be allowed to load content only from the www.deltares domain using the https (secure) protocol. When you navigate to this web page by clicking this topology node in the forecast tree of Delft-FEWS Explorer UI, the Deltares homepage appears to load successfully.
However, when running in debug mode the Log panel will list a number of messages to alert the user to the fact that some content is being blocked because it has not been "whitelisted" in the WebBrowserDisplay.xml configuration file. This content is coming mostly from google domains (i.e. youtube.com, ajax.googleapis.com) and some of these external domains may also need to be whitelisted as well for this Deltares website to be completely functional.
Additionally, if the user tries to follow links on the Deltares home page, every page the user navigates to as well as the external content loaded by the page is checked against the "whitelist" in WebBrowserDisplay.xml to determine if the content should be allowed or blocked. For
If the user directly clicks external links that have not been whitelisted (ie. the LinkedIn, Youtube, Facebook and Twitter links at the bottom of the page) Delft-FEWS Explorer will open such links using the system default browser (i.e. FireFox, Chrome, MSIE) instead of using the Delft-FEWS embedded web browser. If external content is referenced indirectly (i.e. Google API's or other external Javascript libraries, external style sheets etc.) such content will be blocked when hosted on a domain which has not been whitelisted and as a result, the page layout and functionality may be seriously affected.
An example of the WebBrowserDisplay.xml file, allowing the Deltares home page and other important pages hosted by Deltares to fully load in the embedded web browser:
<?xml version="1.0" encoding="UTF-8"?>
<webBrowserDisplay xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews https://fewsdocs.deltares.nl/schemas/version1.0/webBrowserDisplay.xsd">
<defaultBrowser>true</defaultBrowser>
<bringToFront>true</bringToFront>
<chromiumSwitch>--proxy-server="https://proxy-ip:proxy-port</chromiumSwitch>
<domainWhiteList>
<access origin="deltares.nl" />
<access origin="*.deltares.nl" />
</domainWhiteList>
<downloadDir>%REGION_HOME%/downloads</downloadDir>
</webBrowserDisplay>
Origins listed in this file can consist of three parts: <protocol://host:port> where protocol and port are optional parts and only the host name can contain wildcards (* or ?). When the "http" protocol is specified, "https" is also allowed but the opposite is not the case.
In this example, adding both deltares.nl and *.deltares.nl allows the user to navigate all Deltares domains and subdomains (i.e. oss.deltares.nl, publications.deltares.nl etc.) in addition to the www.deltares.nl subdomain listed in topology.xml.
Note: Please use caution when adding external API's like "ajax.googleapis.com", some pages may contain references to external domains (i.e. youtube.com or www.google.com) that may or may not be omitted without serious impact to the look and feel of a webpage.
<downloadDir>
The folder used to download files can be configured with the <downloadDir> element (since 2020.02).
If you do not configure this, a dialog box will pop up to ask the user where he wants to put a downloaded file.
Note: prior to 2020.02 downloaded files would go to %REGION_HOME%/temp/session and did not have the expected file name.
<jcefBinDir>
Normally the JCEF package will be installed in the Modules folder of any FEWS configuration, using the autoExportModuleDataSet option in the client config file.
However, you can use the JCEF package from some other location on your system by adding a <jcefBinDir> element (FEWS 2021.02 branch and later).
This can be useful for example if you have many configurations on your system, and want to save disk space.
Trouble shooting
If the web browser display is not working as expected and the FEWS log does not appear to contain any log messages that are related, please try the following before reporting the problem to Deltares;
- copy the URL in the address bar and try to open this in a stand-alone Chrome browser
- go to the Delft-FEWS temp/session folder and investigate the cef.log file, which contains detailed logging information from the Chromium embedded web browser.
On Linux, some distributions may require that you install specific dependencies for your system, most of this will be provided when you install the chromium standalone browser, for RedHat 8 compatible systems use:
sudo dnf install epel-release-latest-8.noarch
sudo dnf install chromium
sudo dnf install dbus-x11
Developer Tools (debugging)
A new feature which is available in FEWS 2020.02 and later versions is the use of the Chrome Developer Tools which can be very helpful if a specific web application does not function properly in the embedded web browser. To use this, you need to run FEWS in debug mode (-Dlog.debug=true) and it will support remote debugging, to use this you open a separate Chrome browser window and enter the url "http://localhost:9222" to connect to the debugging session. See JVM options that can be applied when starting a Delft-FEWS application for more information.
Example display
Downloads
The JCEF package, which is a Java wrapper for CEF is provided for both Windows and Linux and as of April 2022 the same package applies to all supported FEWS branches (2018.02 and higher)
For FEWS branches older than 2020.01 you need the most recent FEWS patch to be able to use this package. The JCEF package is tested by Deltares on Windows 10 and CentOS8 / RHEL8, it is expected to work on more recent operating system versions.
