Version 4.2.6
 —  Natural for Ajax  —

Map Conversion

This document covers the following topics:


General Information

After the Map Extractor or the INPUT Extractor has been used to create extract files from maps, the Map Converter is the next tool used in the process of converting a map-based application into a Natural for Ajax application. The Map Converter processes the map extract files that were created by the Map Extractor or the INPUT Extractor. It analyzes the map extract files and creates a Natural for Ajax page layout from each map extract file. Controls on the map are converted to controls on the page. Many features of the original map are converted to features of the page.

By default, the Map Converter uses a predefined set of page templates and conversion rules that control the conversion process. The templates and the conversion rules can be modified or extended to adapt the converter to the requirements of a specific conversion project. With the advanced option to program own conversion handlers, the Map Converter provides additional flexibility and extensibility.

The Application Designer development workplace contained in Natural for Ajax provides additional Natural tools for map conversion:

Natural Tools

The following Natural tools can be invoked from the navigation frame:

Top of page

First Steps

We start with a simple map like the one below and we suppose that you have already created a map extract file with the Map Extractor. The map is contained in a Natural library named TESTCONV. The map extract file has been stored in the nat subdirectory of an Application Designer project with the corresponding name testconv.

Simple map

Start of instruction setTo create a Natural for Ajax page layout from an extract file

  1. Open the Application Designer development workplace.

  2. In the Natural Tools node of the navigation frame (which is visible when the Tools & Documentation button has previously been chosen), choose Map Converter.

    The Map Converter is opened.

    Map Converter

  3. Select the project in which you want to store the page layouts that are to be generated. That is, select your project testconv.

  4. Select the conversion rules file to be used. That is, stick with the rules file convrulesDefault.xml to begin with.

  5. Select the map input folder, that is, the folder in which your map extract files are stored.

  6. Select a map extract file.

  7. From the Map Conversion menu, choose Show Map to display the content of the map extract file in XML format.

    Or:
    Choose the icon that is shown in the Select Natural Maps header.

    Map in XML format

  8. From the Map Conversion menu, choose Preview Page Layout to display the resulting page layout as it would turn out using the selected conversion rules file.

    The right side shows a preview of the generated page layout. The Conversion Results area shows a status message which informs either about successful conversion or an error that has occurred.

    XML preview

  9. From the Map Conversion menu, choose Preview in Browser to display the resulting page layout in a separate browser window.

    Preview in browser

  10. After having previewed the conversion result for one or several maps in your project, choose Generate All Layouts from the Map Conversion menu to generate page layouts for all map extract files contained in the selected folder.

    Generate layout

  11. For now close the Map Converter and switch to the project testconv to continue working on the generated page layout.

    Project

  12. You might wish to assign a different name for the adapter to be generated for the page, change other properties or modify the layout in any other way. Then save the layout and generate the adapter as usual.

    When you import the adapter into your Natural library, you will notice that the parameter data area is the same as in the original map. This is the case even though the map uses system variables and variables with special characters. The necessary translation is done inside the generated adapter code and does not influence the application code.

  13. Now create a main program for the adapter and run it in the browser.

    Main program in browser

    You may have noticed the following effects of the applied conversion rules:

    The full concept of customizing the Map Converter is described in Customizing the Conversion Process.

Top of page

Using the Map Converter

The Map Converter is used for mass generation of layouts.

In the First Steps, you have already learned how to use the Map Converter. The topics below provide detailed descriptions of the different options and menu commands that are available in the Map Converter:

Invoking the Map Converter

When you invoke the Map Converter, the following dialog appears.

Map Converter

Start of instruction setTo invoke the Map Converter

Setting the Conversion Options

In order to start the generation, you have to select a project, a conversion rules file and the folder containing your map extract files. The following options are available for this purpose:

Project

This drop-down list box provides for selection all Application Designer projects that are currently defined.

Select the project in which you want to store the page layouts that are to be generated.

Use default rules

When this option button is selected, the default conversion rules and related templates are used. These rules are stored in the subdirectory convrules of the project directory njxmapconverter.

Use project rules

When this option button is selected, the project-specific conversion rules are used. These rules are contained in the subdirectory convrules of your project directory.

When your project does not yet have any project rules and you select this option button, the Conversion Tool is automatically shown in a dialog. You can then copy the default conversion rules and templates to the currently selected project. It is recommended that you copy all or part of the default rules and related templates into your project and adapt the copies to the requirements of your application. See Using the Conversion Rules Tool for further information.

You can also invoke the Conversion Tool manually. To do so, you choose Copy Rules from the Conversion Rules menu.

Rules

This drop-down list box provides for selection all available conversion rules files. When the Use default rules option button is selected, the default rules files are shown. When the Use project rules option button is selected, the rules files in the project directory are shown.

Select the conversion rules file that is to be used.

You can display the XML code of the selected conversion rules file in a dialog. To do so, you either choose the icon that is shown in the Select Conversion Rules header or you choose Show Rules from the Conversion Rules menu.

Map input folder

Specify the folder which contains the map extract files that are to be processed.

Select map

Optional. This drop-down list box provides for selection all map extract files that are stored in the currently selected map input folder.

For mass generation, it is not required that you select a map. However, you can select a map, for example, if you want preview the layout of the resulting Application Designer page as it would turn out using the selected conversion rules file.

You can display the XML code of the selected map extract file in a dialog. To do so, you either choose the icon that is shown in the Select Natural Maps header or you choose Show Map from the Map Conversion menu.

Previewing/Generating a Single Layout

When you choose one of the following commands from the Map Conversion menu, the currently selected conversion rules file and the currently selected map extract file are used for preview or generation of a single layout from a single map extract file:

