Skip to content

The Back Navigation Process

The Forward Navigation Process
Working with Action Menus

Procedure NavigateClose Handle hoCallback

NavigateClose is used to close the current view, remove it from the view stack, and make the invoking view the top view. It is called when you wish to update the invoking view with a selection made from the view being closed. This is typically needed when you are selecting a record from a list and using this to update the invoking view (e.g., Order Zoom invokes a Customer Select for selection – the classic prompt list). Before the view is closed, it will ensure that any changes are saved or ignored as desired. It will then automatically update the invoking view as appropriate.

NavigateClose is sent to the view that should be closed, which must be the top view in the view stack. It is passed hoCallback, which should be an object within the view being closed. This is used to set custom return information to the invoking view.

In most cases, the above is all you need to know about NavigateClose – just send the message. The process is described here in more detail.

NavigateClose performs a close by sending NavigateCloseExec. If the view being closed has changes, special handling is required. You can choose to present a confirmation dialog (either “Save Changes - yes/no/Cancel” or “abandon changes – yes/no”), save the changes without confirmation, or abandon the changes without confirmation. The different options for closing a changed view are controlled by the peChangedViewExitAction, Verify_SaveClearCancel_msg, Verify_Data_Loss_msg properties, and the GetChangedViewExitAction function.

If there are no changes in the view or if there is a need for a close confirmation, NavigateCloseExec will be called directly. If changes exist and a confirmation is required, a client confirmation dialog will be presented, requiring an additional client/server round trip. If the close is confirmed, NavigateCloseExec is called indirectly by the client in the next request/response cycle. If the close is not confirmed, the close process is halted. NavigateCloseExec may require a save. If a save is required and this save fails, the close will be halted.

Assuming the close process continues, the closing view’s tWebNavigateData will be obtained. This is the tWebNavigateData data that was passed into the view when it was invoked and accessed with GetNavigateData. The event OnGetNavigateBackData will be sent to the hoCallback object, passing this NavigateData. The hoCallback object is an object in the view that is being closed. This allows the developer to make any changes in the NavigateData data.

Next, the invoking view will update itself based on the contents of tWebNavigateData. When the navigate-from type is nfFromChild or nfFromMain, the view will be updated with the current or selected record from the view being closed. Finally, the event OnNavigateBack is sent to the invoking object that initiated the original forward navigate. This does nothing but can be augmented to handle custom updates. This is useful when this is returning information from a non-related view (i.e., the navigate-from type was nfUndefined).

OnGetNavigateBackData

Procedure OnGetNavigateBackData tWebNavigateData ByRef NavigateData Handle hoBackToView

The OnGetNavigateBackData event is called during a NavigateClose operation. It is sent to the callback object that was passed to the NavigateCancel method. This callback object should be an object within the view being closed or possibly the view itself. NavigateData is passed by reference, and this event can be used to change any of the data members of the tWebNavigateData struct.

Typically, this would be used when you are passing data back for a non-relational lookup. For example, you might set a name/value pair in the NamedValues member in this event. That NamedValues member would then be used by the invoking view to update a DEO value within the view. This will be used most often when the navigate-from type (NavigateData.eNavigateType) is nfUndefined. For example, if the object being closed was a non-relational list, like a validation table, you might update the selected value as follows:

Procedure OnGetNavigateBackData tWebNavigateData ByRef NavigateData Handle hoBackToView
String sValue
WebGet psCurrentRowID to sValue
Get NamedValueAdd NavigateData.NamedValues "ReturnValue" sValue to NavigateData.NamedValues
End_Procedure

OnNavigateBack

Procedure OnNavigateBack Handle hoCallback tWebNavigateData NavigateData

The OnNavigateBack event is sent to the object that invoked the view that is being closed. It can be used to handle any custom updates that might be required. This event is the last thing that occurs in a close navigation – at this point, the navigation is complete.

When the view about to be closed was navigated to, it was sent the message NavigateForward, passing an hoInvokingObject parameter. Usually, this is the object within the invoking view that sent the NavigateForward message. This is the object that will receive this event. This allows the object that started the forward navigation to decide what to do when the view it navigated to is closed. For example, if a DEO in a Zoom view navigated forward to a Select view that presented a list of validation codes, the DEO would receive this message when the view was closed.

It is passed hoCallback, which is a handle to an object in the view that is being closed. You could use this to WebGet any data from this object or the view. It is also passed NavigateData by reference. This can be used to process an update manually. If you change this NavigateData, this will change the automatic update processing.

This will mostly be used when the navigate-from type is nfUndefined. When NavigateClose encounters an nfUndefined, it performs no automatic update on the invoking view. OnNavigateBack provides you an opportunity to perform your own update.

We will use the example of a Select view that is a validation list. As this view is closed, OnGetNavigateBackData might have been called to load the selected validation value into NavigateData.NamedValues. This could be used in the invoking DEO as follows:

Object oCustomerState is a cWebForm
    Entry_Item Customer.State
    Set psLabel to "State"
    Set pbPromptButton to True

    Procedure OnPrompt
        Register_Object oSelectValidationValue
        Send NavigateForward of oSelectValidationValue Self
    End_Procedure

    Procedure OnNavigateBack Handle hoCallback tWebNavigateData ByRef NavigateData
    String sValue
        Get NamedValueGet NavigateData.NamedValues "ReturnValue" to sValue
        WebSet psValue to sValue
        WebSet pbChanged to True
    End_Procedure
End_Object

When NavigateData.eNavigateType is not nfUndefined, you will usually not change the data in NavigateData, as this may interfere with any automatic update processing. As noted, when NavigateData.eNavigateType is nfUndefined, there is no automatic processing, and OnNavigateBack provides you an opportunity to perform your own update.

Procedure NavigateCancel

NavigateCancel is similar to NavigateClose, except it will not update the invoking view with a selected value. You would send this to the view being closed if you wished to cancel a selection operation. Selecting the second to top breadcrumb item also performs a NavigateCancel.

Before the view is closed, it will ensure that any changes are saved or ignored as desired. It will not update the invoking view.

In most cases, the above is all you need to know about NavigateCancel – just send the message. The process is described here in more detail. Note that it is much like NavigateClose without the update at the end.

NavigateCancel performs a close by sending NavigateCancelExec. If the view being closed has changes, special handling is required. You can choose to present a confirmation dialog (either “Save Changes - yes/no/Cancel” or “abandon changes – yes/no”), save the changes without confirmation, or abandon the changes without confirmation. The different options for closing a changed view are controlled by the peChangedViewExitAction, Verify_SaveClearCancel_msg, Verify_Data_Loss_msg properties, and the GetChangedViewExitAction function.

If there are no changes in the view or if there is a need for a close confirmation, NavigateCancelExec will be called directly. If changes exist and a confirmation is required, a client confirmation dialog will be presented. If the close is confirmed, NavigateCancelExec is called indirectly by the client in the next request/response cycle. If the close is not confirmed, the close process is halted. NavigateCancelExec may require a save. If a save is required and this save fails, the close will be halted. Assuming the close process continues, the closing view will be removed and the invoking view will now be the top view.

Procedure NavigateCancelTo Handle hoView

NavigateCancelTo works the same as NavigateCancel, except you can close all views in the stack up to hoView, which will then become the top view. Selecting any breadcrumb item other than the second to top item performs a NavigateCancelTo.

A description of the navigate cancel process is detailed in NavigateCancel. NavigateCancel actually sends the NavigateCancelTo message passing the second to top view as hoView.

See Also

Developing Web Applications

Previous Topic

The Forward Navigation Process

Next Topic

Working with Action Menus