SDN Contribution

How to Navigate Inside Web Dynpro Component Interface Views

Applies to:
Web Dynpro for Java UI Development, SAP NetWeaver 2004, SAP NetWeaver 2004s

Summary
This article was inspired by the repeated question on how to navigate to a certain view inside a Web Dynpro component (cross-component navigation). As soon as another component interface view wants to navigate to a specific flavor of the target component interface view, we must apply some tricks to fulfill this task. Specific flavor of a component interface view means that we want to display another view other than the defined default view within the target component. This article describes a solution to navigate inside Web Dynpro component interface views, based on serverside-eventing and an additional navigation dispatcher view. It also demonstrates how to transfer parameter values with outbound plugs, inbound plug event handlers, events, and methods across component and controller borders. Created on: 9 May 2006

Author Bio
After his studies in mathematics, physics and computer science Bertram Ganz finished his teacher training at a German grammar school stressing technical sciences. He has been a member of the Web Dynpro Java Runtime development team (SAP NetWeaver ESI Foundation UI) since 2002. The main focus of his work is on knowledge transfer, rollout, and documentation. Bertram regularly publishes articles on Web Dynpro in the context of the SAP NetWeaver Application Server. He also runs several Web Dynpro trainings and is the coauthor of the SAP Press Book, Java Programming with the SAP Web Application Server.

2006 SAP AG

How to Navigate Inside Web Dynpro Component Interface Views

Table of Contents
Summary.......................................................................................................................................... 1 Author Bio ........................................................................................................................................ 1 Table of Contents ............................................................................................................................ 2 Table of Contents ............................................................................................................................ 2 Concept Web Dynpro Navigation Basics...................................................................................... 3 Scenario Navigating from and to Component Interface Views..................................................... 3 Example ....................................................................................................................................... 3 Problem How to Navigate from Outside to Inside a Component Interface View.......................... 4 Solution - Navigation Dispatcher View and Server-side Eventing................................................... 5 Declaration and Implementation Tasks ........................................................................................... 6 Step 1 - Create New NavDispatcherView .................................................................................... 6 Step 2 - Add New ViewContainerUIElement................................................................................ 6 Step 3 - Define New Outbound Plugs within the NavDispatcherView ......................................... 6 Step 4 - Embed All Views within the ViewContainerUIElement................................................... 6 Step 5 - Define New Navigation Links ......................................................................................... 6 Step 6 - Define Event DispatchNavigation in the Component Controller .................................... 7 Step 7 - Define Method fireDispatchNavigation in the Component Controller............................. 7 Step 8 - Subscribe Event Handler in the NavDispatcherView Controller .................................... 8 Step 9 - Implement Inbound Plug Event Handler ........................................................................ 8 Step 11 - Fire Outbound Plugs within NavDispatcherView.......................................................... 8 Conclusion ....................................................................................................................................... 9 Outlook............................................................................................................................................. 9 Related Content............................................................................................................................. 10 Sample Application .......................................................................................................................... 9 Prerequisites ................................................................................................................................ 9 Importing the Project .................................................................................................................... 9 Testing the Sample Application ................................................................................................. 10 Copyright........................................................................................................................................ 11

2006 SAP AG

How to Navigate Inside Web Dynpro Component Interface Views

Concept Web Dynpro Navigation Basics

Before we start, let us first repeat the basics of the Web Dynpro navigation concept. Navigation is based on the concept of navigation plugs and navigation links. Two main types of navigation plugs exist: inbound plugs and outbound plugs. To navigate from one Web Dynpro view to another an outbound plug of View A must be connected with an inbound plug of View B by defining a navigation link. This can easily be done within the Navigation Modeler of the Web Dynpro Tools. It is also possible to start several navigation links from the same outbound plug pointing to different target views. This means that several views (within several view containers like ViewContainerUIElements or ViewAreas) can be replaced with one single outbound plug. After having declared the navigation plugs and navigation links at design time the navigation process must be triggered at runtime by firing outbound plugs within the controller coding. Firing these plugs is based on calling the automatically generated wdFirePlug<name of outbound plug>-methods. These methods are added to the IPrivate-API of the corresponding view controller. You can access this API with the shortcut variable wdThis so that firing and outbound plug looks like this: wdThis.wdFirePlugConfirmOut(). The Web Dynpro Runtime then automatically navigates to the next view assembly by following the declared navigation links. To transfer parameter values to the target view controllers you can declare Java parameters for outbound and inbound plugs. These parameters are passed from the wdFirePlug-method to the inbound-plug-event handlers of the target view controllers. What's the advantage of using navigation plugs and navigation links? The main advantage is the possibility to hide the information on the navigation targets from the controller coding. The view controller of the navigation source view just fires an outbound plug without knowing the navigation target. Consequently you can declaratively change the navigation links without modifying any view controller code.

