WebRegisterPath command

Purpose

Registers a navigation path in a drill-down style Web Application.

Syntax

WebRegisterPath eNavigationMode hoNavigateToView [ hoInvokingObject [ sStateKey ] ]

Argument Explanation

eNavigationMode   The navigation mode. Valid values are nfNavigateForward,nfNavigateForwardCustom, nfNavigateBegin.

hoNavigateToView  The handle of the view object to navigate to.

hoInvokingObject    (optional) Invoking object for the navigation operation. Defaults to Self.

sStateKey               (optional) Custom state key to be used in the URL. Defaults to the psStateViewName of the hoNavigateToView.

What It Does

Registers a forward navigation path into another view. Navigation paths need to be registered when peApplicationStateMode is set to anything other than asmOff. This registration of all possible navigation paths is used to by the framework when a deep link is opened or when the browser its back or forward button is used.

The state-key is the unique identifier in this registration and becomes part of the URL. When a deep link is opened this state-key is searched in the registration to determine the exact details of the navigation (invoking object, navigation mode and the navigate into view). This also makes sure that the deep link contains a valid navigation path. If no state-key is passed then by default the psStateViewName of the navigate forward view is used. If multiple paths into the same view are registered without custom state-key identifiers then psStateViewName is extended with a number.

The registration of a path needs to be done when the WebApp process is started, so the command should be used outside of procedures in the global execution flow. The command will throw an error when used inside a procedure. It is recommended to use the command inside the invoking object, which is why the invoking object is optional and defaults to Self.

Note that the object name passed as hoNavigateToView is registered by the command, to prevent an additional Register_Object to be necessary. This does result in spelling errors to remain undetected by the compiler, but they will be reported at runtime when the application is started.

Example

WebRegisterPath ntNavigateForward oZoomInventory

The code above should be placed inside the invoking object to register a forward navigation to the oZoomInventory view.

Object oNewButton is a cWebMenuItem

    Set psCaption to "New Product"

    Set psCSSClass to "WebClearMenuItem"

    WebRegisterPath ntNavigateForward oZoomInventory

    Procedure OnClick

        Send NavigateForward of oZoomInventory Self

    End_Procedure

    

    Procedure OnGetNavigateForwardData tWebNavigateData ByRef NavigateData Handle hoToView

        Move True to NavigateData.bNewRecord

    End_Procedure

End_Object

The code example above shows how a navigation path is registered on a menu item that navigates into the oZoomInventory view, to create a new inventory item. In this code example, the zoom view and navigation type are specified twice, which is slightly inconvenient. To get around this, the NavigatePath navigation message can be used, which will execute the path registered for the object. This changes the code to the following:

Object oNewButton is a cWebMenuItem

    Set psCaption to "New Product"

    Set psCSSClass to "WebClearMenuItem"

    

    WebRegisterPath ntNavigateForward oZoomInventory

    

    Procedure OnClick

        Send NavigatePath

    End_Procedure

    

    Procedure OnGetNavigateForwardData tWebNavigateData ByRef NavigateData Handle hoToView

        Move True to NavigateData.bNewRecord

    End_Procedure

End_Object

Each navigation path gets a name (which must be unique) for the invoking view. By default, the command uses the psStateViewName of the navigate forward view. If there are multiple paths to this view from the invoking view, this will be extended with an auto-number. Because the oSelectInventory view, which contains the button, used in the samples above already has the oList object that allows to navigate to existing inventory items, this results in the ‘/WebOrderMobile_19_1/Index.html#Inventory/Product2’ URL when using the oNewButton. The optional fourth parameter of the command can be used to customize the name.

Object oNewButton is a cWebMenuItem

    Set psCaption to "New Product"

    Set psCSSClass to "WebClearMenuItem"

    

    WebRegisterPath ntNavigateForward oZoomInventory Self "NewProduct"

    

    Procedure OnClick

        Send NavigatePath

    End_Procedure

    

    Procedure OnGetNavigateForwardData tWebNavigateData ByRef NavigateData Handle hoToView

        Move True to NavigateData.bNewRecord

    End_Procedure

End_Object

This changes the URL into ‘/WebOrderMobile_19_1/Index.html#Inventory/NewProduct’.