View Navigation Options

View Navigation Properties
Application Interfaces - Desktop vs. Drilldown

You can navigate forward or back.

When you navigate forward, you are adding a new view to the view stack and displaying that view. This view stack entry is visually represented by adding a new entry to a breadcrumb trail object. The from-type determines how the new view will be initialized, how it will be used, and what happens when the view is closed.

When navigating forward, the framework uses the from-type information to decide how to initialize the new view, as follows:

From-main: This means the two views are based around the same main-DD. Therefore, when navigating from a Select view to a Zoom view, the Zoom view will display the selected record from the list (Select). If a Zoom view navigates to a Select view, the list will initialize around the record from the Zoom view.
From-child: This means that the new view’s main table is the same as the invoking object’s binding table and that this table has a child table/DDO in the invoking view. The invoking object should be a DEO within the invoking view. The new view will be displayed around the current parent value in the invoking DEO’s view. Most typically, the invoking view will be a Zoom and the new view will be a Select.
From-parent: This means that the new view’s main table is a child of the invoking view’s main table. The new view will automatically be relates-to constrained based on the data in the invoking view, ensuring that only child records will be displayed.

The NavigateForward message is used to navigate to a new view. It is sent to the new view to be added to the view stack and passes a handle to the invoking object.

There is a special version of this message named NavigateBegin that is used to clear the view stack and start navigation from the start of the view stack.

The ordering of views in a view stack and, therefore, forward navigation itself, is dynamic. The same view can be navigated to from any number of views. The developer decides which forward navigation options are allowed by sending NavigateForward to the appropriate object, passing the invoking object. The framework determines the from-type and then, with the assistance of the developer, will determine how the new view should appear and behave. This is referred to as using the view in different contexts.

While the forward navigation process can be automatic, events are provided to support customizations. The OnGetNavigateForwardData event is sent to the invoking object, which allows you to customize the information that is passed to the new view. For example, you could choose to make the new view read-only or start with a new record. In addition, an event named OnNavigateForward is sent to the view being navigated to and can be used to customize your view based on how it is being called. The OnNavigateForward event is important, and you will find yourself using it frequently. It is the main event that allows a view to be used in many different contexts. The tWebNavigateData struct is used to provide context information during the navigate forward process.

The following restrictions are applied to forward navigation:

The framework determines the from-type by looking at the relationships between the main DDOs of the invoking view and the new invoking view. In addition, the invoking object (usually a DEO within the invoking view) and its relationship to the invoking view’s DDOs are used to determine the from-type. It is the developer’s responsibility to ensure that relationships exist between views for the type of navigation you are trying to perform. If you do this improperly, you will not achieve the desired navigation behaviors.
You cannot navigate to a view that already exists in the view stack. This avoids navigation circularity and prevents creating applications that would be too difficult to understand. If you attempt to navigate to a view that is already in the stack, an unhandled error is generated. It is the developer’s responsibility not to allow this.

Back navigation refers to closing a view and moving back to another view in the view stack. Unlike forward navigation, the options for back navigation are more limited. You can only navigate back to a view that is already in the view stack. Typically, you will navigate back a single level, but you can navigate back any number of levels. When you navigate back multiple levels, all views up to the target view are closed.

When you navigate back one level, you may need to update, or at least refresh, the invoking view. An example of this would be navigating back from a Select view with a value that should be updated in the invoking Zoom view. For the most part, the updates that are performed during a navigate back operation are managed automatically.

The NavigateClose method is used to navigate back one level and update the invoking view. The NavigateCancel method is used to navigate back one level, but not update the invoking view. These methods are always sent to the view being closed, which must be the top view in the view stack. The breadcrumb control performs a NavigateCancel when you select the prior breadcrumb option.

You can choose to navigate back to any other view in the view stack. When you do this, all views up to the view being navigated back to are cancelled. Normally, multi-level back navigation is instigated by selecting an item in the breadcrumb control and is managed automatically by the system. It can be done manually by sending the NavigateCancelTo message.

While the back navigation process can be automatic, events are provided to support customizations. The OnGetNavigateBackData event is sent to a callback object within the view that is being closed, which allows you to customize the information that is passed to the invoking view. The OnNavigateBack event is sent to the invoking object in the view being navigated back to, which can be used to customize how the view update should be processed. This is particularly useful when returning from non-relational views and can be used to update values such as validation table selections. The tWebNavigateData struct is used to provide context information during the navigate back process.

When navigating back one level, the framework checks to see if the view to be closed has changes. If so, the developer is given a choice of how to handle this. You can choose to:

Present a “Changes Exist, save changes?” dialog that allows you to select yes, no, or cancel.
Present a “Data Loss, abandon changes?” dialog that allows you to select yes or no.
Save the data without any confirmation.
Close the view and lose the changes without any confirmation.

If you choose to save the changes and those changes fail, the view will not be closed. The default behavior is to present the “Changes exist, save changes” yes/no/cancel dialog. This can be configured on a view-by-view basis using the peChangedViewExitAction property.

When navigating back through multiple views, the changed view logic gets more complicated. The changed view may be in the middle of the view stack being closed, or there may be multiple changed views in the view stack that need to be closed. The framework is smart enough to handle all of these situations, allowing the user to close as many views as possible without losing any data.

View Navigation Options

Forward Navigation

Forward Navigation Restrictions

Back Navigation

Handling Unsaved Changes in Back Navigation

See Also