Configuration

Rendering Engine

This section explains how to configure h3270's rendering engine, which allows you to transform your host applications from a character-based layout to the look and feel of a web application. The rendering engine uses regular expressions as known from many programming tools and languages such as Perl and also Java. In the following, we assume that you are basically familiar with regular expressions. To learn about them, we recommend the book Mastering Regular Expressions by Jeffrey Friedl.

The basic idea is that you provide an HTML template page (or short: template) for one or more host screens. A template says how a particular screen (or a group of screens) should appear in HTML. Each template consists of three parts: an accept pattern, a match pattern, and an HTML body.

The accept pattern is a regular expression that decides whether this template applies to a particular host screen. It applies if the pattern matches the textual representation of the screen.

The match pattern is a regular expression that is used to parse relevant information from the host screen. Text captured by capturing groups in this regular expression can later be inserted into the HTML body.

The HTML body is an ordinary HTML page that may contain special markers such as #1, #2, #3. These special markers indicate where text captured by the match pattern should be inserted into the page.

Syntactically, the accept pattern and the match pattern are specified in two special HTML comments at the start of the template file. (This means that you can edit and view the HTML part with any ordinary HTML tool.) The structure is shown below: Both special comments must begin in the first column of the file, and include the reserved words accept resp. match in the indicated positions. The regular expressions start in the following line and extend to the end of the comment, not including the final newline before the end-of-comment marker. This marker also needs to go into the first column. The rest of the template file, after the two special comments, is the HTML body (it needn't be in <HTML></HTML> tags).

<!-- accept

    Accept Pattern Here

-->

<!-- match

    Match Pattern Here

-->

<html>

    HTML Body Here

</html>

When h3270 starts up, the rendering engine initializes itself by reading all template files from the directory WEB-INF/templates within the h3270 web application. Template files look like ordinary HTML files, with the same extension, .html. When a particular host screen is encountered by h3270, it tries all the accept patterns of the template pages it has found in the above directory against the textual representation of the host screen. The first template that matches is selected to render the screen. (You can find some example templates included within the templates directory of the h3270 distribution.)

The accept pattern is an ordinary regular expression, which is applied to the host screen in JDK standard mode with no optional flags. The pattern only needs to match somewhere inside the host screen, not the entire screen. In the textual representation against which the pattern is matched, screen lines are terminated with newline characters (which correspond naturally to newlines in the pattern). Input fields in the host screen are marked by "{" and "}" characters (these appear in the exact positions where the field attributes were in the original host screen).

The match pattern is applied to the screen after the corresponding accept pattern was found to match. Unlike the accept pattern, the match pattern is applied in DOTALL mode (where "." matches everything, including a newline), because that is more convenient in the match pattern. You can change this by switching DOTALL mode off inside the pattern with "(?-s)". The match pattern needn't match the entire screen, only part of it, but it is an error if the match pattern does not match the screen at all after the accept pattern has succeeded.

Within the match pattern, you can use capturing groups (parenthesized subexpressions) to capture text from the host screen for later insertion into the HTML body. If you want to include an input field from the host screen within the rendered HTML page, you must match this input field within a capturing group. The result must be a capturing group that starts and ends with "{" and "}" characters; such groups are recognized and handled specially by the engine. Thus, a common expression to match and capture an input field is "(\{.*?\})". (This uses a non-greedy asterisk so that the match doesn't run off beyond the terminating "}".)

Within the HTML body, you can use placeholders such as #1, #2, #3 for text that was captured by corresponding groups of the match pattern. To include a literal "#" character in your HTML page, write it as # (the hash mark inside this expression is not counted as a placeholder because it comes after an "&"). If the text that was captured by a particular group is enclosed in "{" and "}" characters, an HTML input field for the corresponding host screen field will be generated.

As an additional feature, you can write a qualified Java class name within braces after a placeholder, such as "#1{org.h3270.render.ParagraphFilter}". This means that before the captured text is placed into the HTML page, it is run through the filter() method of an instance of the specified class, which must implement the interface org.h3270.render.Filter. You can use this to make arbitrary modifications to the text captured from the host screen before it gets into the HTML page. As an example, the above ParagraphFilter finds empty lines within the text and replaces them with HTML <p> tags.

Available Color Schemes and Fonts

You can modify the available color schemes and fonts by editing WEB-INF/h3270-config.xml. You can add a custom color scheme by placing a scheme tag inside the colorschemes tag. Each scheme has the following mandatory attributes:

Attribute	Description
name	Name of the color scheme.
pnfg	Protected Normal Foreground
pnbg	Protected Normal Background
pifg	Protected Intensified Foreground
pibg	Protected Intensified Background
phfg	Protected Hidden Foreground
phbg	Protected Hidden Background
unfg	Unprotected Normal Foreground
unbg	Unprotected Normal Background
uifg	Unprotected Intensified Foreground
uibg	Unprotected Intensified Background
uhfg	Unprotected Hidden Foreground
uhbg	Unprotected Hidden Background

Each color attribute must contain a HTML color code like red or #282828.
The available fonts are also configured in the configuration file. Edit the fonts and add or remove font entries. This configuration option controls which fonts are available in the h3270-Preferences dialogue.

Layout

By default the simple JSP page webapp/simple-screen.jsp is used to display the h3270 screen.
The configuration option style allows to use a simple table-based layout:

include head bar from file style/head.jsp

include navigation bar from file style/navbar.jsp display h3270 screen display keypad

The value can be set to a directory which must contain the files head.jsp and navbar.jsp. These files are included and displayed by h3270. The distribution contains two examples of this feature:

h3270
it-fws

Uncomment style in the configuration file, set it to one of these values and look at the directories webapp/h3270 and webapp/it-fws.