Deploying GWA apps

This section describes how to build and deploy GWA apps with Genero.

Building GWA apps with Genero

Genero provides a command-line tool to create GWA.

Genero Web Applications are distributed as Genero archive (gwa) files, similar to standard Genero archive (gar) files. A GWA package can be deployed on a GAS to be served by a web server.

Genero provides the gwabuildtool command line tool to build GWA applications.

Before building the GWA application:

The Genero BDL development environment (FGLDIR) must be installed to compile your program files.
The GWA must be installed. For more details, go to Install Genero Web Application.
Refer to the topics in the Overview section to quickly become familiar with the features of the GWA.

Program directory required for the build

To build a GWA application, you must prepare a directory, referred to as the programdir, containing the program files (.42m, .42f, and so on) and resource files (images, database files, web components) needed by the Genero Web application. This directory might have a structure similar to that described for mobile applications in Directory structure for GMA apps.

Specifying the GBC to be used

A GBC must be bundled with the GWA. The gwabuildtool selects the GBC at build time in the following order:

The first option, is to use the GBC specified by the gwabuildtool --gbc gbc-directory build option.
If the --gbc option is not specified, gwabuildtool will look for the FGLGBCDIR environment variable.
Finally, it defaults to the FGLDIR/web_utilities/gbc/gbc directory if none of the previous options is set.

GBC is loaded in an iframe inside the GWA application, meaning the index.html of GWA is different from the index.html of GBC.

Any customization of the GBC is expected to work. GWA requires that GBCDIR/index.html exists and GBCDIR/VERSION exists.

You can specify GBC query string options – "debugmode","contextmenu","mobileui", "theme" and so on – as you would with standard server applications. For example, to load the GWA application in debug mode, start your application with gwarun. The URL may be something like this:

http://localhost:9103/d/r/index.html?fglapp=main.42m&uuid=gwarun2024_12_11_18_00_31_769&viaMiniWS=1

Add &debugmode=1 at the end of the URL and reload the application. On reload, the GBC debug icons should be visible in the chromebar at the top. For more information about GBC query string options, refer to Query string parameters page in the Genero Browser Client User Guide.

Specifying environment with fglprofile

If you provide a fglprofile file in your program directory, it will be bundled with your application package. For details of setting environment for your GWA application, go to Setting environment with fglprofile.

The Web manifest file

Every GWA application must be created with a web application manifest file. The gwabuildtool creates a default manifest file that can be modified later. For more details, go to Web application manifest file.

Specifying the start-up module

By default, GWA will load the "main.42m" module as the main entry point (for example, programdir/app/main.42m). You can change this behavior in two ways:

In the URL query string, you can specify fglapp=anothermodule. GWA will then look in the embedded file system for a 42m of that name (for example, /app/anothermodule.42m)
Or with the gwabuildtool, you can use the option --main-module to specify the initial 42m module to be loaded.

Build and deploy the application

Build, deploy, and launch a GWA application on the GAS

It is assumed you have a directory with your Genero program files. For more information on creating the program directory, go to Program directory required for the build

Follow these steps to build the GWA application:

Execute the gwabuildtool command and related build options to create the GWA application.

If required, specify other options, such as the location of the GBC directory with the --gbc option if the default GBC is not to be used. For more information, go to Specifying the GBC to be used.

gwabuildtool --program-dir /usr/myprogramdir

Where the --program-dir option is mandatory. It must be set to the path of your program directory.

The default directory called gwa_dist with all the necessary files is created in your current path.

Deploy and launch the application

After building the GWA application, you can launch your application for testing purpose directly to your browser, using the gwasrv server. For example, execute these commands to run the GWA application created by the gwabuildtool tool:

cd gwa_dist
gwasrv index.html

The default browser opens with an address like http://localhost:9101/d/r/gwa_dist/index.html and serves the Genero application now running in the browser.

To deploy the application on your GAS, you must first produce a Genero archive (gwa) file using fglgar gwa.

Steps

Execute the fglgar gwa command and related options to create a Genero archive (gwa) file.
```
fglgar gwa --gwa gwa_dist --output myapp.gwa
```
Where:
- The --gwa option is mandatory. It must be set to the path of the gwa directory created by the gwabuildtool.
- The --output option is also mandatory. You must set it to the name of the gwa file to generate and the relative or absolute path to where it is to be output.
An archive file (gwa) with all the necessary files is created in the output path.
Execute the gasadmin gwa command and related options to deploy the Genero archive (gwa) file on the GAS.
For details, refer to the gasadmin topic in Genero Application Server User Guide.
```
gasadmin gwa --deploy-archive myapp.gwa 
```
The application should now be accessible on the server where the GAS is running at a URL like this: https://host:port/gas/gwa/myapp/index.html

Change the favicon

This procedure shows you how to change the favicon image.

About this task

A favicon is an icon associated with a URL, displayed in various locations such as a browser's address bar, tab, or alongside the site name in a bookmark list. Figure 1 shows a GWA app displayed using the default favicon.

Figure: Default favicon

The icon is referenced in the generated index.html file at the line containing the <link> element, as shown in the following example:

