Providing the image resource

Supported image formats

Genero supports several image data formats, typically PNG, JPEG and SVG. Check the front-end platform documentation for supported image formats. True Type Font (TTF) files are also supported, the TTF format is used when image-to-font-glyph mapping is enabled by specifying a mapping file in the FGLIMAGEPATH environment variable.

Image resolution

Consider using the appropriate image resolution for the target front-end platform. For example, mobile devices have a much higher pixel density (a higher resolution) than desktop monitors. An image which looks nice on a desktop can appear small or as an upscaled image on a mobile device.

Static and dynamic image resources

The image resource specification is different for static and dynamic images:

For static images (such as button icons), set the image resource in the image attribute (IMAGE, IMAGELEAF, and so on). See Static images.
For dynamic images (such as image fields displaying photos from a database), the image resource is specified with the field/variable value, to be rendered in a form field. The form field is typically defined as an IMAGE item, or an IMAGECOLUMN in a table view. For more details, see Runtime images.

Image resource lookup

The image data can be provided in different ways, according to the image resource specification:

As a Uniform Resource Locator (URL).
As a simple image name (typical for icons).
As a simple file name, typically with a .png or .jpg extension, or a relative or absolute file path .

Using an URL image resource

If the image specification starts with a URL prefix, the front-end will try to download the image from the location specified by the URL.

The network access to the web server must exist and network bandwidth must be sufficient to rapidly download the images.

Table 1. Supported image resource locations (URLs)
Image resource location (URL)	Description
`http://location-specification`	HTTP server
`https://location-specification`	HTTPS server (HTTP over SSL)

Using a simple image name (centralized icons)

If the image specification is a simple name (without a file extension), and the FGLIMAGEPATH environment variable defines an icon mapping file for the runtime system, the image name is converted to a font file and font glyph according to the mapping file entries, and the image form item displays that glyph/icon. The mapping file and the font definition file are centralized on the application server.

A line in the image-to-font-glyph mapping file must have the following format:

image-name=font-file:hexa-ordinal[:color-spec]

For example, if the image mapping file defines the following lines:

smiley=FontAwesome.ttf:f118
red_smiley=FontAwesome.ttf:f118:#8B0000

An image resource (IMAGE attribute, IMAGECOLUMN value, and so on) with the name "smiley" will be mapped to the glyph with ordinal position 0xf118 in the FontAwesome.ttf font file, and the image resources using "red_smiley" will use the same glyph, but will get a red color.

Important: The directory to the font file must be specified in FGLIMAGEPATH, except if the font file is located in the same directory as the mapping file.

A default color can be defined for all TTF icons of a window, by using the defaultTTFColor style attribute:

<StyleList>
  <Style name="Window.important">
     <StyleAttribute name="defaultTTFColor" value="red" />
  </Style>
  ...

A default mapping file named "image2font.txt" and the "FontAwesome.ttf" font file are provided in FGLDIR/lib. If FGLIMAGEPATH is not defined, the runtime system will use these files to make the image to font glyph mapping.

Important: When providing your own customized font file, it must be a valid TTF file. For example, changing the file name is not sufficient to turn it into a different font: In order to produce a valid TTF file, use font management tools such as FontForge (http://fontforge.github.io/en-US/) or Fontello (http://fontello.com). Furthermore, to target Microsoft^® Internet Explorer (version 11), you will need to patch the generated TTF file to remove embedding limitations from TrueType fonts, by setting the fsType field in the OS/2 table to zero. This modification can be done with freeware tools like ttembed.

It is possible to mix several plain image file directories with several image-to-font glyph mapping files in FGLIMAGEPATH. The list of mapping files and directories defines the order of precedence, for example:

$ export FGLIMAGEPATH="/var/myapp/myimages:/var/myapp/myicons.txt:/var/myapp/fontfiles:$FGLDIR/lib/image2font.txt:$FGLDIR/lib"
-- /var/myapp/myimages:           Directory where plain image files can be found
-- /var/myapp/myicons.txt:        custom image-to-font-glyph mapping file (icons)
-- /var/myapp/fontfiles:          Font files used by the myicons.txt mapping file
-- $FGLDIR/lib/image2font.txt:    Genero default icon mapping files (using FontAwesome.ttf)

Consider defining your own image mapping file and make FGLIMAGEPATH point to your own files.

Note: When executing the application on a mobile device, you must define the FGLIMAGEPATH environment variable with the mobile.environment.FGLIMAGEPATH entry in FGLPROFILE. Use $FGLAPPDIR and $FGLDIR placeholders to include the current appdir (i.e. program file directory) and the FGL runtime system directory, respectively.

See FGLIMAGEPATH for more details about this environment variable.

Using file names or paths

If the image specification is a simple file path (without an URL prefix, and typically with an image file extension), the front-end gets the image file from the runtime system. The image file is searched on the platform where the program executes. The runtime system uses FGLIMAGEPATH environment variable when searching for the images. If FGLIMAGEPATH is not set, the current working directory is searched for the image files.

The front-end provides the name of the image file, and a list of supported file extensions. The runtime system searches for image files in different locations as described here: The search depends on the name of the image file, the list of directories defined in FGLIMAGEPATH, and the expected file extensions provided by the front-end.

For example:

Name of the image file: "mycalendar"
FGLIMAGEPATH="/var/myapp/myicons/common:business"
Extensions provided by front-end: ".jpg, .png"

The search for the image file would be as follows:

/var/myapp/myicons/common/mycalendar
/var/myapp/myicons/common/mycalendar.jpg
/var/myapp/myicons/common/mycalendar.png
business/mycalendar
business/mycalendar.jpg
business/mycalendar.png

This search procedure using a proposal of file extensions was implemented to allow different type of front-ends to pass the type of image compression format required, so you can define the image name in your forms without any extension. However, it is much more efficient to specify the image file with a portable extension.

When FGLIMAGEPATH is defined, the current working directory is not searched. If you want to look for image files in the current working directory and in other directories, add "." to the FGLIMAGEPATH path list.

Note: When specifying a file name as an image resource, consider using the extension (.png, .jpg), to avoid unnecessary file searching, trying different combinations with all supported formats (FGLIMAGEPATH). The file extension will also be used by the front-end to easily identify the compression format (for example, to define the Content-Type in an HTML entity).

Application images in Web Components

Web Components can display static images (part of the Web Component assets), and application images provided at runtime (for example, a photo gallery web component). In order to provide application images to a Web Component, the program must use the ui.Interface.filenameToURI() method to convert the local file name to a URI that can be accessed by the front-end.

For more details, see Using image resources with the gICAPI web component.