24 Web Browser Display

Overview

The Web Browser Display (available since 2016.01) can display URLs that has been configured for a topology node 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:

		<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>	

Please be aware that you refer to an existing <iconFile> in your configuration!

Configuration (Delft-FEWS 2018.02 onwards)

Configuration instructions

If you want to add a new Web Browser Display to your configuration, take the following general steps.

1. Download the JCEF package for your Delft-FEWS version, see table at the bottom of this page.
2. Create <explorerTask> placeholder for it in the Explorer.xml, see example above. 
3. Extend the <nodes> in the Topology.xml with URLs to display relevant web content (see below: Display Content Example).
4. Open the *_clientConfig.xml and add the <autoExportModuleDataSet name="jcef" exportDir="Modules"/>, see example below.
5. 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)

<?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
http://fews.wldelft.nl/schemas/version1.0/clientConfig.xsd">
	<clientType>Stand alone</clientType>
	<autoExportModuleDataSet name="jcef" exportDir="Modules"/>
</clientConfiguration>

For Stand Alone:

1. Make sure you apply the edits to the Explorer.xml of your SA application
2. Add URLs to the <nodes> in the Topology.xml (RegionConfig)
3. Move or Copy the jcef.zip into your Config/ModuleDataSetFiles folder
4. Adjust the *_clientConfig.xml of this SA application
5. Start your Delft-FEWS SA application using the (2018.02 way of) clicking the Desktop (or Start Menu) icon. 

For Operator Client:

1. Make the configuration changes as in the general steps above
2. Upload the following files using the Config Manager:
   1. Explorer.xml in the SystemConfigFiles (only if needed)
   2. Topology.xml in the RegionConfigFiles
   3. JCEF package (jcef.zip) to the ModuleDataSetFiles
   4. *_clientConfig.xml in the RootConfigFiles
3. Close the Configuration Manager application
4. 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::

		<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.   

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

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 Deltare 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 http://fews.wldelft.nl/schemas/version1.0/webBrowserDisplay.xsd">
	<domainWhiteList>
		<access origin="deltares.nl" />
		<access origin="*.deltares.nl" />
	</domainWhiteList>
</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 web[age.

Displaying Content

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.

<nodes id="Web" name="Web">
		<node id="node1" name="FOEN Swiss">
			<mainPanel>web browser display</mainPanel>
			<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">
			<mainPanel>web browser display</mainPanel>
			<url>https://www.bfe.admin.ch/themen/00490/00491/00494/index.html?lang=en</url>
		</node>
		<node id="node4" name="YouTube (to test movies)">
			<mainPanel>web browser display</mainPanel>
			<url>https://www.youtube.com/</url>
		</node>	
		<node id="node5" name="Deltares">
			<mainPanel>web browser display</mainPanel>
			<url>https://www.deltares.nl/en/</url>
		</node>
		<node id="node6" name="Rijksoverheid (to test certificates) and redirect to https">
			<mainPanel>web browser display</mainPanel>
			<url>https://www.rijksoverheid.nl/</url>
		</node>
		<node id="node7" name="local html">
			<mainPanel>web browser display</mainPanel>
			<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.

Example display 

Downloads

Please find here the latest JCEF package for the different Delft-FEWS versions (Windows or linux). Please follow the instructions above to unpack them properly.