Navigation Manager

Before the introduction of the Navigation Manager, form navigation was either from one-to-one (always to the same form) or one-to-many (conditional form navigation), where the action performed on the source form decides the target form that must be displayed. This approach where the current form decides the next form to be displayed means that there is a tightly-coupled UI centric form navigation which complicates the maintainability of the code as the developer must remember the entire app flow.

The Navigation Manager introduces a new way of navigation between forms that can be used for inter-app and intra-app navigation. The Navigation Manager enables the concept of Model-driven navigation, where the entire navigation flow of the app resides in a single place called the Navigation Model. In the model-driven navigation, instead of the source form deciding the target form to be displayed, the target form is derived from the model that is configured in the destinationConfig parameter of the source form, that is present in the Navigation Model of the app. The model-driven navigation approach enhances the readability of the application flow and the maintainability of the application code.

The Navigation Manager has two entities - the Navigation Model and the Navigation Controller, and can be used in both composite and independent micro apps. Each micro app has its own Navigation Model and Navigation Controller. The Navigation Model is a JSON representation of the high-level in-and-out flow of the application, and is derived from the NavigationModel.json file that contains information about the preconditions present in the App and the Form, and the destination configs of the Form Modules or UI Modules. You must define all the outgoing paths from a Form in the Navigation Model.

The Navigation Controller is derived from the NavigationController.js file that contains information about callbacks that perform conditional navigation specific to the Forms. The Navigation Controller is mandatory in case of one-many form navigation.

The NavigationModel.json file has the following three objects:

• Forms Object
• Application Object
• UIModules Object

The Syntax of the NavigationModel.json file is as follows:

 { 
    "Application": {
      },
    "Forms": {
      },
    "UIModules" : {
      }
}

Forms Object

The Forms object contains a group of objects that each provide the metadata of individual forms present in the project. Each Form Object contains key-value pairs where the key is the friendly name of the form and the value contains the metadata of the form that provides information about the preconditions and destinations for the specific form.

The Syntax of the Forms Object is as follows:

"Forms": {
"Form Friendly Name": {
    "preConditionConfig": ['', ''],
    "destinationConfig": {
      "friendlyName": "",
      "appName": ""
    }
  }
}

Application Object

The preconditions of a micro app are configured in the Application Object. During app navigation, if the target app has preconditions declared, the source app must set the preconditions of the target app by using the Application Manager APIs.

The Syntax of the Application Object is as follows:

"Application": {"preConditionConfig" : [ "" ]},

NOTE: Even if the source app does not set the mandatory preconditions of the target app, the navigation is successful if the target app already has the preconditions set in its app data (if the preconditions are already set by another micro app).

UIModules Object

The UIModules Object contains a group of objects that each provide the metadata of individual MDA modules. Each UIModules Object contains key-value pairs where the key is the name of the MDA module and the value contains the metadata of the MDA modules that provides information about the destinations of the specific MDA module.

The Syntax of the UIModules Object is as follows:

"UIModules" : {
"<Module Name>" : {"destinationConfig" : {"friendlyName" : ""}},
"<Module Name>" : {"destinationConfig" : { "callback" : ""  , "targetForms" : [ { "friendlyName" : "" } , { "friendlyName" : "" , "appName" : ""}] }}
}

Here is a sample NavigationModel.json file:

define("Accounts/navigation/NavigationModel", {

    "Application": {
        "preConditionConfig": ["token"]
    },

    "Forms": {

        "frmAccountSummary": {
            "preConditionConfig": ['accountID', 'profile'],
            "destinationConfig": {
                "friendlyName": "frmAccountDetails",
                "appName": "Accounts"
            }
        },
        "frmAccountDetails": {
            "preConditionConfig": [],
            "destinationConfig": {
                "callback": "handleFrmAccountDetails",
                "targetForms": [{
                    "friendlyName": "frmProfile"
                }, {
                    "friendlyName": "frmTransact",
                    "appName": "Transactions"
                }]
            }
        }
    },

    "UIModules": {

        "LoginUIModule": {
            "destinationConfig": {
                "friendlyName": "frmDashboard"
            }
        },

        "AccountsUIModule": {
            "destinationConfig": {
                "callback": "fun1",
                "targetForms": [{
                    "friendlyName": "frmProfile"
                }, {
                    "friendlyName": "frmTransact",
                    "appName": "Transactions"
                }]
            }
        }
    }

});

Here is a sample NavigationController.js file:

define("Accounts/navigation/NavigationController", {

    "handleFrmAccountDetails": function(data) {

        if (data != null) {

            if (data.viewProfile == true) {
                return {
                    "friendlyName": "frmProfile",
                    "appName": "Accounts"
                };
            } else if (data.viewTransactions == true) {
                return {
                    "friendlyName": "frmTransact",
                    "appName": "Transcations"
                };
            } else {
                return {
                    "friendlyName": "frmAccountSummary"
                }
            }

        }
        return null
    }

});