Scenario Navigating from and to Component Interface Views

The above navigation concept is also valid for component interface views. A component interface view is the visual interface of a Web Dynpro component. Like normal views component interface views can have navigation plugs (inbound and outbound plugs). In contrast to normal views component interface views can additionally have startup plugs and exit plugs for starting and exiting a Web Dynpro application. Example The main component MainComp visually embeds two User Interface components called UICompA and UICompB (see figure 1). This means the component interface views of UICompA and UICompB are embedded within a window of MainCompA. This is done within the Navigation Modeler after having defined two component usages of UICompA and UICompB within the main component. Afterwards both component interface views can be connected to each other by defining navigation links from outbound to inbound plugs.

2006 SAP AG

How to Navigate Inside Web Dynpro Component Interface Views

Figure 1 Navigation between Web Dynpro Component Interface Views To trigger the navigation from UICompB to UICompA the wdFirePlug-method must be fired within the controller code. This can be directly done within an action event handler of a view controller after having defined a controller usage relation to the component interface view controller. //@@begin javadoc:onActionNavigateToUICompA(ServerEvent) /** Declared validating event handler. */ //@@end public void onActionNavigateToUICompA( com.sap.tc.webdynpro.progmodel.api.IWDCustomEvent wdEvent) { //@@begin onActionNavigateToUICompA(ServerEvent) wdThis.wdGetUICompBInterfaceViewController() .wdFireCrossCompNavOut(); //@@end }

Problem How to Navigate from Outside to Inside a Component Interface View

So far we have not applied some special tricks yet. We just implemented the navigation from UICompB to UICompA. For learning something new we consider the following requirement. Question - How can we navigate to a certain view (or to be more exact view assembly) within the target component without "seeing" this view and its inbound plugs from outside the component? Component Interface Views cannot directly navigate to views inside a component because there are no inner outbound plugs which can be linked to the inner views inbound plugs. In respect of our sample scenario this means: how can we navigate from UICompB to a certain view (like ViewOne ore ViewTwo) within UICompA (see figure 2)?

2006 SAP AG

How to Navigate Inside Web Dynpro Component Interface Views

