Deploying the gICAPI web component files

Deploying the HTML document and the JavaScript gICAPI interface

The gICAPI web component files (main HTML file, additional JavaScript files and other potential assets) must be available on the platform where the front-end executes. According to your configuration, Genero supports several solutions to provide the gICAPI web component files from a single location. In a distributed configuration with many individual front-end nodes, consider centralizing the gICAPI files on a server, instead of copying the gICAPI web component files manually to each front-end device.

Important: If the main gICAPI HTML document references external JavaScript files, put these files in the same directory as the HTML file referencing them.

Deploying gICAPI web component files with the GAS (using any front-end)

When using the Genero Application Server, the gICAPI web component files must be deployed as part of the application program files.

The .xcf configuration file of your application must define the base path to search for HTML web component files. This base path is defined by the WEB_COMPONENT_DIRECTORY entry of the EXECUTION element:

<APPLICATION ...
  <EXECUTION>
     ...
     <WEB_COMPONENT_DIRECTORY>$(application.path)/webcomponents</WEB_COMPONENT_DIRECTORY>
     ...

The HTML document must be located in a sub-directory below the base path, using the same name as defined by the COMPONENTTYPE attribute. As result, the complete path to the HTML document will be:

base-path/component-type/component-type.html

Note: The above example uses the default value of the WEB_COMPONENT_DIRECTORY parameter. If you locate your gICAPI web component files under appdir/webcomponents/component-type, you do not need to set this element in the .xcf file.

For example, if the form file defines the COMPONENTTYPE attribute as follows:

WEBCOMPONENT wc = FORMOMLY.mychart,
   COMPONENTTYPE = "3DChart";

If WEB_COMPOMENT_DIRECTORY is defined as "$(application.path)/webcomponents", and application.path is "/opt/var/gas/appdata/app/myapp", the HTML document will be found in:

/opt/var/gas/appdata/app/myapp/webcomponents/3DCshart/3DChart.html

To simplify deployment of gICAPI web components with the GAS, consider using the fglgar utility. For more details, see GAS documentation.

Note: Unlike other front-ends, the GAS will not ask the VM for gICAPI web component files through the FGLIMAGEPATH mechanism, as described in the next section. The FGLIMAGEPATH mechanism applies only to front-ends using direct connection.

Centralizing gICAPI web component files for GMA, GMI and GDC front-ends (direct connection)

When using a front-end with a direct connection (i.e. not through the GAS), you can automatically transfer web component files to the front-end. Locate the gICAPI web component files on the computer where programs execute and set the FGLIMAGEPATH environment variable. The web component files are automatically transferred if the program executes on a server and the gICAPI web component files are not found locally by the front-end.

When using FGLIMAGEPATH, gICAPI web component files are searched in the following order:

FGLIMAGEPATH-location/webcomponents/component-type/component-type.html
FGLIMAGEPATH-location/component-type.html

If assets such as .js, .css, .png files are referenced by a relative path name in the HTML content, the resources are also transferred via the FGLIMAGEPATH mechanism. If the assets use an absolute path with a concrete URL scheme ( http://something ), the HTML viewer will try to get the resource from the URL location.

Note: Providing gICAPI web component files through FGLIMAGEPATH simplifies the development process for mobile applications, as you do not have to copy the files to the device.

For example, if you define the gICAPI web component field as follows:

WEBCOMPONENT wc = FORMOMLY.mychart,
   COMPONENTTYPE = "3DChart";

If the FGLIMAGEPATH search path contains "/opt/myapp", and the gICAPI files are located under /opt/myapp/webcomponents/3DChart", the gICAPI web component HTML document will be found on the server at:

/opt/myapp/webcomponents/3DChart/3DChart.html

Deploying gICAPI web component files for an embedded mobile application

When running the application on mobile (i.e. in embedded mode), the gICAPI web component files (along with other assets) can be deployed on the device: The files will be found locally on the device.

Note: The GDC front-end supports also local gICAPI file lookup in the GDC installation directory. However, this solution is supported for backward compatibility: Consider centralizing the gICAPI web component files on the application server, by using the GAS or the FGLIMAGEPATH mechanism as described above.

Mobile front-ends make a local search for gICAPI web component files in the following order:

appdir/webcomponents/component-type/component-type.html
appdir/component-type.html

Here component-type is the name defined by the COMPONENTTYPE attribute in the form definition file.

For more details about appdir on mobile devices, see Deploying mobile apps on Android devices and Deploying mobile apps on iOS devices.

Defining the gICAPI files search path by program

To define the base URL to the web component files for a given application, you can also use the setWebComponentPath front call. The URL must be a well formatted absolute URL (e.g. "http://myserver/components" or "file:///c:/components").

Important: This front-call is provided for backward compatibility, consider using one of the other mechanisms described in this topic.

Recommended web component directory layout

When using the default settings in any configuration (i.e. no FGLIMAGEPATH defined, default GAS settings), put the gICAPI web component files under a webcomponents directory, along with the other program files, for example:

appdir
appdir/main.42m
appdir/form1.42f
appdir/form2.42f
appdir/webcomponents/3DChart
appdir/webcomponents/3DChart/3DChart.html
appdir/webcomponents/3DChart/3DChart.js
appdir/webcomponents/3DChart/3DChart.css
appdir/webcomponents/3DChart/icon_close.png
...