Inter-Application-Navigation in Web Dynpro

Summary
Most SAP Web Dynpro navigation scenarios only take place inside a single application (intraapplication-navigation). The user starts an application (activating a URL in a Web browser), then navigates from one View assembly to anotherwithout leaving the applications root component. As an application developer, you simply define navigation links between the views inbound and outbound plugs, then implement the method-calls for firing the views outbound plugs. The term inter-application-navigation describes a different scenario, where the user can navigate from one Web Dynpro application to another by firing an interface view controllers exit plug. This article illustrates how to implement a sample project that demonstrates the navigation from one Web Dynpro application to another. In contrast to intra-application-navigation a URL has to be determined for calling the target application. Getting this URL can be simplified by utilizing special Web Dynpro service classes like WDURLGenerator and WDDeployableObject. For passing values from one application to another, we apply a built-in Web Dynpro mechanism for automatically transferring URL-parameters to a so-called component interface view controller that handles the interface views inbound plug or startup plug events. Besides these central features, this sample application also demonstrates how to access IPublic-APIs of used controllers for setting context data or firing plugs.

Contents
1. Introduction 2. Creating Initial Project 3. Developing the Start Component 4. Developing the Target Component 5. Testing the Sample Application 6. Conclusion

Keywords
Web Dynpro applications, interface views and interface view controllers, root component, URLparameter transfer, inter-application-navigation, context mapping, controller usage, accessing a controllers IPublic-API, startup plugs, exit plugs, WDURLGenerator, WDDeployableObject

1. Introduction
The following screenshots illustrate a scenario involving inter-application-navigation in Web Dynpro. Initially, the Web Dynpro application named StartApp is started in a web browser. It contains an input field for entering a parameter value. This parameter is sent to the target application by the URL upon pressing the Go to target application button.

In the next step the target application is being displayed in the same browser window. Its URL contains one single parameter called hugo with the URL-encoded value, entered by the user in the UI of the start application.

Before we begin developing our inter-application-navigation project, consider the significance of a Web Dynpro application. It is specified by (1) the definition of a single Web Dynpro component, or root component; (2) an interface view of this root component; and (3) a single startup plug of the interface view (Figure 1). The root component can aggregate additional Web Dynpro components by component usage relationships, but this is irrelevant for the definition of an application.

Figure 1. Web Dynpro application and aggregated components. Every Web Dynpro application can then be called up in a web browser by its application URL. Keep in mind that no application controller will be created when defining a Web Dynpro application. An application is just a URL address for launching a Web Dynpro root component. All existing controllers will live inside a corresponding component. The main idea behind navigating from one application to another is to fire an exit plug in root component A (aggregated by application A) referring to the URL of application B (target application). There is no normal navigation link existing between an exit plug and a startup plug, in comparison to navigation links between inbound and outbound plugs. The inter-application-link is just the URL of the target application.

Figure 2. Principle of an inter-application-navigation scenario Figure 2 illustrates this scenario. The exit plug is fired in an interface view controller of the start component (1). For firing an exit plug to the Web Dynpro runtime environment the application developer has to pass some URL-string (2). This can be a link to a web page like http://www.sap.com, or a link to another Web Dynpro application. Because every Web Dynpro application is related to a startup plug of an interface view, the corresponding startup plug eventhandler will be called when the target application is launched (3). Before calling the startup plug eventhandler, the Web Dynpro runtime first instantiates all controllers (like component and view controllers) needed for displaying the initial view assembly in the user interface.

2. Creating initial Project

Now we develop our sample application and start with creating the initial project structure Create a new Web Dynpro project called WebDynpro_InterAppNav. Create two separate new Web Dynpro applications via the context menu item Create application of node Web Dynpro Applications in the Web Dynpro explorer: o StartApp in package com.sap.sdn.webdynpro.interappnav.start related to component StartComp. StartComp has a window with the same name containing a view called StartView. TargetApp in package com.sap.sdn.webdynpro.interappnav.target related to component TargetComp. TargetComp has a window with the same name containing a view called TargetView.

When clicking the node Web Dynpro Applications StartApp you see the references of the defined Web Dynpro application: the related Web Dynpro root component StartComp, the used interface view StartCompInterfaceView and the startup plug Default fired by the Web Dynpro Runtime when starting the defined application (see also Figure 1).