Figure 2 How to navigate from outside to inside a component interface view The first and most simple step to solve this issue is to specify a new navigation plug parameter named targetView which passes an Id value for the requested target view within UICompA. The coding for firing the outbound plug within the navigation source component UICompB then looks like this: public void onActionNavigateToUICompA( com.sap.tc.webdynpro.progmodel.api.IWDCustomEvent wdEvent, int targetView ) { //@@begin onActionNavigateToUICompA(ServerEvent) wdThis.wdGetUICompBInterfaceViewController() .wdFirePlugCrossCompNavOut(targetView); //@@end } With this Id the target component UICompA can then dispatch to the right view. But how does this navigation dispatching inside the target component work? To dispatch the navigation from component interface view to a view inside the same component we must fire an additional outbound plug. But component interface views do not have special inner outbound plugs which can point to a view inbound plug inside the same component.

Solution - Navigation Dispatcher View and Server-side Eventing

To solve the second issue (navigation dispatching inside the target component) we invent a special navigation dispatcher view inside the target component UICompA. This navigation dispatcher view must fulfill the following requirements: 1. It must always be active or displayed within the UICompA window. 2. It must embed the normal view composition (the other views) of UICompA. 3. It must have separate outbound plugs with links to the inbound plugs of the other views. 4. It must dispatch all incoming navigation requests from the inbound plug event handler of the component interface view (of UICompA) by firing its own outbound plugs.

2006 SAP AG

How to Navigate Inside Web Dynpro Component Interface Views

Declaration and Implementation Tasks

Within the next steps we successively develop a view named NavDispatcherView, which fulfils all these requirements. We first start with the declaration tasks. Step 1 - Create New NavDispatcherView We first create a new view with name NavDispatcherView, embed it within the related window of UICompA (related to the component interface view UICompA navigates to) and set its default property to true. Consequently the NavDispatcherView is automatically active (created) when creating the UICompA component instance. Step 2 - Add New ViewContainerUIElement We then add a new ViewContainerUIElement to the NavDispatcherView view layout. This view container is just there for embedding the actual view composition. Instead of directly modeling this view composition (views and navigation links) within a window we model it within the NavDispatcherView. This has the advantage that we can define additional outbound plugs for dispatching the navigation which is not possible on the window level yet. Step 3 - Define New Outbound Plugs within the NavDispatcherView For every target view we want to reach via navigation from outside the component we define a special outbound plug for the NavDispatcherView. Step 4 - Embed All Views within the ViewContainerUIElement Additionally we embed the other (normal) views within the ViewContainerUIElements of the NavDispatcherView. Step 5 - Define New Navigation Links To navigate from the NavDispatcherView to the inner views ViewOne, ViewTwo etc. we must draw navigation links from the outbound plugs of the NavDispatcherView to the inbound plugs of the visually embedded inner views. After having completed these steps the navigation modeler displays the following diagram:

Figure 3 Navigation Dispatcher View within the Navigation Modeler

2006 SAP AG

How to Navigate Inside Web Dynpro Component Interface Views Last but not least we must solve the following problem: how can we fire the NavDispatcherView's outbound plug from within the inbound plug event handler of UICompA's component interface view controller? As the NavDispatcherView controller cannot be used by or does not expose a IPublic-API to the component interface view controller we have to apply another mechanism for interacting between Web Dynpro controllers: server-side eventing. Figure 4 illustrates the event-based mechanism to dispatch navigation from within the component interface controller via the NavDispatcherView:

Figure 4 How to navigate from outside to inside a component interface view 1. First we fire the component controller event DispatchNavigation within the inbound plug eventhandler of the component interface view controller. This is done by calling the public method fireDispatchNavigationEvent(int targetView) within the IPublic-API of the component controller. 2. This method then fires the DispatchNavigation event itself: wdThis.wdFireEventDispatchNavigation(targetView). Notice that this method is not exposed within the IPublic-API of the component controller so that an additional "helper" method fireDisparchNavigationEvent() must be declared. 3. The NavDispatcherView subscribes its event handler onDispatchNavigation() to the DispatchNavigation event of the component controller. 4. It can then fire its own outbound plugs to navigate to the embedded views within the event handler onDispatchNavigation(). Step 6 - Define Event DispatchNavigation in the Component Controller Within the component controller we define a new serverside event named DispatchNavigation and declare the event parameter targetView of type integer for it. Step 7 - Define Method fireDispatchNavigation in the Component Controller Within the component controller we then declare a public method named fireDispatchNavigationEvent() and declare the method parameter targetView of type integer for it.

2006 SAP AG

How to Navigate Inside Web Dynpro Component Interface Views Step 8 - Subscribe Event Handler in the NavDispatcherView Controller Within the NavDispatcherView controller we declare the event handler onDispatchNavigation() and declare the event parameter targetView of type integer for it. This event handler is subscribed to the DispatchNavigation event of the component controller, after having declared the corresponding controller usage relation. Step 9 - Implement Inbound Plug Event Handler Within the component interface view controller of UICompA we fire the DispatcheNavigation event. This is done in the event handler of the component interface views inbound plug. To call the public method fireDispatchNavigationEvent() of the component controller the corresponding controller usage relation must be declared. //@@begin javadoc:onPlugDisplayViewIn(ServerEvent) /** Declared validating event handler. */ //@@end public void onPlugDisplayViewIn( com.sap.tc.webdynpro.progmodel.api.IWDCustomEvent wdEvent, int targetView ) { //@@begin onPlugDisplayViewIn(ServerEvent) wdThis.wdGetUICompAController().fireDispatchNavEvent(targetView); //@@end } Step 11 - Fire Outbound Plugs within NavDispatcherView Within the view controller method onDispatchNavigation() of the class NavDispatcherView.java we can then dispatch navigation plugs by firing the related outbound plug. //@@begin javadoc:onDispatchNavigation(ServerEvent) /** Declared validating event handler. */ //@@end public void onDispatchNavigation( com.sap.tc.webdynpro.progmodel.api.IWDCustomEvent wdEvent, int targetView ) { //@@begin onDispatchNavigation(ServerEvent) switch (targetView) { case 0 : wdThis.wdFirePlugViewOneOut(); break; case 1 : wdThis.wdFirePlugViewTwoOut(); break; case 2 :

2006 SAP AG

How to Navigate Inside Web Dynpro Component Interface Views wdThis.wdFirePlugViewThreeOut(); break; default: break; } //@@end }

