NavigateForward - cWebView

Sent to the object you wish to navigate to in a mobile web application (drilldown interface)

Type: Procedure

Parameters: Handle hoInvokingObject

Parameter Description
hoInvokingObject The object that invokes the navigation. It is usually an object within the current view (the view that is on top of the stack before the navigation).

Parameter	Description
hoInvokingObject	The object that invokes the navigation. It is usually an object within the current view (the view that is on top of the stack before the navigation).

Syntax

Procedure NavigateForward Handle hoInvokingObject

Call: Send NavigateForward hoInvokingObject

Description

Forward navigating from one view to another in a mobile web application (drilldown interface) is accomplished by sending the NavigateForward message:

The NavigateForward message will usually be sent from a DEO, a menu item, a button or a list's row selection event.

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

Use WebRegisterPath to register a navigation path.

WebRegisterPath ntNavigateForward oZoomCustomer
WebRegisterPath ntNavigateForward oSelectOrder

Procedure OnClick String sButton String sRowId
     Send NavigateForward of oZoomCustomer Self
End_Procedure

Procedure OnRowClick String sRowID
    Send NavigateForward of oSelectOrder Self
End_Procedure

The difference between invoking view and invoking object must be understood. The invoking view is the top view in the view stack before the navigate forward operation. This does not have to be passed, because its handle value is known. The invoking object is the object that is requesting the navigation. Usually, it is the control within the invoking view that sent the message (the menu item, button or list). When that is the case, you just pass Self as the hoInvokingObject parameter. While you will usually just pass Self as the parameter, the invoking object does not have to be the object that sent NavigateForward and it does not even have to be an object within an invoking view.

When a view receives the NavigateForward process, it will:

1. Determines the Navigate-From type. The relationship between the invoking view/invoking object and the view being navigated to is used to determine this relationship.

2. Create a tWebNavigateData variable and populate it with proper values. It does this by looking at and using eNavigateType, hoInvokingObject and the invoking view.

3. Sends OnGetNavigateForwardData to hoInvokingObject. This event passes the tWebNavigateData variable by reference, allowing the developer to customize this. Note that OnGetNavigateForwardData is sent to the invoking object, not the invoking view.

4. If the tWebNavigateData.bSaveBeforeNavigate member has been set True in OnGetNavigateForwardData, the invoking view will attempt to save any changed data. If the data cannot be saved or this is an empty record with nothing to save, the navigation will be halted.

5. Initialize the new view based on the contents of the tWebNavigateData variable. Depending on the Navigate-From type, the data in the invoking view and all of the data in the view stack, this will set relates-to constraints and find appropriate records for the new view.

6. Add the new view to the view stack, making it the new top view in the view stack.

7. Move the tWebNavigateData to a private web property, which can be accessed using GetNavigateData and SetNavigateData.

8. If the navigation succeeds (see 9), Send OnNavigateForward to itself, passing the tWebNavigateData instance, a handle to the invoking view and a handle to the invoking object (hoInvokingObject). OnNavigateForward is an important event that the developer will use to further initialize and customize the view. Proper use of this event allows the same view to be used in a variety of contexts.

9. A forward navigation can fail if DDO records cannot be refound. This can happen when data is changed in a multi-user environment or possibly by a programming error. When this happens the forward navigation is reversed. The event OnNavigateForwardRefindError is called which calls NavigateCancel to reverse the process. OnNavigateForward is not sent. See OnRefindRecordError for more on this.

Determining the Navigate From-Type

The cWebView class determines the Navigate-From type as follows:

First the DataDictionary objects (DDOs) for the invoking and invoked views are determined. The Server (Main_DD) of the view being navigated to is defined as the invoked DDO. The Server of the invoking object (being navigated from) is defined as the invoking DDO.

The relationships between these DDOs are then determined based on the DDOs, underlying tables and the relationship between the tables. These relationships are compared as follows:

If the invoking DDO and invoked DDO are the same, this is a from-main navigation (nfFromMain). This often occurs when select view loads a zoom view based on the same table.

If the invoking DDO is a parent (or any ancestor) of the invoked DDO, this is a from-child navigation (nfFromParent). This occurs when a DEO in a Zoom view invokes a parent Select view (prompt list).

If the invoking DDO is a child of the invoked DDO, this is a from-parent navigation (nfFromChild). This often occurs when a Select or Zoom View is used to invoke a select view to show a list of constrained children.

If none of the above, this is from-undefined navigation (nfUndefined).

For the most part, navigation between views will just do the right thing. As long as your DDO structures are properly created, it should be clear by looking at the views if you wish a forward navigation to be used for main-table zoom, parent lookups or constrained child drilldowns.

Undefined From-Type navigations can occur for a number of valid reasons. When navigating forward from the dashboard (i.e., the top of the view stack) the invoking object (the dashboard) will probably not have a DDO structure and will be undefined. The From-Type will be undefined when navigating between views that don't have a table-based relationship such as a custom validation table lookup. When navigation types are undefined, you may need to use OnGetNavigateForwardData to seed your data and NavigateClose to update your data.