Figure 3. Defining a Web Dynpro Application in SAP NetWeaver Developer Studio

3. Developing the Start Component

The development of component StartComp can be separated into the following parts: Component Interface View StartCompInterfaceView: o Defining an exit plug with parameter Url of type string

View StartView: o o o o Defining the view context (value attribute for storing the entered URL parameter) Defining view layout and databinding Defining the interface view controller usage Implementing the action eventhandler for firing an exit plug to the target application URL

Defining an exit plug

For navigating from application StartApp to application TargetApp, we need an exit plug in the interface view of component StartComp. This exit plug does not exist by default like the startup plug with name Default. The exit plug is defined in combination with a parameter named Url of type string, so that we can later pass the URL to our target application. 1. In the Web Dynpro explorer expand node WebDynpro_InterAppNav Web Dynpro Components StartComp Component Interface Interface Views StartCompInterfaceView and then double-click on it. 2. Select tab Plugs 3. Add a new outbound plug of type exit plug (mark checkbox Exit Plug in window New Outbound Plug) named StartAppExit and click on Next. 4. By clicking New add a parameter with name Url (must be exactly named like this) of type string. 4

After having defined this exit plug, the IPublic-API of the interface view controller (named IPublicStartCompInterfaceView.java) is automatically extended by the new method wdFirePlugStartAppExit(String). Since the IPublic-API is accessible for all controllers in the same component (also view controllers) after having declared the usage of the interface view controller, we can call this new method from within the view controller implementation.

The interface IPublicStartCompInterfaceView shown in the Package Explorer

Defining the view context

In the next step we define a single, top-level value attribute in the controller context of view StartView. We need it for storing the URL-parameter value entered by the user. This value is then sent to the target application by adding it to the corresponding target URL. 1. Select view StartView with a double-click on node Web Dynpro Components StartComp Views StartView. 2. In the context tab, define a new top level value attribute named UrlParamValue of type string.

Defining view layout and databinding

The view layout is very simple. Under the title text there is only a mini input form for entering the value of URL-parameter hugo. Additionally, we need a button for triggering the inter-application-navigation step. 1. Select the node Web Dynpro Components StartComp Views StartView 2. Select the Layout tab. 3. In the Outline perspective view, choose the RootUIElementContainer and give its layout property the value RowLayout. 4. Choose UI-element DefaultTextView and enter the text-property Web Dynpro Application 'StartApp'. Give its design property the value header1. 5. For adding the input form, choose the RootUIElementContainer again and select the item Apply Template in its context menu. 6. In the first wizard window, click on the icon Form and then Next. 7. Mark the checkbox for value attribute UrlParamValue, then choose Finish. 8. In the view layout outline choose element UrlParamValue_label and enter Enter value for URL parameter 'hugo' for the text property. Before adding a button UI-element, we must define a new action in the view controller. 1. Select the Actions tab. 2. Click the New button. 3. Enter the Name Go and Text Go to target application. 4. Add a new button with the name GoButton and bind its event onAction to action Go. The View Designer displays the following layout for the StartView.

Defining the interface view controller usage

For being able to access the IPublic-API of an interface view controller from another controller, the corresponding controller usage has to be defined. In our case we want to call method wdFirePlugStartAppExit(String)exposed by the IPublic-API of interface view controller StartCompInterfaceView within the controller of view StartView. 1. Select the Web Dynpro Components StartComp Views StartView node. 2. Select the Properties tab. 3. Add the required usage of the controller StartCompInterfaceView.

After having defined a conroller usage, you can access the IPublic-API of the used controller by calling the method wdGet<name of used controller>Controller(). This method is accessible via the member variable wdThis of type IPrivate<controller name>.

The interface IPrivateStartView shown in the Package Explorer

Implementing the action eventhandler and generating target URL

After finishing the above declarations, we can now implement the eventhandler for the action Go. See figure 3 for a better understanding of this implementation. To access the interface view controller API from inside of the StartView controller, we have declared a corresponding controller usage (1). This usage provides an access to the IPublic-API (2) of the interface view controller (3), which is able to fire an exit plug referencing the target application (4).

