XPager Concepts

Notes Client database design element conversion

XPager Converter is the XPager Suite conversion engine that automates the conversion of Forms, Pages, Views, Folders, Shared Elements and Formula Language to JavaScript, XPages, or ReactJS . This article describes the process of how the Notes database is converted to XPages and the generated design artifacts.

Database Conversion

This section describes how a Notes Database is converted by XPager.

Conversion of a Database has the following steps:

  1. Load converter index

  2. Scan database

  3. Allocate element names

  4. Prepare database

  5. Convert Outlines

  6. Convert Views

  7. Convert Folders

  8. Convert Subforms

  9. Convert Pages

  10. Convert Forms

  11. Write converter index

  12. Build application

Converter Index

Every time a database is converted a record of all converted elements and their corresponding artifacts is stored in the converted database.

Before a database is converted the previous converter index is loaded, if it exists.

The index is used by the Database Converter to determine which, if any, Notes design elements have already been converted. In addition information in the converter index is used by tooling in DDE such as the DXLLink View.

Scanning database

The Database Converter scans the Notes database being converted to determine exactly which Notes design elements exist and when they were last modified.

Allocate Element Names

All Notes design elements are allocated a rootname. This is the name that will be used to generate the names of artifacts such as XPages, Custom Controls and Script Libraries.

For example, a Notes Form called Person might be allocated a rootname of form_Person. XPager would then use this rootname to generate Xpages called form_Person.xsp or a Custom Control called ccform_Person.xsp etc. See artifact naming for more details.

Prepare Database

Static resources such as Custom Controls, SSJS and JS Script Libraries, images and css files are injected into the database.

Element Conversion

During this stage all the Notes design elements are converted in the following order: Outlines, Views, Folders, Subforms, Pages, and Forms.

For more details see: Converting Folders, Converting Forms, Converting Outlines, Converting Pages, Converting Subforms, Converting Views

Write Converter Index

Information about the conversion is written to WebContent/WEB-INF/converterIndex.xml

Build Application

If the XPager is running in DDE then the application is built via the standard Eclipse Clean & Build. This invokes all the XPage, SSJS and other builders on the project.

If the XPager is running from the command line the build step is skipped.

Form/Page/Subform Conversion

This section describes how Notes Forms, Pages, and Subform are converted by XPager.

Conversion of a Form, Page, or Subform has the following steps:

    1. Name allocation

    2. ID allocation

    3. Table conversion

    4. Embedded Element conversion

    5. Embedded Image conversion

    6. Formula conversion

    7. Actionbar conversion

    8. XSLT transformation

Generated Artifacts

Assuming we have a Form, or a Page, or a Subform design element called People. The default rootname would be form_People, or page_People, or subform_People

The conversion will typically result in the following generated artifacts:

  • Artifact: form_People.xsp, or page_People.xsp, or subform_People.xsp

    • Type : XPage

    • Description: The main body of the element

  • Artifact: form_People_body.jss, or page_People_body.jss, or subform_People_body.jss,

    • Type : SSJS

    • Description: The converted formula from the body of the element

  • Artifact: ccform_People_actionbar.xsp, or ccpage_People_actionbar.xsp, ccsubform_People_actionbar.xsp

    • Type : Custom Control

    • Description: Optional, if the element has an action bar. The converted actionbar of the element.

  • Artifact: form_People_actionbar.jss, or page_People_actionbar.jss, or subform_People_actionbar.jss

    • Type : SSJS

    • Description: Optional, if the element has an actionbar. The converted formula from the actionbar of the element.

  • Artifact: embed_xx.gif

    • Type : Image Resource

    • Description: Zero or more Image Resources created from any embedded images on the element.

View/Folder Conversion

This section describes how Notes Viewsand Folders are converted by XPager.

Conversion of a View has the following steps:

    1. Name allocation

    2. ID allocation

    3. Formula conversion

    4. Actionbar conversion

    5. XSLT transformation

Generated Artifacts

Assuming we have a View or a Folder design element called People. The default rootname would be view_People or folder_People

The conversion will typically result in the following generated artifacts:

  • Artifact: ccview_People.xsp

    • Type: Custom Control

    • Description: The main body of the element.

  • Artifact: ccview_People_body.jss

    • Type: SSJS

    • Description: The converted formula from the body of the element

  • Artifact: ccview_People_Actionbar.xsp

    • Type: Custom Control

    • Description: Optional. If the element has an action bar. The converted actionbar of the element.

  • Artifact: ccview_People_actionbar.jss

    • Type: SSJS

    • Description: The converted formula from the actionbar of the element.

Outline Conversion

This section describes how Notes Outlines are converted by XPager.

Conversion of a Form has the following steps:

    1. Name allocation

    2. ID allocation

    3. Formula conversion

    4. XSLT transformation

Generated Artifacts

Assuming we have an Outline design element called People. The default rootname would be ccoutline_People

The conversion will typically result in the following generated artifacts:

  • Artifact: ccoutline_People.xsp

    • Type: Custom Control

    • Description: The main body of the element.

  • Artifact: ccoutline_People_body.jss

    • Type: SSJS

    • Description: The converted formula from the body of the element

Image Conversion

Forms, Subforms and Pages may all contain zero or more embedded images which are images that have been pasted directly onto a form rather than being a reference to an Image Resource.

XPager converts all embedded images to Image Resources and annotates the DXL node with a the imagepath attribute that contains the name of the image resource.

Generated Image Name

Generated Image Resources have a name of the form embed_nn.xxx where:

nn: The number of the Image Resource. XPager counts unique images as it encounters them. Thus the first image will be embedd_1, the second embed_2 etc.

xxx: The file extension corresponding to the type of the embedded image. Either gif or jpg

Identical Images

