Project

General

Profile

OPEN-MIME-RESOURCE

Introduction

OPEN-MIME-RESOURCE is designed to be used for displaying different document types created by 4GL applications or external systems. These documents are loaded into the user's web browser. This can be as a tab or as a new window, depending on the scenario. The browser then determines how to process the document. The document type is defined by standard MIME types. For MIME types which the browser can directly render, it will display the content as a page. For MIME types which cannot be rendered but which have an application helper registered, that helper will be invoked. For unrecognized MIME types, the user will be prompted to save the file locally.

One can use OPEN-URL to load a URL without a MIME type.

In the discussion below document and resource are used interchangeably.

This feature was created in task #1815 and modified in #3474 and #4077.

4GL Syntax

Before Trunk Revision 11340

FWD provides this feature via the following language statement before trunk rev 11340:

OPEN-MIME-RESOURCE <mime-type> <url> [embedded].

Where:

  • mime-type is the resource MIME type. It can hold any valid character expression.
  • url is the resource URL (the path to the resource) and it can be any valid character expression.
  • embedded is any valid logical expression. This parameter can be omitted and in this case this statement is equivalent to true.

After Trunk Revision 11340

Starting from the trunk revision 11340 the command syntax has changed.

The third optional logical expression is substituted by the corresponding named flag constant NOT-EMBEDDED and new optional flag DELETE-SOURCE is added so OPEN-MIME-RESOURCE becomes

OPEN-MIME-RESOURCE <mime-type> <url> [NOT-EMBEDDED] [DELETE-SOURCE].

Where:

  • mime-type is the resource MIME type. It can hold any valid character expression.
  • url is the resource URL (the path to the resource) and it can be any valid character expression.
  • NOT-EMBEDDED represents that the given resource is not displayed as an embedded document in the web browser, the given resource becomes embedded by default if this flag is omitted.
  • If DELETE-SOURCE is present and the given resource is local file, then it must be deleted after this method returns. If DELETE-SOURCE is omitted, then the given resource is not deleted.

Other Details

If url represents a local file system resource, then its file system path will be hidden by mapping its value to a generated virtual path and this document will be accessed by this virtual path. If url represents an external resource, then its url path is not hidden and this statement opens a new browser page by the given url path.

The mime-type parameter is important to be set correctly, but in some cases browsers can detect the loaded content in order to find out its mime-type:

https://developer.mozilla.org/en-US/docs/Mozilla/How_Mozilla_determines_MIME_Types#Introduction

At this time, no checking of the URL is done. It is the application's responsibility to properly secure the input URL. It is strongly recommended to limit the URL to absolute paths and to otherwise check the entire text of the URL before submitting it.

Non-Embedded Example

In this example the file output stream is used to create a file and then this file is displayed. For the web client it is displayed in a new page but for the Swing client the OS helper application associated with the mime type "text/plain" can be used to open this text file.

   def var i as int.

   message "Starting.".

   path = "c:\\test\\report.txt".
   output to value(path) page-size 10.

   repeat i = 1 to 1000:
     display "this is a test line" i.
   end.

   output close.

   message "Finished.".

   open-mime-resource "text/plain" "file:///" + path false.

Embedded Example

If the embedded parameter is true, then this file is embedded into a template html page with help of embed HTML5 element in order to use the browser's plugin API:

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/embed

The current template implementation extends its embedded content into all available screen width:

<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8"/>
<title>${documentTitle}</title>
<style type="text/css">
.view {
position: relative;
width: 100%;
height: 100%;
margin: 0px;
background: white;
}
</style>
</head>
<body class="view">
<embed id="embeddedDocument" type="${documentType}"/>
</body>
<script type="text/javascript">
function onLoad()
{
   var config = {'isStreamed' : ${isStreamed} };
   var el = document.getElementById("embeddedDocument");
   if (config.isStreamed)
   {
      el.src = "https://" + window.location.host + "${webRoot}/${documentHandler}/${documentPath}";
   }
   else
   {
      el.src = "${documentPath}";
   }
   el.width  = window.screen.availWidth;
   el.height = window.screen.availHeight;
}

onLoad();
</script>
</html>

In this case it is important to check if the corresponding plugin is supported by the particular browser:

https://developer.mozilla.org/en-US/docs/Web/API/MimeTypeArray

FWD Implementation Details

The converted Java code will call the one from these static methods of WebBrowserManager that matches exactly all given input type parameters:

Before Trunk Revision 11340

/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
*/
public static void openMimeResource(String mimeType, String path);
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(String mimeType, String path, boolean embedded);
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(character mimeType, character path, logical embedded);
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(character mimeType, character path, boolean embedded);
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
*/
public static void openMimeResource(character mimeType, character path);
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
*/
public static void openMimeResource(String mimeType, character path);
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
*/
public static void openMimeResource(character mimeType, String path);
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(String mimeType, character path, boolean embedded);
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(character mimeType, String path, boolean embedded);
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(String mimeType, character path, logical embedded);
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(character mimeType, String path, logical embedded);

After Trunk Revision 11340

This revision added a new boolean parameter, called deleteContent, at the first position. If DELETE_SOURCE flag is present in 4GL OPEN-MIME-RESOURCE statement, then new boolean parameter is added on the top of the given parameters. The matched version of the following static methods will be used to convert OPEN-MIME-RESOURCE statement.