Preview Page Layout

Shows a single page layout in the preview area of the Map Converter (on the right side).

Preview in Browser

Shows a preview of a single page layout in a separate browser window.

Generate Selected Layout

Generates a single page layout. The resulting file is stored in the currently selected project.

Generating All Layouts

When you choose the following command from the Map Conversion menu, the currently selected conversion rules file and all map extract files in the selected map input folder are used as input for the mass generation:

Generate All Layouts

Generates all page layouts (mass generation). The resulting files are stored in the currently selected project.

Viewing the Conversion Results

After a preview or generation, you can either choose the icon that is shown in the Conversion Results header or you choose the following command from the Map Conversion menu:

Show Layout XML Definition

Shows the XML layout definition for the page which was last generated or previewed in a dialog.

When the last generation was a mass generation, an additional drop-down list box is shown under Conversion Results. This drop-down list box provides for selection the names of all generated page layouts. When you choose the Show Layout XML Definition command (or the corresponding icon), the XML layout definition for the page which is currently selected in the drop-down list box is shown in a dialog.

Conversion results

After a mass generation, an additional icon for previewing a generated page layout is shown in the Conversion Results header. When you choose this icon, the layout for the page which is currently selected in the drop-down list box is shown in the preview area of the Map Converter (on the right side).

When you choose the Show Logs command from the Conversion Logs menu, the Conversion Logs tool is shown in a dialog. For further information on the options in this dialog, see Using the Conversion Logs Tool.

Refreshing the Display

For example, when you have created a new project which is not yet visible in the Map Converter, you can choose the Refresh command from the View menu of the Map Converter. This reloads all projects, conversion rules and map extract files and resets the contents of the dialog.

Top of page

Using the Editor Extension

An editor extension, the Map Conversion Assistant, is used to generate a single layout while designing a page in the Layout Painter. In this case, you fill an empty layout with the information from a map extract file.

Start of instruction setTo add a map to an empty layout using the editor extension

  1. Create a new layout using the Natural Map Converter template.

    Natural Map Converter template

  2. From the Extensions tab of the Layout Painter, choose Map Conversion Assistant.

    The following area is now shown in the Layout Painter.

    Editor extension

  3. Select either the Use default rules option button or the Use project rules option button. See Setting the Conversion Options for information on these option buttons.

  4. Optional. When you choose the Copy Rules button, you can copy the default conversion rules and templates to the current project. In this case, the Conversion Rules tool is shown in a dialog. For further information on the options in this dialog, see Using the Conversion Rules Tool.

  5. From the Rules drop-down list box, select the conversion rules file that is to be used. The rules files that are provided for selection in this drop-down list box depend on the setting of the option buttons (either the default rules or the project rules are shown).

  6. Optional. When you choose the Show Rules button, the XML code of the selected conversion rules file is shown in a dialog.

  7. In the Map input folder text box, specify the folder which contains the map extract files.

  8. From the Select map drop-down list box, select the map that is to be used.

    The XML layout definition of the selected map is now shown at the bottom of the Map Conversion Assistant.

  9. Choose the Add to Page button.

    The map description is converted to the corresponding layout elements and these elements are added to the current layout, which is now shown in the preview area.

    The Add to Page button is now dimmed. If you want to remove the elements you have added to the page, you can choose the Undo Add button.

  10. Optional. When you choose the Show Log button, the Conversion Logs tool is shown in a dialog. For further information on the options in this dialog, see Using the Conversion Logs Tool.

  11. Modify the layout as usual.

Top of page

Using the Conversion Rules Tool

Using this tool you can copy the default conversion rules and templates to a selected project for modification.

Conversion Rules tool

Start of instruction setTo invoke the Conversion Rules tool

Start of instruction setTo copy the conversion rules

  1. From the Project drop-down list box, select the project into which you want to copy the conversion rules.

  2. In the Conversion Rules box, select the rules file(s) that you want to copy and choose the > button.

    Or:
    If you want to copy all files, choose the >> button.

    The selected files are shown on the right side of the Conversion Rules box.

    To deselect one or more files, you can use the < or << button.

    For each selected rules file, the templates that are used in the rules file are automatically selected in the Templates box, so that always a consistent set of rules and templates is selected for copying.

  3. Optional. If you want to overwrite any existing rules and templates files with the same names in the selected project, activate the Overwrite existing files check box.

  4. Choose the Copy Selected Rules button to copy the rules and templates files to the selected project.

Top of page

Using the Conversion Logs Tool

Using this tool you can view the log files that have been created during the conversion of Natural maps to Natural for Ajax layouts. You can also delete these log files.

Conversion Logs tool

Start of instruction setTo invoke the Conversion Logs tool

Start of instruction setTo view a log file

  1. From the Project drop-down list box, select the project for which you want to view a log file.

    The log files contained in this project are shown in the drop-down list box to the right.

  2. Select the log file that you want to view.

  3. Choose the Load Log File button.

    Log lines for the selected log file are now shown at the bottom of the tool. Each log file contains the conversion results of one or several maps. The log lines that are shown belong to an individual map; this is the map that is selected in the Logged map conversions drop-down list box.

  4. Optional. Select a different map from the Logged map conversions drop-down list box.

    The conversion result of the newly selected map is immediately shown at the bottom of the tool.

  5. Optional. Choose the View Text button to display the content of the selected log file as a CSV file in a dialog. This shows the conversion results for all maps.

Start of instruction setTo delete log files

  1. Select the project for which you want to delete the log files.

  2. Choose the Delete Log Files button.

    A dialog appears asking to confirm the deletion.

  3. Choose the Yes button to delete all log files in the selected project.

Top of page