Create an application configuration file

An application configuration file provides the Genero Application Server (GAS) with the information needed to run an application. It becomes available for use as soon as created and when added to a recognized group directory.

Once you have created an application, you need to configure it so that it can be executed by the GAS. For this you need to create an application configuration file. Typically, the name of the file matches the name of the application and has an xcf suffix. For example, if the application name was "app1", create a configuration file named app1.xcf.

Save the file in a defined GROUP directory. By default, the directory where the GAS searches for external application configuration files is defined in the GAS configuration file (default as.xcf) by the tag <GROUP Id="_default">directory</GROUP>. You can specify alternate directories; see GROUP (for an application) or GROUP (for a service).

The configuration file defines an application environment, and starts with the Application element. Within this element, you can define local resources, change the execution environment, the timeout settings, the image, and output settings. You can refer to previously defined components by using the tag attribute Using.

The organization of the elements within the application configuration file depend on the type of application. See Application configuration files.

These examples show some well-formed external application configuration files.

Example 1 - A simple application configuration file

The simplest application configuration file specifies a parent application and the path to the compiled application files. The application inherits the configuration of the parent application. The file is named appname.xcf, where appname is the name of the application.

<APPLICATION Parent="defaultgwc">
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://www.4js.com/ns/gas/3.00/cfextwa.xsd">
  <EXECUTION>
    <PATH>$(res.path.fgldir.demo)/Widgets</PATH>
  </EXECUTION>
</APPLICATION>

In this example, the external application configuration file Edit.xcf provides a configuration for the Edit application. Things to note:

  1. The application name is the name of the configuration file. The GAS uses the configuration file name to identify the application. The Id attribute of <APPLICATION> element is omitted; even if included, its value is not read.
  2. The application configuration file is re-read at each application launch. There is no need to restart the GAS after modifying an application configuration file.
  3. In this example, the Parent application is defaultgwc. A parent application is an abstract application that must be defined in the GAS configuration file. It provides default component configurations, which applications can inherit. See Create abstract applications.
  4. The path to the application executables is defined by the PATH component. See PATH (under EXECUTION).
  5. The MODULE element can specify the name of the .42r module to run. If the module name is the same as the configuration file name, the MODULE element is not necessary, the module name used is the name of the application. See MODULE.

Example 2 - A Web Client for JavaScript (GWC-JS) Application Configuration

While an application inherits its base configuration from the parent application, additional configuration elements can be added and existing configuration elements can be overwritten.

This example configuration file is for a GWC-JS Web application.

<APPLICATION Parent="defaultgwc">
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://www.4js.com/ns/gas/3.00/cfextwa.xsd">
  <EXECUTION>
    <PATH>$(res.path.fgldir.demo)/Widgets</PATH>
  </EXECUTION>
  <!-- Override the default gwc-js with gwc-js-custom-->
  <UA_OUTPUT>
     <PROXY>$(res.uaproxy.cmd)</PROXY>
     <PUBLIC_IMAGEPATH>$(res.public.resources)</PUBLIC_IMAGEPATH>
     <GWC-JS>gwc-js-custom</GWC-JS>
     <TIMEOUT> Using="cpn.wa.timeout"</TIMEOUT>
  </UA_OUTPUT>
 </APPLICATION>
  1. The UA_OUTPUT element provides configuration details for applications rendered by the UA proxy.
  2. The GWC-JS element provides the directory name gwc-js-custom for the customized project, for more information on customization see Configure your environment.
  3. The PUBLIC_IMAGEPATH element specifies the public resources directory used for common images used by applications.

Example 3 - Specifying the use of the HTML5 theme (and other overrides)

This next example is of a hypothetical external application configuration file, tutorialStep1.xcf, for a GWC-HTML5 Web application.
Note: The GWC-HTML5 Web client has been deprecated; new development should use the GWC-JS instead.
<APPLICATION Parent="demo-tut-abstract">
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:noNamespaceSchemaLocation="http://www.4js.com/ns/gas/3.00/cfextwa.xsd">
  <!-- Define a resource to the template HTML file -->
  <RESOURCE Id="res.template.tutorial"
    Source="INTERNAL">$(res.path.demo.dem-tut)/web/tutorial/tutorialStep1.html
  </RESOURCE>
  <EXECUTION>
    <PATH>$(res.path.demo.dem-tut)/src</PATH>
    <MODULE>tutStep1.42r</MODULE>
  </EXECUTION>
  <!-- Override default rendering template -->
  <OUTPUT>
    <MAP Id="DUA_HTML5">
      <THEME>
        <TEMPLATE Id="_default">$(res.template.tutorial)</TEMPLATE>
      </THEME>
  <OUTPUT>
 </APPLICATION>
  1. The Parent attribute of the APPLICATION element defines the parent application as "demo-tut-abstract". The child application inherits the configuration elements defined by the parent application.
  2. The RESOURCE element defines a local resource. This resource maps to a template file. See RESOURCE (for an application).
  3. The PATH element lists the path to the executable. See PATH (under EXECUTION).
  4. The MODULE elements provide the path and file name of the program executable. The MODULE element is often excluded, when the executable name matches the application name as provided in the URL. In this example, had the external application configuration file been named "tutStep1.xcf", then the MODULE element could have been excluded. See MODULE.
  5. The Id attribute of the MAP element defines the output map as DUA_HTML5. This means that the application will use the deprecated GWC for HTML5 theme. See MAP.
  6. The TEMPLATE element overrides the default template (Id="_default") with the template defined by the resource "$(res.template.tutorial)". Recall that this resource was defined at the start of this file using a RESOURCE element. See TEMPLATE.