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.
Configuration (up to Delft-FEWS 2018.02)
To use the Web Browser Display, configure it as <explorerTask> in Explorer.xml. For example:
Please be aware that you refer to an existing <iconFile> in your configuration!
Configuration (Delft-FEWS 2018.02 onwards)
If you want to add a new Web Browser Display to your configuration, take the following general steps.
- Download the JCEF package for your Delft-FEWS version, see table at the bottom of this page.
- Create <explorerTask> placeholder for it in the Explorer.xml, see example above.
- Extend the <nodes> in the Topology.xml with URLs to display relevant web content (see below: Display Content Example).
- Open the *_clientConfig.xml and add the <autoExportModuleDataSet name="jcef" exportDir="Modules"/>, see example below.
- Rename the downloaded JCEF package file to jcef.zip and copy it to your ModuleDataSetFiles folder. (Note: you do not need to declare this moduleDataSet in the ModuleInstanceDescriptors.xml, like you would do normally)
For Stand Alone:
- Make sure you apply the edits to the Explorer.xml of your SA application
- Add URLs to the <nodes> in the Topology.xml (RegionConfig)
- Move or Copy the jcef.zip into your Config/ModuleDataSetFiles folder
- Adjust the *_clientConfig.xml of this SA application
- Start your Delft-FEWS SA application using the (2018.02 way of) clicking the Desktop (or Start Menu) icon.
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
- Close the Configuration Manager application
- Start your Delft-FEWS OC application using the (2018.02 way of) clicking the Desktop (or Start Menu) icon.
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. Underneath this exportDir a dedicated directory called jcef will be present and all binaries required for launching the Web Browser Display can be found here.
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, please check the details here.
Configuring the display
Starting with version 2018.02, a predefined display has been added so you can configure it in <explorerTask> in Explorer.xml.as follows::
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.
Configuring a Whitelist
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
An example of the WebBrowserDisplay.xml file, allowing the Deltares home page and other important pages hosted by Deltare to fully load in the embedded web browser:
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.
Setting as default Browser
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.
Configuring a folder for downloads
Using FEWS release 2020.02 and later the folder used to download files can be configured using the the WebBrowserDisplay.xml configuration file using a <downloadDir> element. 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: in earlier releases downloaded files would go to %REGION_HOME%/temp/session and did not have the expected file name, a bit inconvenient.
Configuring a different location for the JCEF package
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 if you have many configurations on your system, in order to save some disk space you can use the JCEF package from some other location on your system in the WebBrowserDisplay.xml by adding a <jcefBinDir> element (FEWS 2021.02 branch and later)
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.
An optional <mainPanel> element has been added in this example to give the browser window the focus if it was hidden by some other content window.
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.
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.
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 CentOS7, it is expected to work on more recent operating system versions.