Skip to content

The Forward Navigation Process

Related topics:
- The tWebNavigateData Struct
- The Back Navigation Process

Forward navigating from one view to another is accomplished by sending the NavigateForward message:

Procedure NavigateForward Handle hoInvokingObject

This message is sent to the new object you wish to navigate to. The NavigateForward message will usually be sent from a DEO, a menu item, a button or a list’s row selection event:

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

Procedure OnRowClick String sRowID
    Send NavigateForward to oSelectOrder Self
End_Procedure

Parameters - 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). The invoking object is commonly the control (menu item, button, or list) that sent the message; in that case, pass Self. The invoking object does not need to be within an invoking view.

When a view receives the NavigateForward process it will:

  1. Determine 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. Send the event OnGetNavigateForwardData to hoInvokingObject. This event passes the tWebNavigateData variable by reference, allowing the developer to customize it. Note that OnGetNavigateForwardData is sent to the invoking object, not the invoking view.
  4. If the tWebNavigateData.bSaveBeforeNavigate member has been set to 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. Send the OnNavigateForward event 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.

Determining the navigate-from type

The cWebView class determines the navigate-from type as follows:

First the DDOs for the invoking and invoked views are determined. The Server (main DDO) 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 a 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).

In most cases navigation between views will work automatically if your DDO structures are properly created. Undefined from-type navigations can occur for valid reasons (for example, when navigating forward from the dashboard the invoking object may not have a DDO structure). When navigation types are undefined you may need to use the OnGetNavigateForwardData event to seed your data and the OnNavigateClose event to update your data.

NavigateForwardCustom is a custom version of NavigateForward, which always navigates forward using nfUndefined.

Normally the framework determines what type of navigation you are performing by comparing the invoking and invoked views. Use NavigateForwardCustom when you want the navigation to be manual (nfUndefined), even if the framework might think otherwise. In this case the new view will not be initialized automatically — you will handle initialization manually in OnNavigateForward. When navigating back from a custom navigation, the returning view will not be updated automatically; you may handle this manually in OnNavigateBack.

When working with nfUndefined navigations you will often need to pass custom data between views. Use the tWebNavigateData's NamedValues member (an array of name/value pairs) and the messages NamedValueAdd, NamedValueGet, NamedValueIndex, and NamedValueRemove to manage that data.

NavigateBegin is a special-case variant of the NavigateForward method. It is used when you want the view to be the first and only view in the view stack. It does the following:

  1. Clears the breadcrumb trail by removing all existing views from the view stack.
  2. Adds itself to the view stack by sending NavigateForward.

Signature:

Procedure NavigateBegin Handle hoInvokingObject Boolean bUnconditional

Parameters: - hoInvokingObject — handle to the object that invokes this process. This is one of the times where hoInvokingObject will probably not be inside an invoking view (there may be no invoking view). - bUnconditional — determines how closing of the views behaves when there are changed views in the view stack. If bUnconditional is true, it unconditionally clears the view stack. If it is false and change warnings are enabled for a changed view, it will halt the navigation with a warning.

Example:

Object oCustomer_itm is a cWebMenuItem
    Set psCaption to "Customer Query"
    Procedure OnClick
        Send NavigateBegin of oSelectCustomer Self False
    End_Procedure
End_Object

Note: Clearing the view stack has different meanings depending on whether you have defined a dashboard object and assigned it to the cWebApp phoDashboard property. If a dashboard object exists, the dashboard object is always the first item in the stack, making the view in NavigateBegin the second view in the stack. If there is no dashboard object, it will be the first view in the stack.

OnGetNavigateForwardData

Procedure OnGetNavigateForwardData tWebNavigateData ByRef NavigateData Handle hoToView

When NavigateForward is sent to a view, the view will initialize the tWebNavigateData variable and send OnGetNavigateForwardData to the invoking object. This event can be used by the developer to customize the data. NavigateData is passed by reference, allowing the developer to make changes.

You can use this to designate that the view should be read-only or new. Examples:

Read-only Zoom view:

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

Procedure OnGetNavigateForwardData tWebNavigateData ByRef NavigateData
    Move True to NavigateData.bReadOnly
End_Procedure

Zoom view for new record entry:

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

Procedure OnGetNavigateForwardData tWebNavigateData ByRef NavigateData Handle hoToView
    Move True to NavigateData.bNewRecord
End_Procedure

Note that OnGetNavigateForwardData is sent to the invoking object (hoInvokingObject). OnGetNavigateForwardData is added to cWebBaseUIObject, so it is directly resolved by most web objects without the need to delegate. The default behavior is to do nothing.

Debug tip: Inspect the eNavigateType member in the tWebNavigateData struct to see what the navigate-from type was set to. The best place to view this is in the OnGetNavigateForwardData event because this value is determined and set right before the event is called.

Using custom data and the name/value pair array

During forward and back navigation additional data may be passed between views using the name/value pair array in the tWebNavigateData type. Each pair consists of a case-insensitive name and a value. Use SetNamedValue to add data and GetNamedValue to retrieve a value. The developer controls what data is entered and how it is used.

  • During forward navigation the name/value data will be set in OnGetNavigateForwardData. The data can be used to customize the new view’s behavior using OnNavigateForward. It can also be accessed at any time using GetNavigateData to access the tWebNavigateData instance.
  • During back navigation, the name/value data will be passed back and can be changed using OnGetNavigateBackData and used by OnNavigateBack.