Conclusion
As long as two views belong to the same component, the navigation from one view to the other can be directly defined with a single navigation link. In case these two views belong to separate components they cannot be directly linked with each other because they are hidden behind the component borders. This article described a practical solution for such a cross-component-navigation scenario by answering the following main question: How can we dispatch a component interface views inbound plug to an inbound plug of an inner target view? By introducing a special navigation dispatcher view inside the navigation target component we can create inner navigation links that are connected with the target views. Because the navigation dispatcher view must be always visible during the whole target component lifecycle we set its default-property to true and embedded all inner views within a ViewContainerUIElement. The navigation dispatcher views outbound plugs are fired from within interface view controller by firing an event and passing the id of the requested target view.

Outlook
You might ask why it is quite cumbersome in SAP NetWeaver 04 and 04s to navigate across Web Dynpro component borders. The answer is: there is no simpler solution because we cannot define inner outbound plugs within component interface views. To dispatch navigation we have to fire outbound plugs which can only be defined on view but not on interface view level. As a consequence of this issue the Web Dynpro component architecture will be enhanced within the next major SAP NetWeaver release so that navigation plugs can also be defined on the window level (window plugs). The component interface view controller will then be implemented by the new window controller so that the navigation dispatching mechanism described in this article can be managed by the window controller directly. A special navigation dispatcher view is then no longer needed because the window itself can dispatch navigation requests. Based on the new window plug concept, all cross-component-navigation scenarios can be implemented more easily within the next major SAP NetWeaver release.

Sample Application
This article is based on a Web Dynpro sample application, which is available for download on the SAP Developer Network (SDN) under Web Dynpro Sample Applications and Tutorials Cross-Component Navigation. Prerequisites The sample application is based on a SAP NetWeaver 04 Stack 14 installation. Importing the Project Read the instructions on how to import the Local Web Dynpro Sample DC into your developer workspace.

2006 SAP AG

How to Navigate Inside Web Dynpro Component Interface Views Testing the Sample Application The sample application starts with the component interface view of the UI Component A. Press the LinkToAction-UI-element to navigate to the other UI Component B. From there you can navigate back to a specific View within the target UI component A. Depending on the clicked LinkToAction-UI-element a specific value of the event parameter targetView is passed to the action event handler (see the previous section Problem How to Navigate from Outside to Inside a Component Interface View). Based on the described solution the corresponding view within the target UI Component A is displayed.

Related Content
1. Sample Application: Creating an Extended Web Dynpro Application 2. Sample Application: View Composition 3. Sample Application: Designing Component-Based Web Dynpro Applications

2006 SAP AG

10

How to Navigate Inside Web Dynpro Component Interface Views

Copyright
Copyright 2006 SAP AG. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft, Windows, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere, Netfinity, Tivoli, Informix, i5/OS, POWER, POWER5, OpenPower and PowerPC are trademarks or registered trademarks of IBM Corporation. Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation. UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group. Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc. HTML, XML, XHTML and W3C are trademarks or registered trademarks of W3C, World Wide Web Consortium, Massachusetts Institute of Technology. Java is a registered trademark of Sun Microsystems, Inc. JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. MaxDB is a trademark of MySQL AB, Sweden. SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP NetWeaver, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary. These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. These materials are provided as is without a warranty of any kind, either express or implied, including but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. SAP shall not be liable for damages of any kind including without limitation direct, special, indirect, or consequential damages that may result from the use of these materials. SAP does not warrant the accuracy or completeness of the information, text, graphics, links or other items contained within these materials. SAP has no control over the information that you may access through the use of hot links contained in these materials and does not endorse your use of third party web pages nor provide any warranty whatsoever relating to third party web pages. Any software coding and/or code lines/strings (Code) included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, except if such damages were caused by SAP intentionally or grossly negligent.

2006 SAP AG

11