ui.Interface.filenameToURI

Converts a file name to an URI to be used as a web component image resource.

Syntax

ui.Interface.filenameToURI(
   path STRING )
  RETURNS STRING
  1. path is the local file name to be converted to a URI.

Usage

The ui.Interface.filenameToURI() class method converts a local (VM context / server) file name to an URI that can be accessed by the front-ends to get the resource.

This method is typically used to provide application image files in Web Components. It can also be used to provide other resource or media files to the front-end, for specific usage. For example, to display a PDF file with GBC using the "launchUrl" front call. Another use case is to play an audio file with the "playSound" front call.

Note: The runtime system uses the same mechanism to provide the front-end with images referenced in form elements. Thus, there is no need to call this method except when using application images in web components.

The ui.Interface.filenameToURI() method can be used when executing applications behind a GAS, but it can also be used with direct connection to the front-end (typical GDC desktop connection), or when running apps on a mobile device.

The VM context file name to URI mapping is done as follows:
  • If the path parameter is already an URI (it has a scheme like http:, https:, file:), the file name is returned as is.
  • If the path parameter is an absolute, relative file path, or a simple file name:
    • When the program is executing behind a GAS, user agents can access files via HTTP. In this architecture, the method will produce an URI that can be referenced in HTML elements of a web component: The image resource will be available from this location.
    • When using a direct connection to the (GDC) front-end without using the GAS, the method returns the file name as is, and the image resources will be transmitted to the GDC through the FGLIMAGEPATH mechanism.
    • When executing an app on a mobile device, both front-end and runtime system coexist on the same platform and can access the file on the system. In this architecture, the method builds the complete local path to the file from the list of directories defined in the FGLIMAGEPATH environment variable.
Note: The URI or file path returned by the filenameToURI() method is only valid during the program's lifetime. Do not store URIs returned by filenameToURI() in a persistent way.

For more details, see Providing the image resource and Using image resources with the gICAPI web component

Example

MAIN
    DEFINE uri STRING
    LET uri = ui.Interface.filenameToURI("myimage.png")
    CALL ui.Interface.frontCall("standard", "launchURL", [uri], [])
END MAIN