XPager will only create one unique Notes Image Resource per database. If the same embedded image is used in one or more places (either on the same Form or different ones) in the same database, only one Image Resource is created and all the corresponding gif nodes will have the same imagepath.

Formula Conversion

Overview

XPager will convert the formula code on Notes design elements into SSJS code which is then stored in SSJS Script Libraries and called from the generated XPages and Custom Controls.

For each converted Notes design element two SSJS script Libraries will be created, one containing the code from the body of the element, the other containing the code from the action bar.

For example, for a Notes form called form1, XPager will create two script libraries corresponding to the two generated controls:

  • Generated Artifact: form_Form1.xsp

    • Description: XPage corresponding to the Body of the Form.

  • Generated Artifact: form_Form1_body.jss

    • Description: Converted formula code from the Body of the Form.

  • Generated Artifact: ccform_Form1_actionbar.xsp

    • Description: Custom Control corresponding to the Actionbar of the Form.

  • Generated Artifact: ccform_Form1_actionbar.jss

    • Description: Converted formula code from the Actionbar of the Form.

The generated SSJS Script Libraries will automatically be included in the generated Xpage and Custom Control.

Converting Formula

Formulas are converted to SSJS using the Formula Converter.

Each formula is converted to a fragment of SSJS. The fragment is wrapped in a named SSJS function and written to a Script Library. These SSJS functions are then called from appropriate places in the generated XPage.

Example: Here is a Form Window Title formula before conversion:

< code event='windowtitle'><formula>@UpperCase("Hello world")</formula>< /code>

The Formula Converter will convert this formula into the following fragment of SSJS:

return @UpperCase("Hello World");

XPager derives a name for the SSJS function by combining the ID of the formula node and the code event. The generated SSJS function for the window title formula above would look like this (Note that the old formula code is added as a comment at the top of the generated action):

function form_windowtitle() {

// @UpperCase("Hello World")

try {

return @UpperCase( "Hello World" ) ;

} catch (e) {

errHandle(e, form_windowtitle, SEVERITY_LOW, "error") ;

}

}

In the generated XPage the window title function is called from the xp:this:pageTitle.

< xp:this.pageTitle>#{javascript:form_windowtitle() ;}</xp:this.pageTitle>

Externalizing Formula Strings

If the converted application will support multiple languages the formula converter can externalize string literals to make translation easier.

To enable string externalization you must create a custom XPager configuration and set the Formula Converter Configuration option externalizeFormulaStrings to true.

When externalization is enabled the formula converter will remove certain types of literal string from the SSJS code and write them to a properties file. The externalized strings are replaced by a call to getString(key) which will load the string from the appropriate properties file.

function form_windowtitle() {

// @UpperCase("Hello World")

try {

return @UpperCase( getString("form_windowtitle_0") ) ;

} catch (e) {

errHandle(e, form_windowtitle, SEVERITY_LOW, "error") ;

}

}

Here is the generated properties file. The user is responsible for creating other property files in different languages.

#XPager. External strings from SSJS script library form_Form1_body

#Fri Oct 18 13:45:54 BST 2022

form_windowtitle_0=Hello World

Embedded Element Conversion

Notes design elements such as Forms, Subforms and Pages may contain other embedded Notes design elements such as Views, Outlines and Navigators. In addition Hotspots, Outline Entries etc may contain Named Element References. In both cases we are dealing with a reference to another Notes design element.

This section describes how references to elements are converted by XPager.

Types of element reference

Element references fall into two broad categories, Hard-coded and Computed

Hard-coded element references

These are specified by the developer and will never change.

XPager will add a controlname attribute that contains the name of the corresponding custom control which should be embedded in place of the original Notes design element.

Computed element references

These are computed by a formula at runtime and it is not possible for XPager to determine which element should be embedded.

Embedded Subforms

Example: A hard-coded embedded subform refers to a Notes Subform called mySubform:

<subformref name='mySubform'>

After conversion the node will have a controlname added:

<subformref name='mySubform' controlname='ccsubform_mySubform.xsp'>

Embedded Views

Example: A hard-coded embedded view refers to a Notes View called my notes view:

<embeddedview name='my notes view'>

After conversion the node will have a controlname added:

<embeddedview name='my notes view' controlname='ccview_my_notes_view.xsp'>

Embedded Outlines

Example: A hard-coded embedded outline refers to a Notes View called my outline:

<embeddedoutline name='my outline'>

After conversion the node will have a controlname added:

<embeddedoutline name='my outline' controlname='ccoutline_my_outline.xsp'>

Table Conversion

Notes tables are classified with their structure and this classification can be used to convert tables to different types of Xpage tables, such as Dojo tables, xe:fromTable, standard xp:table, or tableless responsive tables using bootstrap.

Before translating tables with XSLT, the DXL of tables in Form/View/Subform/Page elements, will have an attribute tabletype added to it.

The tabletype attribute is specifying table type, where it can have different types such as Type1 or TypeX.

Table Types

The following types of table are recognized. If a table does not fall into one of these types it is TypeX.

  • Type 1 - A table with label/field pairs arranged horizontally.

  • Type 2 - A table with label/field pairs arranged vertically.

  • Type X - Any table that does not fall into one of the preceding types.

Type 1

A table with label/field pairs arranged horizontally.

This type of table has a tabletype of type1.

Every label (ie par) node has a field attribute that has the id of the corresponding field node.

Every field node has a label attribute that has the id of the corresponding par node.

Type 2

A table with label/field pairs arranged horizontally.

This type of table has a tabletype of type2.

Every label (ie par) node has a field attribute that has the id of the corresponding field node.

Every field node has a label attribute that has the id of the corresponding par node.

Type X

Any table that does not fall into one of the preceding types.

This type of table has a tabletype of typex.

None of the labels or fields will have a label or field attribute.