Navigate Inside a UI Component - How to

Guide
Skip to end of metadata

Attachments:6
Added by Hasan Zubairi, last edited by Hasan Zubairi on Jul 30, 2014 (view change)
Go to start of metadata
Introduction
A navigation changes the current view assembly. It always leaves the current view (via an outbound
plug) and goes to a different view (via an inbound plug). The possible navigations (i.e. connections
from outbound plugs to inbound plugs) are part of the runtime repository of the current UI
component. It is also possible to go beyond the boundaries of the current UI component. Then the
navigation either leads into an embedded UI component (outside in) or it leaves to the embedding UI
component (inside out). In this case it is necessary to define plugs as part of the UI component.
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
Prerequisites For enabling a UI component to have a link and to execute a navigation you need
some basic knowledge about working in the UI component workbench (transaction
BSP_WD_CMPWB). We assume that you already have a simple input field as UI element on your
view.
Overview The smallest UI part that can be used by a navigation is the view. Navigations in a UI
component start always within a view (in contrast to a custom controller). Any navigation consists of
the following steps:
Rendering: You have to provide a UI element (i.e. a link or a button), which is supposed to trigger
the navigation on client side (browser)
Eventing: You need some code on server side, which handles the event of clicking the UI element.
Linking: You declare an id of your navigational link and add both a start point and an end point.
Your code passes this id to the WebClient UI Framework, which executes the navigation.
The rendering is influenced in the context node of your view. The event handler is implemented in
the implementation class of your view controller. The linking is declared in the runtime
repository of the UI component.
Rendering
Change Field Properties You can influence the rendering of the UI, e.g. you can define that a field
is to be visualized as a link instead of an input field. Your UI element is bound to an attribute of a
context node. (If not then you can directly influence the attributes of your tag on your layout.) Each
attribute can have specific GET methods. With the GET_P methods you can define different
properties that influence the rendering. As example we will have a look at the properties field
type and on click.
The interface IF_BSP_WD_MODEL_SETTER_GETTER contains all available properties.
The property field type provides the general information about how to render the UI element (e.g.
render a link instead of the default input field). We need to implement some code in the GET_P
method that is bound to our UI element. Whenever the method is asked for the field type then we will
provide the information to render a link (all available field types are part of the interface
IF_BSP_DLC_VIEW_DESCRIPTOR). See the code example below.
The property on click provides the name of an event, which should be triggered on clicking on the
link. The event name is case sensitive! Again we need a very simple piece of code in the GET_P
method. Whenever the method is asked for the on click event name we will provide this information.
Avoid spaces and special characters! See the code example below. You will need the event name
later on defining a handler, which reacts on the event.
If the GET_P method of your context node attribute does not already exist then create it with forward
navigation in the UI component workbench.


METHOD get_p_resulturl.

CASE iv_property.
WHEN if_bsp_wd_model_setter_getter=>fp_fieldtype.
rv_value = if_bsp_dlc_view_descriptor=>field_type_event_link.
WHEN if_bsp_wd_model_setter_getter=>fp_onclick.
rv_value = 'ClickResultURL'. "#EC NOTEXT
WHEN OTHERS.
RETURN.
ENDCASE.

ENDMETHOD.

Test Your Result If you start the UI component you will get the field RESULTURL as a link and on
clicking the link the event ClickResultURL will be triggered. As the application still does not react on
this event nothing will happen.
Eventing
Overview The UI Runtime automatically ensures that the triggered event is dispatched to your view
controller. In the view controller class you will need to react on the event in a handler method. This
handler method can evaluate data, attach data to the navigation and call an outbound plug method
of the view controller. The outbound plug method delegates the navigation to the UI runtime and
provides necessary information about the navigation.
Event Handler The workbench has a wizard for creating event handlers (see picture). The event
name must exactly match the string that is returned by the GET_P method (see section Rendering).

