OPEN-MIME-RESOURCE¶

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 iframe HTML element:

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe
https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement

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: fixed;
width: 100%;
height: 100%;
margin: 0px;
background: white;
}
</style>
<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.height = window.innerHeight;
   var resizeListener = function()
   {
      el.height = window.innerHeight;
   }
   window.addEventListener("resize", resizeListener);
}
window.onload = onLoad;
</script>

</head>
<body class="view">
<iframe id="embeddedDocument" type="${documentType}" scrolling="auto" width="100%" style="overflow:auto;border:0;"/>
</body>
</html>

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. There are two cases for using OPEN-MIME-RESOURCE with the default settings and with NOT-EMBEDDED option.
For the default settings the target resource is opened in new window or tab.

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.

If NOT-EMBEDDED option is set, then the target resource is downloaded using an html link pointed to the target resource. It is important that the corresponding helper application action for downloading the target resource was set to Always Ask or Save File.

For Firefox it can be set with help of Settings menu.