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.
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.
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.
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.
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:
- 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.
- 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).
- 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.
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).
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.
- 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.
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).
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.
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.
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:
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.