ui.Interface.filenameToURI

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

Syntax

ui.Interface.filenameToURI(
   filename STRING )
  RETURNING uri INTEGER
  1. filename is the local file name to be converted to a URI.
  2. uri is the resulting 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.

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.

This method is typically 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 filename parameter is already an URI (i.e. has a scheme like http:, https:, file:), the file name is returned as is.
  • If the filename 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 cohexist on the same platform and can access to the same file system. In this architecture, the method builds the complete local path to the file, following the list of directories defined in the FGLIMAGEPATH environment variable.
Note: The URI or file path returned by the filenameToURI() method are only valid during the program live time: Do not stores these values in a persistent way.

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

Example

LET uri = ui.Interface.filenameToURI("myimage.png")