/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
*/
public static void openMimeResource(String mimeType, String path)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    deleteContent
 *           Indicates if the source content will be deleted after the document is loaded by
 *           the client.
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
*/
public static void openMimeResource(boolean deleteContent, String mimeType, String path)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    deleteContent
 *           Indicates if the source content will be deleted after the document is loaded by
 *           the client.
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(boolean deleteContent,
String mimeType,
String path,
boolean embedded)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(String mimeType, String path, boolean embedded)
/**
 * Opens the specified file resource in a browser's window.
 * 
 * @param    deleteContent
 *           Indicates if the source content will be deleted after the document is loaded by
 *           the client.
 * @param    filePath
 *           The file path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
 * @param    preferredMimeTypes
 *           The preferred resource mime types.
*/
public static void openMimeResource(boolean deleteContent,
String filePath,
boolean embedded,
List&lt;String&gt; preferredMimeTypes)
/**
 * Opens the specified file resource in a browser's window.
 * 
 * @param    filePath
 *           The file path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
 * @param    preferredMimeTypes
 *           The preferred resource mime types.
*/
public static void openMimeResource(String filePath,
boolean embedded,
List&lt;String&gt; preferredMimeTypes)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(character mimeType, character path, logical embedded)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(character mimeType, character path, boolean embedded)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    deleteContent
 *           Indicates if the source content will be deleted after the document is loaded by
 *           the client.
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(boolean deleteContent,
character mimeType,
character path,
boolean embedded)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    deleteContent
 *           Indicates if the source content will be deleted after the document is loaded by
 *           the client.
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(boolean deleteContent,
character mimeType,
String path,
boolean embedded)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    deleteContent
 *           Indicates if the source content will be deleted after the document is loaded by
 *           the client.
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(boolean deleteContent,
String mimeType,
character path,
boolean embedded)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    deleteContent
 *           Indicates if the source content will be deleted after the document is loaded by
 *           the client.
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
*/
public static void openMimeResource(boolean deleteContent, character mimeType, character path)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
*/
public static void openMimeResource(character mimeType, character path)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
*/
public static void openMimeResource(String mimeType, character path)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    deleteContent
 *           Indicates if the source content will be deleted after the document is loaded by
 *           the client.
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
*/
public static void openMimeResource(boolean deleteContent, String mimeType, character path)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
*/
public static void openMimeResource(character mimeType, String path)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    deleteContent
 *           Indicates if the source content will be deleted after the document is loaded by
 *           the client.
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
*/
public static void openMimeResource(boolean deleteContent, character mimeType, String path)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(String mimeType, character path, boolean embedded)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(character mimeType, String path, boolean embedded)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(String mimeType, character path, logical embedded)
/**
 * Opens the specified resource in a browser's window.
 * 
 * @param    mimeType
 *           The resource mime type.
 * @param    path
 *           The url path to the target resource.
 * @param    embedded
 *           The document is embedded in the template document.
*/
public static void openMimeResource(character mimeType, String path, logical embedded)

The client common api

This code will use driver-specific code for the launching or loading. It invokes this client side code of ThinClient that delegates this call farther to the GUI Swing or Web client drivers.

   public void openMimeResource(boolean deleteContent,
                                String  mimeType,
                                String  urlString,
                                boolean embedded)
   {
      urlString = UiUtils.resolveResourceUrl(urlString);
      try
      {
         tk.getInstanceDriver().openMimeResource(deleteContent, mimeType, urlString, embedded);
      }
      catch (MalformedURLException | URISyntaxException e)
      {
         displayErrorMessage("A malformed URL is provided: '" + urlString + "'");
      }
   }

In particular it is important to note that in some cases a browser program or a OS helper application will be launched and in other cases the URL will be loaded into an existing browser. See below for specific.

The statement will return after the launch/load occurs. It will not block or otherwise wait for the page/browser to be closed.

This feature was implemented in task #1815.

ChUI Drivers

The ChUI drivers don't support this feature, they silently do nothing in this case.

Swing GUI

The Swing GUI driver will launch the OS helper application in case of file:/// URL or the OS default browser in all other cases if the OS desktop feature (API) is supported, otherwise it will launch a separate executable program. The command line program name for this executable is calculated as follows:

1. If browser-executable is specified in the directory, it will be honored. This value can hold a simple program name OR it can be the program name and default arguments. The first text in the entry must be the program name. If there is whitespace following the program name, any text after the whitespace is treated as the default arguments to the program. Due to this design, you may not use embedded whitespace inside the browser's program name. See the directory configuration reference for details on where to specify this value in the directory.

2. If not specified, then a platform specific browser default is used:

Platform Browser Program Default Arguments
Linux firefox n/a
MacOS open -a safari
Solaris firefox n/a
Windows iexplore.exe n/a

In addition to any default arguments, the URL is passed on the command line.

Web GUI

The web GUI driver does not launch a separate browser. It will simply load the URL into a new browser window in the same browser instance in which the FWD web client is already running.

The Window loads the provided URL with this JavaScript code (see https://developer.mozilla.org/en-US/docs/Web/API/Window/open):

window.open(url, "_blank");

If a window named "_blank" does not exist, it should open new window, otherwise it will load into the existing window of that name. From the Mozilla documentation:

The open() method creates a new secondary browser window, similar to choosing New Window from the File menu. The strUrl parameter specifies the URL to be fetched and loaded in the new window. If strUrl is an empty string, then a new blank, empty window (URL about:blank) is created with the default toolbars of the main window.

...

If a window with the name already exists, then strUrl is loaded into the existing window.


© 2004-2020 Golden Code Development Corporation. ALL RIGHTS RESERVED.