Dynamic Cross Component Navigation - How to Guide

Introduction
Cross component navigation can be defined in the following 3 ways:
Direct mapping of a source id (consisting of UI component, interface view, outbound plug) to a target id (consisting of UI
component, interface view, inbound plug)
Generic mapping of UI object type and UI object action to a navigation target - this mapping is still based on dedicated
outbound plugs of the Work Area Component Repository
Dynamic generic mapping of UI object type and UI object action to a navigation target navigation via a descriptor object
The direct mapping of outbound plugs to inbound plugs is the most specific way of defining navigation. It also requires
quite a lot of customizing to cover the complete navigation setup and does not guarantee consistent navigation across all
navigation requests issued from different components - for example, each component can define a different navigation
target to display a sales order. We discourage you from using the direct mapping of an outbound plug to an
inbound plug in the navigation bar profile of your business role!
The navigation based on generic mapping of UI object type and UI object action uses the Work Area Component
Repository to determine the navigation targets. This type of navigation adds a layer of abstraction. Instead of mapping a
specific outbound plug to a specific inbound plug, combinations of UI object type and UI object action are mapped to
targets. This means that all outbound plugs which use the same combination of UI object type and UI object action share
the same target. This also ensures a consistent navigation across the application.
The dynamic generic navigation is very useful for components that can not define specific outbound plugs since their
content is generic (e.g. the activity clipboard content is based on customizing; e.g. the document flow of business
transactions can contain many different objects). A new object called the navigation descriptor object is introduced to
carry data, which is sufficient of finding a navigation target. This can be the UI object type but it can also be a business
object (BOL entity or BOR key) that has to be processed. The UI object action defines what to do (display, edit, search, ...)
and it is always part of the descriptor object.
Release Relevance
The features described on this page are available in all releases of the Web Client UI Framework. Exceptions are marked
explicitly.
How to Use
The following activity diagram shows how the navigation works inside the WebClient framework.

From an application point of view you can influence the navigation by:
Code in the actions of the grey swim lanes.
Customizing in the italic maintenance views (all are part of the navigation bar profile; see transaction CRMC_UI_NBLINKS)
How to Use at SAP
Work Area Component Repository
The work area component repository defines all available components with their inbound plugs and outbound plugs. The
plugs have to be part of the interface view of the UI component. Only components that are defined in the repository can
directly be included in the work area of the application frame.
Each inbound plug and outbound plug can be assigned to a combination of UI object type and UI object action.
For outbound plugs the assigned UI object type and UI object action describe the requested navigation target on high
level. This assignment is not used during cross component navigations with descriptor object. But it is used in the case that
the currently loaded work area component is left via one of its outbound plugs.
For inbound plugs the assigned UI object type and UI object action describe the provided navigation target on high level.
This assignment is only used to provide a value help in the customizing of generic outbound plug mapping, override generic
outbound plug mapping and specific outbound plug mapping.
Descriptor Object
The descriptor object allows navigation via one outbound plug to different targets - the information contained inside the
descriptor object is converted to a combination of UI object type and UI object action, which in turn can be mapped to
targets.
The descriptor object provides the following information:
1. UI object type
2. UI object action
3. Object to be processed (optional)
4. Component name (optional)
The developer of a UI component has to create the descriptor object. It can then be used to check if a certain navigation
target is available. It can also be added to the data collection passed to the inbound plug of the target in order to execute
navigation.
When the descriptor object is passed via the data collection, its data is evaluated to determine the target. In case it carri es
information that allows the creation of a BOL entity instance (for example the key and type of an entity), the BOL entity
instance is created and added to the data collection. The descriptor object is then deleted from the data collection and the
target inbound plug gets the same data as if the navigation would have been based on a direct mapping of outbound plug to
inbound plug using dedicated plugs. There is no extra coding needed on the inbound plug to enable it for dynamic
navigation.
How To Create The Descriptor Object
Service class CL_CRM_UI_DESCRIPTOR_OBJ_SRV provides the following 4 methods for creating a descriptor object:
CREATE_BOR_BASED
CREATE_ENTITY_BASED
CREATE_UI_OBJECT_BASED
CREATE_ADVANCED_SEARCH_BASED
Each of the methods takes a certain set of parameters and returns a reference to a descriptor object.
The example below assumes that you have an entity, which does not belong to your component. You want to trigger a cross
component navigation and display the entity.

DATA lr_descriptor_object TYPE REF TO if_bol_bo_property_access.
DATA lr_nav_srv TYPE REF TO if_crm_ui_navigation_service.
DATA lr_window_controller TYPE REF TO cl_bsp_wd_window.
DATA lr_data_collection TYPE REF TO if_bol_bo_col.

* create a descriptor object with a given BOL entity
CALL METHOD cl_crm_ui_descriptor_obj_srv=>create_entity_based
EXPORTING
ir_entity = lr_entity
iv_ui_object_type = space " is determined based on the
entity
iv_ui_object_action = 'B' " see CRMT_UI_ACTION
iv_component = 'MY_COMPONENT_NAME' " is used in Override Generic OP
Mapping
RECEIVING
rr_result = lr_descriptor_object.

* if the navigation is supported according to the customizing then add the
descriptor object to the data collection
lr_nav_srv = cl_crm_ui_navigation_service=>get_instance( me ).
IF lr_nav_srv->is_dynamic_nav_supported( ir_descriptor_object =
lr_descriptor_object ) EQ abap_true.
CREATE OBJECT lr_data_collection TYPE cl_crm_bol_bo_col.
lr_data_collection->add( iv_entity = lr_descriptor_object ).
ELSE.
" error handling
RETURN.
ENDIF.

* leave the ui component via an outbound plug of the current window
lr_window_controller ?= me->view_manager->get_window_controller( ).
lr_window_controller->call_outbound_plug(
iv_outbound_plug = 'MYWINDOWOPNAME'
iv_data_collection =
lr_data_collection ).

Do not use the interface IF_CRM_UI_NAVIGATION_SERVICE=>NAVIGATE_DYNAMICALLY as it ignores the concept
of outbound plugs! Only UI parts outside of the work area might use this interface method.
On window level you fire the outbound plug, which tells the UI runtime to leave the current UI component.

METHOD op_mywindowopname.
me->fire_outbound_plug( iv_outbound_plug = 'MYWINDOWOPNAME'
iv_data_collection = iv_data_collection ).
ENDMETHOD.

Object Mapping
The information needed to map between the different object types is taken from two places:
1. The setup of the UI object types
2. The object mapping definition
In the example of How To Create The Descriptor Object a BOL entity is part of the descriptor object and added to the data
collection. The Web Client UI framework gets the BOL object type (name) and gets the assigned mapping class, which is
either defined by SAP (maintenance view CRMV_UI_OBJ_MAPS) or the customer (maintenance view
CRMV_UI_OBJ_MAP). The mapping class provides a UI object type according to the given BOL entity.
The mapping class has to implement the interface IF_CRM_UI_OBJ_MAPPER. The interface provides these mappings:
input output
input output
UI object type BOL entity
BOR key BOL entity
BOR key UI object type
BOL entity UI object type
BOL entity BOR key
It is in the responsibility of the object owners that a unique mapping is possible. Some hints:
Many UI object types can use the same BOL entity. But there must be a technical attribute in the model of the BOL entity,
which allows a unique assignment to a UI object type.
The same it true for many UI object types and only one corresponding BOR object.
Some UI object types do not have a corresponding BOR object. Then provide an empty implementation.
It is allowed to use the mapping classes in your own coding on UI level. Class CL_CRM_UI_OBJECT_MAPPING_SRV
provides the access to the mapping classes.