Figure 4. Start Component and firing exit plug Now there is only one open question: How do we refer to the target application with a URL? The corresponding URL can easily be generated by applying two Web Dynpro service classes called WDURLGenerator and WDDeployableObject, provided the following two conditions are true. The first condition is that the target application (which is a Deployable Object Part) is named TargetApp. The second condition is that it belongs to the same Web Dynpro project, also called Deployable Object, as the start application. The URL-generation has to imply the addition of the namevalue-pair of URL-parameter hugo. Implement the following source code in method onActionGo() of view controller StartView.java and afterwards press keys CTRL+Shift+F for organizing the imports:

//@@begin javadoc:onActionGo(ServerEvent) /** Declared validating event handler. */ //@@end public void onActionGo(com.sap.tc.webdynpro.progmodel.api.IWDCustomEvent wdEvent) { //@@begin onActionGo(ServerEvent) // Get component's message manager IWDMessageManager messageMgr = wdComponentAPI.getMessageManager(); // Get name of deployable object this component belongs to String deployableObjectName = wdComponentAPI.getDeployableObjectPart().getDeployableObjectName(); Map urlParameters = new HashMap(); // get URL parameter value entered by user, stored in context attribute // UrlParamValue. Put parameter hugo in the sneak preview version. urlParameters.put("hugo", wdContext.currentContextElement().getUrlParamValue()); try { // Get deployable object part of target application. // Precondition: assume, that other application belongs to the same // Web Dynpro Project (Deployable Object) WDDeployableObjectPart deployableObjectPart = WDDeployableObject.getDeployableObjectPart( deployableObjectName, "TargetApp", WDDeployableObjectPartType.APPLICATION); // Get target URL based on deployable object part and URL parameters

String urlToTargetApp = WDURLGenerator.getApplicationURL(deployableObjectPart, urlParameters); // Fire exit plug to target URL via IPublic-API of used interface view // controller wdThis.wdGetStartCompInterfaceViewController() .wdFirePlugStartAppExit(urlToTargetApp); } catch (WDURLException e) { messageMgr.reportException(e.getLocalizedMessage(), false); } catch (WDDeploymentException ex) { messageMgr.reportException(ex.getLocalizedMessage(), false); } //@@end }

Upon exiting Web Dynpro application A to start another Web Dynpro application B, all components (starting from the root component) and their aggregated controllers will be automatically destroyed by the Web Dynpro Java Runtime.

4. Developing the Target Component

The development of component TargetComp can be structured like this: 1. Component Interface View TargetCompInterfaceView: a. Defining the component controller usage b. Adding a startup plug parameter with name hugo of type string c. Implementing the startup plug eventhandler and storing the retrieved URL-parameter in the component controller context

2. Component Controller TargetComp: a. Defining the component context (value attribute for storing the retrieved URL parameter) 3. View TargetView: a. Defining the component controller usage b. Defining the view context by defining a context mapping relation to the component context c. Defining view layout and databinding

See the following diagram (figure 4) to better understand the differences between the start and the target component.

Figure 5. Target Component and storing the retrieved URL-parameter in the component context

When the target application is addressed by the start application, the startup plug (1) of the defined interface view in component TargetComp is automatically fired by the Web Dynpro runtime. The interface view controller implements an eventhandler for this startup plug and automatically retrieves the value of URL-parameter hugo. This URL-parameter retrieval inside a startup plug eventhandler is automatically done by the Web Dynpro runtime. The only requirement an application developer has to fulfill is to add a parameter of type string for every URL-parameter with the same name. How can the interface view controller (2) store the retrieved URL-parameter value so that other controllers can access it? Because an interface view controller does not have its own context, context mapping cannot be applied. But instead of mapping to another context, we can access the context of the component controller (4) via its IPublic-API (3) after having declared the usage of this controller. The URL-parameter value can then easily be displayed in view TargetView (5) after having defined the context mapping from the view context to the component context (4).

Adding a startup plug parameter with name hugo of type string

1. In the Web Dynpro explorer, select the node WebDynpro_InterAppNav Web Dynpro Components TargetComp Component Interface Interface Views TargetCompInterfaceView. 2. Add a new plug parameter named hugo of type string to the inbound (exit) plug Default.

