This document covers the following topics:
The map conversion process reads a map extract file and transforms it into a corresponding Natural for Ajax page layout file. The conversion process is controlled by rules and templates.
The Map Converter ships with a default set of conversion rules and corresponding template files. This set allows for default map conversions without changing rules or templates. In most cases, you will add or modify some conversion rules and/or templates to customize the conversion according to the requirements of your application.
For advanced customization, there is also the possibility to plug own Java-written conversion classes (the so-called "tag converters") into the conversion processing. But you should only do this in very rare cases.
The following topics are covered below:
By default, for each row and column in a map, a corresponding row and column is generated in the layout. By default, the Map Converter inserts the converted rows and columns at a defined position within a corresponding page template. Template and insert position can be defined by the user. Skipping or different handling of specific rows and columns can be defined via corresponding conversion rules.
The following sections describe the default processing for rows and columns in case no specific rules for different insert positions are specified:
For each row in a map, the Map Converter generates an ITR (independent table row) control with the default settings. For empty rows, an ITR control containing the control defined in the EMPTYROW_TEMPLATE is generated.
The fields and literals within a row are aligned to columns according to the following rules:
Column Start Position
If an absolute column start position is defined for a field or literal in the
map, the corresponding control in the page layout is aligned so that it starts
exactly with the specified column. This is done by inserting a HDIST (horizontal
distance) control with a corresponding width as a filler.
Note:
A precise vertical alignment of fields is only possible if absolute column
start positions are defined for the fields.
Conversion Rules
If no absolute column start position is defined for a field or literal in the
map, a HDIST control is not added as a filler by default. In this case, the
field or literal is simply appended as the last subnode of the current ITR
control. In many cases, this would result in a layout that requires additional
manual adding of fillers. This is because appending two field controls without
adding any HDIST control often does not look as intended. Therefore, the Map
Converter includes default conversion rules for filler settings. You can modify
the default conversion rules or add your own conversion rules to fine-tune this
behavior. For more information, see Conversion
Rules.
Column Width
A character map has a fixed number of rows and columns. For the literal
"ABCD", this means that it uses exactly 4 columns.
Calculating the correct width and height of field on a web page is more complex.
The width of "ABCD" will most likely be greater than
the width of "llll". Very short fields (with a length
of one or two characters) should have a minimum width so that the content is
fully visible. You can fine-tune the width by adapting the predefined conversion
rule variable $$widthfactor$$ or by adding your own
conversion rules. For more information, see Conversion
Rules.
The map extract file also contains information about arrays. With Application Designer, arrays are usually rendered as grid controls. Application Designer provides a couple of grid controls. These are:
TEXTGRID2 - a grid containing text.
TEXTGRIDSSS2 - a text grid with server-side scrolling.
ROWTABLEAREA2 - a grid containing other controls.
MGDGRID - a managed grid.
You can find more details on these grid controls ...
... in the context of Natural: Natural Page Layout > Working with Grids
... in the context of Java: Java Page Layout > Working with Grids
The Map Converter tries to convert arrays into suitable grid controls. Before the real conversion of arrays to grid controls can be done, the Map Converter must first identify the sequence and grid areas on the map. During this process of area identification, the Map Converter groups literals and fields together into sequences and areas. Whether the corresponding fields or literals are actually converted into a grid depends on the conversion rules that are executed after this area identification step.
This process of area identification is simply a kind of marking. The corresponding sequence and area objects can be used as source in the conversion rules to define the actual controls.
The conversion is done in several steps:
The map extract file is loaded and the corresponding rows and columns are collected.
The sequence and grid areas are identified.
For each row, the list of items in this row is processed, according to the column order. An item can be one of the following: a simple literal, a field or an area. For each found item, the corresponding conversion rules are executed.
Different conversion projects have different requirements to the conversion process. The Map Converter is driven by conversion rules and thus allows for flexible control of the conversion process. Conversion rules define how source items (items from a given map extract file) are mapped to target items (items in the page layout to be created) and under which conditions a certain source item shall be converted to a certain target item. The Map Converter is delivered with a default set of conversion rules contained in the file convrulesDefault.xml in the subdirectory convrules in the Application Designer project njxmapconverter. A more application-specific conversion can be achieved by copying and modifying the default set of rules or by adding own rules.
Each set of conversion rules is defined in an XML file according to the XML schema convrules.xsd in the subdirectory convrules in the Application Designer project njxmapconverter. Each individual conversion rule consists of a name, a description, a source and a target. The source identifies an element in the map extract file. The target identifies controls and attributes to be generated in the page layout.
The conversion rules make often use of regular expressions and so-called capture groups. For more information about regular expressions, see for instance the web site http://www.regular-expressions.info.
The following topics are covered below:
The following examples are provided:
The following example rule (contained in the default conversion rules file) defines
that fields in the map extract file with the qualification AD=O shall
be converted to field controls with the property displayonly="true".
<convrule rulename="Ofield_rule">
<description>Defines the control template to be used for input fields
which are specified as output only.</description>
<source>
<sourceitem>ifField</sourceitem>
<sourcecond>
<condattr>//ifAD</condattr>
<condvalue>.*O.*</condvalue>
</sourcecond>
</source>
<target>
<targetitem>$OFIELD_TEMPLATE</targetitem>
</target>
</convrule>
The source element specifies that this rule applies to fields (element
ifField) that have an AD parameter (element
ifAD) that contains a letter "O" (matching
the regular expression .*O.*). The target element specifies that these
fields are to be converted to whatever is contained in the template file
OFIELD_TEMPLATE.xml. This template file must be contained in
the same directory as the conversion rules file.
The template file contains the detailed specification of the field to be generated. The file OFIELD_TEMPLATE.xml delivered with the map converter contains, for instance, the following:
<?xml version="1.0" encoding="UTF-8"?> <field valueprop="$$" width="$$" noborder="true" displayonly="true"/>
That is, the resulting field is generated without a border
(noborder="true") and as a display-only field
(displayonly="true"). The valueprop and
width to be assigned ($$) are not determined by this
rule, but are left under the control of other rules.
The following example rule (contained in the default conversion rules file) defines
that for all fields that are defined with the format An
in the map extract file, an attribute datatype="string n" shall be
added to the element that is generated into the page layout.
<convrule rulename="AfixType_rule">
<description>All Natural "An" dfFields are converted to the
Application Designer datatype "string n". Example: "A10" is
converted to "string n".</description>
<source>
<sourceitem>dfField</sourceitem>
<selection>
<selectattr>dfFormat</selectattr>
<selectval>A([0-9]+)</selectval>
</selection>
</source>
<target>
<targetitem>$$</targetitem>
<targetattr>
<attrname>datatype</attrname>
<attrvalue>string $1</attrvalue>
</targetattr>
</target>
</convrule>
The source element specifies that this rule applies to fields that have in the
field definition (element dfField) a format (element
dfFormat) of An (matching the regular
expression A([0-9]+)). The target element specifies that for whatever
element is generated into the page layout for this kind of fields, an attribute
datatype="string $1" shall be added. In terms of regular expressions,
$1 refers to the contents of the first "capture group"
of the regular expression A([0-9]+). In case of a format A20,
$1 will evaluate to 20 and thus an attribute datatype="string
20" will be generated.
The control to be generated into the page layout
(<targetitem>$$</targetitem>) is not determined by this
rule, but is left under the control of other rules.
Summary: The combination of the two rules in example 1 and 2 makes sure that output
fields, for example, of format A20 are converted to field controls with
displayonly="true" and datatype="string 20".
The following more advanced rule was created for the use of a specific conversion project. The following task had to be achieved: A literal of the format "F10 Change" shall be converted to a button that is named "F10", is labeled "Change" and raises an event named "PF10". With the explanations from the examples above, the rule should be nearly self-explanatory.
Note that according to the rules of regular expressions, the variable
$1 refers to the string matched by the expression part in the first
pair of parentheses (the first "capture group"), that is for instance
"F10", and the variable $3 refers to the
string matched by the expression part in the third pair of parentheses (the third
"capture group"), that is for instance
"Change".
<convrule rulename="Function_rule" lone="true">
<description>Generates a button from specific literals.</description>
<source>
<sourceitem>ltLiteral</sourceitem>
<selection>
<selectattr>ltName</selectattr>
<selectval>(F[0-9]+)(\p{Space})(.*)</selectval>
</selection>
</source>
<target>
<targetitem>$BUTTON_TEMPLATE</targetitem>
<targetattr>
<attrname>name</attrname>
<attrvalue>$1</attrvalue>
</targetattr>
<targetattr>
<attrname>method</attrname>
<attrvalue>P$1</attrvalue>
</targetattr>
</target>
<target>
<targetitem>hdist</targetitem>
<targetattr>
<attrname>width</attrname>
<attrvalue>4</attrvalue>
</targetattr>
</target>
<target>
<targetitem>label</targetitem>
<targetattr>
<attrname>name</attrname>
<attrvalue>$3</attrvalue>
</targetattr>
</target>
</convrule>
The Map Converter is delivered with a default set of conversion rules contained in the file convrulesDefault.xml in the subdirectory convrules in the Application Designer project njxmapconverter. A more application-specific conversion can be achieved by copying and modifying the default set of rules or by adding own rules.
The following topics are covered below:
Like every conversion rules file, the file contains exactly one "Root_rule". The root rule specifies the template file to be used for the overall page layout. In this template file, the application-specific page layout can be defined, using company logos, colors, fonts, etc. The root rule must always have "map" as the source item and must refer to some variable defined in the page template file as the target item. The place of that variable specifies where in the page template the converted map items are placed. See for instance the root rule from the default conversion rules:
<convrule rulename="Root_rule">
<description>Exactly one rule with the sourceitem "map" is required.
This rule must define the natpage template and insert position of
the conversion result.</description>
<source>
<sourceitem>map</sourceitem>
</source>
<target>
<targetitem>$NATPAGE_TEMPLATE.$MAPROOT</targetitem>
</target>
</convrule>
The rule refers to a page layout template NATPAGE_TEMPLATE.xml and refers to a variable defined in that template where the converted map elements shall be placed. Here is the corresponding content of the page layout template NATPAGE_TEMPLATE.xml:
<?xml version="1.0" encoding="UTF-8"?>
<natpage xmlns:njx=http://www.softwareag.com/njx/njxMapConverter
natsource="$$NATSOURCE$$" natsinglebyte="true">
<titlebar name="$$TITLEVAR$$" align="center">
</titlebar>
<pagebody>
<njx:njxvariable name="MAPROOT"/>
</pagebody>
<statusbar withdistance="false"/>
</natpage>
This template specifies the following:
The overall page layout shall consist of the elements titlebar,
pagebody and statusbar.
The converted map elements shall be placed into the pagebody.
The name of the Natural adapter to be generated from that page layout shall be
determined by a rule (natsource="$$NATSOURCE$$"). There must be a
corresponding rule that yields a value for the variable
$$NATSOURCE$$, for instance derived from the map
name. We shall see later how to define such a rule.
All strings in the page layout shall be mapped to Natural variables of type A
in the adapter interface (natsinglebyte="true").
The text displayed in the title bar shall be determined by a rule
(name="$$TITLEVAR$$"). There must be a corresponding rule that
yields a value for the variable $$TITLEVAR$$, for
instance derived from a literal in the first row in the map. We shall see later
how to define such a rule.
The default conversion rules file contains a set of rules that control the conversion of data types: from Natural data types in the map to corresponding Application Designer data types in the page layout. An example was given above in Example 2. Usually, these rules need not be adapted. They have been chosen in such a way that the process of extracting maps, converting them to layouts and generating Natural adapters for these usually yields the same data types in the adapter interface as in the map interface.
Other default conversion rules define a default mapping for literals, modifiable fields, output fields, modifiable grids, output grids, system variables and fields with special characters like "#" in their names. These rules need only be adapted in special cases.
Some conversion rules need to be adapted in nearly all conversion projects. These rules are contained in the section "APPLICATION SPECIFIC RULES" in the default conversion rules file.
The following topics are covered below:
Each application has a different naming convention for Natural objects. There is a
rule (it is named "Natsource_rule" in the default
conversion rules file) that controls how adapter names are derived from map names.
The rule replaces the first letter "M" in the map name
with an "A" and places the resulting string into the
variable NATSOURCE. Remember that in the default page
template, the natsource property of NATPAGE (which
defines the adapter name to generated) is preset with the variable reference
$$NATSOURCE$$. Thus, a map with the name TESTM1 results
in an adapter named TESTA1. Other naming conventions for maps will
require a more sophisticated adapter naming rule.
Each application has a different way of showing titles in a map. Often, the title
string shall be placed into the title bar of the resulting page layout during
conversion. There is a rule (in the default conversion rules file, it is named
"Titlevar_rule") that controls how the title string in
a map is recognized. The rule searches in the first row of a map for a literal
enclosed in "***" and places the resulting string into
the variable TITLEVAR. Remember that in the default
page template, the name property of the
titlebar element (which defines the string to be shown
in the title bar) is preset with the variable reference $$TITLEBAR$$.
So this rule takes care that the found literal is placed into the
titlebar element of the page. Other conventions for map
titles will require a more sophisticated rule.
When writing your own conversion rules, you can use the default rules as examples. In order to write rules from scratch, you need to know the elements of the map that can be referred to as source items and the full syntax of the rule definition.
The XML schema of the map extract files is contained in the file naturalmap.xsd in the subdirectory convrules in the Application Designer project njxmapconverter.
As described in Processing of Sequence and Grid Areas, one step in the map conversion is the detection of sequence and grid areas in the map. Conversion rules can also refer to the detected sequence and grid areas. The XML schema of the map extract files after the detection of sequence and grid areas is described in the extended XML schema naturalmapxml_extended.xsd in the same directory.
The syntax of the conversion rules is described by the XML schema convrules.xsd in the same directory.
The basic structure of a conversion rule is as follows:
<convrule rulename="..."> <description>...</description> <source>...</source> <target>...</target> <target>...</target> ... </convrule>
This means, a conversion rule consists of one source
element and (optionally) one or several target elements.
The source element identifies an item from the map. The
target elements specify the conversion output. If no
target elements are specified, nothing is generated from
the identified source element.
The basic structure of a source element is as follows
(example):
<source>
<sourceitem>ltLiteral</sourceitem>
<selection>
<selectattr>ltName</selectattr>
<selectval>\*\*\*(.*)\*\*\*</selectval>
</selection>
<sourcecond>
<condattr>ltRow</condattr>
<condvalue>1</condvalue>
</sourcecond>
</source>
The sourceitem element refers to a specific kind of item
on a map, such as a literal (ltLiteral), a defined field
(dfField), an input field (ifField) or the identifier of
the map (identity). The elements that can be used here are specified by
the XML schema that describes the map extract after the detection of sequence and grid
areas (naturalmapxml_extended.xsd). Therefore, the elements
sequenceArea and gridArea,
which are only known after this processing, can also be used here.
The selectattr and selectval
elements are used to match an element of a specific kind by its attribute values. The
selectval element uses regular expressions to perform a
match. Capturing groups such as (.*) can be used here, so that the target
part of the conversion rule can later refer to parts of the matched value.
The selectattr element not only accepts single attributes
but also XPATH expressions. You can find an example for the usage of XPATH expressions
in the file convrulesSNoGrids.xml:
<source> <sourceitem>ifField</sourceitem> <selection> <selectattr>ifIndex/ifOffset</selectattr> <selectval>([1-9]*)</selectval> </selection> </source>
In the above example all ifIndex/ifOffset values,
which are subnodes of the currently processed ifField are
found. For each value found it is checked whether it matches the regular expression
specified in the selectval element. Only if all values
found match the regular expression, the capturing is done on the concatenated found
values. If any values found do not match the regular expression, the rule is not
applied to the ifField.
When you are using XPATH expressions, it is important to keep the two-step process in mind:
matching for each single value and
capturing on the concatenated values.
Finally, there can be zero, one or several sourcecond
elements, which allow to define further to which map items the rule applies. If
several sourcecond elements are specified, the rule is
triggered only if all conditions match (logical AND).
The basic structure of a target element is as follows:
<target>
<targetitem>...</targetitem>
<targetattr>
<attrname>...</attrname>
<attrvalue>...</attrvalue>
</targetattr>
<targetattr>
...
</targetattr>
...
</target>
In detail, there are several different options to specify a target item:
Specify the root element name of an Application Designer control, along with its attributes and
attribute values. The attribute value can be a constant, a variable or a reference
to a capturing group from a regular expression in a
sourcecond element of the same rule. In this case,
the corresponding control is generated during conversion.
<target>
<targetitem>label</targetitem>
<targetattr>
<attrname>height</attrname>
<attrvalue>10</attrvalue>
</targetattr>
<targetattr>
<attrname>width</attrname>
<attrvalue>$$width$$</attrvalue>
</targetattr>
<targetattr>
<attrname>name</attrname>
<attrvalue>$1</attrvalue>
</targetattr>
</target>
Specify the name of a variable that is defined in the conversion rules file in a
convvariable element.
<target> <targetitem>$$name$$</targetitem> </target>
Refer to the name of a template file, optionally along with attribute names and values. In this case, whatever is contained in the template file will be generated. Attribute definitions in the template file are replaced.
<target>
<targetitem>$BUTTON_TEMPLATE</targetitem>
<targetattr>
<attrname>name</attrname>
<attrvalue>$1</attrvalue>
</targetattr>
<targetattr>
<attrname>method</attrname>
<attrvalue>P$1</attrvalue>
</targetattr>
</target>
Refer to the name of a template variable and the name of a template file, separated by a dot. In this case, the template variable is replaced with whatever is contained in the template file.
<target> <targetitem>$GRIDITEM.$GRIDITEM_TEMPLATE</targetitem> </target>
Only in the root rule: Specify the name of a template file and the name of a template variable that is contained in this file, separated by a dot. In this case, the template variable is replaced with the entire result of the map conversion.
<target> <targetitem>$NATPAGE_TEMPLATE.$MAPROOT</targetitem> </target>
Specify "$$" as the target item. This is useful when writing a more general rule that is to apply after another more specific rule has already created a target item. The attributes specified along with the target item "$$" are applied to the already created target item, whatever this target item was.
<target>
<targetitem>$$</targetitem>
<targetattr>
<attrname>datatype</attrname>
<attrvalue>xs:double</attrvalue>
</targetattr>
</target>
Specify "$." as the target item. This refers to the template that is currently being processed. The attributes specified along with the target item "$." are applied to the current template.
<target>
<targetitem>$.</targetitem>
<targetattr>
<attrname>$$NATSOURCE$$</attrname>
<attrvalue>$1-A</attrvalue>
</targetattr>
</target>
The Map Converter assembles page layouts from templates. Which templates are used, how they are assembled and how variables in templates are filled is controlled by the conversion rules.
A template file describes the general layout of an entire Application Designer page layout or of an individual Application Designer control. A template can contain variables and references to other templates. During conversion, the Map Converter resolves the structure of the templates and fills the variables with specific values, depending on the contents of the map.
A template file can describe a simple control such as a FIELD control or a more complex control such as a TEXTGRIDSSS2 control. For the same control, multiple templates may exist. For example, an ofield_TEMPLATE and an ifield_TEMPLATE may both be templates for the FIELD control. The ofield_TEMPLATE would be used for output fields, the ifield_TEMPLATE for modifiable fields. Which template is used for which subset of fields of the map is specified in the conversion rules.
Template files are well-formed XML files which contain control definitions. They are placed in the folder convrules of your Application Designer project directory. The file name must end with "_TEMPLATE.xml". The Map Converter ships with a set of default template files.
The following topics are covered below:
As already seen in the examples above, templates can contain variables. Variables can be freely defined by the user. Example:
<?xml version="1.0" encoding="UTF-8"?>
<natpage xmlns:njx=http://www.softwareag.com/njx/njxMapConverter
natsource="$$NATSOURCE$$" natsinglebyte="true">
<titlebar name="$$TITLEVAR$$" align="center">
</titlebar>
<pagebody>
<njx:njxvariable name="MAPROOT"/>
</pagebody>
<statusbar withdistance="false"/>
</natpage>
Variables as placeholders for the property values of controls
An example is the variable $$TITLEVAR$$ in the
template above. If a template contains a variable such as
name="$$TITLEVAR$$", there must be a corresponding rule that yields
a value for the variable $$TITLEVAR$$. The Map
Converter replaces the variable with this value.
The built-in variable $$ has a specific meaning. If
it occurs as a property value, there is no specific rule needed to produce the
value. Instead, the Map Converter receives the value from a so-called tag
converter. Tag converters are Java classes that are delivered with the Map
Converter. Exchanging or writing your own tag converters is an advanced way of
extending the Map Converter and is usually not required. See Tag
Converters for further information.
Variables as placeholders for controls and containers
An example is the variable MAPROOT in the template
above. Such a variable is defined by inserting an NJX:NJXVARIABLE control (from
the controls palette of the Layout Painter) into a template. As long as the XML of the
template is well-formed, an NJX:NJXVARIABLE control can be inserted at any place
in the template. Conversion rules refer to this variable as $MAPROOT.
Notice that the value in the name property of an
NJX:NJXVARIABLE control does not start with $. Instead, the NJX:NJXVARIABLE
control itself defines that it is a variable. The NJX:NJXVARIABLE control is a
special control in the Natural Extensions section of the
Layout Painter's controls palette.
Templates can refer to other templates. This can be done via adding variables. The variable can serve as a placeholder for another template. The template name is defined via a corresponding rule.
Example (GRID_TEMPLATE.xml):
<?xml version="1.0" encoding="UTF-8"?>
<rowtablearea2 withborder="false" griddataprop="$$gridname$$" rowcount="$$" >
<tr>
<hdist></hdist>
<njx:njxvariable name="GRIDHEADER" />
</tr>
<repeat>
<tr>
<hdist></hdist>
<njx:njxvariable name="GRIDITEM" />
</tr>
</repeat>
</rowtablearea2>
This means: A conversion rule like the following maps a grid area detected in the map to a ROWTABLEAREA2 control and formats the header and rows as specified in the templates GRIDHEADER_TEMPLATE.xml and GRIDITEM_TEMPLATE.xml.
<convrule rulename="Griditem_rule">
<description>Mapping rule for the items of grid.</description>
<source>
<sourceitem>gridArea//ifField</sourceitem>
</source>
<target>
<targetitem>$GRIDITEM.$GRIDITEM_TEMPLATE</targetitem>
</target>
<target>
<targetitem>$GRIDHEADER.$GRIDHEADER_TEMPLATE</targetitem>
</target>
</convrule>
Only NATPAGE templates (like the default NATPAGE template NATPAGE_TEMPLATE.xml) can be edited with the Layout Painter. Templates for individual controls must currently be edited using a text editor.
A template must be a valid XML document. The root element must correspond to the root
element of a valid Application Designer control. Templates can contain variables. A special variable is
the variable $$.
Example:
<?xml version="1.0" encoding="UTF-8"?> <button name="$$" method="$$"></button>
Each template is processed by a so-called tag converter. Tag converters are in charge
of resolving the variable $$. A tag converter is a Java
class that must support a specific interface and be available in the class path of the
Map Converter. Which tag converter is used depends on the root element of the template.
In the above example, the root element is the BUTTON control. The following rule applies:
If a Java class with the name
com.softwareag.natural.mapconverter.converters.BUTTONConverter
is found in the Java class path, this Java class is used as the tag converter.
Otherwise, the class
com.softwareag.natural.mapconverter.converters.DEFAULTConverter
is used as the tag converter.
In the above example, the Map Converter tries to find the class
BUTTONConverter first. Since a specific tag converter for the
BUTTON control is not delivered with the Map Converter, the class
DEFAULTConverter is used as the tag converter.
In order to supply a custom tag converter for the BUTTON control, for instance, you
would have to create a Java class BUTTONConverter that belongs to the
package com.softwareag.natural.mapconverter.converters and make
it available in the Java class path of the Map Converter.
Detailed information on how to write your own tag converters is provided in the Application Designer development workplace as Javadoc; see Map Converter Extension API in the Natural Tools node of the navigation frame (under ).