<link rel="icon"
href=logo512.png.63839.eb1d062b9dc0e90a6f05a237c8a2e3c8.png sizes="512x512"
type="image/png"/>

The favicon can be set with the "icons" property in the gwa/gwa.webmanifest file, using the GWA-specific "GWA:linkRel" attribute. This attribute's value corresponds to the "rel" attribute in the <link> element.

Steps to change the favicon

Place your favicon image in your programdir/gwa directory.
The image file for the favicon is typically in png format; however, other formats, such as svg, may also be used, depending on browser support. For example, Chrome and Edge support the svg format.
Open the gwa/gwa.webmanifest file in a text editor.
The following snippet illustrates how to define the "icons" property:
```
{
  "_": "gwa.webmanifest file",
  "_hint": "To add comments, use underscore as the 1st letter of the option",
  "icons": [
    { "_hint":"next icon appears as link in the manifest"},
    { "src": "bug.png",
      "type": "image/png",
      "sizes": "690x690",
      "purpose": "any",
      "GWA:linkRel": "icon"
    }
  ]
}
```
Where:
1. In the "src" both a relative path (to the gwa directory) and absolute path to the image file are supported. The attribute value is passed to the 'href' attribute in the <link> element of the generated index.html, with the source file's name represented as an MD5 hash.
2. The "type" and "sizes" attributes are directly copied to the corresponding <link> element properties in the generated index.html file. The size value reflects the actual pixel size (width in pixels by height in pixels) of your png file.
3. The "purpose" attribute is not transferred to the generated index.html file because it is not a <link> element attribute.
4. The GWA:linkRel attribute is used internally by the gwabuildtool and does not appear in the generated webmanifest file accessible to the browser. This attribute's value corresponds to the "rel" attribute in the <link> element in the generated index.html. In addition to "icon," other values, such as "apple-touch-icon," can be used in the context of favicons.

Build and test

Follow the instructions to build and run the GWA in Build and deploy the application
Check whether the favicon displays as expected.
Figure: Customized favicon

After completing the task above, you may want to consider that the icon can also be turned off by using the "GWA:removeFromManifest" attribute. Setting this attribute to true will omit the icon from the generated webmanifest file, resulting in the creation of only a <link> tag.

For example:

{ "_": "gwa.webmanifest file", 
  "icons": [
    { "_hint":"next icon appears only as a link and is removed from the resulting manifest"},
    { "src": "bug.png",
      "type": "image/png",
      "sizes": "690x690",
      "purpose": "any",
      "GWA:linkRel": "apple-touch-icon",
      "GWA:removeFromManifest":true
    }
  ]
}

Customize the index page

The GWA allows customization of index.html using custom CSS and HTML files.

To customize the look and feel of the GWA loading and ending pages, you can modify the index.html file. You have two options for this customization:

Custom CSS file: Use a custom CSS file to modify the visual appearance and layout of HTML elements.
Custom HTML template file: This option is only necessary if customizing the CSS is not sufficient, meaning you explicitly want to add elements to the existing index_tpl.html page located in gwa-install-dir/lib/gwa/index_tpl.html. Note that while this customization allows for greater flexibility, it can be more susceptible to being broken by future updates, so it should be used cautiously.

By choosing either option, you can effectively tailor the user experience to your requirements.

Customize CSS

Create a custom CSS file. The custom CSS file must be named gwa_custom.css and placed in your programdir/gwa directory.
Update the gwa_custom.css file. For most visual changes—such as colors, fonts, spacing, and button styles—CSS is the ideal place to make modifications. For example, you can alter the visual appearance and layout of HTML elements on the index page by defining or creating CSS classes.
```

body {background-color: green}
```

Customize index_tpl.html

Create a custom index_tpl.html by copying the default template from the GWA installation directory (gwa-install-dir/lib/gwa/index_tpl.html) to your program directory (programdir/gwa) .
Update the index_tpl.html file. If you need to change the structure of the page—such as adding or removing elements, changing layout containers, or adding a logo—you may need to edit the template itself. In this case, using the custom CSS may be unnecessary, as you can directly include the CSS within the page. However, you still have the option to use the gwa_custom.css file, which will be injected using the placeholder.
Important:
If a custom HTML file exists at programdir/gwa/index_tpl.html, it will be used as the template instead of the default one. Therefore, when modifying the index_tpl.html file, ensure that all templating comments remain intact. Specifically, do not alter the injection points indicated by comments such as:
- 
- 
- 
These comments mark the locations where the build tool adds essential content, including links to icons, manifest files, and version information.

Troubleshooting GWAs

What steps can you take if you have trouble with a Genero web application (GWA)?

If a GWA is stuck during the load process, check the browser debug console for errors.

The error is most likely visible in the console, either from the JavaScript side or from the fglrun side. fglrun VM runtime errors appear as alerts in the GBC UI like in any other Genero app.

If the error is not an fglrun runtime error:

First, try reloading the app with the browser reload option with:
- "Force Reload this page"(Chrome).
- "Reload page from Origin" (Safari®).
- Ctrl-F5 (Firefox™).
Next, clear the browser cache and then reload.
Next, clear website data for the development host and reload.

If all that is unsuccessful, send a copy of the web development console log to support.