The Web Dynpro runtime will pass the value of a URL-parameter named hugo to the parameter named hugo in the startup plug eventhandler of the interface view controller.

Defining the component context

Before implementing this startup plug eventhandler, we define a new context value attribute in the component controller. The component context acts as a global storage place that can be accessed by all other controllers in the same component. 9

1. Select component TargetComp. 2. In the context tab, define a new top level value attribute named UrlParamValue of type string.

Defining the component controller usage

1. In the Web Dynpro Explorer, select the interface view TargetCompInterfaceView again. 2. Select the Properties tab. 3. Add the required usage of component controller TargetComp. Make sure that you mark the checkbox of the component controller and not of the component interface controller.

Implementing the startup plug eventhandler

Select tab implementation and implement the following source code in method onPlugDefault() of view controller TestCompInterfaceView.java:

//@@begin javadoc:onPlugDefault(ServerEvent) /** Declared validating event handler. */ //@@end public void onPlugDefault( com.sap.tc.webdynpro.progmodel.api.IWDCustomEvent wdEvent, java.lang.String hugo) { //@@begin onPlugDefault(ServerEvent) // the method value of method parameter 'paramter' will be automatically // filled with URL-parameter parameter wdThis.wdGetTargetCompController() .wdGetContext().currentContextElement().setUrlParamValue(hugo); //@@end }

The value of URL-parameter hugo is passed to the startup plug Default. By accessing the IPublic-API of the used component controller it can easily be stored in the component context.

Defining a mapped view context attribute

For defining the mapping between view- and component context we can use the data modeler tool. 1. Open the data modeler with a double-click on the node Web Dynpro Components TargetComp 2. In the toolbar of the data modeler click on the icon Create a data link.

3. Draw a data link from the view controller symbol TargetView to the component controller. 4. Define a context mapping relation by dragging context attribute UrlParamValue at the right side (component context) and then dropping it to the root node of the view context at the left side. 5. Mark the checkbox for value attribute UrlParamValue and rename the mapped attribute to ReceivedParameter. Then click the Finish button.

10

Defining view layout and databinding

The view layout of the TargetView looks quite similar to the one of view StartView. So we can apply the Copy & Paste feature provided by the Web Dynpro tools. 1. Select the node Web Dynpro Components StartComp Views StartView 2. Select the Layout tab. 3. In the Outline perspective view select the three elements of type TextView, Label and InputField. To do this you must to press the Shift button. 4. In the context menu select item Copy. 5. Select view Web Dynpro Components TargetComp Views TargetView 6. Delete the UI-element DefaultTextView. 7. Select the UI-element RootUIElementContainer and select context menue item Paste. 8. Change property text of the TextView-UI-element to Web Dynpro Application 'TargetApp'. 9. Change property text of the Label-UI-element to Received value of URL parameter 'hugo'. 10. Change property readOnly of the InputField-UI-element to true. 11. Finally, we must define the databinding: Bind the property value of the input field to the context attribute ReceivedParameter.

5. Testing the Sample Application

We can now build, deploy, and run our Web Dynpro project developed to demonstrate the navigation between two separate applications with URL-parameter transfer. The application should have the same behavior like described in the introduction. Enter some text for the URL parameter hugo and then press the button for navigating to the target application. In the same browser window, the target application will be displayed with the URL-parameter value. At this point, the previous start application, or better its aggregated start component, is destroyed by the Web Dynpro runtime.

Exercise
The view displayed in the target application does not contain a button for navigating back to the start application. A good exercise is to extend the sample project so that this functionality is also provided. The development process is quite similar to the tutorial description above (navigating from the start application to the target application), but its the other way round without implementing the URLparameter transfer.

6. Conclusion
This Web Dynpro tutorial demonstrated how to navigate from one Web Dynpro application to another by generating the corresponding application URL and firing an interface view controllers exit plug. To generate the target application URL, the two Web Dynpro service classes WDURLGenerator and WDDeployableObject were used. The data transfer between two applications is based on adding name-value-pairs to the application URL, which can be received by the interface view controller of the target component.

11