Professional Documents
Culture Documents
SAP AG Dietmar-Hopp-Allee 16 69190 Walldorf Germany T +49/18 05/34 34 24 F +49/18 05/34 34 20 www.sap.com SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP NetWeaver, Copyright 2005 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. These materials are subject to change without notice. These 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, and Informix are trademarks or registered trademarks of IBM Corporation in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation. Disclaimer 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. 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. Any Java Source Code delivered with this product is only to be used by SAPs Support Services and may not be modified or altered in any way. Some components of this product are based on Java. Any code change in these components may cause unpredictable and severe malfunctions and is therefore expressively prohibited, as is any decompilation of these components. 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. 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.
Typographic Conventions
Type Style Example Text Represents Words or characters quoted from the screen. These include field names, screen titles, pushbuttons labels, menu names, menu paths, and menu options. Cross-references to other documentation. Example text Emphasized words or phrases in body text, graphic titles, and table titles. Technical names of system objects. These include report names, program names, transaction codes, table names, and key concepts of a programming language when they are surrounded by body text, for example, SELECT and INCLUDE. Output on the screen. This includes file and directory names and their paths, messages, names of variables and parameters, source text, and names of installation, upgrade and database tools. Exact user entry. These are words or characters that you enter in the system exactly as they appear in the documentation. Variable user entry. Angle brackets indicate that you replace these words and characters with appropriate entries to make entries in the system. Keys on the keyboard, for example, F2 or ENTER.
Icons
Icon Meaning Caution Example Note Recommendation Syntax
EXAMPLE TEXT
Example text
Example text
<Example text>
EXAMPLE TEXT
Contents
1 2 3 4 CREATING AN EXTENDED WEB DYNPRO APPLICATION .......................................... 1 QUIZ APPLICATION ......................................................................................................... 3 CREATING THE FIRST PARTS OF THE APPLICATION................................................ 6 VIEW MODELING AND USER INTERFACE LAYOUT .................................................... 6 4.1 4.2 4.3 4.4 5 6 7 Determining the Content and Interaction of Views.................................................... 7 Defining a View Composition .................................................................................... 9 Implementing the View Composition....................................................................... 13 Designing a View Layout......................................................................................... 17
USING THE ACTIONBUTTON TEMPLATE ................................................................... 23 CREATING NAVIGATION TRANSITIONS ..................................................................... 25 CONTROLLER CONTEXTS AND DATA BINDING ....................................................... 26 7.1 7.2 Defining Controller Contexts ................................................................................... 27 Defining Data Binding ............................................................................................. 33
CONTEXT PROGRAMMING ........................................................................................... 35 8.1 8.2 8.3 Adding QuizData Node Elements in Context Nodes............................................... 35 Initializing Top Level Value Attributes ..................................................................... 39 Programming Context State Changes .................................................................... 41
Creating an Extended Web Dynpro Application Determining the Content and Interaction of Views
October 2005
Purpose
You will now be familiarized with additional main concepts of Web Dynpro-based application development by creating a short quiz application. You will learn about the following aspects of the Web Dynpro programming model, for example: Creating a Web Dynpro application with multiple views and a navigation structure Working with event handlers (action event handlers, inbound plug event handlers) that you declare yourself Reading contents from the property resource bundles and storing them in a Web Dynpro context (value nodes, value node elements) Dividing data between view controllers and component controllers using context mapping Manipulating UI element attributes at runtime using data binding Integrating the Web Dynpro application in the SAP Enteprise Portal
Process Flow
In the following procedure, you learn how to create this Web Dynpro application. Again, you must first create a new Web Dynpro application in a Web Dynpro component. The development process of a Web Dynpro application has the following categories: Visual Declarative Programmatic
The following table shows which development steps belong to which category.
Visual View Modeling Creating a view set and inserting it into a window Creating views or empty views and inserting them into a window Defining a View Composition Creating inbound plugs and outbound plugs
Creating an Extended Web Dynpro Application Determining the Content and Interaction of Views
October 2005
View Design Designing view layouts in the View Designer Inserting UI element into views and assigning a static value to individual attributes
Declarative Controller Contexts Defining a context value node with attributes for quiz data elements in the component controller Defining the use of the component controller in view controllers Defining context mapping between the view controller context and component controller context
Data Binding Data binding of state-dependent UI element attributes to corresponding context value attributes
User Interaction Defining actions for user interaction in the view controllers Assigning actions to the event handlers of the corresponding UI elements
Programmatic Context initialization Initializing different contexts in the corresponding wdDoInit() controller methods (for example, quiz data elements and layout-specific value attributes) Navigation Triggering navigation events in the corresponding action event handlers State Changes Customizing context data in action event handlers and inbound plug event handlers Changing the lead selection of a context value node with the cardinality 1 ..n (QuizData) to display a corresponding value node element using data binding
We recommend that you structurally subdivide the development process of a Web Dynpro application into the categories visual, declarative, and programmatic. The table shows that the Web Dynpro programming model provides good support of the visual and declarative
October 2005
approach, so the programmatical aspect can be reduced to a minimum. With the exception of the predated implementation of the navigation event handler, this structure reflects the sequential development process of the quiz example application.
Quiz Application
The extended Web Dynpro application is a short quiz on subjects related to Web Dynpro. The first page of this quiz application should look like this:
This single view contains a Group UI element with a welcome text and a button. The user can see the first question in a separate view after choosing Start Quiz. Next to the question, another view with a question mark appears.
October 2005
When the user chooses Show Answer, the question mark disappears and the answer is displayed.
When a question mark is displayed, the button ShowAnswer is visible but not active. The subsequent question is displayed when the user chooses Next Question. Of course, the Next Question! button should not appear when the user reaches the last question.
October 2005
When the user chooses End Quiz in the answer view, the quiz terminates. The two views Question and Answer disappear. In the upper view, a short goodbye text and a new Exit Quiz button are displayed. This button terminates the quiz application and the system navigates to an Internet page. The user can also choose the Start Quiz button to return to the first quiz question.
Create the first parts of the Web Dynpro application [Page 6] in the SAP NetWeaver Developer Studio.
Creating the First Parts of the Application Determining the Content and Interaction of Views
October 2005
Procedure
You create the basic parts of a Web Dynpro application, which can be addressed in the Web browser. Within the Web Dynpro project, these parts include the Web Dynpro application in the project and the root component used by the application (Web Dynpro component).
For detailed information about the creation of these parts, refer to tutorial Creating a Simple Web Dynpro Application [External].
...
1. Open the SAP NetWeaver Developer Studio and create a new Web Dynpro project using the NewProject Wizard. Call it WebDynpro_Quiz, for example. 2. Create a new Web Dynpro application QuizApp called . Enter the package name com.sap.tc.webdynpro.tutorials.quiz, for example, as the Package. 3. In the window Referenced Web Dynpro Components, check the checkbox Create new component. 4. Enter Quiz as the name for the new Web Dynpro component. Accept the suggested package name Component Package.
Within a complex Web Dynpro project, we recommend that you store several Web Dynpro components and Web Dynpro applications of the project in individual packages to separate them logically and structurally.
Before you start developing new views and their user interface designs, you must define the overall visual appearance of the quiz application in the Web browser. This view modeling [Page 6] comprises the specification of the view composition at design time using a view set and the definition of the navigation structure.
Purpose
Before you start creating the different views, first determine what form your application is to take. This includes defining a view composition, which contains all view assemblies that can be displayed in the application. Additionally, you must know the navigation structure that is used to call the individual view assemblies. Only then should you start with the concrete layout of the specific views. Quiz Application [Page 3] has already explained what form the quiz application is to take in the Web browser at runtime and which navigation options the user is to have.
Process Flow
The development of the application involves the following steps:
...
View Modeling and User Interface Layout Determining the Content and Interaction of Views 1. Conception and View Modeling:
October 2005
Before you start specifying the view composition in the SAP NetWeaver Developer Studio, you design the structure of the quiz application in this step. In the next step, the view modeling that takes place here is mapped to a concrete view composition using the Web Dynpro tools in the SAP NetWeaver Developer Studio. 2. View Composition: During development, the view composition is defined by the inclusion of views and empty views in the view areas of a view container and the definition of the navigation structure between these views. For this procedure, the Web Dynpro tools provide the Navigation Modeler [External]. 3. User Interface Layout: In this step, you develop the view layouts and the user interface elements in the views using the visual Web Dynpro tools in the SAP NetWeaver Developer Studio.
Now begin with the design of the quiz application by determining the content and interaction of the views [Page 7].
4.1
...
Welcome: Display a message when starting or ending the application (welcome and goodbye messages). Start or exit the quiz. Question: Display a quiz question from which you can navigate to the next question or display the corresponding answer. QuestionMark: This area is used to display an unanswered question. Answer: Display answer for current quiz question. Possibility of ending the quiz by moving on to the goodbye message in the Welcome view.
In a Web Dynpro application, the views contain the actual user interface elements. The following graphic shows how to reach the individual views and specifies the basic navigation structure.
View Modeling and User Interface Layout Determining the Content and Interaction of Views
October 2005
Welcome
Question
QuestionMark
Answer
October 2005
4.2
At runtime, only one view can be displayed within a view area. The default view, which is initially displayed, is the Welcome view in the view area top and the default view for the two other view areas is the empty view. The assignment of views and empty views to the three view areas top, left, and right specifies all possible view assemblies that is, the possible combinations of views that can be displayed in the window at the same time. In this example, the following view assembly is the default view assembly: View area top: Welcome, View area left: Empty view, View area right: Empty view By specifying the possible views in a view area, you determine in this example that there is a maximum of six different view assemblies at runtime.
October 2005
A navigation link is the association between an outbound plug belonging to view A and an inbound plug of the target view B. You can assign multiple navigation links to one individual outbound plug. An outbound plug defines an event that can trigger a change of one view assembly to another. An inbound plug defines the starting point of a view for any number of navigation links and can be considered an onLoad event or an onDisplay event. You can use the corresponding event handling methods in the view controller to make state changes to the content of a view, where necessary. The following graphic illustrates the desired view composition:
View Welcome
View Question
View Answer
Empty View
View QuestionMark
Empty View
The Welcome view is associated with the Question view and QuestionMark view. The Question view is associated with the Answer view and QuestionMark view, whereas the Answer view is associated with the Welcome view and the two empty views. This view composition enables you to access three of the six possible view assemblies using navigation links. View Area Top Welcome Welcome Welcome View Area Left Empty view Question Question View Area Right Empty view QuestionMark Answer
10
October 2005
However, the following three view assemblies cannot be accessed: View Area Top Welcome Welcome Welcome View Area Left Empty view Empty view Question View Area Right QuestionMark Answer Empty view
The following graphics illustrate the state changes between the view assemblies at runtime. These changes are defined by the navigation links between the outbound plug and the inbound plug.
11
October 2005
View Welcome
View Welcome
1 - Start Application
View Welcome
View Welcome
View Question
View Answer
3 - Display Answer
View Welcome
View Welcome
View Answer
5 - End Quiz
Internet page
A Web Dynpro application terminates when, in a view, the user triggers an outbound plug that is specified as an exit plug. The navigation link of this exit plug does not have a target view. In this example, the exit plug contains the address of an internet page (for example, www.sap.com), which is called after the Web Dynpro application terminates.
12
View Modeling and User Interface Layout Implementing the View Composition
October 2005
The change from the first to the second view assembly is established by triggering the StartQuizOut outbound plug of the Welcome view. This view contains two navigation links to the views Questions and QuestionMark. Before the target views Question and QuestionMark are displayed, the event handling routines of the inbound plugs DisplayQuestion and DisplayQuestionMark are executed.
View Welcome
View Question
This conceptual introduction has prepared you for the actual visual development of the view composition [Page 13] in the SAP NetWeaver Developer Studio.
4.3
Use
By defining the view composition, you specify all view assemblies of a Web Dynpro application that can be accessed at runtime by navigation. The view composition of this example application looks as follows:
13
View Modeling and User Interface Layout Implementing the View Composition
October 2005
Left
Question View
Right
Answer View
Empty View
QuestionMark View
Empty View
Outbound plug
Inbound plug
Navigational link
Prerequisites
You have created an empty Web Dynpro project that you want to use for implementing the view composition. You are in the Web Dynpro Explorer of the SAP NetWeaver Developer Studio.
You can graphically trace the development process in the graphic Navigation Modeler tool. Open the Navigation Modeler by choosing Edit in the context menu of your Web Dynpro window Quiz. You can also use the following procedure, which is graphically supported in the Navigation Modeler.
Procedure
The view composition is implemented by the visual insertion of the following parts:
14
View Modeling and User Interface Layout Implementing the View Composition
October 2005
View Name Welcome Question No entry (= empty view) Answer QuestionMark No entry (= empty view)
Properties - default
1. In the toolbar of the Navigation Modeler, select the icon Embed View. 2. Place the cursor on the view area in which the new view is to be embedded and and left-click. 3. Choose Embed new View and enter a descriptive view name for it. If you want to create an empty view, choose Embed empty View and Finish. 4. In the Web Dynpro Explorer, select the newly added view for example, WebDynpro Web Dynpro Components Quiz Windows Quiz QuizViewSet Left Question. Display the corresponding Properties view. 5. Assign the appropriate entry according to the table above to the view property default. This specifies which view within the view area is displayed in the first view assembly. The newly created views are displayed under the corresponding view area nodes. The views that you have not declared as empty views, also appear under the view node.
15
View Modeling and User Interface Layout Implementing the View Composition
October 2005
ShowQuestionIn
ShowQuestionMarkIn ShowAnswerIn
EndQuizOut
Choose Create Inbound Plug or Create Outbound Plug in the context menu of the view node to which you want to assign the new plug. You can also define inbound plugs and outbound plugs in the Navigation Modeler.
1. Open the node WebDynpro Web Dynpro Components Quiz Component Interface Interface Views in the overview tree of your project. Double-click the interface view QuizInterfaceView. 2. Switch to the tab page Plugs. 3. Choose New next to the table with the outbound plugs. Enter a descriptive name for the new outbound plug, for example, GotoUrl, and choose Exit Plug. 4. Select the new outbound plug GotoUrl and choose New next to the parameter table. Enter the name Url (case-sensitive) for the new parameter and choose string as the type.
Welcome
ShowQuestionMarkOut ShowAnswerOut
QuestionMark Answer Welcome EmptyView (view area left) EmptyView (view area right)
Answer
EndQuizOut
...
16
October 2005
Note that several navigation links can start from a single outbound plug. The individual navigation links do not have names. The navigation is programmatically started when an outbound plug is triggered and the assigned navigation links are executed. 1. Choose Create Navigation Link in the context menu of the outbound plug of the start view. A list is displayed containing all possible target views and the inbound plugs contained in them. The view area in which the target view is contained is displayed in brackets next to the target view. 2. Select the target view and the corresponding inbound plug.
Result
You have implemented the view composition of the quiz application and can now continue with the detailed design of the different view layouts.
4.4
Prerequisites
You are in the SAP NetWeaver Developer Studio and have created empty views.
17
October 2005
Procedure
Use of MIME Objects
The following images are used in the quiz application. Save them locally in the directory src/mimes/Components/com.sap.tc.webdynpro.tutorials.quiz.Quiz. File Name a.jpg Image File Name q.jpg Image
questionmark.jpg
question.jpg
exit.jpg end.jpg
You now create the appropriate UI elements for the empty views. 3. Double-click the view in the Web Dynpro Explorer to start editing in the View Designer and select the Layout tab. You see a hierarchical overview of all UI elements of the view in the Outline area. The top node of this structure is always RootUIElementContainer.
UI elements are always embedded in a superordinate container UI element (for example, the transparent container or a group). 4. You create the UI elements in the Outline area. In this area, choose Insert Child in the context menu of the superordinate UI element into which you want to insert the new UI element. 5. You can edit the properties of the selected UI element in the View Designer using the Properties tab. The following overview lists the UI elements that should be defined for the views of this Web Dynpro application.
Welcome View
Insert the UI elements of the table into the Welcome view. Create the UI elements according to their order in the table. You can delete the existing UI element DefaultTextView provided by default. View Layout in the View Designer of the Web Dynpro Tools
18
October 2005
Property
Value
Group WelcomeViewGroup of type Group in the UI element RootUIElementContainer Properties of Group design Properties of Group layout Properties of Group width Layout colCount Caption sapcolor GridLayout 100% 2
created automatically
Properties of TextView design Properties of TextView text LayoutData colSpan LayoutData hAlign LayoutData paddingBottom Pushbutton
Properties of Button text Properties of Button imageSource LayoutData hAlign LayoutData paddingRight LayoutData width
Pushbutton ExitButton of type Button in the UI element WelcomeViewGroup Properties of Button text Properties of Button imageSource LayoutData width Exit Quiz exit.jpg 50%
Question View
Insert the following UI elements into the Question view (delete DefaultTextView): View Layout in the View Designer of the Web Dynpro Tools
19
October 2005
Property
Value
Group QuestionViewGroup of type Group in the UI element RootUIElementContainer Properties of Group design Properties of Group layout Properties of Group width Layout colCount sapcolor GridLayout 100% 2
Caption QuestionViewGroup_header of type Caption in the UI element QuestionViewGroup Properties of Caption text Image Question View
Properties of Image source Properties of Image tooltip LayoutData hAlign LayoutData paddingTop Text
Properties of TextView design Properties of TextView text Properties of TextView wrapping LayoutData hAlign LayoutData vAlign Text
Properties of TextView design Properties of TextView text LayoutData paddingTop LayoutData paddingBottom
20
October 2005
LayoutData hAlign
center
Pushbutton ShowAnswerButton of the type Button in the UI element TransparentButtonContainer Properties of Button text Properties of Button imageSource Show Answer answer.jpg
Pushbutton NextQuestionButton of the type Button in the UI element TransparentButtonContainer Properties of Button text Properties of Button imageSource LayoutData paddingLeft Next Question question.jpg medium
Answer View
Insert the following UI elements into the Answer view (delete DefaultTextView): View Layout in the View Designer of the Web Dynpro Tools
Property Container
Value
created automatically
Properties layout
Group AnswerViewGroup of type Group in the UI element RootUIElementContainer Properties of Group design Properties of Group layout Properties of Group width Layout colCount LayoutData paddingLeft Caption sapcolor GridLayout 100% 2 medium
21
October 2005
Properties of TextView design Properties of TextView text Properties of TextView wrapping LayoutData hAlign LayoutData vAlign Pushbutton
Properties of Button text Properties of Button imageSource LayoutData colSpan LayoutData hAlign LayoutData paddingBotton LayoutData paddingTop
QuestionMark View
Insert the following UI elements into the QuestionMark view: View Layout in the View Designer of the Web Dynpro Tools
Property Container
Value
Image QuestionMarkImage of type Image in the UI element RootUIElementContainer Properties source Properties tooltip questionmark.jpg question mark
22
October 2005
center middle
Now create the pushbuttons by using the ActionButton template [Page 23].
5
Use
The wizard for the ActionButton template allows you to easily create a button, an action, an event handler, and the code for calling a method and triggering an event.
Procedure
To create a button using the ActionButton template, proceed as follows: 1. In the context menu for the group child of the outline view, choose Apply Template. 2. Choose the option ActionButton. Enter a name for the template or use the default. 3. Choose Next. In the next window, you define the button label, an action, and the events. Enter the label and action. You can also use the default name for the event, as it is automatically created to suit the action. 4. Choose Next to proceed to the wizard window for defining the methods and plugs. By setting the Fire Plug flag, you define the firing of the plug. 5. Close the wizard by choosing Finish and save your changes by choosing Save all Metadata. 6. In the outline window, choose your newly created button and move it to the superordinate container UI element (for example, TransparentButtonContainer or GroupChild).
You can edit the properties of the selected UI element in the View Designer using the Properties tab.
The following is an overview of the buttons and their properties that the views of this Web Dynpro application should contain.
Property
Value
Button StartQuizButton in the UI Element WelcomeViewGroup of the Question View Assigning Action Event Triggering Outbound Plug Properties of Button text Properties of Button imageSource StartPressed StartQuizOut Start Quiz start.jpg
23
October 2005
Button ExitButton in the UI Element WelcomeViewGroup of the Welcome View Assigning Action Event Properties of Button text Properties of Button imageSource LayoutData width ExitPressed Exit Quiz Exit.jpg 50%
Button ShowAnserButton in the UI Element TransparentButtonContainer of the Question View Assigning Action Event Triggering Outbound Plug Properties of Button text Properties of Button imageSource ShowAnswerPressed ShowAnswerOut Show Answer answer.jpg
Button NextQuestionButton in the UI Element TransparentButtonContainer of the Question View Assigning Action Event Triggering Outbound Plug Properties of Button text Properties of Button imageSource LayoutData paddingRight ShowNextQuestionPressed ShowQuestionMarkOut Next Question question.jpg medium
Button EndQuizButton in the UI Element AnswerViewGroup of the Answer View Assigning Action Event Triggering Outbound Plug Properties of Button text Properties of Button imageSource LayoutData colSpan LayoutData hAlign LayoutData paddingBottom LayoutData paddingTop EndQuizPressed EndQuizOut End Quiz end.jpg 2 center large large
24
October 2005
6
Use
You must define the runtime behavior of the application regarding navigation transitions between individual view assemblies in a separate step. The navigation transition occurs at runtime when an outbound plug in an action event handler of the view controller is triggered. There are two steps:
Action event handler calls outbound plug (programmatic) Outbound plug traces navigation links (declarative)
This indirection during the trigger process of the navigation transition ensures that navigation transitions can be subsequently modified in a purely declarative way without having to change the source code. The method call that triggers the outbound plug remains unchanged in the source code.
Procedure
A navigation transition is usually triggered when the user selects a button. You need to do the following:
...
1. Define an action event with a template assistant (already completed in the previous section) 2. Assign the action event to the onAction event of the Button UI element. This step is done in the view Properties (already completed in the previous section) 3. Programmatically trigger the outbound plug (which has at least one navigation link) in an action event handler of the view controller.
25
October 2005
trigger the exit plug, the controller of the interface view must be defined as the required controller in the Welcome view.
...
1. Open the Welcome view in the View Designer and select the Properties tab. Choose Add next to the Required Controllers table and add the QuizInterfaceView controller. 2. Select the Implementation tab and add the following source code for the onActionExitPressed event handler:
/** declared validating event handler */ public void onActionExitPressed(com.sap.tc.webdynpro.progmodel.api.IWDCustomEvent wdEvent ) { //@@begin onActionExitPressed(ServerEvent) wdThis.wdGetQuizInterfaceViewController().wdFirePlugGotoUrl("http://www.sap.com"); //@@end }
When the user triggers the GotoUrl exit plug, the Web Dynpro application terminates. This also ends the user session.
Result
You have defined action events, bound them to buttons, and used the corresponding outbound plug methods for the programmatic triggering of the navigation transitions. You can now observe the runtime behavior of the application at the current development state:
...
1. Choose Rebuild Project for your Web Dynpro project. 2. Choose Deploy new archive and run in the context menu of the Web Dynpro application QuizApp.
The next section is about controller contexts and data binding [Page 26].
7
Use
Within a Web Dynpro component, controller contexts are used as storage locations for data with different structures. Each view controller contains its own context. At a superordinate level, the application development can store additional information in the controller context of a Web Dynpro component or in the context of the custom controller. Controller contexts have a tree structure consisting of context nodes, node elements with different cardinalities, and context attributes of different data types. However, you must differentiate between the abstract level of the context at design time and its concrete definition at runtime. Context mapping between context nodes allows the shared use of context data. To do this, the context data is stored in the component context, for example, and made available for write and read access using the context mapping definition in the view context and a reference semantics. Data binding between the UI element properties and data that is stored in the controller context of a view enables you to easily display this data on the user interface. Note that this
26
October 2005
purely declarative data transfer from the controller layer to the view layer of an application is possible without any programmatic effort.
Activities
Contexts can be used for the following functions:
Context design: You define the required context structures in the controllers of a view and in the component controller. This includes value nodes and value attributes, which represent layout-specific data like the visibility of a UI element and pure business data like question-answer pairs. Context mapping: You must define source and target of the mapping. In this example, the data in both views Question and Answer is used. The controller context of the Web Dynpro component (more precisely, a value node contained in it) serves as the data source. Data binding: You must connect context-dependent properties of individual UI elements with the value attributes of the corresponding controller contexts of a view using data binding.
Now read how you create a controller context to define the active part of the Web Dynpro view that is involved in the data flow.
7.1
When defining a controller context, you must first specify, which data is variable in the quiz application and therefore must be mapped in a corresponding controller context. There are the following three categories:
...
View-owned business data: This includes data that is only relevant within a single view. For example, the short text that is displayed in the Welcome view and customized at the start and before the termination of the application. View-owned layout data: Data that is used for customizing UI element layouts. For example, the value of the visibility property of a button UI element. In this way, the layout of UI elements can be controlled at runtime using data binding of UI element properties to value attributes in the view context. Cross-view business data: If you want to make context data available for several controllers, you must define a corresponding data source by defining a value attribute in the controller context of the component. After defining a value attribute in the controller context of a view, this attribute can be mapped to the attribute in the controller context of the component.
For example, the question-answer text pairs in the quiz example application must be stored in the controller context of the component, so they are available both in the Question view context and the Answer view context. The context mapping between the controller context of a view and the controller context of a Web Dynpro component is only possible if a controller usage has previously defined in the view controller and this controller usage refers to the component controller.
27
October 2005
The properties of a selected value attribute are displayed in the Properties tab. Select string as the default data type.
...
Add the following value attributes as the top level attributes below the root node. How to set the data type of the value attributes to Visibility is described below. View Welcome Value Attribute Name TextMessage ExitButtonVisibility Data type string Visibility
(com.sap.ide.webdynpro.uielementdefinitions)
Question
NextButtonVisibility
Visibility
(com.sap.ide.webdynpro.uielementdefinitions)
If the values that can fill a value attribute should be restricted to a set of constants, the data type Simple Data Type must be assigned to the type property of the value attribute. For further information about the data type Simple Data Type, refer to Data Types [External]. To select Simple Datatype Visibility for value attributes ExitButtonVisibility and NextButtonVisibility, choose (in the Value column for property type) to open the input dialog for selecting a static data type Simple Datatype.
28
October 2005
Select the DDIC Simple Type radio button and then open the node DtDictionary com.sap.ide.webdynpro.uielementdefinitions. It contains all data types that refer to specific UI element properties.
Select the data type Visibility and exit the dialog box by choosing Finish. You have to adjust the data type of the value attribute ExitButtonVisibility so that you can bind the visibility property of a UI element to this value attribute at a later time.
29
Controller Contexts and Data Binding Defining Controller Contexts QuizData: Value node with the cardinality 0..n Question: Answer: Counter: as "1 to
October 2005
Value attribute of the type string for storing a question text Value attribute of the type string for storing an answer text Value attribute of the type string for storing a counter, such 3"
At runtime, the QuizData value node has then a reference to the collection of node elements of the QuizData type each of them with the attributes question, answer, and counter. The following diagram illustrates the relationships:
Context
1..1 Root Node 1..n QuizData Question Answer Counter
Root Node 0 Root Node Element 1..n QuizData 0 Question 1 Answer 1 1/3
Context
Design Time
Value Node Value Attribute Node Element
Runtime
List of Node Elements 0..n Cardinality
...
Select the Context tab of the component controller Quiz. Add a new value node QuizData to the root node Context using the context menu. You do not have to customize the properties of this value node.
Add three new value attributes below the value node QuizData (all of the type string), as described above:
Question Answer
30
October 2005
Counter
Carry out the following steps in both controllers of the Question and the Answer.
...
In the context menu of the node WebDynpro_Quiz Web Dynpro Web Dynpro Components Quiz, select the entry Open Data Modeler:
Place the cursor on the Question view and left-click. Drag the data link to the Component Controller and release the left mouse button. The dialog box for defining the context mapping appears. Drag and drop the value node QuizData (in the context of the Quiz component controller) to the root node of the context of the view Question view. In the following dialog box, select the QuizData value node.
31
October 2005
Since the value attributes Answer in the controller context of the Question view, Counter, and Question in the controller context of the Answer view are not required, you can delete each of these value attributes using the context mapping definition. The context mapping between the view controller and the component controller is graphically represented:
To complete the data link definition, choose Finish. Context mapping requires the declaration of a controller usage (required controllers) listed in the Properties perspectives view of a controller. This declaration is automatically created by the Data Modeler. In the example application, the controllers of the views Quiz and Answer use the component controller Quiz.java..
Result
You have learned how to define the controller context of a view as an information storage and how to use the controller context of a Web Dynpro component to access shared data sources using context mapping. In the following section, individual variable UI element properties are bound to the data sources stored in the controller context of the view.
32
October 2005
TextView TextEdit
?
TextEdit
Frage Zhler
Antwort
Context Mapping
Context Mapping
In the next step, you can easily define data binding, which is a purely declarative approach to establish a connection between the user interface and different controller contexts.
7.2
Data binding stands for the connection of a UI element property with a data source that is stored in the controller context. A context path must be declared for this connection. The previously described procedures - for example, the definition of the individual context structures and the creation of different UI element properties - have made all necessary preparations to allow you to declare several data bindings in an easy way.
Procedure
The procedure for the data binding of a single UI element property is as follows:
33
Controller Contexts and Data Binding Defining Data Binding 1. Select the layout tab of the View Designer 2. Select the UI element properties in the Properties window 3. Select the property in the Properties tab 4. Choose the button at the right edge of the Value column
October 2005
5. Select the value attribute to which the property is to be bound in the subsequent dialog box 6. Confirm the selection and exit the dialog box choosing OK
In the Value column, the entry of the context path for the selected value attribute is displayed - for example, <context value attribute name> for the top level value attribute that is located directly below the root node or <context value node name>.<context value attribute name> for value attributes that are assigned to an independent value node.
Use the description above to define the following data bindings in the three views Welcome, Question, and Answer: UI Elements of the View Welcome Property Context Element
TextMessage ExitButton
Question
TextMessage ExitButtonVisibility
AnswerText
Answer
UI elements whose events are bound to declared actions - for example, the event onAction for the Button UI element - can also be controlled without data binding of the property enabled to a context attribute of the type boolean. These UI elements are activated or deactivated at runtime when the state of the corresponding action object wdThis.wdGet<Action Name>Action() changes in the view controller using the method setEnabled(boolean). Therefore, all UI elements bound to this action are automatically activated or deactivated on the user interface.
34
October 2005
After the declarative description of the data binding, you can continue with the initialization of the defined contexts [Page 35] and the customizing of the context contents in case of state changes.
Context Programming
Purpose
In the previous section, the different context structures have been defined and partly connected to each other using context mapping. In addition, individual UI element properties have been bound to corresponding value attributes, which are defined in the controller contexts of the views. This declarative part of the development process is followed by the initialization of the individual context structures and the customizing of the context contents for the different state changes that occur at runtime.
Process Flow
The section Context Programming is divided into three separate chapters:
...
1. Reading of question-answer texts and their storage in the quiz controller context: Contrary to the value attributes that- by default - are contained in the context at runtime, the individual node elements must be instantiated by the source code and be bound to the corresponding value node. The question-answer texts used in the quiz application are read from resource bundles. 2. Initializing top level value attributes: The previously defined top level value attributes are initialized in this section. 3. Context state changes and actions: After initializing the context structures, they have the initial state. If events occur at the application runtime that should cause state changes within the context structures, these events must be described in the corresponding event handlers. UI elements bound to actions should be activated or deactivated without using data binding. In the quiz application, the event onAction of the button ShowAnswerButton is bound to the action ShowAnswerPressed. The activation or deactivation of the corresponding action objects in the view controller automatically changes the state of the button ShowAnswerButton on the user interface (activated, deactivated).
Start initializing the different context structures within the Quiz component. In the first step, the quiz texts are read from the resource bundles and are stored in the component context. See Adding QuizData Node Elements in Context Nodes [Page 35] hinzufgen.
8.1
In the following diagram, you can see the different context structures of the quiz example application, which were defined in the individual controllers (component controller and view controller).
35
October 2005
Context
1..1 Root Node 1..n QuizData Question Answer Counter
Context
1..1 Root Node NextButtonVisibility 1..n QuizData Question Counter
Context
1..1 Root Node 1..n QuizData Answer
Context
1..1 Root Node TextMessage ExitButtonVisibility
Design Time
Value Node Value Attribute Context Mapping
Note that the diagram illustrates a design time abstraction of the context structures that are actually available at runtime. The main difference between the runtime perspective and design time perspective of the context is that the value nodes represent collections (for example, lists) of concrete node elements (with predefined possible cardinalities) at runtime. At design time, the type of these node elements is defined by the context structure, which is contained in the value node (value attributes or additional child nodes). You must now instantiate these node elements of the type QuizData in the generic event handler wdDoInit() of the quiz component controller and store them in the QuizData value node. The top level value attributes, which are directly below the root node, are automatically created during the Web Dynpro runtime and can therefore be directly initiated by the application development.
Procedure
Before you implement the wdDoInit() method in the component controller, you must store the question-answer texts, which are displayed in the example application, in two resource bundles.
36
October 2005
following dialog box - for example, Questions.properties. To complete this step, choose Finish.
1. Import the question-answer pairs from the resource bundles 2. Create node elements of the type QuizData for individual question-answer pairs 3. Bind node elements of the type QuizData to the QuizData value node Implementation in the Quiz Component Controller
37
October 2005
//===== STEP 1: Load resource bundles for questions and answers ========== // Get the questions-answer resource handlers for the current session locale // using the factory class WDResourceHandler. IWDResourceHandler resourceHandlerForQuestions = WDResourceHandler.createResourceHandlerForCurrentSession(); IWDResourceHandler resourceHandlerForAnswers = WDResourceHandler.createResourceHandlerForCurrentSession(); // Load the resource bundle "Questions.properties" located // in the package "com.sap.tc.webdynpro.tutorials.quiz.resources.Questions" // for locale set in the resource handler. resourceHandlerForQuestions.loadResourceBundle( "com.sap.tc.webdynpro.tutorials.quiz.resources.Questions", this.getClass().getClassLoader()); resourceHandlerForAnswers.loadResourceBundle( "com.sap.tc.webdynpro.tutorials.quiz.resources.Answers", this.getClass().getClassLoader()); // get the number of question-answer-pairs contained in the resource bundle int size = Integer .valueOf(resourceHandlerForQuestions.getString("SIZE")).intValue(); //===== STEP 2: Create context node elements of the type QuizData ========= // begin populating context node QuizData Collection questions = new ArrayList(); for (int i = 0; i < size; i++) { // instantiate the new context node element of type QuizData IPublicQuiz.IQuizDataElement quizDataElement = wdContext.createQuizDataElement(); // set contained context value attributes quizDataElement.setQuestion(resourceHandlerForQuestions.getString("Q"+i)); quizDataElement.setAnswer(resourceHandlerForAnswers.getString("A"+i)); quizDataElement.setCounter(String.valueOf(i+1)+"/"+String.valueOf(size)); // add new context node element of the type QuizeData to ArrayList questions.add(quizDataElement); } //===== STEP 3: Bind collection of Q&A pairs to context value node QuizData ==== // Bind collection of context node elements to context value node QuizData wdContext.nodeQuizData().bind(questions); //@@end }
38
October 2005
Result
After executing the source text, which is implemented in the wdDoInit() method, the context of the component controller has the following structure at runtime note that the diagram shows only three out of the seven node elements of the type QuizData.
Value Nodes Value Attribute Node Element Currently selected Node Element (Lead Selection) List of Node Elements 0..n Cardinality
Context
Runtime
The four top level value attributes within the controller context are initialized in the next step [Page 39].
8.2
There are three top level value attributes within the quiz component: NextButtonVisibility, TextMessage, and ExitButtonVisibility. The value attributes TextMessage and ExitButtonVisibility can be initialized in the wdDoInit() method of the controller of the view Welcome. This method is called by the Web Dynpro runtime during the creation of this view. Implement the following source code in the controller of the Welcome views:
39
Context Programming Initializing Top Level Value Attributes The local member variable welcomeMessage is defined in the next section.
October 2005
The only instance of the root node element can be accessed at runtime using the wdContext.currentContextElement() method. This instance contains the defined structure of value attributes and may contain the defined structure of value nodes. You receive the read and write accesses for the value attributes using the automatically generated mutator methods for example, wdContext.currentContextElement().setTextMessage(welcomeMes sage).
The value attribute NextButtonVisibility is to be initialized whenever the user chooses the Start Quiz button in the Welcome view to display the first quiz question in the Question view. The corresponding event handler in the Question view controller is the onPlugShowQuestionIn() method, which is called when the user navigates to the Question view.
The wdDoInit() method in the Question view controller is only called when the Question view is added to current view group that is, when the view is visible. The lifetime of the view controller is as long as its view is visible during subsequent view group changes. If a view is no longer in the current view group, its view controller in the Web Dynpro runtime is also deleted until it is requested again within a succeeding view group (another call of the wdDoInit() method).
Implement the following source code in the controller of the view Question:
In the code line wdThis.wdGetShowAnswerPressedAction().setEnabled(true);, the action ShowAnswerPressed is activated. All UI elements with an event bound to this action are automatically activated. In the quiz application, this is the case for the button ShowAnswerButton (Creating Navigation Changes [Page 25]). Since the first question is to be displayed after calling the Question view, the lead selection of the value node QuizData in the quiz component controller must be set to the first node element. As a consequence, the attribute values of the first node element of the type QuizData are automatically displayed on the user interface using data binding.
40
October 2005
In the last section of this example application, different context state changes are specified using implementation [Page 41], for example, the setting of new values in value attributes or the changing of the lead selection in the value node QuizData to switch to another question.
8.3
Use
The states, which are stored in the different contexts, are changed according to the events triggered by the user in the event handlers of the view controllers Welcome.java and Question.java. The UI element properties bound to the view context (such as text of the TextView UI element or visible for the Button UI element) must be adjusted to each new situation on the user interface and the navigation in the list of QuizData node elements is necessary to display the desired question-answer pair on the user interface.
Procedure
Add the code lines contained in the following tables to the appropriate user coding areas of the individual view controllers.
View-Controller Welcome.java
You must initialize the view context in the Welcome view controller again by selecting the Start Quiz button (display the welcome message, hide the exit button for exiting the application). When terminating the quiz, the exit button and a goodbye message must be displayed after selecting the End Quiz button in the Answer view. The text messages are stored in two string variables welcomeMessage and endMessage, which are only visible in the view controller. Implementation in the View Controller Welcome.java
41
October 2005
... /** declared validating event handler */ public void onActionStartPressed(com.sap.tc.webdynpro.progmodel.api.IWDCustomEvent wdEvent ) { //@@begin onActionStartPressed(ServerEvent) wdDoInit(); wdThis.wdFirePlugStartQuizOut(); //@@end } ... /** declared validating event handler */ public void onPlugEndQuizIn(com.sap.tc.webdynpro.progmodel.api.IWDCustomEvent wdEvent ) { //@@begin onPlugEndQuizIn(ServerEvent) wdContext.currentContextElement().setTextMessage(endMessage); wdContext.currentContextElement().setExitButtonVisibility(WDVisibility.VISIBLE); //@@end } ... /* * The following coding section can be used for any Java coding that has * not to be visible to other controllers/views or that contains constructs * currently not supported directly by Web Dynpro (such as inner classes or * member variables etc.). </p> * * Note: The content of this section is in no way managed/controlled * neither by the Web Dynpro Designtime nor the Web Dynpro Runtime. */ //@@begin others private String welcomeMessage = "Welcome to this short quiz about navigation and view sets in Web Dynpro!"; private String endMessage = "Goodbye, we hope you enjoyed this short Web Dynpro quiz application!"; //@@end
wdContext.nodeQuizData().moveNext();
If the lead selection points to the last node element, the Next Question button must be hidden by assigning the value WDVisibility.BLANK to the NextButtonVisibility value attribute. We recommend you deactivate the Show Answer button by deactivating the corresponding action ShowAnswerPressed. Implementation in the View Controller Question.java
42
Portal Integration of the Web Dynpro Application Programming Context State Changes
October 2005
/** declared validating event handler */ public void onActionShowNextQuestionPressed( com.sap.tc.webdynpro.progmodel.api.IWDCustomEvent wdEvent) { //@@begin onActionShowNextQuestionPressed(ServerEvent) wdContext.nodeQuizData().moveNext(); wdThis.wdGetShowAnswerPressedAction().setEnabled(true); //--- hide Next button, if last question is reached if (wdContext.nodeQuizData().getLeadSelection() == wdContext.nodeQuizData().size()-1) { wdContext.currentContextElement().setNextButtonVisibility(WDVisibility.BLANK); } wdThis.wdFirePlugShowQuestionMarkOut(); //@@end } ... /** declared validating event handler */ public void onActionShowAnswerPressed(com.sap.tc.webdynpro.progmodel.api. IWDCustomEvent wdEvent) { //@@begin onActionShowAnswerPressed(ServerEvent) //disable ShowAnswer button wdThis.wdGetShowAnswerPressedAction().setEnabled(false); //--- trigger navigation by firing outbound plug wdThis.wdFirePlugShowAnswerOut(); //@@end }
You have now successfully developed an extended Web Dynpro application and already become familiar with several components of the Web Dynpro programming model. You integrate the Web Dynpro application in the SAP Enterprise Portal in the next step [Page 43].
SAP Enterprise Portal provides a number of functions that you can use to develop your Web Dynpro applications. Among other things, this includes handling portal events or navigating between Web Dynpro applications in an SAP Enterprise Portal, or even between a Web Dynpro application and a non-Web Dynpro application. When you integrate the Web Dynpro application, you have to define a system in the portal first of all and subsequently create an iView as a logical container for the Web Dynpro application.
Procedure
Creating a Folder and Determining a System
The following information describes how you determine a system on which the Web Dynpro application should run: 4. In the portal, choose System Administration System Configuration System Landscape.
43
Portal Integration of the Web Dynpro Application Programming Context State Changes
October 2005
5. In the Portal Catalog, navigate to the folder in which you want to create the system. If an appropriate folder does not already exist, create a new one. 6. In the context menu for this folder, choose New System. The wizard is started. 7. On the Template selection screen, choose R/3 System with Load Balancing and then choose Next. 8. Assign a system name, system ID and prefix to your system: a. System name, such as WD <mySystemName> b. System ID, such as WD_<mySystemID> c. System ID prefix, such as com.sap Also select the master language for your application. 9. Choose Next. The next window displays an overview of all entries that you have made. This enables you to change your entries again before you finish the process. If you want to make changes, choose Back to return to the relevant wizard input form. 10. Choose Finish.
1. From the Display dropdown list box, choose System Aliases. 2. Determine a name for the system alias, such as MySystem. Add the alias by choosing Add. 3. Choose Save to save your changes.
1. Open the system in the System Landscape Editor. 2. In the Property Category dropdown list box, choose Web Application Server (WAS). 3. Maintain the following properties: a. WAS Host Name = <Host name>.<domain name>:<port number> (this corresponds to the Web Dynpro server location, such as iwdf9406.wdf.sap.corp:50000) b. WAS Protocol = http Note: Check whether the SAP Web Application Servers J2EE Engine is configured to use HTTPS. 4. Save the changes.
1. In the portal, navigate to Content Administration Portal Content. The Portal Content Studio opens. 2. In the Portal Catalog, go to the folder where you want to create your new Web Dynpro iView.
44
Portal Integration of the Web Dynpro Application Programming Context State Changes
October 2005
3. In the context menu for this folder, choose New iView. The iView wizard appears on the right-hand side. Choose the standard iView template SAP Web Dynpro iView. Choose Next. 4. On the next screen, define the iView Name and iView ID. The name of the iView is used as the title of the iView. The key consists of the technical name and iView ID prefix. You can use it to determine a separate namespace. Choose Next. 5. To specify the application variant, choose ABAP or JAVA. 6. On the next screen you have to define the Web Dynpro-specific properties: a. System Select the system alias from the dropdown list box that you want to use for your Web Dynpro application. For each J2EE Engine you have to create a system alias first of all (as already described) before you can have a Web Dynpro application run on it. b. WebDynproNamespace You have to define the development module that your Web Dynpro application contains. If you are working locally without a Design Time Repository (DTR), you have to define your Web Dynpro project as described above. Ensure that both the development module as well as the Web Dynpro project contain the provider name. The following values are possible, for example: sap.com/tc~wd~tools for a development module or local/MyWebDynproProject for a Web Dynpro project. In the Create a simple Web Dynpro application project, it is local/WebDynpro_Basics, for example.
The specific name of the development module is the same as the one in the SAP Management Console under the LIST_APP command. You will also find the name in the URL address of the Web Dynpro application after URL. c. Application Name The application name is the same as the one for the Web Dynpro application, such as WelcomeApplication. d. ApplicationParameters If your Web Dynpro application contains call parameters, you can determine specific values for the iView. Note that there are two parameters:
parameter1 and parameter2 In this case, you can determine the following application parameter string: parameter1=value1¶meter2=value2.
7. After defining the Web Dynpro-specific properties, another wizard dialog box opens where you can define other iView properties. Choose Finish. 8. To display a preview of your iView, choose Preview from the context menu.
Result
You have created a separate system and a Web Dynpro iView and you can now integrate this iView in pages, worksets and roles.
45