The wizard changes three parts of your UI component:
1. Catching the event: The implementation class of your view controller has a super class. This super
class gets a small piece of code in method DO_HANDLE_EVENT, which reacts on the provided
event name. In here the event name has to match exactly at runtime. Then an event handler method
will be called.
2. Creating event handler: The event handler method is created (happens also in the super class). This
method is automatically redefined in the implementation class of the view controller. The name of the
method gets the prefix EH_ON plus the event name (e.g. EH_ONCLICKRESULTURL).
3. Updating workbench: The event handler gets listed in the UI component workbench. Forward
navigation will open the source code.
Test Your Result If you now start the UI component and click the link then you will end up in the
event handler method (set a break-point in there). As it is still empty nothing will happen.
Implementing The Event Handler Method Finally you have to call the outbound plug, i.e. you want
to leave the current view via a specific exit. This is the only mandatory call in the event handler
method. (We do not have the outbound plug, yet. So you can still leave the implementation empty
and add the call after having created the outbound plug as described in the next section.

METHOD eh_onclickresulturl.

* call outbound plug
me->op_displayresulturl( ).

ENDMETHOD.

Outbound Plug We want to navigate. In its first step navigating means leaving the current view.
This is done via outbound plugs. Again the UI component workbench has a wizard for creating
outbound plugs (see picture).

The outbound plug name is not case sensitive. The wizard creates the outbound plug method in the
view controller class and automatically redefines it in the implementation class of the view controller.
The workbench display gets updated and you can use forward navigation for opening the source
code.
Remember: Now you can add the call of the outbound plug to the event handler method.
The implementation of the outbound plug method must contain a delegation of the navigation to the
UI runtime. Use the method NAVIGATE of the view manager. (We do not have declared any
navigational link, yet. So you can still leave the implementation empty and add the call after having
created the navigational link as described in Linking section).

METHOD op_displayresulturl.
me->view_manager->navigate( source_rep_view = me->rep_view
outbound_plug = 'NavLinkDisplayResultURL' "#EC
NOTEXT
data_collection = iv_data_collection ).
ENDMETHOD.

The parameter OUTBOUND_PLUG must get the name of the navigational link! It does not get
the name of the current outbound plug although the parameter name indicates this.
Remarks:
If you want to trigger a cross component navigation then have a look at Use Dynamic Cross
Component Navigation - How to Guide.
If you want to delegate the navigation to a UI component, which embeds your UI component, then
have a look at Leaving The Current UI Component section.
Optional Event Handler Coding
It is possible to attach data to the navigation. The receiving view of the navigation can extract the
data and react depending on the data. The data has to be put into the parameter data_collection of
the outbound plug. If your link is on a form view it is quite simple to get the current data.

* get current BOL data from context node
DATA lr_bol_bo TYPE REF TO if_bol_bo_property_access.
lr_bol_bo = me->typed_context->createurl->collection_wrapper->get_current(
).

* add BOL data to data collection of the navigation
DATA lr_data_collection TYPE REF TO if_bol_bo_col.
CREATE OBJECT lr_data_collection TYPE cl_crm_bol_bo_col.
lr_data_collection->add( iv_entity = lr_bol_bo ).

* call outbound plug
me->op_displayresulturl( iv_data_collection = lr_data_collection ).

If your link is in a table or a tree it is a little bit more complicated as you need the row index of the
clicked UI element. The necessary information is available with the provided parameter
HTMLB_EVENT_EX. Use a service method of the THTMLB library for getting the row index (and the
column if needed).

* get row index and column of UI element that was clicked
DATA lv_index TYPE i.
DATA lv_column TYPE string.
cl_thtmlb_util=>get_event_info( EXPORTING iv_event = htmlb_event_ex
IMPORTING ev_index = lv_index
ev_column = lv_column ).

* get BOL data according to row index from context node
DATA lr_bol_bo TYPE REF TO if_bol_bo_property_access.
lr_bol_bo = me->typed_context->createurl->collection_wrapper->find(
iv_index = lv_index ).

* add BOL data to data collection of the navigation
DATA lr_data_collection TYPE REF TO if_bol_bo_col.
CREATE OBJECT lr_data_collection TYPE cl_crm_bol_bo_col.
lr_data_collection->add( iv_entity = lr_bol_bo ).

* call outbound plug
me->op_displayresulturl( iv_data_collection = lr_data_collection ).

Remark: Attaching data to the navigation is only one possibility of providing data to the target view of
the navigation. Alternatively you can use data binding with custom controllers (works within the
boundaries of one UI component) or even with a global custom controller (works across UI
components). Data binding has the advantage that the target view will already have the correct data
during the initialization phase of the context. Data that is attached to the navigation is evaluated in
the inbound plug of the target view. Typically this data replaces the context data. The inbound plug
runs after the context initialization.
Linking
Navigational links define a connection from a source view (and its outbound plug) to a target view
(and its inbound plug) within a UI component. If your target view does not exist yet, then create it
now and add an inbound plug to the new view.
The component workbench has a wizard for creating a navigational link in the runtime repository
editor. Switch to edit mode and use the context menu of the node Navigational Links for adding a
new navigational link. In the provided pop up you can specify the navigation source (outbound plug
of a view) and the navigation target (inbound plug of a view). Context sensitive value helps facilitate
the correct handling.

You can see the result in the runtime repository browser. Save your changes!

Remember: Now you can complete the implementation of your outbound plug. In there the
navigational link is called.
Test Your Result If you now start the UI component and click the link then the navigation will be
executed and the inbound plug of the target view will be called.
Leaving The Current UI Component
It is possible to start a navigation in the current UI component and to define that the navigation
should leave the current UI component. This is possible in two directions:
Navigating into an embedded UI component
Navigating to the parent (embedding) component.
Remark: Additionally you could trigger a cross component navigation (see Use Dynamic Cross
Component Navigation - How to Guide)
Whenever a navigation goes beyond the boundaries of the current UI component then it is
necessary to add plugs to the interface of the UI component. Only plugs of windows can participate
in the interface of a UI component. Editing the UI component interface is done in the runtime
repository editor.
Navigating Into An Embedded UI Component Embedded UI components are available in the
current UI component with the help of so called usages. One usage provides the interface of an
embedded UI component to the current runtime repository. The interface of the embedded UI
component must provide an inbound plug. The wizard of adding navigational links automatically
provides inbound plugs of all available usages. The usage id is separated by a dot from concrete
parts of the usage.
Navigating To The Parent (Embedding) Component Your current component has no information
about the outer world. It can only define outbound plugs in its interface and fire these outbound
plugs. Go to your window and add an outbound plug with the wizard of the UI component
workbench. Update the runtime repository and add in there the outbound plug at the window and at
the corresponding interface view. (The interface view exposes your window to the outside world. It
exists only in the runtime repository.)

Remark: If you look at the UI component from the outside then it is a black box. The interface view is
visible on the surface of the black box and it can be used by a parent component like an own view.
Therefore it is called interface view.
In the outbound plug of the view we can add the following lines for calling the outbound plug of the
current window. Again you can use the data collection for transporting data with the navigation.

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

There exists the special method FIRE_OUTBOUND_PLUG, which is on window level, for leaving the
current UI component. So here is the code of the window outbound plug:

METHOD op_leavetoparentcomponent.
me->fire_outbound_plug( iv_outbound_plug = 'LEAVETOPARENTCOMPONENT'
iv_data_collection = iv_data_collection ).
ENDMETHOD.

After this call it is up to the parent component to handle the navigation. This can be done in different
ways:
Declaration in the runtime repository that the fired outbound plug is directly connected to an
outbound plug of the interface view. I.e. the navigation uses a fast transit through the UI component
and is directly passed to the next parent UI component.
Declaration in the runtime repository that a navigational link has the fired outbound plug as source
view. I.e. the UI component itself handles the navigation.