The data is stored in the tWebNavigateData struct in the NamedValues member. The NamedValue member is an array of type tNameValuePair, defined as:

Struct tNameValuePair
    String sName
    String sValue
End_Struct

Although you may use the data directly, you are encouraged to use the SetNamedValue and GetNamedValue interfaces.

NamedValueAdd

Function NamedValueAdd tNameValuePair[] Data String sName String sValue Returns tNameValuePair[]

NamedValueAdd adds a name and value to a tNameValuePair array.

NamedValueGet

Function NamedValueGet tNameValuePair[] Data String sName Returns String

NamedValueGet retrieves the value for a named pair.

OnNavigateForward

Procedure OnNavigateForward tWebNavigateData NavigateData Integer hoInvokingView Integer hoInvokingObject

The OnNavigateForward event is sent to the object that is being shown at the end of the NavigateForward process. Use this event to fully customize a view based on the context of how it was invoked. Parameters:

  • NavigateData — the tWebNavigateData instance that defines the context for navigation. Although GetNavigateData can be used to retrieve it, it is passed here as a convenience. If you need to change any of the struct’s members, use SetNavigateData to update the value.
  • hoInvokingView — handle to the view that invoked this view (the view one level down on the view stack). It may be 0 if this view is the only view on the stack. The invoking view is always synchronized, so you can access any web property data from this view.
  • hoInvokingObject — handle to the web object that invoked this view (the object passed to NavigateForward and which received OnGetNavigateForwardData). It may be 0 if unknown. hoInvokingObject may not be a child of hoInvokingView.

Common uses for OnNavigateForward: - Change captions and labels to provide contextual information to the user. - Hide and show buttons based on how the view is being used.

Example skeleton:

Procedure OnNavigateForward tWebNavigateData NavigateData Integer hoInvokingView Integer hoInvokingObject
    // turns all buttons on
    WebSet pbRender of oButton_1 to True
    WebSet pbRender of oButton_n to True

    // now for the different navigate types, turn off unnecessary buttons
    Case Begin
        Case (NavigateData.eNavigateType = nfFromMain)
            // a main file lookup
        Case Break

        Case (NavigateData.eNavigateType = nfFromChild)
            // a parent lookup
        Case Break

        Case (NavigateData.eNavigateType = nfFromParent)
            // a constrained parent query
        Case Break

        Case Else
            // unknown, probably the start of query. You might need to
            // use the NamedValues array to further refine this operation
        Case End
    End_Procedure
  1. eNavigateType — tells you where your view came from and is the most important piece of information passed. Typical values:
  2. nfFromMain — If your new view is a Zoom, this is a Select list to Zoom for the same table.
  3. nfFromChild — If your new view is a Select, this is probably a parent lookup from a Zoom.
  4. nfFromParent — If your new view is a Select, this is a constrained parent-to-child drilldown.
  5. nfUndefined — This is probably the start of a query (dashboard or menu), or other non-table-based navigation. Use NavigateData.NamedValues to pass additional info.
  6. iTable — When used with nfFromParent, indicates which parent table is being used for the relates-to constraint. When used with nfFromMain or nfFromChild, it tells you what your main table is.
  7. bNewRecord — When true, indicates that the view (probably a Zoom) is adding a new record. You can also check the HasRecord property of the view’s main DDO.
  8. bReadOnly — When true, indicates that the view is read-only. You can also test this with the IsViewReadOnly function. If a view is read-only, all DEOs will be disabled, but you may need to disable other controls (such as buttons) yourself. To change a read-only view to editable, send the ChangeEditMode message.

Refer to the samples to see practical uses of OnNavigateForward.

FindFromTop and FindFromBottom

These methods are meant to be used with data-aware, DD-based lists and will cause the grid to be refilled starting at the top or bottom of the list. "Top" and "Bottom" refer to the list itself and not whether the list is using a regular or reversed ordering. While the same result can be achieved by sending a clear and a find to your list's DD, these methods are easier because they know what index to use and whether ordering should be reversed.

Example: apply a new SQL filter and refresh the list from the top

// apply a new SQL filter and refresh the list from the top
Procedure OnClick
    String sVal
    WebGet psValue of oFilterCombo to sVal
    WebSet psFilter of oDemoConstrainedGrid to sVal
    WebGet psValue of oFromForm to sVal
    WebSet psFilterFrom of oDemoConstrainedGrid to sVal
    WebGet psValue of oToForm to sVal
    WebSet psFilterTo of oDemoConstrainedGrid to sVal
    Send RebuildAllConstraints of oCustomer_DD
    // after applying the filter, refill the list from the top.
    Send FindFromTop of oList
End_Procedure

OnNavigateForwardPreFindInit

Procedure OnNavigateForwardPreFindInit tWebNavigateData NavigateData Handle hoInvokingObject

This is called during NavigateForward after the automatic constraints have been applied but before the constraints have been rebuilt and any records have been found for the view. Use this to apply any additional constraints for the view or to set finding properties such as piSortColumn.

Do not use this to find DD records or fill the DDOs yourself — that will happen automatically as the next step in view initialization. Do not send RebuildAllConstraints (or Rebuild_Constraints) in this event; rebuilding will happen immediately after this event completes.

To apply constraints unique to a particular navigation context, set custom web properties to the filter values in this event and use those web properties in your OnConstrain event to build the constraint filter. For global constraints (for example, Company ID) consider setting those filters elsewhere in the application.

Previous Topic: The tWebNavigateData Struct
Next Topic: The Back Navigation Process

See also