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 totrue
.
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. IfDELETE-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<String> 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<String> 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 choosingNew Window
from theFile
menu. ThestrUrl
parameter specifies the URL to be fetched and loaded in the new window. IfstrUrl
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.
OPEN-MIME-RESOURCE parameters:¶
© 2004-2020 Golden Code Development Corporation. ALL RIGHTS RESERVED.