WD UI Navigation

SAP NetWeaver Developer's GuideSAP NetWeaver Developer's GuideSAP NetWeaver Developer's GuideSAP NetWeaver Developer's Guide

Release: SAP NetWeaver 2004sRelease: SAP NetWeaver 2004sRelease: SAP NetWeaver 2004sRelease: SAP NetWeaver 2004s

View View View View –––– Programming Programming Programming Programming

UI and NaUI and NaUI and NaUI and Navigatiovigatiovigatiovigationnnn

Document Version 1.00 – October 2005

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

© 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. 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. 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. Disclaimer 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. Any Java™ Source Code delivered with this product is only to be used by SAP’s Support Services and may not be modified or altered in any way. 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.

T yp o g r a p h i c C o n v e n t i o n s

Type Style Represents

Example Text 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.

EXAMPLE TEXT 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.

Example text 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.

Example text Exact user entry. These are words or characters that you enter in the system exactly as they appear in the documentation.

<Example text> Variable user entry. Angle brackets indicate that you replace these words and characters with appropriate entries to make entries in the system.

EXAMPLE TEXT Keys on the keyboard, for example, F2 or ENTER.

I c o n s

Icon Meaning

Caution

Example

Note

Recommendation

Syntax

Contents

1 VIEW – PROGRAMMING UI AND NAVIGATION................ ............................................. 1

2 VIEW STRUCTURE AND DESIGN ................................................................................... 2 2.1 Creating a View......................................................................................................... 2 2.2 Creating a View Set .................................................................................................. 4 2.3 Embedding a View in a View Set .............................................................................. 5 2.4 Copying a View ......................................................................................................... 6 2.5 Renaming a View ...................................................................................................... 6 2.6 ViewContainerUIElement API ................................................................................... 7 2.7 View Templates......................................................................................................... 8

2.7.1 Using the ActionButton Template................................................................... 9 2.7.2 Using the Form Template............................................................................... 9 2.7.3 Using the Table Template ............................................................................ 10

3 NAVIGATION, PLUGS AND NAVIGATION LINKS................. ....................................... 11 3.1 Creating a Plug........................................................................................................ 11 3.2 Creating a Link ........................................................................................................ 12 3.3 Implementing Methods for Outbound Plug Calls .................................................... 13 3.4 Suspend and Resume Plug .................................................................................... 14

4 UI ELEMENTS, DATA BINDING AND EVENT HANDLING........... ................................ 15 4.1 UI Elements: Methods, Properties and Events ....................................................... 16

4.1.1 Common UI Element Properties................................................................... 18 4.1.2 Methods of the UI Element APIs .................................................................. 19 4.1.3 Layout........................................................................................................... 21 4.1.4 Containers .................................................................................................... 33 4.1.5 BIApplicationFrame API: Integrating BEx Web Applications ....................... 40 4.1.6 Breadcrumb Navigation................................................................................ 43 4.1.7 Web Dynpro BusinessGraphics API - IWDBusinessGraphics ..................... 47 4.1.8 Button - ButtonRow ...................................................................................... 80 4.1.9 Caption API .................................................................................................. 82 4.1.10 CheckBox API .............................................................................................. 83 4.1.11 DateNavigator............................................................................................... 87 4.1.12 DropDownByIndex API................................................................................. 93 4.1.13 DropDownByKey API ................................................................................... 96 4.1.14 FileUpload and FileDownload: Data Transfer .............................................. 99 4.1.15 Gantt API .................................................................................................... 108 4.1.16 HorizontalGutter API................................................................................... 110 4.1.17 Web Dynpro GeoMap API - IWDGeoMap.................................................. 111 4.1.18 Web Dynpro IFrame API – IWDIFrame...................................................... 127 4.1.19 Image API................................................................................................... 130 4.1.20 InputField API ............................................................................................. 132 4.1.21 ItemListBox API .......................................................................................... 133 4.1.22 Label API .................................................................................................... 136 4.1.23 Legend API................................................................................................. 137

4.1.24 LinkToAction API ........................................................................................ 143 4.1.25 LinkToURL API........................................................................................... 144 4.1.26 MenuBar and Popup Menu ........................................................................ 145 4.1.27 Network API................................................................................................ 153 4.1.28 Web Dynpro OfficeControl API – IWDOfficeControl .................................. 156 4.1.29 PhaseIndicator............................................................................................ 168 4.1.30 ProgressIndicator API ................................................................................ 174 4.1.31 Web Dynpro RadioButton API - IWDRadioButton...................................... 175 4.1.32 RoadMap API ............................................................................................. 187 4.1.33 Table........................................................................................................... 192 4.1.34 Tabstrip....................................................................................................... 224 4.1.35 Web Dynpro TextEdit API - IWDTextEdit ................................................... 228 4.1.36 TextView API .............................................................................................. 232 4.1.37 Web Dynpro TimedTrigger API - IWDTimedTrigger .................................. 235 4.1.38 ToggleButton API ....................................................................................... 237 4.1.39 ToggleLink API ........................................................................................... 238 4.1.40 Toolbar ....................................................................................................... 239 4.1.41 Tree API ..................................................................................................... 255 4.1.42 TriStateCheckBox API................................................................................ 279 4.1.43 ValueComparison API ................................................................................ 280

4.2 Data Binding of User Interface Element Properties .............................................. 283 4.2.1 Bindable Data Types .................................................................................. 285 4.2.2 Typing Context Attributes for Data Binding ................................................ 285 4.2.3 Assignment of Dictionary Types and Java Types ...................................... 288 4.2.4 Dynamic Metadata...................................................................................... 291 4.2.5 Code Examples of Data Binding ................................................................ 292 4.2.6 Code Example of Key Binding.................................................................... 296 4.2.7 Data Binding of a Dropdown List Box and Radio Button Group ................ 299 4.2.8 Code Example of the Use of a Recursive Node......................................... 300

4.3 Dynamic UI Generation......................................................................................... 303 4.4 Event Handling of UI Elements ............................................................................. 304

4.4.1 UI Element Event Model............................................................................. 306 4.4.2 Generic Validation Service ......................................................................... 307 4.4.3 Web Dynpro Action at Runtime – Interface IWDAction.............................. 309 4.4.4 Creating an Action at Design Time............................................................. 310 4.4.5 Action Types............................................................................................... 312 4.4.6 Non-Validating and Validating Actions ....................................................... 314 4.4.7 Event Parameter and Parameter Mapping................................................. 316 4.4.8 Web Dynpro ParameterMapping API - IWDParameterMapping................ 319

5 PROGRAMMING USER MESSAGES.......................... ................................................. 320 5.1 Error Handling ....................................................................................................... 320 5.2 Creating a User Message ..................................................................................... 325 5.3 Messages.............................................................................................................. 326 5.4 Processing a Message.......................................................................................... 328 5.5 Example for Using Messages ............................................................................... 330

6 INTERNATIONALIZATION OF WEB DYNPRO PROJECTS.............. ......................... 334

6.1 Use 334 6.2 Internationalization Concepts for a Web Dynpro Project ...................................... 336 6.3 Translation of the Texts......................................................................................... 337 6.4 Creating Language-Dependent Resources at Design Time ................................. 338 6.5 Overview ............................................................................................................... 338 6.6 Messages.............................................................................................................. 341 6.7 Processing a Message.......................................................................................... 343 6.8 Search Process for Determining the Required Resource Bundle......................... 345 6.9 Internationalization Service ................................................................................... 347

7 EVELOPMENT OF INTERACTIVE ADOBE FORMS FOR THE WEB DYNPRO UI .... 348 7.1 Adobe Library ........................................................................................................ 351

7.1.1 Web Dynpro InteractiveForm API - IWDInteractiveForm ........................... 351 7.1.2 Web Dynpro Form – UI Element CheckFields ........................................... 356 7.1.3 Web Dynpro Form – UI Element EnumeratedDropDownList..................... 356 7.1.4 Web Dynpro Form – UI Element EnumeratedDropDownListNoSelect ...... 356 7.1.5 Web Dynpro Form – UI Element HideReaderToolbar................................ 357 7.1.6 Web Dynpro Form – UI Element SubmitToSAP ........................................ 357 7.1.7 Web Dynpro Form – UI Element ValueHelpDropDownList........................ 358

7.2 Example of the Use of an Interactive PDF Form .................................................. 358 7.3 Configuring the Destination URL for the Adobe Document Services ................... 365

View – Programming UI and Navigation October 2005

Creating a View

View – Programming UI and Navigation 1

1 View – Programming UI and Navigation

View Structure and Design and Navigation Between Vi ews

These two sections provide information on how to design and arrange views, and how to navigate between views.

Graphical tools are available for designing and implementing the user interface. The Navigation Modeler [External] provides support when you create the logical interface elements (known as views) for the Web Dynpro application; it also supports the arrangement of these views on the screen. With the view definition you create an element that firstly acts as a container for your Web interface definitions and secondly contains the active part, the context. You then assign the elements to the interface and supply them with data;

See:

• View Structure and Design [Page 2]

• Navigation, Plugs and Navigation Links [Page 11]

UI Elements, Data Binding and Event Handling

These sections provide information on the individual UI elements, their data binding to the context, and the handling of events using action binding and parameter mapping.

The graphical View Designer [External] tool provides support when you create the actual user interface with elements such as text fields, input fields, buttons, and so on. The tool offers a wide range of preconfigured user interface elements, which you can define for the interface using Drag&Drop. As well as the traditional elements, numerous complex elements, such as a tables, and business graphics with a number of different display options are also available.

See:

• UI Elements [Page 16]

• Data Binding of User Interface Element Properties [Page 283]

• Event Handling [Page 304]

Other Services and Functions

Web Dynpro comes with the Message Editor, a tool for the implementation of user and error messages.

See:

• Programming User Messages [Page 320].

You also have the possibility to internationalize your Web Dynpro applications.

See:

• Internationalization of Web Dynpro Projects [Page 334].

The integrated Adobe Designer tool supports the development of interactive Adobe forms.

See:

• Development of Interactive Adobe Forms for the Web Dynpro UI [Page 348]

View Structure and Design October 2005

Creating a View


2 View Structure and Design

Window – View – View Set

The top node of the interface definition hierarchy is the window which is displayed when a Web Dynpro application is executed. This window is made up of at least one view. A view in turn consists of UI elements.

You can define the display sequence of multiple views using plugs and navigation links.

It is also possible to display multiple views at the same time. To do this, you have to embed the views in a view set. A view set provides various containers in which you can arrange views or other view sets. You can also use the ViewContainerUIElement to embed views.

The graphical tool that helps you with the creation and design of a UI is called the Navigation Modeler [External]. You can also use this tool to define the navigation between the views.

Empty View

The empty view is a special type of view. It is always generated automatically in a window or a view set area, provided that no view has been embedded manually. It may also be preferable to embed an empty view in a non-empty window as well. Just like a normal view, the empty view occupies a certain area of a window at runtime and can be used to hide a different view, for example, using specific controls.

When you create an empty view, an inbound plug with the default name ShowEmptyView is created.

2.1 Creating a View You create a view with graphical support in the Navigation Modeler [External] or Data Modeler [External]. A screen display can show more than one view; to implement this, use a view set into which you embed the desired views. View sets are also created using the graphical Navigation Modeler tool.

The following graphic shows an example of how a Web Dynpro application can be structured by embedding views in a view set. In this example, the interface of the application is separated into the views Customer Search, Customer Details, Product Details, and so on. The views are in turn integrated in the two view sets User Identification and Details.


Creating a View


View Set Details

ViewContacts

ViewCust. History

View Set User Identification

EmptyView

ViewCust. List

ViewProducts

ViewSearch

ViewDetails

ViewP. Details

View Set Area

Screen Display Screen Display

While views are created using the Navigation Modeler, the layout of the individual views is designed and implemented in another graphical tool, the View Designer [External].

Prerequisites Before you can define a view, you must create a Web Dynpro project and a Web Dynpro component with a window.

Procedure Since you can also use views in a Web Dynpro application without using view sets, the following simply describes the procedure for creating a new view without the use of a view set:

1. Open the Navigation Modeler, by choosing the context menu entry Open Navigation Modeler for the window name in the Web Dynpro Explorer.

2. In the graphical Navigation Modeler tool, choose Embed View in the selection area.

3. In the wizard, choose Embed new view followed by Next.

4. Enter a name for the view. You can also specify a different package here, or you can create a new package by entering the new package name in the input field.

5. Close the wizard by choosing Finish and then choose Save all Metadata to save your changes.

Result The new view is displayed graphically in the Navigation Modeler. In the Web Dynpro Explorer, the view is displayed below the subnode Views of the node

<MyWebDynproComponent>. The file system contains the directory


Creating a View Set


/<myWDProject>/src/packages/<myPackage>/ . This directory in turn contains the following files, which were created automatically by the Web Dynpro Generator at the same time as the view definition.

• View XML file <myView>.wdview

� View context file for the data flow between the view and the view context. The file contains the following subobjects:

� View controller reference

� Web Dynpro component reference

� Transparent container for user interface elements

� User interface element references, including layout data

• View controller XML file <myView>.wdcontroller

� View context file for the data flow between the view context and the other Web Dynpro entities. The file has the following parameters:

� Controller event handler inbound plug

� Main node Context (value node with cardinality 1:1)

� Controller reference to the Web Dynpro component

• View properties file <myView>.wdview.xlf

� XML file that is relevant for translation.

Under no circumstances should you change any of the files listed above. However, you can display the relevant source code in the Navigator view. To open the XML Editor, choose the context menu entry Open With → Text Editor for the relevant file.

Additional Information To define a view as part of a view set, proceed as described in Embedding a View in a View Set [Page 5]. For information about reusing a view, refer to Copying a View [Page 6].

2.2 Creating a View Set A number of view set types are available that you can use for the layout of your Web Dynpro application.

Prerequisites Before you can define a view set, you must create a Web Dynpro project and a Web Dynpro component with a corresponding window.

Procedure 6. In the Web Dynpro Explorer, start the graphical Navigation Modeler [External] tool by

choosing the context menu entry Open Navigation Modeler for the window name of the relevant project.

7. In the function selection area, choose Create Viewset.

8. Click once on the editor area. The view set wizard opens. Enter a name for the view set. You can select from a number of view set layouts in the dropdown list.


Embedding a View in a View Set


9. Save the view set by choosing Finish.

Result The view set is displayed graphically in the Navigation Modeler. In the Web Dynpro Explorer, the view set is displayed as an element of the window. The individual view set areas, the cells, are displayed as subnodes of the view set. If you insert views into a view set, these views are displayed as elements of the cells.

2.3 Embedding a View in a View Set You can either embed an existing view in a view set, or create the view when you embed it.

Prerequisites Before you embed a view, you must define a view set. The following steps are carried out using the Navigation Modeler [External].

Procedure: Embedding a New View If you want to create the view when you embed it, proceed as follows: ...

1. In the tool selection list, select Embed View.

2. In the layout area of the Navigation Modeler, click on the cell of the view set in which the view is to be embedded.

3. In the wizard, choose Embed New View and, in the next window, enter a name for the view.

4. Use the package that you entered for the component definition or select another package by choosing Browse.

5. Choose Finish.

Procedure: Embedding an Existing View To embed an existing view in a view set, proceed as follows: ...

1. In the tool selection list, select Embed View.

2. In the Navigation Modeler, click on the cell of the view set.

3. Choose Embed Existing View in the wizard.

4. In the next wizard window, select the desired view and close with Finish.

Result The view is displayed graphically in the Navigation Modeler. In the Web Dynpro Explorer view, the embedded view is an element of the view set cell. At file system level, the system creates a view usage for the embedded view in the XML file <myWindow>.wdwindow as an element of the view set definition. You can display the file in the Navigator view. Under no circumstances should you make any changes to this file.


Copying a View


You can embed more than one view in a view set area. With the navigation definition, you specify which view is to be displayed at runtime. Furthermore, the default flag specifies which views or view sets are displayed as initial.

2.4 Copying a View You can copy a view within the same Web Dynpro component or to another Web Dynpro component.

Procedure ...

1. In the Web Dynpro Explorer, place the cursor on the view to be copied.

2. Choose the context menu entry Copy on the source view.

3. Select the Views node in the target Web Dynpro component and choose Paste from the context menu.

4. In the dialog box that appears, you can change the name of the view or the package, or accept the values of the source view.

Result The view is copied and displayed in the Web Dynpro Explorer. The following application entities are also copied along with the view:

• View layout, including the user interface elements

• View context, including the context definition

• Component Usage

• Plugs

• Actions

• Methods, including the subscribed events

The class and method names are automatically adjusted in the source code.

For the view copy, you must newly define the following:

• Component interface controller

• Event source of the methods

• Mapping definition

2.5 Renaming a View

Use You can rename a created view at a later stage. A wizard is available for this refactoring function.


ViewContainerUIElement API


Prerequisites You have already created a view using the graphical Navigation Modeler [External] tool.

Procedure </p>

1. In the Web Dynpro Explorer, place the cursor on the view you wish to rename.

2. In the context menu, choose Rename.

3. In the first wizard window, enter the new name for the view.

4. If any Web Dynpro entities other than the Web Dynpro component and the view have references to the renamed view, choose Next. If there are no such elements, choose Save + Finish in the first wizard window.

5. In the second window, you can uncheck the Web Dynpro elements that are not relevant for the renaming. The grayed out objects need to be updated in the case of the name change; these objects cannot be omitted from the renaming.

6. Choose Save + Finish.

Result The view is displayed with its new name in the file system and the Web Dynpro Explorer.

2.6 ViewContainerUIElement API

Definition The ViewContainerUIElement UI element is an area within a view that contains another view.

Like all UI elements, the ViewContainerUIElement has the visible property to control its visibility within the view layout. The visible property can have one of the following three values: none , blank , and visible.

The properties enabled and tooltip are ignored and have no visual effects in the browser.

Description of UI Element Properties • visible

Specifies the visibility of the UI element in the view layout. The default value of this property is visible . The visible property can be filled with the following values and is represented by the enumeration type Visibilty.

blank The UI element is not visible on the screen, but takes up space.

none The UI element is not visible on the screen and does not take up space.

visible The UI element is displayed on the screen.

Overview of Inherited and Additional Properties Name Interface Type Initial Value Bindable Value


View Templates


Required

enabled IWDUIElement boolean true bindable No

tooltip IWDUIElement String bindable No

visible IWDUIElement Visibility visible bindable No

Performance Considerations When passing view layout information to the Web Browser, the Web Dynpro runtime environment checks whether or not the current view assembly contains non-visible or empty UI elements of the type ViewContainerUIElement with the visibility property value set to none or blank. If these values are set, the embedded views and their UI elements are not sent to the Web Browser. This reduces the round trip times and improves the performance of the application.

The optimization of the round trip times is only supported when the visibility property is bound to a context attribute of the type Visibility and the readOnly property of the context attribute is set to the value true .

Round trip times can be optimized for the visibility property of the UI element ViewContainerUIElement but not for other UI containers like the Group UI element or the Tray UI element. The UI elements they contain are passed to the Web Browser regardless of the visibility property.

Separate views should be used in applications that use the visibility property to display and hide UI elements using data binding. These views can be embedded into the view composition using the UI element ViewContainerUIElement . Especially when only one or two of many ViewContainerUIElement UI elements are to be displayed the optimazation reduces the round trip times considerately.

2.7 View Templates The Web Dynpro tools provide three templates for making data available to forms and tables in a Web Dynpro application and for defining the properties of buttons that you defined for the user interface. These templates can be called when working in the Data Modeler.

You can use the form template to define attributes for a form-like user interface layout that is to be part of the view. The table template supports you when defining data binding for tables created in the view. The ActionButton template allows you to specify the properties of a button.

There is also a template for Portal eventing . It allows you to insert source code for navigating a Web Dynpro application in a SAP Enterprise Portal.

The following describes how to start the main wizard for these templates. Detailed information about the wizards is available in the sections Using the Form Template [Page 9], Using the Table Template [Page 10], Using the ActionButton Template [Page 9], and Using the Template for Portal Eventing [External].

Prerequisites You have created a project, a Web Dynpro component, and a view.


View Templates


Procedure To open the view templates wizard, proceed as follows: Ö

1. Open the Data Modeler by choosing the context menu entry Open Data Modeler for the component name in the Web Dynpro Explorer.

2. In the Data Modeler, place the cursor on the view for which you want to start a template and choose Apply Template in the context menu.

3. The main wizard is started. Choose the desired template type.

2.7.1 Using the ActionButton Template 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.

Prerequisites You have completed all steps described under View Templates [Page 8].

Procedure To create a button using the ActionButton template, proceed as follows: ...

1. Choose the option ActionButton. Enter a name for the template or use the default.

2. Choose Next. In the next window, you define the button label, an action, and the events. You can either use the default name or enter a new one. The names for the label, action, and event, can be assigned independently.

3. 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.

4. Close the wizard by choosing Finish and save your changes by choosing Save all Metadata.

2.7.2 Using the Form Template You can use the form template wizard to create a form layout for a view, based on the view context. For designing and implementing this form layout, you can use controller context data or access the data of a declared Web Dynpro model directly.


Before you can begin defining the data for the form, you must have transferred the application data from the back end to the application controller by defining data binding. You must also have defined the data flow between the controller and an existing view. Proceed as described under Creating a Data Link [External].

Procedure 5. Choose the option Form. Enter a name for the template or use the default.

6. Choose Next. In the next window, you select those context attributes from the mapped data that you want to pass to the form for the data binding.


View Templates


7. Choose Next if you want to make changes to the bound data. If no changes are necessary, you can close the wizard by choosing Finish.

8. In the next window, you can specify the order of the data. For example, to move the first line further down, select the table entry and move the element down using the arrow button on the right.


Result You can display the created layout in the layout tool View Designer [External], which is opened in the Data Modeler by choosing the context menu entry Edit on the view for which you created the form layout.

The View Designer displays the user interface elements defined when making the specifications for the form template, including their data source.

2.7.3 Using the Table Template The graphic tool Data Modeler [External] provides support for creating a table layout for a view through the Table Template Assistant. When you define this table layout, you can access the controller context data directly.


Before you commence with the layout definition and data binding for the table, you must set the data flow definition from the backend to the application controller as well as from the controller to the view already created. Proceed as described under Creating a Data Link [External].

Procedure ...

1. Choose the option Table. Enter a name for the layout template or use the default.

2. Choose Next. You see a window in which you can choose the context attributes you require for the table.

3. Choose Next if you want to make changes to the bound data. In the next assistant window, you can change the table entries – for example, the display sequence of the properties – by choosing an entry and moving up or down with the arrow keys.

4. If no changes are necessary, you can close the assistant by choosing Finish.


Result You can display the created layout in the layout tool View Designer [External], which you start in the Data Modeler by choosing the context menu entry Edit on the view for which you created the form layout.

The View Designer displays the user interface elements defined when making the specifications for the layout assistant, including their data source.

Navigation, Plugs and Navigation Links October 2005

Creating a Plug


3 Navigation, Plugs and Navigation Links

Navigation Between Views The navigation from one view to the next is performed using an outbound and an inbound plug which are connected by a navigation link. You can thus define the sequence in which the views of a Web Dynpro application are called. The Navigation Modeler, a graphical Web Dynpro tool, helps you with this task.

It is not possible to control the data flow with this type of navigation. To do this, you must use the graphical Web Dynpro tool called Data Modeler.

You can use one of the following options to control event handling when a plug is triggered:

• For an inbound plug, a method called onPlug<plug_name> is generated by default. This method is executed when the inbound plug is called using the outbound plug of the preceding view and a navigation link. Instead of this method, you can also call an existing method or have no event handling performed.

• For an outbound plug, a method called wdFirePlug<plug_name> is generated by default. You can call this method in the implementation at exactly the place where you want to navigate to the next view.

You can pass parameters to the methods which must be the same for both the outbound and inbound plug if these are connected by a navigation link.

Application Startup and Exit In the interface view, you can define an inbound plug of type Startup and an outbound plug of type Exit Plug which determine the start and end point of a Web Dynpro application.

Navigation Between a Web Dynpro Application and Ano ther Web Application In the interface view, you can define an outbound plug of type suspend and an inbound plug of type resume . Using these plugs, you can navigate from within a Web Dynpro application to any other Web application (suspend ), and then navigate back from this application to your Web Dynpro application (resume ).

Additional Links Navigation Modeler [External]

Event Handling [Page 304]

Web Dynpro Application: Configuration, Deployment and Execution [External]

3.1 Creating a Plug You define a plug with graphical support provided by the Navigation Modeler [External].


Creating a Link


Prerequisites Before you create a plug, you must create the application entities project, component, and view.

Procedure ...

1. Open the Navigation Modeler, by choosing the context menu entry Open Navigation Modeler for the window name in the Web Dynpro Explorer: The work area of the Navigation Modeler is displayed in the right area of the screen.

2. In the function selection area, choose Create Outbound Plug or Create Inbound Plug. In the work area of the Navigation Modeler, click once on the view for which you want to create the plug. It is irrelevant whether you start by defining an outbound plug for the start view or creating an inbound plug for the subsequent view.

To define a view as a start view, you must create an outbound plug for this view using the following wizard: Enter a name for the plug; you can assign the same name to plugs in different views.

3. Choose Next to proceed to the next window and define the parameters.

4. Close the wizard by choosing Finish and then choose Save all Metadata. The outbound plug is then displayed in the form of a red arrow on the right side of the view.

5. To start the wizard for the inbound plug of the subsequent view, choose Create Inbound Plug and then click once on the view in the work area. Make the required entries in the wizard. With an inbound plug you can also define an event handler for the view. When you create the event handler, you choose from the following options:

a. Create an event handler with the default name onPlug<myInboundPlug> .

b. Use the predefined event handler with the name onActionRadioButtonPressed .

c. Define an event handler with optional properties. Choose New, and enter the following in the wizard: Name, Return type, Event source, Subscribed event.

d. If you do not need an event handler for the inbound plug, choose Use None.

6. Close the wizard by choosing Finish and then choose Save all Metadata. The inbound plug is then displayed in the form of a blue arrow on the left side of the view.

In the Web Dynpro Explorer, all created plugs are displayed as entities of the view.

Additional Information The next development step is to create a navigation link between an outbound plug and an inbound plug. Refer to Creating a Link [Page 12].

3.2 Creating a Link You create a link to implement the navigation between two views of a Web Dynpro application in the graphical Navigation Modeler [External] tool. To do so, proceed as follows:

Prerequisites Before you can define a navigation link, you must create an outbound plug for the start view and an inbound plug for the subsequent view. See also, Creating a Plug [Page 11].


Implementing Methods for Outbound Plug Calls


Procedure ...

1. In the Web Dynpro Explorer, start the Navigation Modeler by choosing the context menu entry Open Navigation Modeler for the window name of your project.

2. In the selection area, choose Link.

3. Use the mouse to draw a line from the outbound plug of the start view to the inbound plug of the subsequent view. When you have finished the line, a plug symbol is displayed to indicate that the connection has been implemented.

Result In the Navigation Modeler, the link is displayed as a line between the outbound plug of the start view and the inbound plug of the subsequent view. In the Web Dynpro Explorer, the navigation link is displayed as an entity of the outbound plug.

3.3 Implementing Methods for Outbound Plug Calls To call the outbound plug of the start view, you must implement a method in the subsequent view. To do so, you must edit the implementation file that was generated automatically for the subsequent view. Proceed as follows.

Procedure ...

1. In the Web Dynpro Explorer, start the edit mode for the view by choosing the context menu entry Edit.

2. Choose the Implementation tab.

3. Add code to your event handler as follows:

public void onAction<myAction>(){//@@begin onAction<myAction>(Server Event)wdThis.wdFire<myOutboundPlug>();//@@end}

Use the CodeInsight function for the implementation.

Enter the code in the green comment area intended for this purpose. Otherwise your changes will be deleted by the Web Dynpro Generator in a refresh at compile time.


Suspend and Resume Plug


3.4 Suspend and Resume Plug

Use The suspend plug and the resume plug enable the interoperability between Web Dynpro and other Web applications, such as Java Server Faces or Struts.

They are used to suspend a running Web Dynpro application (when the suspend plug is fired) in order to jump into an external Web application and to resume the Web Dynpro application (using the resume plug) at the same position as soon as it is called by the external application.

The suspend plug is an outbound plug of the InterfaceView of type suspend , the resume plug is an inbound plug of the InterfaceView of type resume .

Suspend Plug

When the suspend plug is fired, parameter Url is used to pass the URL that must be used by the external application in order to be able to resume the Web Dynpro application via the resume plug.

This URL is composed of the address of the Web Dynpro application and of the parameters required to call the resume plug. The Web Dynpro runtime automatically appends it to the URL of the external application.

To fire the suspend plug, the following method is used:

• fireSuspendPlug(String Url)

All parameters are contained in the URL; the parameter string must not exceed 1k, including the part that is added later by the Framework. To encode the application parameters, use a tool such as the Java URL Encoder.

The External Application

The external application received the URL, which it must use later to call the Web Dynpro application again, in the form of a parameter. This parameter is called sap-wd-resumeurl and consists of the URL of the Web Dynpro application and of a parameter containing the session ID. This parameter enables the external application to call the Web Dynpro application via the resume plug. Additional parameters that have been included can now be read and processed. When you intend to navigate from the external application back to the Web Dynpro application, you can again include parameters into the resume URL of the Web Dynpro application.

The Web Dynpro application can be called either using a HTTP POST request or using a HTTP GET request.

Behavior of the Web Dynpro Application During the S uspend State

When the suspend plug is fired, the Web Dynrpo application assumes a suspend state, due to which the application can be resumed at exactly the same position when it is called again via the resume plug.

The length of the suspend state depends on the interval you set in the application property ExpirationTime .

If this duration is exceeded before the Web Dynpro application has been called by the resume plug, then the Web Dynpro application is terminated. If the resume plug is called after the application has been terminated, then the Web Dynpro application is restarted. The difference to a normal application start is that the resume plug is called instead of the startup plug.

UI Elements, Data Binding and Event Handling October 2005

Suspend and Resume Plug


When the resume plug is called in this case, it is possible to restore the state the Web Dynpro application had before it was terminated: you must store the current state of the Web Dynpro application before you terminate it.

If the Web Dynpro application changes its state, the event stateChangeEvent is triggered, which can be queried in the wdDoApplicationStateChange method of the component controller. Here, you can use IWDApplicationStateChangeInfo to query the status. Three reasons are possible for calling the method:

• Suspend: The Web Dynpro application is suspended. In this case you should minimize the storage requirement.

• Resume: The Web Dynpro application is reactivated.

• Timeout: The Web Dynpro application is terminated due to a timeout event. After that, the wdDoExit methods are called.

In addition, you can query the session ID under which the Web Dynpro application can store data. This session ID is again passed in the call of the resume plug, thus storing the data.

Resume Plug

The resume plug is fired when the external application calls the Web Dynpro application using the resume URL.

Additional Links:

For information on the application properties, see Configuring a Web Dynpro Application [External].

4 UI Elements, Data Binding and Event Handling

This section contains information on the following topics:

UI Elements: Methods, Properties and Events A view is made up of user interface elements. Using container elements, you can group the UI elements together. You then assign a layout to determine the arrangement of the individual UI elements on the screen. This section gives an overview of the available UI elements, their methods, properties and events, and provides useful hints on how to use these elements.

See UI Elements: Methods, Properties and Events [Page 16]

Data Binding of UI Element Properties This section gives a general introduction to data binding, that is, the binding of properties to the context. For special information on the binding of certain properties, refer to the documentation of the respective UI element.

See Data Binding of User Interface Element Properties [Page 283]


UI Elements: Methods, Properties and Events


Event Handling Similarly to data binding, the events of a UI element are bound to an action whose source code you implement in the context of the controller. This section describes how events, actions and their parameters are related and how you can connect them.

See Event Handling [Page 304].

4.1 UI Elements: Methods, Properties and Events In Web Dynpro, the UI elements are defined as interfaces. All independent elements are derived from the abstract base class IWDUIElement, whereas the aggregated elements are derived from the abstract base class IWDViewElement.

For information on the abstract base classes, refer to the Javadocs. For information on the UI element APIs displayed on the UI, refer to this documentation.

The UI element reference guide is not available anymore and replaced by this structure.

Javadocs For the reference to the interface, refer to:

• NWDS help under API References or

• the SDN under http://www.sdn.com/sdn/javadocs.sdn.

If you do not have an SDN user, you must register before you can log on.

Assignment of UI Elements to the Libraries

UI Elements API Libraries

InteractiveForm [Page 351] com.sap.tc.webdynpro.clientserver.uielib.adobe.api

BIApplicationFrame com.sap.tc.webdynpro.clientserver.uielib.bi.api

BusinessGraphics

GeoMap

com.sap.tc.webdynpro.clientserver.uielib.graphics.api

RFidReader

FunctionKey

BarCodeReader

com.sap.tc.webdynpro.clientserver.uielib.mobile.api

OfficeControl com.sap.tc.webdynpro.clientserver.uielib.officecomp.api




Layout elements

Container Elements

Button - ButtonRow

BreadCrumb

Caption

CheckBox - CheckBoxGroup

DateNavigator

DropDownByIndex – DropDownByKey

FileUpload - FileDownload

HorizontalGutter

Image

InputField

InvisibleElement

Label

LinkToAction - LinkToURL

PhaseIndicator

ProgressIndicator

MenuBar and PopupMenu

RadioButton - RadioButtonGroups

RoadMap

Tab - Tabstrip

Table and the UI elements it contains

TextEdit

TextView

TimedTrigger

Toggle

ToolBar – ToolBarItems

Tree

TriStateCheckBox

ValueComparison

ViewContainerUIElement [Page 7]

com.sap.tc.webdynpro.clientserver.uielib.standard.api

For documentation on mobile add-on elements, refer to Mobile Web Dynpro [External]. For documentation on interactive Adobe forms, refer to Development of Interactive Adobe Forms for the Web Dynpro UI [Page 348].




Structure The following UML class diagram illustrates the relationships between the base classes of UI elements.

ViewElem ent

LayoutData

Layout

UIElem ent

enabled : Boolean = truetooltip : Trans latableTextvis ible : Vis ibility = vis ible

0..11

+LayoutData0..1

+UIElem ent

1

UIElem entContainer

height : Stringwidth : String

11

+Layout

1

+UIElem entContainer

1

0..n

0..1

+Children0..n

+Container0..1

<<default>>

4.1.1 Common UI Element Properties

Independent UI Elements All independent UI elements are derived from the abstract base class IWDUIElement, which provides the following properties and the corresponding methods.

• enabled This property specifies whether or not an event can be triggered by a user interaction.

The enabled property has no effect on the UI element children you inserted into the UI element container. If, for example, you set the enabled property to false in the group UI element, an input field inserted in it is not automatically deactivated. If the UI element children in this group UI element are also to be deactivated, you must set the relevant property for each UI element separately.




• tooltip This property describes a note for the UI element that is displayed when the user places the cursor on the UI element.

• visible This property specifies the visibility of the UI element. The default value of this property is set to visible .

blank The UI element is not visible on the screen but takes up space.

none The UI element is not visible on the screen and takes up no space.


Properties Overview

Name Interface Type Initial Value Bindable Value Required


tooltip IWDUIElement String (TranslatableText)

bindable No

visible IWDUIElement WDVisibility visible bindable No

Associated UI Elements: View Elements All UI elements that are available within another UI element are derived only from IWDViewElement. This interface is used to uniquely identify an element and provide the appropriate view.

Methods in the Web Dynpro IWDViewElement API

When creating an element, an ID is assigned to the element that identifies the element in its view.

Method Name Return Value Parameter Short Descriptio n

getID String Returns the unique name (ID) for each element.

getView IWDView Returns its view.

4.1.2 Methods of the UI Element APIs The methods of all UI element APIs are, as a matter of principle, built in the same manner.

You can find detailed descriptions of the individual methods in the Javadocs in the SDN or in the NWDS help under API References .




Methods for Property Handling One Get- and one Set method exists for the property of a user interface element:

Getter- and Setter methods

• The Get methods return the value of a property or an element. The name of the method is created according to the following pattern: get<Name of the property> Example : IWDTable, property: design, m ethod: getDesign .

• The Set methods set the value of a property or an element. If a property is readOnly , then this method is not implemented. The name of the method is created according to the following pattern: set<Name of the property> Example : IWDTable, property: design, method: setDesign .

Data Binding Methods

If a property can, or must be bound to the context, the respective Bind- and BindingOf methods are available.

• The Bind methods bind the value of a property to the Context-Element specified by the path. The name of the method is created according to the following pattern: bind<Name of property> Example : IWDTable, property: design, method: bindDesign .

• The BindingOf methods return the path of the context element to which a property is bound and return NULL if no binding exists. The name of the method is created according to the following pattern: bindingOf<Name of the property> Example : IWDTable, property: design, method: bindingOfDesign .

Methods for Event Handling • The Get methods return the value of an event. The name of the method is created

according to the following pattern: get<Name of the property> Example : IWDTable, event: onFilter, method: getOnFilter .

• The Set methods set the value of an event. The name of the method is created according to the following pattern: set<Name of the property> Example : IWDTable, event: onFilter, method: setOnFilter .

• The MappingOf method return the parameter mapping for an event. The name of the method is created according to the following pattern: mappingOf<Name of the event> Example : IWDTable, event: onFilter, method: mappingOfOnFilter .

Methods for Handling of Aggregated Elements If an interface element can contain other elements, the following methods are available:

• Two Add methods that add an element.

• If only the element is transferred as parameter, then the element is added at the and of a list

• If an index is transferred as well, then this element is transferred at the specified index position.




The name of both methods is created according to the following pattern: add<Name of the element> Example : IWDTable, element: Column, method: addColumn .

• The Destroy methods remove and delete the respective elements. The name of the method is created according to the following pattern: destroy<Name of the element> . Example: IWDTable, element: Column, method: destroyColumn . If all elements of a type are to be removed, then the name is: destroyAll<Name of the elements> Example : IWDTable, element: Column, method: destroyAllColumns .

• The Get methods are used to determine the allocation to the superordinate or subordinate elements. The name of the method is created according to the following pattern: get<Name of the elements> Example : IWDTable, element: Column, method: getColumn .

• The Has methods test whether aggregated elements exist within this element. The name of the method is created according to the following pattern: has<Name of the elements> Example : IWDTable, element: Column, method: hasColumns .

• The Iterate methods return an iterator about all aggregated elements within the current element. The name of the method is created according to the following pattern: iterate<Name of the elements> Example : IWDTable, element: Column, method: iterateColumns .

• The Remove methods remove the respective aggregated elements. These are retained, and can later be added to the current element again. You can delete individual or all elements.

• On individual elements, you can either transfer the index or the ID, the method is created according to the following pattern: remove<Name of the element>. Example: IWDTable, element: Column, method: removeColumn .

• If you want to remove all elements, use a method that is created according to the following pattern: removeAll<Name of the elements> Example : IWDTable, element: Column, method: removeAllColumns .

Some user interface elements have additional methods; These are described there.

4.1.3 Layout

Definition The layout specifies the arrangement of the UI elements in their container. An object of the type Layout can be added to each container. To each child object contained in this container, an appropriate object of the type LayoutData can be added. This IWDLayoutData object specifies the layout properties of the corresponding child - for example, the position in a coordinate system defined by the layout.




Layout Classes Each UI element container aggregates a corresponding layout object that describes how the inserted UI element children are assigned within the container. This type of layout object is a subclass of the abstract base class IWDLayout.

The following layout classes are available for arranging the UI elements in a view:

• IWDFlowLayout [Page 23] A flow layout sequentially arranges the container children. This means that you cannot describe defined line breaks, for example. A flow layout depends on the client technology and the size of the browser window.

• IWDGridLayout [Page 25] A grid layout arranges the container children in a two-dimensional grid with a defined column number and any number of rows. Line breaks can be defined. Line breaks are automatically inserted when a UIelement is too long to be displayed within one row.

• IWDMatrixLayout [Page 27] A matrix layout arranges the container children in a tabular format, similar to the grid layout. You can use the properties stretchedHorizontally and stretchedVertically to specify whether or not the UI elements match the container size. You cannot explicitly define the number of columns, for example, which you can do when using the grid layout. Instead you assign a IWDMatrixHeadData object to a UI element so this UI element is wrapped. It is a great advantage of the matrix layout over the grid layout that you can easily create consistentlayout structures using the provided cell classes.

• IWDRowLayout [Page 31] A row layout has a similar behavior as the matrix layout. However, it sequentially assigns the UI elements to exactly one column. If you assign a IWDRowHeadData object to a UI element, it is exactly this UI element that is wrapped. It is a great advantage of the row layout that you can easily create consistent layout structures using the predefined cell classes, which are also provided in the matrix layout.

LayoutDataClassUIElement

ClassUIElementContainer Layout

Aggregation

Generalization

ViewElement

0..n

0..1

Children

Container

1

0..1




LayoutData Classes Each UI element references to an IWDLayoutData object.

These classes are used to control:

• Padding between individual UI elements and between the UI element and the grid cell

• Horizontal and vertical alignment of the UI elements within the grid

• Width and height of the UI element in the cell

The IWDLayoutData object is an instance of the subclass of the abstract IWDLayoutData base class. Web Dynpro provides the following LayoutData classes for the layout classes IWDFlowLayout, IWDGridLayout, IWDMatrixLayout, and IWDRowLayout:

• IWDFlowData [Page 23]

• IWDGridData [Page 26]

• IWDMatrixData [External]

• IWDRowData [Page 31]

4.1.3.1 FlowLayout API

Definition In Web Dynpro, a flow layout is a container layout that arranges the UI elements on the screen from left to right in a flow and wraps UI elements, if necessary.

Description of UI Element Properties The properties defaultPaddingBottom, defaultPaddingLeft, defaultPa ddingRight , and defaultPaddingTop are deprecated and can no longer be used.

• wrapping The property wrapping of the type boolean specifies whether or not the UI elements can be wrapped. The default value is true. This property is not bindable. If the value of this property is false , the UI elements are not wrapped. If the space is too small, UI elements are not displayed in one line but truncated on the right.

4.1.3.2 FlowData API

Definition The Web Dynpro IWDFlowData API provides the layout data for an user interface element in a container (to which a flow layout is assigned).

Description of Properties The properties paddingBottom, paddingLeft, paddingRight , and paddingTop are deprecated and can no longer be used.




• cellDesign

lPad This value specifies the distance of 2 pixels to the upper and lower edge and can be used in the last right column.

lrNoPad This value specifies the distance of 2 pixels to the upper and lower edge and can be used in the last right and the first left column.

lrPad This value specifies the distance of 2 pixels to the upper and lower edge and a margin of the page of 4 pixels. It should not be used in the far left and far right column.

padless This value specifies a distance of 0 pixel to the edges. It is used for contents with their own padding.

rPad This value specifies the distance of 2 pixels to the upper and lower edge and a margin of the page of 4 pixels. It can also be used in the far left column and prevents the contact between cell contents.

The default value is rPad.

• vGutter Specifies additional, horizontal distances between the cell contents. The default value of this property is none. It can be set separately for each cell. The vGutter property can be filled with the following values and is represented by the enumeration type WDLayoutCellSeparator .

Value Display in default cell design

Short description

large

Additional horizontal distance of 31 pixels

largeWithRule

Additional horizontal distance of 31 pixels with a vertical line

Medium


mediumWithRule


none

No additional distance

xLarge Additional horizontal distance of 63 pixels

xLargeWithRule Additional horizontal distance of 63 pixels with a vertical line

Properties Overview Layout data is not bindable.

Name Interface Type Initial Value

cellDesign IWDFlowData WDLayoutCellDesign rPad

vGutter IWDFlowData WDLayoutCellSeparator none




4.1.3.3 GridLayout API

Definition The grid layout (IWDGRidLayout) is a layout that arranges the UI elements in the UI element container in the form of a grid. The number of grid columns can be specified using the grid layout property colCount .

The UI element InvisibleElement allows you to fill cells that should not display anything.

Description of GridLayout Properties • cellPadding

Specifies the padding of the UI element to the grid cell edge for all grid layout cells.

• cellSpacing Specifies the space between the individual grid cells for all grid layout cells.

• colCount Specifies the number of grid columns.

• stretchedHorizontally Specifies whether or not the UI elements match the container size of the horizontal alignment.

• stretchedHorizontally Specifies whether or not the UI elements match the container size of the vertical alignment.

The following diagram illustrates how the GridLayout properties work:

Properties Overview Name Interface Type Initial Value Bindable Value

Required

cellPadding IWDGridLayout int 0 not_bindable No

cellSpacing IWDGridLayout int 0 not_bindable No

colCount IWDGridLayout int 1 not_bindable No

stretchedHori IWDGridLayout boolean true not_bindable No




zontally

stretchedVertically

IWDGridLayout boolean true not_bindable No

4.1.3.4 GridData API

Definition The Web Dynpro IWDGridData API provides the layout data for an user interface element in a container (to which a grid layout [Page 25] is assigned). A grid layout defines a number of cells. In a grid layout cell, you can align a UI element both horizontically (left-justified, horizontally centered, right-justified, and so on) and vertically (top-aligned, vertically centered, bottom-aligned, and so on). The default settings for the alignment of the UI elements within the grid layout is left-justified and top-aligned.

Description of Properties • cellBackgroundDesign

Specifies the design of the cell background. The default value of this property is transparent . You can use the background colors fill1 , fill2 , and fill3 as separators between the individual semantically different cell contents. The cellBackgroundDesign property can be filled with the following values and is represented by the enumeration type WDCellBackgroundDesign .

Value Short Description

border The color of the cell borders. This value is used for nested grid layouts to create grid net lines.

fill1 The color corresponds to the value primarycolor of the design property of the Group UI element. *)

fill2 The color corresponds to the value secondarycolor of the design property of the Group UI element. *)

fill3 The color corresponds to the color value of the third level of a Tree UI element. *)

header The color is identical with the color of the header area of a Tree UI element or a table.

plain White background.

transparent The background is transparent. The individual cells are displayed without grid net lines.

*) The colors to be displayed depend on the design topic and the documentation refers to the SAP Standard Design 2002.

• colSpan Specifies the number of columns occupied by the UI element in the grid.

• hAlign This property is deprecated and can no longer be used.

• height Specifies the height of the UI element in the grid layout cell.

• paddingBottom Specifies the padding of the UI element to the bottom grid layout cell.

• paddingLeft Specifies the left padding of the UI element to the grid layout cell.

• paddingRight Specifies the right padding of the UI element to the grid layout cell.

• paddingTop Specifies the padding of the UI element to the top grid layout cell.

• vAlign Specifies the vertical alignment of the UI element in the grid layout cell. The default value of this property is baseline . The vAlign property is represented by the enumeration type WDCellVAlign and can be used to specify the alignment value of the grid layout cell.

baseline Alignment with a common baseline, the first text line is always displayed at the defined location.

bottom Bottom padding - alignment with bottom edge.

middle Centered vertically.

top Top padding - alignment with top edge.




• width Specifies the width of the UI element in the grid layout cell.

When defining the properties paddingBottom , paddingLeft , paddingRight , and paddingTop , the layout is added to cellpadding that is already defined in grid layout.

Properties Overview Name Interface Type Initial Value Bindable Value Required

cellBackgroundDesign IWDGridData WDCellBackgroundDesign transparent not_bindable No

colSpan IWDGridData int 1 not_bindable No

height IWDGridData String (CSS Size) not_bindable No

paddingBottom IWDGridData String (CSS Size) not_bindable No

paddingLeft IWDGridData String (CSS Size) not_bindable No

paddingRight IWDGridData String (CSS Size) not_bindable No

paddingTop IWDGridData String (CSS Size) not_bindable No

vAlign IWDGridData WDCellVAlign baseline not_bindable No

width IWDGridData String (CSS Size) not_bindable No

4.1.3.5 MatrixLayout API

Definition The matrix layout (IWDMatrixLayout) arranges the UI elements in a grid structure. It uses predefined cell classes that guarantee appropriate distances between cells in the grid. The vGutter property lets you specify additional horizontal distances easily. You can set these additional distances (known as gutters) with or without separators. In addition, the matrix layout can include horizontal separators to separate the rows further, represented by the HorizontalGutter UI element. The distance for each cell is specified by assigning a specific enumeration value of the class WDLayoutCellSeparator of the matrix data object [External]. This type of layout is preferable to the Grid-Layout, since it makes the layout structure in a container more consistent. Using the interface IWDMatrixHeadData [Page 30], you can specify the UI element that appears at the start of each new line.

You should avoid using nested matrix layouts. Instead, use row layouts [Page 31] wherever possible. The row layout differs from the matrix layout in that the content is not organized in table cells. That is, the individual elements are not aligned vertically with each other. When the row layout is implemented in an application, performance is better than if a matrix layout were used, but the layout flexibility is not compromised. For this reason, you should structure the view and container in horizontal areas as early as possible, using the row layout. You should only use the matrix layout if you need to display a table and align the elements vertically.

Description of UI Element Properties • stretchedHorizontally

Specifies whether UI elements aligned using this layout are adapted horizontally to the container size, so that the container is completely filled horizontally.

• stretchedVertically Specifies whether UI elements aligned using this layout are adapted vertically to the container size, so that the container is completely filled vertically.





Required

stretchedHorizontally IWDMatrixLayout

boolean true not_bindable No

stretchedVertically IWDMatrixLayout

boolean true not_bindable No

4.1.3.6 MatrixData API

Definition The Web Dynpro IWDMatrixData API provides the layout data for an user interface element in a container (to which a Matrix layout is assigned).

Description of UI Element Properties • cellBackgroundDesign

Specifies the design of the cell background. The default value of this property is transparent. You can use the background colors fill1 , fill2 , and fill3 as separators between the individual semantically different cell contents. The cellBackgroundDesign property can be filled with the following values and is represented by the enumeration type WDCellBackgroundDesign .


border The color of the cell borders. This value is used for nested grid layouts to create grid net lines.








• cellDesign Specifies the distance between the cell content and the outer edge of the cell. The default value of this property is rPad . The cellDesign property can be filled with the following values and is represented by the enumeration type WDLayoutCellDesign .

Value Display Short Description




lPad

This value specifies a distance to the top edge (2 pixels), the bottom edge (2 pixels) and can be used in the last matrix column on the right.

lrNoPad

This value specifies a distance to the top edge (2 pixels), the bottom edge (2 pixels) and can be used in the last matrix column on the right or the first on the left.

lrPad

This value specifies a distance to the top edge (2 pixels), the bottom edge (2 pixels), the left edge (4 pixels), and the right edge. It should not be used as the last matrix column on the right or first on the left.

padless

This value specifies a distance of zero pixels to the edges of the cell. It is intended for nested contents that have their own specified padding or for cases where there is no need for cell content padding.

rPad

This value is appropriate for displaying most content, and is thus set as the default value. It can be used as the first matrix column on the left. It specifies a distance to the top edge (2 pixels), the bottom edge (2 pixels), and the right edge (4 pixels) and thus prevents cell contents from touching.

• colSpan Specifies the number of columns the UI element occupies in the matrix layout.

• hAlign This property is deprecated and can no longer be used.

• height Specifies the height of the cell.

• vAlign Specifies the vertical alignment of the UI element within the grid. The default value of this property is baseline . The vAlign property can be filled with the following values and is represented by the enumeration type WDCellVAlign .

baseline Alignment with a common baseline, the first text line is always displayed at the defined location.

bottom Bottom padding - alignment with bottom edge.

middle Centered vertically.

top Top padding - alignment with top edge.

• vGutter Specifies additional, horizontal distances between the cell contents. The default value of this property is none. It can be set separately for each cell. The vGutter property can be filled with the following values and is represented by the enumeration type WDLayoutCellSeparator .

Value Display in default cell design

Short description

large


largeWithRule





Medium


mediumWithRule


none




• width Specifies the width of the cell.

Overview of Inherited and Additional Properties Name Interface Type Initial

Value Bindable Value

Required

cellBackgroundDesign

IWDMatrixData

WDCellBackgroundDesign

transparent not_bindable

No

cellDesign IWDMatrixData

WDLayoutCellDesign rPad not_bindable

No

colSpan IWDMatrixData

int 1 not_bindable

No

height IWDMatriaData

String (CSS size) not_bindable

No

vAlign IWDMatrixData

WDCellVAlign baseline not_bindable

No

vGutter IWDMatrixData

WDLayoutCellSeparator

none not_bindable

No

width IWDMatrixData

String (CSS size) not_bindable

No

4.1.3.7 MatrixHeadData API

Definition The Web Dynpro IWDMatrixHeadData API provides the layout data for an user interface element in a container (to which a Matrix layout is assigned). You can specify a new line in a Matrix layout with this object.




4.1.3.8 RowLayout API

Overview The row layout arranges the UI elements in a single column. Like the Matrix-Layout [Page 27], the row layout uses predefined cell classes, which ensure that the distances between cells are appropriate for the entire row. The vGutter property of the RowHeadData object lets you specify additional horizontal distances easily. You can set these additional distances with or without separators. The distance for each cell is specified by assigning a specific enumeration value of the class WDLayoutCellSeparator of the RowHeadData [Page 31] object. The subelement RowHeadData [Page 31] allows you to specify which UI element appears at the start of each new row within the container. The row layout differs from the matrix layout in that the content is not organized in table cells. That is, the individual elements are not aligned vertically with each other. When the row layout is implemented in an application, performance is better than if a matrix layout were used, but the layout flexibility is not compromised. For this reason, you should structure the view and container in horizontal areas as early as possible, using the row layout. You should only use the Matrix layout [Page 27] if you need to display a table and align the elements vertically.

4.1.3.9 RowData API

Definition The Web Dynpro IWDRowData API provides the layout data for an user interface element in a container (to which a row layout [Page 31] is assigned). A UI element starts in a new row if the layout data is supplied by an instance of the subclass RowHeadData [Page 31]. The layout data is valid for the entire row.

Subordinate Interfaces IWDRowHeadData [Page 31].

4.1.3.10 RowHeadData API

Definition The RowHeadData element defines the layout data of a UI element that starts a new row in a row layout. The values of the following properties are valid for the entire row.

Description of UI Element Properties • hAlign

This property is deprecated and can no longer be used.

• rowDesign Specifies the design (padding) of a row. Thus, you cannot create gaps between the elements of a row. The default value of this property is rPad . The rowDesign property can be filled with the following values and is represented by the enumeration type WDLayoutCellDesign .

Value Display Short Description




lPad

Specifies the distance to the top edge (2 pixels), the bottom edge (2 pixels), and the left edge (4 pixels).

lrNoPad

Specifies the distance to the top edge (2 pixels) and the bottom edge (2 pixels).

lrPad

Specifies the distance to the top edge (2 pixels), the bottom edge (2 pixels), the left edge (4 pixels), and the right edge (4 pixels).

Padless

There is no distance between the row and the edges.

rPad

Specifies the distance to the top edge (2 pixels), the bottom edge (2 pixels), and the right edge (4 pixels) and thus prevents cell contents from touching.

• rowBackgroundDesign Specifies the design of the row background. The default value of this property is transparent . You can use the background colors fill1 , fill2 , and fill3 to highlight semantically different rows. The rowBackgroundDesign property can be filled with the following values and is represented by the enumeration type WDCellBackgroundDesign .


border The color of the cell borders. This value is used for nested row layouts to create grid net lines.








• vGutter Specifies an additional distance to the left edge. The default value of this property is none . Other values are only appropriate if the row layout is used in a matrix layout. The vGutter property can be filled with the following values and is represented by the enumeration type WDLayoutCellSeparator .

large





largeWidthRule


medium


mediumWithRule


none




Overview of Inherited and Additional Properties Name Interface Type Initial Value Bindabl

e Value Required

hAlign IWDRowHeadData

WDCellHAlign beginOfLine not_bindable

No

rowDesign IWDRowHeadData

WDLayoutCellDesign

rPad not_bindable

No

rowBackgroundDesign

IWDRowHeadData


transparent not_bindable

No

vGutter IWDRowHeadData

WDLayoutCellSeparator

none not_bindable

No

4.1.4 Containers The abstract basis class of the container elements is IWDUIElementContainer. The UIElementContainer UI element is the abstract base class of a container that can contain any number of UI elements known as children of the container. The display of the container children within the container is specified by the layout object.

The size of a container is specified using the properties width and heigth whose values can be specified in CSS units (px, em, or percentage).

The following container classes are available for the application developer:

• TransparentContainer The class TransparentContainer is a UI element container without any visual representation. A TransparentContainer UI element is transparent and can be filled with an any quantity of UI elements (children).

• ScrollContainer

• Group

• Tray




The ScrollContainer, Group and Tray provide the opportunity for horizontal and vertical scrolling.

The following UML class diagram shows the interrelationship of the different containers:

ScrollContainer

accessibil i tyDescription : T ranslatableTextdefaultButtonId : Stringscroll ingMode : Scroll ingMode = none

TransparentContainer

isLayoutContainer : Boolean = true

Group

design : GroupDesign = primarycolorhasContentPadding : Boolean = true

Caption

text : T ranslatableText

1

1

+Group 1

+Header

1

ToolBar

1

0..1

+Group 1

+ToolBar

0..1

Tray

onToggle : StringonToggle_expanded : Boolean = falsedesign : T rayDesign = transparentexpanded : Boolean = truehasContentPadding : Boolean = true

1

1

+Tray 1

+Header

1

1

0..1

+Tray 1

+ToolBar

0..1

4.1.4.1 ScrollContainer API

Definition The ScrollContainer UI element enables you to use a vertical and horizontal scroll bar for the visible UI elements Group [Page 35] and Tray [Page 38].

Description of UI Element Properties • accessibilityDescription

When accessibility is activated, the assigned text is added to the tooltip. This description provides semantic details of the UI element and is only read by the screen reader if the user focuses the complete Ul element.

• defaultButtonId Specifies the ID of the assigned default button.

• enabled The enabled property has no effect on the UI element children you inserted into the UI




element container. If, for example, you set the enabled property to false in the group UI element, an input field inserted in it is not automatically deactivated. If the UI element children in this group UI element are also to be deactivated, you must set the relevant property for each UI element separately.

• scrollingMode Specifies how the scroll bar appears within the UI element container. The scrollingMode property can be filled with the following values and is represented by the enumeration type WDScrollingMode .

auto The scroll bar within the container is activated automatically.

both A vertical and horizontal scroll bar are activated.

none Scrolling within the text context is not possible.

The properties enabled and tooltip are ignored and do not affect the browser.

The properties height and width must be specified for the ScrollContainer UI element – that is, you must assign values to these properties for the scrolling modes both and auto. If you do not want to have scroll bars for the UI element and assign the value none to the scrollingMode property, you should use another container UI element – for example, the TransparentContainer UI element.


Value Bindable

Value Required

accessibilityDescription IWDScrollContainer String bindable No

defaultButtonId IWDScrollContainer String bindable No


height IWDUIElementContainer String (CSS size) bindable No

scrollingMode IWDScrollContainer WDScrollingMode none bindable No


bindable No


width IWDUIElementContainer String (CSS size) bindable No

Subordinate Interfaces IWDGroup, IWDTray

4.1.4.2 Group API

The Web Dynpro class Group which implements the IWDGroup interface is the base class of a group UI element.




Definition The Group UI element is a UI element container and can be used to group multipe UI elements under one common title. The following diagram shows that the UI element resembles a display panel with a colored background.

The enabled property has no effect on the UI element children you inserted into the UI element container [External]. If, for example, you set the enabled property to false in the group UI element, an input field inserted in it is not automatically deactivated. If the UI element children in this group UI element are also to be deactivated, you must set the relevant property for each UI element separately.

The Group UI element with the default design primarycolor :

Description of UI Element Properties • design

Describes the appearance of the Group UI element. The design property can be filled with the following values and is represented by the enumeration type WDGroupDesign .

primarycolor The group panel has the same background color as the title bar (color of the primary group).

sapcolor The title bar and the borders around the panel have the blue SAP color. The background color of the panel is white.

secondarybox The panel does not have borders.

secondaryboxcolor The background color of the panel is different from the background color of the title bar.

secondarycolor The panel has the same background color as the title bar (color of the secondary group). You can use this value when you want to display subgroups within a group.

• enabled The inherited enabled property is ignored and does not affect the browser. The label in the header of the Group UI element can be hidden by setting the value of the visible property for the header to none .

• hasContentPadding Specifies whether or not it is possible to insert padding between content and UI element borders.




Overview of Inherited and Additional Properties


Bindable

Value Required

accessibilityDescription

IWDScrollContainer String bindable

No

defaultButtonId IWDScrollContainer String bindable

No

design IWDGroup WDGroupDesign

primarycolor

bindable

No

enabled IWDUIElement boolean true bindable

No

hasContentPadding IWDGroup boolean true bindable

No

height IWDUIElementContainer

String (CSS size)

bindable

No

scrollingMode IWDScrollContainer WDScrollingMode

none bindable

No


bindable

No

visible IWDUIElement WDVisibility visible bindable

No

width IWDUIElementContainer

String (CSS size)

bindable

No

4.1.4.3 TransparentContainer API

The TransparentContainer (IWDTransparentContainer) is a UI container without any visual representation. A TransparentContainer UI element is transparent and can be filled with an any quantity of UI elements (children). In addition, the TransparentContainer UI element allows you to arrange its inserted UI elements through the specified layout.

The properties enabled and tooltip are ignored.

Description of UI Element Properties • isLayoutContainer

Specifies whether the transparent container can be used as a layout container.



Required





IWDScrollContainer String bindable No

defaultButtonId IWDScrollContainer String bindable No



String bindable No

isLayoutContainer IWDTransparentContainer

boolean true not_bindable

No

scrollingMode IWDScrollContainer WDScrollingMode

none bindable No




String bindable No

4.1.4.4 Tray API

Definition The Tray UI element (IWDTray) is a UI element container like the Group UI element container and can be used to group a set of UI elements under one common title. Unlike the Group UI element it provides additional functions. For example, the Tray UI element can be displayed or hidden.

A Tray UI element may have an optional menu represented by the menu element [Page 149]. A toolbar can be inserted as well - see Toolbar.

The following graphic shows how the UI element is displayed when a Menu UI element and a UI element are used within the Tray UI element.


Describes the appearance of the Tray UI element. The design property can be filled with the following values and is represented by the enumeration type WDTrayDesign .

fill The content area appears with a background color.

plain The content area appears with a white background and a frame.

transparent The background is transparent; the content area appears without a frame.

• enabled The enabled property has no effect on the UI element children you inserted into the UI




element container. If, for example, you set the enabled property to false in the group UI element, an input field inserted in it is not automatically deactivated. If the UI element children in this group UI element are also to be deactivated, you must set the relevant property for each UI element separately.

• expanded Specifies whether the Tray UI element is expanded. The value false only shows a header with the expand icon. The toolbar and content area are invisible in this state. Pressing the button expands the Tray UI element and the expand button and the expand button changes to a collapse button.

• hasContentPadding Specifies whether there is a padding between the content area and the tray border.


Required


IWDScrollContainer

String (Translatable Text)

bindable No

defaultButtonId

IWDScrollContainer

String bindable No

design IWDTray WDTrayDesign transparent bindable No


expanded IWDTray boolean true bindable No

hasContentPadding

IWDTray boolean true bindable No


String (CSS size)

bindable No

scrollingMode IWDScrollContainer

WDScrollingMode

none bindable No


bindable No



String (CSS size)

bindable No

Events • The action that is executed when the user expands or collapses the tray. The event

parameter is the new state. The value true means that the tray has been expanded.

Event Parameter Type

expanded boolean

See Parameter Mapping [External].




4.1.5 BIApplicationFrame API: Integrating BEx Web Applications

Definition In a BIApplicationFrame, Web templates that are based on BEx Web Applications [External] can be accessed using a URL. Various attributes can be set for a Web template. They are passed as parameters using the URL. When using the BIApplicationFrame, these parameters can be set as properties of the UI element.

See also:

Web Template Properties [External]

Object Tag for Properties of Web Templates [External]

Description of Properties of the BIApplicationFrame • dataMode

Specifies the property DATA_MODE of the Web template to be displayed. dataMode is of the enumeration type WDDataMode and according to the values of the Web template it can be filled with the following values: default , hybrid , new, static , staticHybrid, and stored .

• dataProviderStateName Specifies the data provider of the Web template to be displayed and corresponds to the property DATA_PROVIDER.

• dataProviderStateType Specifies the type of the data provider. dataProviderStateType is of the enumeration type WDDataProviderStateType and can be filled with the following values:

Value of the property Corresponding properties of the data provider in the Web template

infoprovider INFOCUBE

query QUERY

view VIEW

• height Specifies the height of the BIApplicationFrame and can be specified in relative CSS units like em, ex, or percentage.

• meltVariables Specifies the property MELT_VARIABLES of the Web template to be displayed.

• server Specifies the Web address of the server.

• serverType Specifies whether the addressed Web Application Server is a Java Server or an ABAP Server.

• stateless Specifies the property STATELESS of the Web template to be displayed.

• suppressSystemMessages Specifies the property SUPPRESS_SYSTEM_MESSAGES of the Web template to be displayed. The value CONDITIONAL is not supported.




• suppressWarnings Specifies the value of the property SUPPRESS_ WARNINGS of the Web template to be displayed.

• templateId Specifies the property TEMPLATE_ID of the Web template to be displayed.

• usePersonalization Specifies the property USE_PERSONALIZATION of the Web template to be displayed.

• variablesClear Specifies the property VARIABLES_CLEAR of the Web template to be displayed.

• variableScreen Specifies the property VARIABLES_ SCREEN of the Web template to be displayed.

• variant Specifies the property VARIANT of the data provider.

• width Specifies the width of the BIApplicationFrame and can be specified in relative CSS units like em, ex, or percentage.

Overview of Inherited and Additional Properties of BIApplicationFrame Name Interface Type Initial


Required

dataMode IWDBIApplicationFrame

WDDataMode default bindable No

dataProviderStateName

IWDBIApplicationFrame

String bindable No

dataProviderStateType


WDDataProviderStateType

default bindable No

debug IWDBIApplicationFrame

boolean false bindable No


height IWDBIApplicationFrame

String bindable No

meltVariables IWDBIApplicationFrame

boolean true bindable No

server IWDBIApplicationFrame

String bindable No

serverType IWDBIApplicationFrame

WDServerType abap bindable No

sessionId IWDBIApplicationFrame

String not_bindable

No

stateless IWDBIApplicationFrame


suppressSystemMessages






suppressWarnings IWDBIApplicationFrame


templateId IWDBIApplicationFrame

String bindable No


usePersonalization IWDBIApplicationFrame


variablesClear IWDBIApplicationFrame


variableScreen IWDBIApplicationFrame


variant IWDBIApplicationFrame

String bindable No


width IWDBIApplicationFrame

String bindable No

4.1.5.1 BIMethods API: Access to Actions of a BEx W eb Application

Definition Various actions can be executed in a Bex Web Application – for example, the filtering oder arranging of data in a table. These actions are mapped in the BIApplicationFrame to the methods BIMethods. You find the Javadocs for the BIMethods in the package: com.sap.tc.webdynpro.clientserver.uielib.bi.api.WDB IMethods .

Methods

The following methods allow the setting and removing of filters:

• clearSelectionState

• setSelectionState in multiple overloaded versions

See also Filter [External]

The DrillDown methods relate to the arrangement of elements of a table in the Web template and specify whether they are arranged in columns or rows. See also: Drilldown [External]

• removeDrillDown

• drillDown

The following methods map to the methods for the definition of Web items:

• resetItem

• resetItemToLibraryItem

• setItemParameter

See also: Resetting and Reinitializing Web Items [External]




Parameters

The parameters of the type WDOperator can be filled with the following values: bt for BETWEEN, eq for equal to, ge for greater than or equal to, gt for greater than, le for less than or equal to and lt for less than. These parameters correspond to the relational operators of Open SQL. See also Selecting Lines [External]

The parameters of the type WDAxis can be filled with the following values: columns , row , free . This parameter specifies whether the elements are arranged in columns or rows.

4.1.6 Breadcrumb Navigation A BreadCrumb displays the current page in the context of a navigation path. You can, for example, display a history of the pages last visited or the structure of the information provided. A BreadCrumb consists of individual links or entirely represents a link, as displayed in the following screen graphics:

behaviour Property and Its Effect at Runtime

multipleLinks

singleLink

You can insert two different types of BreadCrumb steps into a BreadCrumb.

• BreadCrumbStep (IWDBreadCrumbStep)

• MultipleBreadCrumbStep (IWDMultipleBreadCrumbStep)

BreadCrumbSteps are bound to individual context attributes. In this way, the number of displayed steps is defined during runtime. A MultipleBreadcrumbStep is bound to a context node. This allows the number of displayed steps to be dynamically adjusted at runtime.




Structure

UIElementM

ViewElementM

MultipleBreadCrumbStep

dataSource : Object

M

BreadCrumbStep

textDirection : TextDirection = inherittext : TranslatableTexttooltip : TranslatableTextvisible : Boolean = true

BreadCrumb

behaviour : BreadCrumbBehavior = multipleLinkssize : BreadCrumbSize = mediumseparatorImageSource : StringseparatorText : TranslatableText = >onSelect : StringonSelect_step : String

0..*

1

+Steps0..*

+BreadCrumb1

4.1.6.1 BreadCrumb API

The Web Dynpro class BreadCrumb , which implements the IWDBreadCrumb interface, is the base class for representing Breadcrumb navigation.




Description of UI Element Properties • behaviour

This property defines whether the entire breadcrumb path is a link or each single breadcrumb step. The behaviour property can be filled with the following values and is represented by the listing type WDBreadCrumbBehavior .

multipleLinks Each breadcrumb step is an independent link.

singleLink The entire BreadCrumb path is a single link.

• separatorImageSource This property defines the file path of the screen that serves as a separator between the individual BreadCrumb steps.

• separatorText This property defines the text or characters that serves as a separator between the individual BreadCrumb steps.

• size The size property can have the following values and is represented by the listing type WDBreadCrumbSize: large , medium, and small. The standard value is medium.


Required

behaviour IWDBreadCrumb WDBreadCrumbBehavior multipleLinks bindable No


separatorImageSource IWDBreadCrumb String bindable No

separatorText IWDBreadCrumb String > bindable No

size IWDBreadCrumb WDBreadCrumbSize medium bindable No



Events The event onSelect is triggered whenever a user clicks a breadcrumb step.

Name Class Parameter

onSelect IWDBreadCrumb (String step)

4.1.6.2 BreadCrumbStep API

Definition The Web Dynpro class BreadCrumbStep implements the IWDBreadCrumbStep interface.




A breadcrumb step is an element of a BreadCrumb that is implemented as IWDBreadCrumb.

Description of UI Element Properties • text

This property specifies the text.

• textDirection With this property you can specify the text direction. This enables the labels for the BreadCrumb step to be read in other languages that require a specific text direction. The textDirection property can be filled with the following values and is represented by the listing type WDTextDirection .

inherit The text direction is inherited from the parent element. Therefore, the text direction is identical to the one of the parent element.

ltr The text runs from left to right.

rtl The text runs from right to left.

The default value for this property is inherit .

• tooltip This property describes a note for the view element, which is displayed when the user places the cursor on the view element.

• visible This property specifies whether or not the BreadCrumb step is displayed. This property enables you to easily hide a BreadCrumb step.



Required

text IWDBreadCrumbStep String bindable No

textDirection IWDBreadCrumbStep WDTextDirection inherit bindable No

tooltip IWDBreadCrumbStep String bindable No

visible IWDBreadCrumbStep boolean true bindable No

4.1.6.3 MultipleBreadCrumbStep API

Definition A MultipleRoadMapStep is bound to a context node and enables the application developer to dynamically adapt the BreadCrumb. Depending on how many elements are assigned to the context node, the number of displayed BreadCrumb steps can vary.

Description of UI Element Properties • dataSource

This property defines the context node to which the MultipleBreadCrumbStep must be bound.




Overview of Inherited and Additional Properties Name Interface Type Initi

al Value

Bindable Value Required

dataSource

IWDMultipleBreadCrumbStep

Object bindable_mandatory

No

text IWDBreadCrumbStep String bindable No

textDirection

IWDBreadCrumbStep WDTextDirection

inherit

bindable No

tooltip IWDBreadCrumbStep String bindable No

visible IWDBreadCrumbStep boolean true bindable No

4.1.7 Web Dynpro BusinessGraphics API - IWDBusinessGraphics

Definition The BusinessGraphics UI element provides several chart types such as vertical bar charts or pie charts, that can be used for the graphical illustration of data and data relationships. In addition, there are more complex chart types such as portfolio and gantt that can help the user of your Web application to make decisions for corporate planning or find information in general.

You can use the Chart Designer [External] to modify the UI element properties and additional properties, the chart elements, and adapt them to suit your requirements. For detailed information on this tool, refer to

• Chart Designer [External]

• Calling Chart Designer [External].

For further information about the chart types like the three-dimensional pie chart below and detailed documentation about Internet Graphics Service (IGS), refer to the SAP library under SAP NetWeaver → Application Platform (SAP Web Application Server) → ABAP Technology →UI Technology →Frontend Services.




Use When using a business graphic, always display this UI element alongside a Label UI element to ensure accessibiltiy.

Description of the UI Element Properties • backgroundColor

Specifies the background color of a BusinessGraphics UI element.

• chartType Specifies the chart type. The following chart types are available:

Chart Type Short Description Example

area Describes a surface diagram.

bars Describes a bar chart.

columns Describes a vertical bar chart.

doughnut Describes a ring chart.

gantt Describes a chart of the type Gantt.

lines Describes a line chart.

pie Describes a pie chart.

pipeline Describes a chart of the type pipeline.




polar Describes a chart of the type polar.

portfolio Describes a chart of the type portfolio. This chart type can be used as an analytical means in the strategic corporate planning because it can illustrate the competitiveness, for example.

profile_area Describes a chart of the type profile_area.

profiles Describes a chart of the type profiles.

radar Describes a chart of the type radar.

scatter Describes a chart of the type scatter.

speedometer Describes a chart of the type speedometer.

split_pie Describes a chart of the type split_pie.

stacked_area Describes a chart of the type stacked_area.

stacked_bars Describes a chart of the type stacked_bars.

stacked_columns Describes a chart of the type stacked_columns.

stacked_lines Describes a chart of the type stacked_lines.

stacked_profile_area Describes a chart of the type stacked_profile_area.

stacked_profiles Describes a chart of the type stacked_profiles.

stacked_radar Describes a chart of the type stacked_radar.

• customizing Describes how the chart is displayed on the screen. This property is assigned to a Web address (URL) linking to an XML file that describes the appearance of the business graphic on the screen – for example, the graphic color, the background color, fonts, and so on. It also specifies whether the graphic displays a legend or not. You can specify these settings directly in the SAP NetWeaver Developer Studio using the Chart Designer tool. To call the tool, place the cursor on the UI element, click the right mouse button, and select the Start Chart Designer menu option in the context menu.




The BusinessGraphics properties dimension and fontFamily are provided by the meta model itself. They overwrite the Customizing settings if they differ from meta model settings.

• seriesSource Describes the path to the context node in the hierarchical structure of the context that provides the data.

• dimension Describes the dimensions of the chart. The following dimensions are available:

pseudo_three A pseudo-three-dimensional chart, the z-axis is not displayed.

three A real three-dimensional chart.

two A two-dimensional chart (surface diagram).

• fontFamily Specifies the font for the graphic elements.

• height Specifies the height of the chart and can be specified in relative CSS units like em, ex, or percentage.

• igsUrl This property can specify the Web address (URL) of the server on which the Internet Graphics Service should run. This means that you can overwrite the global URL for which the Web Dynpro System Configuration [External] in the default.properties file has been set.

• transparentColor Specifies the color to be used as transparent color. You can specify the colors in RGB, HSB, or X11 - for example, rgb(255,0,0), or slateblue.

• width Specifies the width of the chart and can be specified in relative CSS units like em, ex, or percentage.



Required

backgroundColor IWDBusinessGraphics String not_bindable No

chartType IWDBusinessGraphics WDBusinessGraphicsType columns not_bindable No

customizing IWDBusinessGraphics String not_bindable No

seriesSource IWDBusinessGraphics Object bindable_mandatory No

dimension IWDBusinessGraphics WDBusinessGraphicsDimension two not_bindable No

enabled [External] IWDUIElement boolean true bindable No

fontFamiliy IWDBusinessGraphics String not_bindable No

height IWDBusinessGraphics String 300 not_bindable No

igsUrl IWDBusinessGraphics String not_bindable No

tooltip [External] IWDUIElement String (TranslatableText) bindable No

transparentColor IWDBusinessGraphics String not_bindable No




visible [External] IWDUIElement WDVisibility visible bindable No

width IWDBusinessGraphics String 300 not_bindable No

Events • onAction

Describes the action to be executed when the user selects a certain area of the business graphic.


ID String

For further information, refer to Event Parameter and Parameter Mapping [Page 316].

Data Binding See Data Binding of BusinessGraphics UI Elements [Page 70].

Methods of the Web Dynpro IWDBusinessGraphics API Method Name Parameter Return Value Description

addSeries (IWDAbstractSeries series)

Adds a Series element at the end of the Series elements list.

addSeries (IWDAbstractSeries series, int index)

Adds a Series element at the specified index position of the Series elements list.

bindingOfSeriesSource

String Returns the path of the context element to which the seriesSource property is bound. Returns NULL if no binding exists.

bindSeriesSource (String path) Binds the seriesSource property to the context node specified by a path.

destroyAllSeriesList

Removes all Series elements. These are destroyed and no longer exist,




so that the associated IDs can be used for new elements.

destroyCategory Removes and deletes the category for this BusinessGraphics element.

getBackgroundColor

String Returns the value of the backgroundColor property.

getCategory IWDCategory Returns the category for this BusinessGraphics element.

getChartType WDBusinessGraphicsType

Returns the value of the chartType property.

getCustomizing String Returns the value of the customizing property.

getDimension WDBusinessGraphicsDimension

Returns the value of the dimension property.

getFontFamily String Returns the value of the fontFamily property.

getHeight int Returns the value of the height property.

getIgsUrl String Returns the value of the igsUrl property.

getOnAction IWDAction Returns the action that is executed when the onAction event is triggered.

getSeriesList IWDAbstractSeries[] Returns an array of the Series elements.




getTransparentColor

String Returns the value of the transparentColor property.

getWidth int Returns the value of the width property.

hasSeriesList boolean Checks whether or not Series elements exist in this BusinessGraphics element.

iterateSeriesList Iterator Returns an iterator about all Series elements in this BusinessGraphics element.

mappingOfOnAction

IWDParameterMapping Returns the parameter mapping for the onAction action.

numberOfSeriesList

int Returns the number of the Series elements.

removeAllSeriesList

Removes all Series elements. They remain and can be added to this BusinessGraphics element.

removeSeries (int index) IWDAbstractSeries Removes the Series element at the specified index position.

removeSeries (String id) IWDAbstractSeries Removes the Series element with the specified ID.

setBackgroundColor

(String backgroundColor) Sets the value of the backgroundColor property.

setCategory (IWDCategory category) Sets the category for this BusinessGraphics element.




setChartType (WDBusinessGraphicsType chartType)

Sets the value of the chartType property.

setCustomizing (String customizing) Sets the value of the customizing property.

setDimension (WDBusinessGraphicsDimension dimension)

Sets the value of the dimension property.

setFontFamily (String fontFamily) Sets the value of the fontFamily property.

setHeight (int height) Sets the value of the height property.

setIgsUrl (String igsUrl) Sets the value of the igsUrl property.

setOnAction (IWDAction action) Sets the action that is executed if the onAction event is raised.

setTransparentColor

(String transparentColor) Sets the value of the transparentColor property.

setWidth (int width) Sets the value of the width property.

Additional methods described in the following APIs are available using inheritance: IWDUIElement [External], IWDViewElement [External].

For detailed documentation of all inherited methods, see the documentation for the relevant APIs.

The relationships to the associated APIs are explained under Meta Model of the BusinessGraphics UI Element [External].

Associated Interfaces IWDAbstractSeries [External]

IWDCategory [Page 55]




4.1.7.1 Web Dynpro Category API - IWDCategory

Overview The Category object is a part the BusinessGraphics UI Element [Page 47] and describes the categories of a graphical representation. Categories of a chart are a discrete value range or an unsorted set of objects - such as January, February, March, and so on - that do not have a distance term and therefore have no relation to each other. In a vertical bar chart, the categories are displayed next to each other in columns with the categories on the x-axis and the values on the y-axis. This enables the user to compare individual categories – for example, the sales figures for each month of one year.

The following chart shows a business graphic of the vertical bar chart type with six categories and three data series. The six categories are displayed on the horizontal x-axis. The three data series are displayed as vertical columns for each category.

For example, the categories of a chart can represent the first six months, and each data series can represent a pharmaceutical company. The height of an individual column can indicate the revenue of a company in one month.

Unlike the simple category-based charts such as vertical bar charts, the more complex scatter charts and portfolio charts do not contain categories.




A pie chart represents all categories of a data series.

Property Descriptions • description

Specifies the texts of the categories. You can statically specify this property value at design time or bind it to a context attribute so that the value is provided automatically by the context at runtime.

• eventID Enables you to define an ID that can determine from which object the event has been triggered.

• tooltip Describes a note for the UI element that is displayed when the user places the cursor on the UI element.


Required

description IWDCategory String No bindable_mandatory No

eventID IWDCategory String bindable No

tooltip IWDCategory String (TranslatableText)

No bindable No

Events • onAction

This property can be used to execute a predefined Web Dynpro action when selecting the category area in the generated graphic.

Methods in the Web Dynpro IWDCategory API Method Name Parameter Return Value Short Descriptio n

bindDescription (String path) Binds the value of the description property to the context element specified by the path.

bindEventID (String path) Binds the eventID property to the context node specified by a path.

bindingOfDescription String Returns the path of the context element to which the description property is bound. Returns NULL if no binding exists.




bindingOfEventID String Returns the path of the context element to which the eventID property is bound. Returns NULL if no binding exists.

bindingOfTooltip String Returns the path of the context element to which the tooltip property is bound. Returns NULL if no binding exists.

bindTooltip (String path) Binds the value of the tooltip property to the context element specified by the path.

getBusinessGraphics IWDBusinessGraphics Returns the BusinessGraphics element in which this Category element is contained.

getDescription String Returns the value of the description property.

getEventID String Returns the value of the eventID property.

getOnAction IWDAction Returns the action that is executed when the onAction event is triggered.

getTooltip String Returns the value of the tooltip property.

mappingOfOnAction IWDParameterMapping Returns the parameter mapping for the onAction action.

setDescription (String value) Sets the value of the description property.

setEventID (String eventID) Sets the value of the eventID property.

setOnAction (IWDAction action)

Sets the action that is executed if the onAction event is




raised.

setTooltip (String value) Sets the value of the tooltip property.

Additional methods are available using inheritance: IWDViewElement [External].

4.1.7.2 Web Dynpro Series API - IWDSeries

Overview The Series object is used to specify a more complex data series. You can use this object for displaying data series if you do not want to display a category-based chart or if the number of data series is not definite at design time.

A data series represented by the Series object can contain exactly one Point object [Page 61].

Property Descriptions • customizingID

An ID is assigned to this property, and the ID stores information about the representation of the data series under the Customizing XML file of the BusinessGraphics UI element.

• dataBeginIndex This property can be used to display a selection of node elements of the bound context node. The dataLength property is used to define the number of node elements to be selected.


• pointSource This property is used to specify the data source. You can use it to specify the path to the context node that provides the data for this object.

• dataLength You can use this property to specify the number of node elements if you have specified a selection using the dataBeginIndex property.

• label This property is used to specify an optional text to be displayed for a point in a business graphic.

• leadSelectionCustomizingID This property can be used to select an alternative Customizing. The data series must be selected.

• showSelectedOnly A Boolean value that describes the selection of a data series. If the value is set to true, only the selected data series are displayed.




• tooltip Describes a note that is displayed when the user places the cursor on the area of the data series.



Required

customizingID IWDSeries String No bindable No

dataBeginIndex IWDSeries int 0 bindable No

dataLength IWDSeries int 0 bindable No

eventID IWDSeries String bindable No

label IWDSeries String (TranslatableText)

No bindable No

leadSelectionCustomizingID IWDSeries String No bindable No

pointSource IWDSeries Object No bindable_mandatory No

showSelectedOnly IWDSeries boolean false not_bindable No

tooltip IWDSeries String (TranslatableText)

No bindable No

Methods in the Web Dynpro IWDSeries API Method Name Parameter Return Value Short Descriptio n

bindCustomizingID (String path) Binds the customizingID property to the context node specified by a path.

bindDataBeginIndex (String path) Binds the dataBeginIndex property to the context node specified by a path.

bindDataLength (String path) Binds the dataLength property to the context node specified by a path.


bindingOfCustomizingID String Returns the path of the context element to which the customizingID property is bound. Returns NULL if no binding exists.

bindingOfDataBeginIndex String Returns the path of the context element to which the dataBeginIndex property is bound. Returns NULL if no binding exists.

bindingOfDataLength String Returns the path of the context element to which the dataLengthproperty is bound. Returns NULL if




no binding exists.


bindingOfLabel String Returns the path of the context element to which the label property is bound. Returns NULL if no binding exists.

bindingOfLeadSelectionCustomizingID String Returns the path of the context element to which the leadSelectionCustomizingIproperty is bound. Returns NULL if no binding exists.

bindingOfPointSource String Returns the path of the context element to which the pointSource property is bound.Returns NULL if no binding exists.

bindingOfTooltip String Returns the path of the content element to which the tooltip property is bound. Returns NULL if no binding exists.

bindLabel (String path) Binds the label property to the context node specified by a path.

bindLeadSelectionCustomizingID (String path) Binds the leadSelectionCustomizingIDproperty to the context node specified by a path.

bindPointSource (String path) Binds the pointSource property to the context node specified by a path.


destroyPoint Removes and deletes the point element for this Series element.

getCustomizingID String Returns the value of the customizingID property.

getDataBeginIndex int Returns the value of the dataBeginIndex property.

getDataLength int Returns the value of the dataLength property.

getEventID String Returns the value of the eventIDproperty.

getLabel String Returns the value of the label property.

getLeadSelectionCustomizingID String Returns the value of the




leadSelectionCustomizingIDproperty.

getPoint IWDPoint Returns the point element for this Series element.

getShowSelectedOnly boolean Returns the value of the showSelectedOnly property.

getTooltip String Returns the value of the tooltipproperty.

setCustomizingID (String value) Sets the value of the customizingID property.

setDataBeginIndex (int value) Sets the value of the dataBeginIndex property.

setDataLength (int value) Sets the value of the dataL engthproperty.


setLabel (String value) Sets the value of the labe l property.

setLeadSelectionCustomizingID (String value) Sets the value of the leadSelectionCustomizingIDproperty.

setPoint (IWDPoint point) Sets the point element for this Series element.

setShowSelectedOnly (Boolean showSelectedOnly)

Sets the value of the showSelectedOnly property.

setTooltip (String value) Sets the value of the tooltip property.

Additional methods are available using inheritance: IWDAbstractSeries [External], IWDViewElement [External].

4.1.7.3 Web Dynpro Point API - IWDPoint

Overview The Point object defines the structure of the points of a more complex data series. The data binding and the subobject structure of a Point object indicates the number of values and their value types of a data point in a data series. A data series represented by the Series [Page 58] object can contain exactly one Point object. A Point object can be filled with one or more value objects, either the NumericValu []e class or the TimeValue [Page 69] class.


Describes how the chart is displayed on the screen. An ID is assigned to this property,




and the ID stores information about the representation of the data series under the Customizing XML file of the BusinessGraphics UI element.


• valueSource This property is used to specify the data source. You can use it to specify the path to the context node that provides the data for this object.




Required

customizingID IWDPoint String bindable No

eventID IWDPoint String bindable No

valueSource IWDPoint Object bindable_mandatory No

label IWDPoint String (TranslatableText) bindable No

tooltip IWDPoint String (TranslatableText) bindable No

Methods in the Web Dynpro IWDPoint API Method Name Parameter Return Value Short Descriptio n

addValue (IWDAbstractValue value)

Adds a value element at the end of the value elements list.

addValue (IWDAbstractValue value, int index)

Adds a value element at the specified index position of the value elements list.


bindCustomizingID (String path) Binds the customizingID property to the context node specified by a path.

bindingOfCustomizingID String Returns the path of the context element to which the




customizingID property is bound. Returns NULL if no binding exists.


bindingOfLabel String Returns the path of the context element to which the label property is bound. Returns NULL if no binding exists.


bindingOfValueSource String Returns the path of the context element to which the valueSource property is bound. Returns NULL if no binding exists.

bindLabel (String path) Binds the label property to the context node specified by a path.


bindValueSource (String path) Binds the valueSource property to the context node specified by a path.

destroyAllValues Removes all value elements. These are destroyed and no longer exist, so that the associated IDs can be used for




new elements.




getSeries IWDSeries Returns the Series element in which this Point element is contained.


getValues IWDAbstractValue[] Returns an array of the value elements.

hasValues boolean Checks whether or not value elements exist in this point element.

iterateValues Iterator Returns an iterator about all value elements in this point element.

numberOfValues int Returns the number of the value elements.

removeAllValues Removes all value elements. They remain and can be added to this point element.

removeValue int index IWDAbstractValue Removes the value element at the specified index position.

removeValue String id IWDAbstractValue Removes the value element with the specified ID.

setCustomizingID (String customizingID)

Sets the value of the customizingID property.

setEventID (String eventID) Sets the value of the eventID




property.

setLabel (String label) Sets the value of the label property.

setTooltip (String tooltip) Sets the value of the tooltip property.


4.1.7.4 Web Dynpro SimpleSeries API - IWDSimpleSeri es

Overview The SimpleSeries object is used to specify a simple data series. This object should be used when: ...

1. The number of data series is already determined and known at design time

2. The chart is category-based and each point has only one y value


An ID is assigned to this property, and the ID stores information about the representation of the data series under the Customizing XML file of the BusinessGraphics UI element.




• value This property specifies the path to the context attribute that provides the data for this object.


Required

customizingID IWDSimpleSeries String No not_bindable No

eventID IWDSimpleSeries String not_bindable No

label IWDSimpleSeries String No not_bindable No




(TranslatableText)

tooltip IWDSimpleSeries String (TranslatableText)

No not_bindable No

value IWDSimpleSeries Double 0.0 bindable_mandatory No

Methods in the Web Dynpro IWDSimpleSeries API Method Name Parameter Return Value Short Descriptio n

bindingOfValue String Returns the path of the context element to which the value property is bound. Returns NULL if no binding exists.

bindValue (String path) Binds the value property to the context node specified by a path.





getValue String Returns the value of the value property.

setCustomizingID (String customizingID)

Sets the value of the customizingID property.


setLabel (String label) Sets the value of the label property.


setValue (String value) Sets the value of the value property.

Additional methods are available using inheritance: IWDAbstractSeries [External], IWDViewElement [External].




4.1.7.5 Web Dynpro NumericValue API - IWDNumericVal ue

Overview The NumericValue class is availabe for using numeric values of the data type double . This class can be used for specifying the value of a point - for example, the x value for scatter charts or the y value for category-based business graphics.

Property Descriptions • type

This property specifies the value type. The type property can be filled with the following values and is represented by the enumeration type WDValueTypeEnumeration .

Enumeration Value Short Description

chart Describes the value for a small chart within a chart in a portfolio chart (see graphic below).

size Describes the size of a point in a portfolio chart.

trendX Describes the y component in the trend arrow of a portfolio chart.

trendY Describes the y component in the trend arrow of a portfolio chart.

x Describes the x value in a business graphic – for example, in a scatter chart.

y Describes the y value in a business graphic – for example, in a category-based chart.

• value This property specifies the numeric value of a point. It must be bound to a context attribute within a context structure that provides the data for the values at runtime. The initial value of this property is 0.0.

Overview of Inherited and Additional Properties Name Interface Type Initia

l Value


type IWDNumericValue

ValueTypeEnumeration

bindable No

value

IWDNumericValue

0.0 bindable_mandatory

No

Methods in the Web Dynpro IWDNumericValue API Method Name Parameter Return Value Short

Description

bindingOfType String Returns the path of the context element to which the




type property is bound. Returns NULL if no binding exists.


bindType (String path) Binds the type property to the context node specified by a path.


getType WDValueTypeEnumeration Returns the value of the type property.


setType (WDValueTypeEnumeration value)

Sets the value of the type property.


Additional methods are available using inheritance: IWDAbstractValue [External]; IWDViewElement [External].




Example Portfolio chart for the representation of the chart value of the enumeration type WDValueTypeEnumeration:

4.1.7.6 Web Dynpro TimeValue API - IWDTimeValue

Overview The TimeValue class is available for the use of time values of the data type long .

Property Descriptions • value

This property specifies a time value for a point in a chart. It must be bound to a context attribute within a context structure that provides the data for the values at runtime. . The time values must have the format YYYYMMDD, where Y is the year, M is the month, D is the day – for example, 20040205. In addition, you can use a semicolon as a separator to specify hours, minutes, seconds, and milliseconds. The following formats are valid:

o YYYYMMDD

o YYYYMMDD;HHMMSS

o YYYYMMDD;HHMMSSZZZ (H=hours, M=minutes, S=seconds, Z=milliseconds).

In general, this format refers to all graphics with time lines, such as TimeScale graphic.


Required

value IWDTimeValue String bindable_mandatory No




Methods in the Web Dynpro IWDTimeValue API Method Name Parameter Return Value Short Descriptio n



getValue long Returns the value of the value property.

setValue (long) Sets the value of the value property.

Additional methods are available using inheritance: IWDAbstractValue [External], IWDViewElement [External].

4.1.7.74.1.7.74.1.7.74.1.7.7 Data Binding of a BusinessGraphics UI Element

Overview The BusinessGraphics UI element can be used for displaying data in a chart. A business graphic can contain categories, which represent a discrete value range describing - for example - the months or quarters of a year. The categories of a business graphic are displayed on the x-axis in a vertical bar chart. In a pie chart, however, the categories represent the individual pie chart sections and the size of these sections represent the data series. The chart types scatter, portfolio, the charts for the milestone trend analysis, and its subtypes like TimeScatter belong to the non category-based charts. A BusinessGraphics UI element can contain only one category object. You can bind the description property of the category object to a context attribute. If the description property of the category object is bound to a context attribute, the context provides the description of the individual categories at runtime. The wdDolnit method of the controller implementation can fill the context with data at runtime.

In addition, each BusinessGraphics UI element contains at least one data series that can be either of the SimpleSeries type for simple charts, such as vertical bar charts and pie charts, or of the Series type. You should use data series of the Series type for complex chart types like scatter [Page 73], Gantt [Page 75], or portfolio that require the definition of an x value. The relationships of the BusinessGraphics UI element to the associated classes and its subclasses are described in the Metamodel of the UI element [External].

The data binding type of a BusinessGraphics UI element depends on the chart type you want to use. To display a particular chart type, you require a corresponding context structure. The structure of the BusinessGraphics UI element must be represented in the context structure.




Data Binding of Individual BusinessGraphics UI Elem ents

BusinessGraphics UI Element

The seriesSource property of the BusinessGraphics UI element is bound to a context node, under which all data for the data series resides.

For more information about the use of a business graphic, see Using Business Graphics [External]. For a description of the individual steps and procedures, see Inserting a BusinessGraphics UI Element [External].

Category Subelement

The subelement is only used for the category-based charts. You can bind the description property of the category object to a context attribute that can be used for specifying category names. The description property is usually bound to a sibling value attribute of the value property of the SimpleSeries object, because the number of data series values should be identical to the number of categories. Therefore, each element of the context node specifies a category.

The binding of the tooltip property is optional.

• If you bind the tooltip property to a context attribute, each category contains a different tooltip.

• If you assign a value to the tooltip property instead of binding it to a context attribute, all categories contain the same tooltip.

SimpleSeries Subelement

• Each SimpleSeries subelement of a BusinessGraphics UI element represents a data series. The SimpleSeries subelement is used for a simple, category-based chart in which each point contains only a value of the type y. The value property is bound to a context attribute that provides the data series values. The context node superordinate to the context attribute provides all node elements at runtime. The number of node elements equals the number of data points of a simple data series. Since only the context node with the lead selection provides data, it does not matter if the context node is defined as a singleton node or a non-singleton node.

Series Subelement

Each Series subelement of a BusinessGraphics UI element represents a multiple data series, and multiple Series subelements can be combined in a chart. The Series subelement is used for more complex data bindings. The seriesSource property of the BusinessGraphics UI element is bound to a context node superordinate to all context attributes that provide all relevant data for the data series.

This context node, which is bound to the seriesSource UI element property, provides all node elements at runtime. The number of these node elements at runtime equals the number of data series for the Series subelement.




The pointSource property must be bound to a context node that is the child of the context node to which the seriesSource UI element property is bound. The number of elements that this node contains at runtime determines the number of data series points to be displayed. If all bindable properties of the Series subelement are to be bound, they must be bound to context attributes that are children of this parent node. You can specify the context attributes that should apply to the whole data series. If the label property, for example, is bound to a context attribute, all elements of the assigned data series have the same value for the label property. However, the value of the label property is different for additional data series because they are bound to different context attributes. Alternatively, you do not need to bind these properties of the Series subelement. In this case, all data series have the same value for these properties.

The values of the data series are specified using the subelements Point and Value, NumericValue, or TimeValue. This allows the display of category-based and non-category-based graphics.

Point Subelement

The pointSource property of the Series subelement must be bound to a context node that is the child of the context node to which the seriesSource property of the BusinessGraphics UI element is bound. All other bindable properties – such as label and tooltip – must be bound to the context attributes that are children of the context node to which the valueSource property of the Point subelement is bound. You can specify the context attributes that apply to the points. If the label property, for example, is bound to a context attribute, all points of the assigned data series have different values for the label property. However, the bindable properties of the Point subelement do not have to be bound. In this case, all data series have the same value for these properties.

If all points have the same number of values and the number of values is known at runtime, you do not need a separate data source fort he valueSource UI element property. The valueSource UI element property is then bound to the same context node as the pointSource UI element property of the Series subelement. However, if different points in a data series contain different numbers of values (as is often the case for portfolio charts), you must specify a separate data sources for the valueSource UI element property. The valueSource UI element property must be bound to a child of the context node that is bound to the pointSource UI element property of the Series subelement.

Value Subelement

The Value subelement that is represented by the subelements NumericValue and TimeValue specifies the actual values of a point.

In general, the value property of the NumericValue subelement or TimeValue subelement must be bound to a context attribute of the context node to which the valueSource property of the Point subelement is bound.

To make data binding as flexible as possible, you have several options for displaying the data: ...

1. The valueSource property of the Point subelement is bound to the same context node as the pointSource property of the Series subelement. If the type property of the NumericValue subelement is not bound, but set permanently to a specific type, each point has a value with a fixed type.

2. The valueSource property of the Point subelement is bound to the same context node as the pointSource property of the Series subelement. If the type property of




the NumericValue subelement is bound to a sibling attribute of the value property, each point has a value whose type can be different for each point.

3. The valueSource property of the Point subelement is bound to a context node that is the child of the node to which the pointSource property of the Series subelement is bound. If the type property of the NumericValue subelement is bound to a sibling attribute of the value property, each point has any number of values of different types.

4. The valueSource property of the Point subelement is bound to the same context node as the pointSource property of the Series subelement. The value property of the TimeValue subelement must be bound to a context attribute subordinate to the context node to which the valueSource property of the Point subelement is bound.

5. Any combination of points 1 to 4 is possible; multiple and different points exist.

Example For a detailed procedure on creating presentation charts, see:

Using Business Graphics [External]

Code Example of a Complex Business Graphic Presentation [Page 73]

Code Example of a Gantt Chart [Page 75]

For more information, see Web Dynpro BusinessGraphics API [Page 47].

4.1.7.8 Code Example of a Complex Business Graphic Presentation

The example below illustrates the following for a complex scatter chart, a non-category-based chart type:

• The structure of the Business Graphic UI element with its subelements

• The corresponding context structure

• The source code of the controller implementation that fills the context with data. This code can be defined either in the wdDolnit method or in the supply function of the controller implementation

Displaying a Scatter Chart

The non-category-based chart types can contain more complex data series that are specified using the series object. To display points in a scatter chart, you need the definition of the x and y values. ...

1. Structure of the BusinessGraphics UI element for a scatter chart in the “TestScatterView” view

(see screenshot of the SAP NetWeaver Developer Studio below):

BusinessGraphics Series Point NumericValue

Associated Class Subclass NumericValueSubclass




2. Structure of the corresponing context, which provides the data and must support the creation of the BusinessGraphics UI element.

(see screenshot of the SAP NetWeaver Developer Studio below): Re item 1: Screenshot of the UI element structure Re. item 2: Screenshot of the context structure from the example

XValue has type x YValue has type y

Node B represents a non-singleton node The context attributes xValue and yValue have type String.

3. Data Binding

The individual associated objects of the BusinessGraphics UI element and their subobjects are bound to the corresponding context nodes and context attributes.

Object Object ID Data Binding Path Within the Context Structure

BusinessGraphics BG

series-Source property → value node A

TestScatterView.A

Series Series

pointSource property → value node B

TestScatterView.A.B

Point Point

valueSource property → value node B

TestScatterView.A.B

Value XValue

value property → value attribute xValue

TestScatterView.A.B.xValue

Value YValue

value property → value attribute yValue

TestScatterView.A.B.yValue

4. Source code in the wdDolnit method of the controller implementation, which fills the context with data at runtime. /** Hook method called to initialize controller. */

public void wdDoInit() { //@@begin wdDoInit() IPrivateTestScatterView.IANode aNode = wdContext.nodeA(); // loop over series for (int aIndex = 0; aIndex < 2; ++aIndex) { IPrivateTestScatterView.IAElement aElement =

aNode.createAElement(); aNode.addElement(aElement); // set series attributes (...) IPrivateTestScatterView.IBNode bNode = aElement.nodeB(); // loop over points for (int bIndex = 0; bIndex < 4; ++bIndex) { IPrivateTestScatterView.IBElement bElement =

bNode.createBElement(); bNode.addElement(bElement); bElement.setXValue(String.valueOf(aIndex*10 + bIndex)); bElement.setYValue(String.valueOf(100 + aIndex*10 +

bIndex)); } } //@@end }

5. Display of the scatter chart in the browser:




4.1.7.9 Code Example for Displaying a Gantt Chart

Use A Gantt chart is a complex chart type that shows one or more actions or activities over a period of time.

The example below shows the following for a Gantt chart, a non-category-based chart type:

• The structure of the Business Graphic UI element with its sub-elements


• The source code of the controller implementation that fills the context with data. This code can be defined either in the wdDolnit method or in the supply function of the controller implementation

The category-based chart types can contain more complex data series, which are specified using the series and point objects. To display points in a Gantt chart, you need the definition of the start and end values.

Structure of the BusinessGraphics UI element for a Gantt chart in the “GanttTestView” view (see screenshot of the SAP NetWeaver Developer Studio below):

BG Series Point TimeValue

Associated Class Subclass TimeValueSubclass

CategoryAssociated Class

Procedure

Creating the Layout of View StartView

6. Delete the UI element DefaultTextView that was automatically generated

with the view.

7. Add BusinessGraphics UI element BG.

8. Add category element Category .

Screenshot of view structure:




9. Add series element Series .

10. Add TimeValue element StartValue .

11. Add TimeValue element EndValue .

...

Creating the Context Structure

1. Create context node Category from collection type List (singleton node)

2. Create context attribute description of type String

3. Create context node Series from collection type List (singleton node)

4. Create context node Point from collection type List (non-singleton node)

5. Create context attribute cuId of type String

6. Create context attribute endValue of type String

7. Create context attribute label of type String

8. Create context attribute startValue of type String

Defining Data Binding of the User Interface Element Properties

In general: The seriesSource property of the BusinessGraphics UI element is bound to a context node superordinate to all context attributes that provide all relevant data for the data series. The pointSource property of the Series element must be bound to a context node that is the child of the context node to which the seriesSource property of the BusinessGraphics UI element is bound. All other bindable point element properties – such as label and tooltip – must be bound to the context attributes that are children of the context node to which the valueSource property of the Point element is bound. The valueSource property of the Point element is bound to the same context node as the pointSource property of the Series element. As a result, each point has the same number of values. The value property of the TimeValue element must be bound to a context attribute subordinate to the context node to which the valueSource property of the Point element is bound.




The seriesSource property of UI element BG is bound to context node

Series .

The description property of the Category element is bound to context attribute

Category.description .

The pointSource property of the Series element is bound to context

node Series.Point .

The customzingID property of the Point element is bound to context

attribute Series.Point.cuId .

The label property of the Point element is bound to context attribute

Series.Point.label .

The valueSource property of the Point element is bound to context node

Series.Point .

The value property of the StartValue element is bound to context attribute

Series.Point.cuId .




The value property of the EndValue element is bound to context attribute

Series.Point.EndValue .

Implementing a Controller

The source text below illustrates how the context is filled with data for the above example at runtime. The required data is supplied in four string arrays, catLabels , pointCustomizing , pointLabels , and timeValues , and written to the context in two loops, seriesIndex and pointIndex .

The first loop writes the category descriptions to the context and sets the description for each category node element. You can group the category descriptions under a superordinate description. To do so, you have to start the descriptions of the subcategories with two backslashes, as illustrated in string array catLabels .

The loops of the series index and point index create the points for a series. Each point is assigned a time segment consisting of a start point and an end point. Each point is also assigned point Customizing and a point label. This is achieved by writing the example data to the context with the loop passes. The time values must have the format YYYYMMDD, where Y is the year, M is the month, D is the day – for example, 20040205. In addition, you can use a semicolon as a separator to specify hours, minutes, seconds, and milliseconds.

The following formats are valid:

• YYYYMMDD

• YYYYMMDD;HHMMSS

• YYYYMMDD;HHMMSSZZZ (H=hours, M=minutes, S=seconds, Z=milliseconds).

In general, this format refers to all graphics with time lines, such as TimeScale graphic.

To give the presentation graphics the appearance shown in the screenshot under Use, you have to define Customizing for the individual points. To do so, call the Chart Designer from the context menu and define the point Customizing for the values listed in string array pointCustomizing in the overview of graphical elements.

You also have to define the legend of the Gantt chart in the Chart Designer, using the Caption property under node Advanced .




//@@begin javadoc:wdDoInit() /** Hook method called to initialize controller. */ //@@end public void wdDoInit() { //@@begin wdDoInit() String[] catLabels = { "Team 1", "\\1Tomoko Akino", "\\1Hans Bosch", "\\1Marvin Smith",

"Team 2", "\\1Jose Vega", "\\1Bao Yin", "Out of office" }; String[][] pointCustomizing = { { "approved", "cancelled", "approvedPartTime" }, { "approved" }, { "approved" }, { "sent", "approvedPartTime", "notsentPartTime", "notsent"}, { "approved", "zSeveralEntries", "zSeveralEntries", "zSeveralEntries", "zSeveralEntries", "zSeveralEntries", "zSeveralEntries" }, { "outOfOffice", "outOfOffice", "outOfOffice", "outOfOffice", "outOfOffice", "outOfOffice", "outOfOffice", "outOfOffice", "outOfOffice", "outOfOffice", "outOfOffice", "outOfOffice", "outOfOffice", "outOfOffice", "outOfOffice" } }; String[][] pointLabels = { { " ", " ", " " }, { " " }, { " " }, { " ", " ", " ", " "}, { " ", " ", " ", " ", " ", " ", " " }, { "1", "2", "2", "2", "4", "3", "3", "3", "1", "1", "2", "1", "2", "1", "1" } }; String[][][] timeValues = { { { "20020528", "20020606" }, { "20020606", "20020608" }, { "20020610", "20020611" } }, { { "20020531", "20020606" } }, { { "20020607", "20020613" } }, { { "20020527", "20020601" }, { "20020606", "20020607" }, { "20020612", "20020613" }, { "20020617", "20020619"} }, { { "20020531", "20020606" }, { "20020531", "20020601" }, { "20020601", "20020602" }, { "20020602", "20020603" }, { "20020603", "20020604" }, { "20020604", "20020605" }, { "20020605", "20020606" } }, { { "20020527", "20020528" }, { "20020528", "20020529" }, { "20020529", "20020530" }, { "20020530", "20020531" }, { "20020531", "20020601" }, { "20020603", "20020604" }, { "20020604", "20020605" }, { "20020605", "20020606" }, { "20020606", "20020607" }, { "20020607", "20020608" }, { "20020610", "20020611" }, { "20020611", "20020612" }, { "20020612", "20020613" }, { "20020617", "20020618" }, { "20020618", "20020619" }} }; IPrivateGanttTestView.ICategoryNode catNode = wdContext.nodeCategory(); for (int catIndex = 0; catIndex < catLabels.length; ++catIndex) { IPrivateGanttTestView.ICategoryElement catElement = catNode.createCategoryElement(); catNode.addElement(catElement); catElement.setDescription(catLabels[catIndex]); } // loop over series IPrivateGanttTestView.ISeriesNode seriesNode = wdContext.nodeSeries(); for (int seriesIndex = 0; seriesIndex < timeValues.length; ++seriesIndex) { IPrivateGanttTestView.ISeriesElement seriesElement = seriesNode.createSeriesElement(); seriesNode.addElement(seriesElement); // set series attributes (...) IPrivateGanttTestView.IPointNode pointNode = seriesElement.nodePoint(); // loop over points for (int pointIndex = 0; pointIndex < timeValues[seriesIndex].length;

++pointIndex) { IPrivateGanttTestView.IPointElement pointElement = pointNode.createPointElement(); pointNode.addElement(pointElement); pointElement.setStartValue(timeValues[seriesIndex][pointIndex][0]); pointElement.setEndValue(timeValues[seriesIndex][pointIndex][1]); pointElement.setCuId(pointCustomizing[seriesIndex][pointIndex]); pointElement.setLabel(pointLabels[seriesIndex][pointIndex]); } } //@@end }

Result You have created a Gantt chart. Before you can call the Web Dynpro application for testing, however, you must build the Web Dynpro project and install the Web Dynpro application on the SAP J2EE Engine.

You start the Web Dynpro applications by choosing Deploy new archive and run in the context menu of the corresponding Web Dynpro application. The Web Dynpro application is called in the browser from a Web address and the Gantt chart appears.




4.1.8 Button - ButtonRow The UI element Button simulates the pushbutton on the screen. The user can execute statements and actions by clicking the pushbutton.

The UI element ButtonRow can be used to arrange buttons in a row.

You can accurately arrange multiple buttons using ButtonRow. Buttons and ToggleButtons can be inserted. The ButtonRow itself does not contain additional properties, but has the corresponding methods to create and maintain the inserted buttons.

Definition IWDButton inherits from IWDAbstractButton , which is the abstract base class of pushbuttons. It inherits the ability to display an icon from the base class IWDAbstractCaption and adds the ability to display a text on the pushbutton and trigger an action.


Describes the style of the Button UI element - for example, the button size or the highlighting of the button label. The design property can be filled with the following values and is represented by the enumeration type ButtonDesign .

Values Visual Display Short Description

emphasized

Displays the UI element with highlighted left edge.

next Displays the button with a triangle pointing to the right.

previous Displays the button with a triangle pointing to the left.




standard Displays the UI element with default background and text color.

• imageAlt This property is deprecated and can no longer be used.

• imageFirst Defines the position of the icon in relation to the corresponding text. If the value of this property is true , the icon is displayed to the left of the text.

• imageSource Specifies the Web address (URL) of the icon to be displayed. You can assign an absolute Web address – http:// … to this property. If you store the icons in the directory mimes/Components/<Komponentenklasse> of the Web Dynpro project in the Navigator using the menu item Import, you must only enter the icon name - for example, icon.gif. The URL Generation Service automatically determines the URL of the icon (see also URL Generation Service). You can also store the icons in the directory mimes/Applications/<application class> . In this case, you must manually create the URL using the URL Generation Service. If you use the SAP icons and want to refer to them, you use the alias ~sapicons . If you assign the alias ~sapicons/<name>.gif to the imageSource property, you refer to an icon called <name>.gif of the SAP icons. For a description and a listing of all possible SAP icons, see the SAP Design Guild under http://www.sapdesignguild.org/. Select the following path: Sitemap → Resources → Visual Design & Icons → SAP R/3 Icons → R/3 Icon Lists. The filename of the icon consists of the bitmap name entered in the table and the prefix “s_”. If the bitmap name in the table is F_CUTO, you must enter the value

~sapicons/s_f_cuto.gif to reference to the SAP icon .

• size This property is deprecated and can no longer be used.

• text Describes the label text of the Button UI element.

• textDirection Specifies the text direction and allows you to use subordinated UI elements for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type textDirection .





• width Specifies the width of the Button UI element and can be specified in CSS units like em, ex, pixels, or percentage.



Required




design IWDButton WDButtonDesign standard bindable No


imageFirst IWDAbstractCaption boolean true bindable No

imageSource IWDAbstractCaption String bindable No

text IWDAbstractButton String bindable No

textDirection IWDAbstractCaption WDTextDirection inherit bindable No



width IWDButton String bindable No

Event This event on Action - inherited from IWDAbstractButton - is triggered when the user clicks the button.

4.1.9 Caption API

Definition

The Caption class, which implements the IWDCaption interface, is a concrete subclass of the IWDAbstractCaption class. The UI element can be used by several UI elements – such as Group, Tab, Table, TableColumn, and Tray – to provide a header or an icon for them.

The enabled property which is inherited by the superclas UIElement , does not affect the display.

Description of UI Element Properties • imageAlt



• imageSource Specifies the Web address (URL) of the icon to be displayed. You can assign an absolute Web address – http:// … to this property. If you store the icons in the directory mimes/Components/<component class> of the Web Dynpro project in the Navigator using the menu item Import, you must only enter the icon name - for example, icon.gif. The URL Generation Service automatically determines the URL of the icon (see also URL Generation Service [External]). You can also store the icons in the directory mimes/Applications/<application class>. In this cas e, you must manually create the URL using the URL Generation Se rvice . If you use the SAP icons and want to refer to them, you use the alias ~sapicons . If you assign the alias ~sapicons/<name>.gif to the imageSource property, you




refer to an icon called <name>.gif of the SAP icons. For a description and a listing of all possible SAP icons, see the SAP Design Guild under http://www.sapdesignguild.org/. Select the following path: Sitemap → Resources → Visual Design & Icons → SAP R/3 Icons → R/3 Icon Lists. The filename of the icon consists of the bitmap name entered in the table and the prefix “s_”. If the bitmap name in the table is F_CUTO, you must enter the value


• readOnly Specifies whether or not the user can check the checkbox.

• state Describes the error status of the UI element. The data type of this property corresponds to the enumeration type WDState . You can use the following values in the application:

normal Describes the default state of the UI element.

required Specifies whether the entered value is required.

• text Specifies the text.

• textDirection Specifies the text direction and allows you to use subordinated UI elements for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type WDTextDirection .






Required







4.1.10 CheckBox API The checkbox enables the user to select a Boolean value (true/false). The UI element consists of a graphic with text. The checkmark in the box indicates that the option is selected and the value is set to true .




Definition The Web Dynpro class Checkbox which implements the IWDCheckBox interface is the base class of checkboxes.

Description of UI Element Properties • checked

Specifies whether or not a checkbox is selected. The Boolean value true indicates that the option is selected. A checkmark appears in the graphic that is displayed on the screen.

Short Description Visual Display

The checkbox UI element that is displayed with the value true.

The checkbox UI element that is displayed with the value false.





• text Specifies the text that is associated with the checkbox graphic and displayed to the right of the box.

• textDirection Specifies the text direction and allows you to use a MenuActionItem element for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type WDTextDirection .




• The default value for this property is inherit .



Required

checked IWDAbstractToggle

boolean false bindable_mandatory

No


readOnly IWDCheckBox boolean false bindable No




state IWDCheckBox WDState normal

bindable No

text IWDAbstractToggle

String (TranslatableText)

bindable No

textDirection

IWDAbstractToggle

WDTextDirection

inherit bindable No


bindable No


Events • onToggle (boolean checked)

The onToggle event of the type IWDAbstractToggle is executed by clicking the checkbox. The transfer parameter is the new status. See Event Parameter and Parameter Mapping [Page 316].

4.1.10.1 CheckBoxGroup API

Definition The checkbox group enables the user to select one element from a set of options checking it. The CheckBoxGroup UI element lists the checkboxes as a table. As opposed to the RadioButtonGroup, you can check multiple fields.

Visual Display



• colCount Specifies the number of columns in which the CheckBox elements are grouped.

• readOnly Specifies whether or not the user can check the checkbox in the checkbox group.

• state Describes the status of the UI element. The data type of this property corresponds to the enumeration type WDErrorState . You can use the following values in the application:






• textDirection Specifies the text direction and allows you to use a checkbox group for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type WDTextDirection .





• texts Specifies the path of the context attribute within a context node whose node elements provide the texts of the individual checkboxes at runtime.

• width Specifies the minimum width of the CheckBoxGroup UI element. You can specify the width in CSS units like em, ex, pixel, or percentage.



Required

accessibilityDescription IWDCheckBoxGroup String (TranslatableText)

bindable No


colCount IWDCheckBoxGroup int 1 bindable No

readOnly IWDCheckBoxGroup boolean false bindable No

state IWDCheckBoxGroup WDState normal bindable No

textDirection IWDCheckBoxGroup WDTextDirection inherit bindable No

texts IWDCheckBoxGroup String (TranslatableText)

bindable_mandatory Yes


bindable No


width IWDCheckBoxGroup String bindable No

Events • onToggle

Describes the action that is executed when the user checks a checkbox in the CheckBox group.

Event parameters Type Description

checked boolean The new value of the checkbox.




index int Index (0..n) of the selected checkbox.


Data Binding A checkbox group is a multiple selection displayed as a group of checkboxes on the screen.

The view context must provide the node X that can contain 0 to n values (X.cardinality=0..n). The context node must contain an attribute y that provides the texts for the checkbox fields. The data type of the context attribute y can be any simple data type – for example, String, int, and so on. The number of checkboxes equals the number of node elements. The selection of the checkboxes is determined by the multiple selection of the node. The texts property of the CheckBoxGroup UI element is bound to the attribute y by assigning the context path of the context y to the texts property.

For further information about the context structures, refer to Context Description [External]; for information about the data binding model, refer to Data Binding Within Web Dynpro [Page 283].

4.1.11 DateNavigator

Definition The DateNavigator UI element enables users to display and enter dates. Its features include the ability to navigate in a calendar and choose a day, month, year, or range of dates. Primarily, this element should be used to help users to input dates in an appropriate format.

You can insert a DateNavigatorMarking element in the DateNavigator. In combination with an assigned legend, you can use this element to highlight a text in color and add a corresponding description in the legend. For example, events in the calendar can be highlighted in a different color and each event can be described with agenda, time, and location.

Values of the properties: monthPerColumn = 1, monthsPerRow = 4




Structure

UIElement(f rom Core)

DateSelectionMode

single : String = 0range : String = 1none : String = 2

<<enum>>

ViewElement(f rom Core)

DateM arkingCategory

one : String = 0two : String = 1three : String = 2four : String = 3

<<enum>>DateNavigatorMarking

category : DateMarkingCategory = onedate : Datetool tip : T ranslatableT extdataSource : ObjectdaySemantics : T ableCellDesign = standard

DateNavigatorLegend

category : DateMarkingCategory = onetext : T ranslatableT extdataSource : ObjecttextDi rection : TextDi rection = inherit

DateNavigator

accessibi l i tyDescription : T ranslatableT extfi rstDayOfWeek : DayOfWeek = autofi rstSelectedDate : DatelastSelectedDate : DatelegendId : StringmonthsPerColumn : Integer = 1monthsPerRow : Integer = 3selectionMode : DateSelectionMode = singlestartsWi th : DateonDaySelect : StringonDaySelect_day : DateonMonthSelect : StringonMonthSelect_month : IntegeronMonthSelect_year : IntegeronStartDateChanged : StringonStartDateChanged_startDate : DateonWeekSelect : StringonWeekSelect_week : IntegeronWeekSelect_year : Integer

0..1

1

+Marking 0..1

+DateNavigator 1

0..1

1

+Legend0..1

+DateNavigator1

DayOfWeek

auto : String = 0sunday : String = 1monday : String = 2tuesday : String = 3wednesday : String = 4thursday : String = 5friday : String = 6saturday : String = 7

<<enum>>

4.1.11.1 DateNavigator API

The Web Dynpro class DateNavigator which implements the IWDDateNavigator interface is the base class of a calendar UI element.


When accessibility is activated, the assigned text is added to the quick info. This description provides semantic details of the UI element and is only read by the screen reader if the user focuses the complete Ul element.

• firstDayOfWeek




The firstDayOfWeek property can be filled with the following values and is represented by the enumeration type DayOfWeek.

auto Specifies the first day of the week automatically - for example, according to the country-specific beginning of the week.

friday Friday with the ordinal number defined in java.util.Calendar .

monday Monday with the ordinal number defined in java.util.Calendar .

saturday Saturday with the ordinal number defined in java.util.Calendar .

sunday Sunday with the ordinal number defined in java.util.Calendar .

thursday Thursday with the ordinal number defined in java.util.Calendar .

tuesday Tuesday with the ordinal number defined in java.util.Calendar .

wednesday Wednesday with the ordinal number defined in java.util.Calendar .

• firstSelectedDate

Specifies the first date in the selected date range.

• lastSelectedDate

Specifies the last date in the selected date range.

• legendId

Specifies the ID of the assigned legend.

• monthsPerColumn

You use this property to specify the number of months in a column.

• monthsPerRow

You use this property to specify the number of months in a row.

• selectionMode

Specifies whether the user can choose a single date or a range of dates. The selectionMode property can be filled with the following values and is represented by the enumeration type DateSelectionMode.

none A date or date range cannot be selected.

range The user can choose a contiguous block of dates.

single The user can choose only one date.

• startsWith

Defines the start of the displayed date range.



Required

accessibilityDescription IWDDateNavigator String (TranslatableText)

bindable No


firstDayOfWeek IWDDateNavigator DayOfWeek auto bindable No

firstSelectedDate IWDDateNavigator java.sql.Date bindable No




lastSelectedDate IWDDateNavigator java.sql.Date bindable No

legendId IWDDateNavigator String bindable – no:

monthsPerColumn IWDDateNavigator int 1 bindable No

monthsPerRow IWDDateNavigator int 3 bindable No

selectionMode IWDDateNavigator DateSelectionMode single bindable No

startsWith IWDDateNavigator java.sql.Date bindable No


bindable No


Events • onDaySelect (java.sql.Date day)

Specifies the action executed when the user selects a day. The event parameter is the chosen day. The parameter day is of the type java.sql.Date and is the selected day.

• onMonthSelect (int month, int year)

Specifies the action executed when the user selects a month. Event parameters are the chosen months (in the range of 1 to 12) and the chosen year is of the type integer.

• onStartDateChanged (java.sql.Date startDate)

Specifies the action that is carried out when the user changes the startsWidth property. The event parameter startDate of the type java.sql.Date is the new start date.

• onWeekSelect (int week, int year)

Specifies the action that is executed when the user selects a week. The event parameters week and year are the selected week (in the range 1 to 53) and the selected year is of the type integer .

4.1.11.2 DateNavigatorMarking API

Definition This view element allows you to highlight entries of a specific category within the DateNavigator UI element [Page 88]. You can also define a tooltip for the highlighted entry. You should only use this view element in conjunction with a legend element, with which you can also explain each highlighting to the user.

Description of the View Element Properties • category

This property is deprecated, use daySemantics instead.

• dataSource

Specifies the path to the context node which stores the date, category, and tooltip of the highlighting.




• date

Specifies the path to the context attribute that stores the date of the highlighting.

• daySemantics

Specifies the background color of the cell. The cellDesign property can be filled with the following values and is represented by the enumeration type TableCellDesign .

badvalue_dark Dark background color that indicates a negative value.

badvalue_light Light background color that indicates a negative value.

badvalue_medium Medium background color that indicates a negative value.

criticalvalue_dark Dark background color that indicates a critical value.

criticalvalue_light Light background color that indicates a critical value.

criticalvalue_medium Medium background color that indicates a critical value.

goodvalue_dark Dark background color that indicates a good value.

goodvalue_light Light background color that indicates a good value.

goodvalue_medium Medium background color that indicates a good value.

group_level1 Background color for cells of group level 1



key_medium Medium background color for cells of key column

negative Background color that indicates a negative value.

positive Background color that indicates a positive value.

standard Standard background color, the same for the entire row

one Color of category one, depends on the respective design theme used.

two Color of category two, depends on the respective design theme used.

three Color of category three, depends on the respective design theme used.

four Color of category four, depends on the respective design theme used.

The default value for this property is standard .

• tooltip

Specifies the path to the context attribute which stores the tooltip of the highlighting. You should bind the property to a context attribute of the multiple context node, because otherwise each highlighting has the same tooltip.


Required

category IWDDateNavigatorMarking

DateMarkingCategory one bindable No




dataSource IWDDateNavigatorMarking

Object bindable_mandatory Yes

date IWDDateNavigatorMarking

java.sql.Date bindable_mandatory Yes

daySemantics

IWDDateNavigatorMarking

TableCellDesign standard bindable No

tooltip IWDDateNavigatorMarking

String (TranslatableText) bindable No

4.1.11.3 DateNavigatorLegend API

The DateNavigatorLegend is deprecated; instead, insert a legend element and use the legendId property of the DateNavigator element to assign it.

Definition The DateNavigatorLegend element (IWDDateNavigatorLegend) allows you to add a legend to the DateNavigator UI element [Page 88]. You can use this view element with the DateNavigatorMarking view element to highlight calendar entries and to associate them with the legend entries. A maximum of four legend entries can be used according to the categories described below. Legend entries are stored as elements of a context node. Each highlighting of a date is stored in a separate context node. If the value of the category attribute equals the value of the legend entry category, the category refers to the corresponding legend entry.

Description of the View Element Properties • category

Specifies the path to the context attribute which stores the category of the legend entry. When doing this, you must make sure that two legend entries cannot be assigned to the same category. The category property must be bound to a context attribute, to whose multiple superordinate context nodes the dataSource property is bound. The category property can take the following values and is represented by the list type WDDateMarkingCategory :

Four Color of category four. *)

One Color of category one. *)

Three Color of category three. *)

Two Color of category two. *)

*) The color for each highlighting depends on the respective design theme used – the documentation refers to the SAP Standard Design 2002.

• dataSource Specifies the path to the context node which stores the categories and texts of the legend entries. Each node element represents one entry in the legend. The legend entries are displayed in the order of the node elements.




• text Specifies the path to the context attribute which stores the texts of the legend entries. This property is used to describe a category.

• textDirection Specifies the text direction and allows you to use PatternSequenceStep elements for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type WDTextDirection .





Properties Overview Name Interface Type Initial Value Bindable Value Required

category IWDDateNavigatorLegend

WDDateMarkingCategory

One bindable_mandatory

Yes

dataSource IWDDateNavigatorLegend


Yes

text IWDDateNavigatorLegend


bindable Yes

textDirection IWDDateNavigatorLegend

WDTextDirection

inherit bindable No

4.1.12 DropDownByIndex API The Web Dynpro class DropDownByIndex , which implements the IWDDropDownByIndex interface, is the base class of the dropdown list boxes for which index binding is used.

Definition A DropDownByIndex UI element provides the user with a dropdown list box. You cannot select more than one entry from the selection list. The UI element consists of a text field, a button, and a selection list. Any list entry already selected is displayed in the text field. When selecting the button, a list with all possible values is displayed.

Visual Display:




When using a dropdown list box, always display this UI element alongside a label to ensure accessibility.

Description of UI Element Properties • labelFor

The DropDownByIndex element can also be used as a label for other UI elements. You can use the labelFor property to reference to a UI element.

• selectionChangeBehaviour The change of the lead selection can cause a data loss – for example, if the changed or new data was not written to the context due to syntax errors. You can avoid the data loss using the selectionChangeBehaviour property before changing the lead selection:

auto If the data was written to the context, the value auto specifies that the ItemListBox automatically changes the lead selection of its data source directly after an interaction by the user before the corresponding event is triggered.

manual Specifies that the ItemListBox does not change the lead selection of its data source after an interaction by the user but triggers the corresponding event. In this case, the event handler must change the lead selection to enable the ItemListBox to display the data in a main detail view, for example. This setting allows you to check the change of the lead selection.


Overview of Inherited and Additional Properties Name Interface Type Initial Value

enabled IWDUIElement boolean true

labelFor IWDAbstractDropDown String

readOnly IWDAbstractDropDown boolean false

selectionChangeBehaviour IWDAbstractDropDownByIndex WDLeadSelectionChangeBehaviour auto

state IWDAbstractDropDown WDState normal

textDirection IWDAbstractDropDown WDTextDirection inherit

texts IWDAbstractDropDownByIndex String


visible IWDUIElement WDVisibility visible

width IWDAbstracDropDown String

Events • onSelect

Describes the action that is executed when the user selects a different list entry from the dropdown box. The newly selected index (starting from zero) is passed as an event parameter.




Event Parameter Type Description

index int Index of the newly selected context element

Data Binding For further information, refer to Data Binding of a Dropdown List Box and Radio Button Group [Page 299] and Code Examples for Data Binding [Page 292].

4.1.12.1 Data Binding for DropDownByIndex Elements

The view context provides the content to be displayed in the dropdown list box and the selected index.

The view context must contain a context node X that can store any number of node elements (X.cardinality=0..n). Each node element represents an entry in the dropdown list box.

The context node X contains a context attribute y that provides the texts for the list entries. The data type of the context attribute y can be any simple data type – for example, String, int, and so on. If the data type of the context attribute y is not of the type String, this type is converted into a String representation by the Web Dynpro Framework. The selected value is specified by the lead selection of the node X.

The texts property of the DropDownByIndex UI element is bound to the attribute y by assigning the path of the context X.y to the texts property.

Example for Data Binding of the DropDownByIndex UI Element:

Procedure at design time: ...

1. Create a view with the name TestView.

2. Insert the DropDownByIndex UI element as a container child of the TestView view. (Step 1)

3. Create the context structure, as described in step 2. Create the context node X with the cardinality 0..n. Insert the value attribute y of the type String into this node. Then perform the data binding of the DropDownByIndex UI element in the Properties window of the View Designer. The texts property must be bound to the value attribute y with the context path description TestView.X.y (step 3). The context path TestView.X.y describes the attribute y in the context node X of the view context of the TestView view.

You can fill the context with test data using the following controller implementation. public void wdDoInit() { //@@begin wdDoInit() String[] letters = new String [] { "A" , "B" , "C" , "D" }; //Create context elements for the node "X" List nodeElements = new ArrayList(); for ( int i = 0; i <letters.length; ++i) { IPrivateTestView.IXElement xElement =




wdContext.createXElement(); xElement.setY(letters[i]); nodeElements.add(xElement); } //Bind node element list to the node wdContext.nodeX().bind(nodeElements); //Set node’s lead selection which determines the se lected item wdContext.nodeX().setLeadSelection(1); //@@end

}

Behavior at runtime:

At runtime, a context node consists of a number of node elements, which contain the values to be displayed – as illustrated in step 4 of the diagram below. The lead selection is set to the second value (zero-based index). Step 5 shows the dropdown list box with the possible values A, B, C, and D, as displayed in the browser.

2. Defining the context structure:Node X with cardinality 0..n

Attribute y of typeString

3. Data binding of UI element:The property texts isbound to path X.y

Design Time

4. Context nodeAt runtime, a node consists of the individual nodeElements that contain the values to be displayed.

Node Elements

Element0

y: “A“

Runtime

Element3

y: “D“

Lead selection is set to thesecond value

Knoten X

5. Representation of dropdown list box

1. Inserting the dropdown list box

Element1

y: “B“

Element2

y: “C“

4.1.13 DropDownByKey API

Definition A DropDownByKey UI element provides the user with a selection list from which he or she can select no more than one entry. The UI element consists of a text field, a button, and a selection list. Any list entry already selected is displayed in the text field. When you select the pushbutton, a list with all possible values is

Visual Display




displayed.

The dropdown list box UI elements do not differ from each other when displayed on the screen. However, the data binding model for the DropDownByKey UI element has a completely different concept. See Data Binding Within Web Dynpro [Page 283] and Data Binding of a Dropdown List Box and Radio Button Group [Page 299]).

When using a dropdown list box, always display this UI element alongside a Label UI element (that is, an element with a label) to ensure accessibility.

Description of UI Element Properties • labelFor

The DropDownByKey element can also be used as a label for other UI elements. You can use the labelFor property to reference to a UI element.

• selectedKey Use this property to determine the value from the value set, which is to be selected from the list of the dropdown listbox.


Overview of Inherited and Additional Properties Name Interface Type Initial Value Bindable


labelFor IWDAbstractDropDown String not_bindable

readOnly IWDAbstractDropDown boolean false bindable

selectedKey

IWDAbstractDropDownByKey String bindable_mandatory

size IWDDropDownByKey WDDropDownListBoxSize standard bindable

state IWDAbstractDropDown WDState normal bindable

textDirection

IWDAbstractDropDown WDTextDirection inherit bindable

tooltip IWDUIElement String (TranslatableText) bindable


width IWDAbstractDropDown String bindable

Events • onSelect

This property can assign the action to be executed when the user selects a list entry from the dropdown list box.




Event Parameter Type Description

key String Key of the selected entry.

Data Binding For further information, refer to Data Binding of a Dropdown List Box and Radio Button Group [Page 299]. For a code example, refer to Key Binding [Page 296].

4.1.13.1 Data Binding for DropDownByKey Element

Data Binding The context provides the content to be displayed within the UI element, the corresponding keys, and the selected key.

The context must provide the node X that can contain 0 to n elements. (X.cardinality=0..n). The node must contain the attribute y, whose data type can contain a value set (set of value/description pairs). The keys of the dropdown list box are the values of this value set. The texts displayed in the selection list are the respective descriptions. The selected key is provided by the current value of the attribute y.

The selectedKey property of the DropDownByKey UI element is bound to the attribute y by assigning the path of the context X.y to the selectedKey property. For further information, refer to Data Binding of a Dropdown List Box and Radio Button Group [Page 299] and to Key Binding [Page 296].

Example for Data Binding of the DropDownByKey UI El ement:

Procedure at design time: ...

1. Insert the DropDownByIndex UI element into the TestView (see 1).

2. Define a simple data type in the Java Dictionary.

3. Define the values and the respective descriptions (see table under 3) for this data type. Then create the context structure, as described in step 3.

4. Within any context structure, define a value attribute y of a simple data type that contains the corresponding value set.

5. Bind the property selectedKey to the value attribute y with path <path>.y.

Behavior at runtime:

Step 5 shows the dropdown list box with the possible values Small, Medium, and Large, as displayed in the browser as the result of the declarative design time definitions.




3. Defining the context structure:

Root node

Attribute y of a type with value set

4. Data binding of theUI element:The property selectedKeyis bound to the path<Pfad>.y

Design Time

Runtime

5. Representation of Dropdown list box

Context path

Value Description

S Small

M Medium

L Large

1. Inserting the dropdown list box

2. Defining a simple data type in the Java Dictionary

See Event Parameters and Parameter Mapping [External].

4.1.14 FileUpload and FileDownload: Data Transfer The elements FileUpload and FileDownload are used to transfer files between server and client.

FileUpload With FileUpload the user can use a Browse… button to select a file on the hard disk, which will be loaded into the context during the next round trip, that is, for example, if the user clicks another button. Any further administration and storage of the file on the server is controlled internally by the Web Dynpro Framework.

You can activate a virus scanner for the FileUpload element. SAP provides the virus scan profile webdynpro_FileUpload . Refer to Delivered Virus Scan Profiles [External]

FileDownload With the FileDownload element, the user can download a file. Depending on the selected setting of the behaviour property, the user can open the file or store it on the local hard disk.




The data source, that is the file to be downloaded is determined by the resource property. To be able to load a file into the context with the FileDownload element, you need the WDResourceFactory. Insert the following code into the wdDoInit method: IWDResource resource = WDResourceFactory.createRes ource( new byte [<number of bytes>], "<name of the file>" , WDWebResourceType.<type of the file>); wdContext.currentUiResourceElement().setResource(re source);

currentUiResourceElement depicts the context node under which you have created the value attribute resource of type Resource.

4.1.14.1 FileUpload API

Definition You can use the FileUpload UI element to upload files from the client to the server. The UI element appears with an input field, in which the directory path and the file name appear, and a button for searching for the file.

Description of UI Element Properties • data

This property is deprecated, use resource instead.

• fileName

This property is deprecated, the file name is determined by the resource property.

• resource

Specifies the data source and contains the data, the file name, and the MIME type. For more information on data binding of this property, see Data Binding of the Property resource for FileDownload and FileUpload [Page 105]

• textDirection

Specifies the text direction and allows you to use FileUpload UI elements for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type TextDirection.

inherit The text direction is inherited from the parent element and is thus the same as the text direction of the parent element.

ltr The text direction is from left to right.

rtl The text direction is from right to left.


• width

Determines the width of the FileUpload UI element that you can specify in CSS sizes, such as em, ex, pixels or percentage values.






data IWDFileUpload Object bindable_mandatory No


fileName IWDFileUpload String bindable No

resource IWDFileUpload Resource bindable_mandatory Yes

textDirection IWDFileUpload TextDirection inherit bindable No


bindable No


width IWDFileUpload String bindable No

4.1.14.2 FileDownload API

Definition Using the FileDownload element, the user can load a file from the server to the client to store it there or to open it in the appropriate program. The look of the FileDownload elements resembles a link, because the representation is determined by the type property, which provides the option of indicating whether the user has clicked the element before.

The data source, that is the file to be downloaded is determined by the resource property. The target property determines the ID of the target window in the browser.

Description of UI Element Properties • behaviour

determines the behavior after the user has clicked the FileDownload element. behaviour is of enumeration type FileDownloadBehaviour and can have the following values:

� allowSave

An Open/Save dialog box appears. The user can directly save the file locally or open it with the appropriate program.

� auto

The behavior is predefined and depends on the MIME type of the file to be downloaded. The list below describes the behavior for the individual file types; false means that the attachment is opened in the same window, whereas for true a new window is opened.

Constant File Extension

MIME Type acc. to W3C Attachment




APPLET "jar" "application/x-java" true

CSS "css" "text/css" false

DOC "doc" "application/vnd.ms-word"

"application/x-msword"

false

FLASH "swf" "application/x-shockwave-flash"

false

GIF_IMAGE "gif" "image/gif" false

HTML "html" "text/html" false

JAVA "java" "application/x-java" false

JAVA_SCRIPT "js" "text/js" false

JPG_IMAGE "jpg" "image/jpeg" false

PDF "pdf" "application/pdf" false

PNG "png" "image/x-png" false

PPT "ppt"

"application/vnd.ms-powerpoint" "application/x-mspowerpoint"

false

PS "ps" "application/postscript" false

RTF "rtf" "application/rtf"

false

SVG "svg" "image/svg+xml" false

TXT "txt" "text/plain" false

UNKNOWN "" "" true

VML "vml" "text/vml" false

WD_APPLICATION "" "" false

XLS "xls" "application/vnd.ms-excel"

"application/x-msexcel"

false

XML "xml" "text/xml" false

XML_CONFIGURATION "xml" "text/xml" true

� openInplace

The file is opened in the appropriate application program within the current window. Which program is opened, depends on the MIME type of the file.

• data

This property is deprecated, use resource instead.

• imageFirst

Defines the position of the icon in relation to the corresponding text. If the value of this property is true , the icon is displayed to the left of the text.

• imageHeight

Determines the height of the graphic next to the FileDownload link. You can specify the height in CSS units like em, ex, pixels, or percentage.




• imageSource

Specifies the Web address (URL) of the icon to be displayed. You can assign an absolute Web address – http:// … to this property. If you store the icons in the directory mimes/Components/<component class> of the Web Dynpro project in the Navigator using the menu item Import, you must only enter the icon name - for example, icon.gif. The URL Generation Service automatically determines the URL of the icon (see also URL Generation Service). You can also store the icons in the directory mimes/Applications/<application class> . In this case, you must manually create the URL using the URL Generation Service. If you use the SAP icons and want to refer to them, you use the alias ~sapicons . If you assign the alias ~sapicons/<name>.gif to the imageSource property, you refer to an icon called <name>.gif of the SAP icons. For a description and a listing of all possible SAP icons, see the SAP Design Guild under http://www.sapdesignguild.org/. Select the following path: Sitemap → Resources → Visual Design & Icons → SAP R/3 Icons → R/3 Icon Lists. The filename of the icon consists of the bitmap name entered in the table and the prefix “s_”. If the bitmap name in the table is F_CUTO, you must enter the value


• imageWidth

Determines the width of the graphic next to the FileDownload link. You can specify the width in CSS units like em, ex, pixel, or percentage.

• resource

Specifies the data source and contains data, the file name, and the MIME type. The resource property must be bound to a context attribute of type Resource.

• size Specifies the size of the FileDownload element. The size property can be filled with the following values and is represented by the enumeration type WDButtonSize.

small The UI element is displayed in a small font.

standard A standard font size is displayed.

• target

Specifies the browser window in which the page is to be opened. You can manually specify the name of the target window or use the following values:

� "" The page is opened in a new window without a name. This is the default value.

� _self is no longer supported. Use exit plugs instead and specify the URL there.

• text

Describes a label text.

• textDirection

Specifies the text direction and allows you to read the texts of subordinated UI elements in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type TextDirection.








• type

Describes the graphical representation of the FileDownload element. The type property can be filled with the following values and is represented by the enumeration type LinkType.

function

The UI element is displayed in the standard design and underlined.

navigation

The UI element is displayed with underline and in a font color that indicates that the link has already been visited.

reporting The UI element is displayed in the standard design without underline.

result The UI element is displayed without underline.

• wrapping

Indicates whether or not the text of the FileDownload element is wrapped. If the initial value is false , the text is not wrapped.



Required

behaviour IWDFileDownload

FileDownloadBehaviour

auto bindable No

data IWDFileDownload


No


imageFirst IWDAbstractCaption


imageHeight

IWDLink String bindable No

imageSource

IWDAbstractCaption

String bindable No

imageWidth

IWDLink String bindable No

resource IWDFileDownload

Resource bindable_mandatory

Yes

size IWDLink LinkSize standard

bindable No

target IWDFileDownload

String bindable No

text IWDLink String bindable No




(TranslatableText)

textDirection

IWDAbstractCaption

TextDirection inherit bindable No


bindable No

type IWDFileDownload

LinkType navigation

bindable No


wrapping IWDLink boolean false bindable No

4.1.14.3 ata Binding for resource Property with Fil eDownload and FileUpload

Use The resource property of the elements FileUpload and FileDownload determines the data of the file to be transferred. The resource property is of the predefined Dictionary Simple Type Resource from the package com.sap.ide.webdynpro.uielementdefinitions .

Below you will find a description of how to bound the resource property to the context.

Prerequisites • You have already created a Web Dynpro project with a view.

• You have inserted a FileDownload or a FileUpload element into the view.

Procedure ...

1. Create a value attribute called resource in the context of the view.

2. In the Properties window, select the type property and …. The Type Selection wizard is started.

3. Select the Dictionary Simple Type , navigate to Dictionaries → Local Dictionary → com.sap.ide.webdynpro.uielementdefinitions and select Resource . Confirm with Okay.




4. In the View Designer, switch to the Layout tab, select the desired FileDownload or FileUpload element and select the resource property in the Properties window.

5. Select the … button to the right, select the resource value attribute in the context viewer and confirm with Okay.

6. Save your metadata.

Result You have created a context attribute of the Dictionary Simple Type Resource and have bound the resource property of the FileDownload or FileUpload element to this attribute. The data source is now bound to the data source of the file to be transferred and can be used.




4.1.14.4 Loading the InputStream at FileDownload on Demand

With the FileDownload element, the content of the file is loaded into the context when the page is built, which happens in the wdDoInit method. If the FileDownload element is used, for example, in a table, this can lead to performance problems.

For this reason, it is possible to delay loading the file content into the context until the download is triggered, that is, when the user actually clicks the FileDownload element. The example below describes the procedure you can use to load data into the context only in the moment you really need it.

Prerequisites • You have created a Web Dynpro project with component and view and you have

included a FileDownload element into the view.

• In the context of the view, you have created a value node named resourceNode .

• In this value node, you have created a value attribute of type com.sap.ide.webdynpro.uielementdefinitions.Resource , as described in Data Binding of Property resource at FileDownload and FileUpload [Page 105].

Procedure ...

1. In the context of your view, under the value node resourceNode , create a value attribute, name it onDemandStream and confirm with Finish .

2. Switch to the Property window, and for the type property click …. The Type Selection wizard is started.

3. Select Java Simple Type, click Browse… and in the next window in the field Choose a Type enter com.sap.tc.webdynpro.progmodel.api.IWDInputStream . Confirm twice with Okay.

4. Set the readonly property to true .

5. Set the calculated property to true . A calculatedAttributeGetter method with the name getOnDemandStream is created.

6. To generate the InputStream, include this method into the following code: IWDInputStream stream = null ; try { String path = WDURLGenerator.getResourcePath(

wdComponentAPI.getDeployableObjectPart(), "<name of download file>" ); stream = WDResourceFactory.createInputStream( new FileInputStream(path));

} catch (Exception ioExp) {

}

return stream;

7. The two attributes resource and onDemandStream must be linked.

Switch to method wdDoInit and enter the following code:




IPrivateLoadOnDemandView.IResourceNodeElement elem = wdContext.currentResourceNodeElement(); //getting the attributepointer of the calculated attribute IWDAttributePointer attributePointer = elem.getAttributePointer( "onDemandStream" ); IWDResource resource = WDResourceFactory.createResource( attributePointer, "<name of the file>" , WDWebResourceType.<type of the file>); // setting value to the bound attribute elem.setResource(resource);

8. Save your data.

Result You have created a FileDownload element whose data will be loaded into the context only when the download is actually triggered.

4.1.15 Gantt API

Definition A Gantt diagram or bar chart graphically represents a chronological sequence of activities in form of bars on a time axis. The individual activities are visualized in rows using horizontal bars.

See also:

JNet – Introduction for Developers [External]

Properties

Description

• archive, classId, codeBase and type are properties the Framework sets automatically; do not change any of them.

• dataSource

Determines the data source of the Gantt. You can use it to specify the path to the context node providing the data.

• height

Determines the height of the Gantt element, which you can specify in relative CSS units like em, ex, or percentage.

• layout

Determines the look of the Gantt. layout is represented by the enumeration type NetworkLayout and can have the following values:

� standard

� yworks determines a special display using a wrapper of yFiles.

• width




Determines the width of the Gantt element, which you can specify in relative CSS units like em, ex, or percentage.




archive IWDAbstractActiveComponent String not_bindable No

classId IWDAbstractActiveComponent String not_bindable No

codeBase IWDAbstractActiveComponent String not_bindable No

dataSource IWDGantt Object bindable_mandatory No


height IWDAbstractActiveComponent String 300px bindable No


type IWDAbstractActiveComponent String not_bindable No


width IWDAbstractActiveComponent String 300px bindable No

Events • onCellEdited

is triggered after the user has clicked a cell. The table cell must be defined as a hyperlink.

• onCellsSelected

is triggered after the user has modified the cell content.

• onColumnAdded

is triggered after the user has added a column.

• onColumnMoved

is triggered after the user has moved or resized a column.

• onColumnRemoved

is triggered after the user has removed a column.

• onGeneric

allows user-defined events to be included.

• onRowAdded

is triggered after the user has added a row.

• onRowCollapsed

is triggered after the user has collapsed a row.

• onRowExpanded

is triggered after the user has expanded a row.

• onRowMoved

is triggered after the user has moved a row.




• onRowRemoved

is triggered after the user has removed a row.

Overview of Inherited and Additional Events

Name Class Parameters

onCellEdited Gantt (String chart, String component, String graph, String parameters)

onCellsSelected Gantt (String chart, String component, String graph, String parameters)

onColumnAdded Gantt (String chart, String component, String graph, String parameters)

onColumnMoved Gantt (String chart, String component, String graph, String parameters)

onColumnRemoved Gantt (String chart, String component, String graph, String parameters)

onGeneric Gantt (String chart, String component, String graph, String name, String parameters)

onRowAdded Gantt (String chart, String component, String graph, String parameters)

onRowCollapsed Gantt (String chart, String component, String graph, String parameters)

onRowExpanded Gantt (String chart, String component, String graph, String parameters)

onRowMoved Gantt (String chart, String component, String graph, String parameters)

onRowRemoved Gantt (String chart, String component, String graph, String parameters)

4.1.16 HorizontalGutter API The Web Dynpro class HorizontalGutter implements the IWDHorizontalGutter interface.

Definition • The HorizontalGutter UI element helps you structure the layout and the text parts of

Web Dynpro screen, similar to the HTML tag <hr>. You use it to insert additional, vertical spaces between UI elements and to group together elements and texts that belong together.

You can display the HorizontalGutter UI element either with or without a visible line.

Description of UI Element Properties • imageAlt


• height Specifies the height of the HorizontalGutter UI element. The height property can be filled with the following values and is represented by the enumeration type WDHorizontalDividerRuleHeight .

medium 17 pixels high

large 31 pixels high

small 7 pixels high

ruleHeight The height of HorizontalGutter




corresponds to the height of the separator

• ruleType The ruleType property is represented by the enumeration type WDHorizontalGutterRuleType and can be filled with the following values:

areaRule Separator is displayed

none No separator is displayed

pageRule Is used to separate window areas

• width Specifies the width which can be specified in CSS units like em, ex, pixels, or percentage.


Name Interface Type Initial Value Bindable

Value Required


height IWDHorizontalGutter medium bindable No

ruleheight IWDHorizontalGutter HorizontalDividerRuleHeight bindable No

ruleType IWDHorizontalGutter WDHorizontalGutterRuleType

areaRule bindable No

tooltip IWDUIElement String (TranslatableText) bindable No


width IWDHorizontalGutter String (CSS size) 100% bindable No

4.1.17 Web Dynpro GeoMap API - IWDGeoMap

Definition You can use the GeoMap UI element to display a section of a map.

You use the values of the properties top , left , bottom , and right to specify the geographical coordinates and define the map section to be displayed. The geographical coordinates are derived from the longitude and latitude values of a geographical location and must be entered in WGS84 format based on the reference system World Geodetic System –1984 (WGS84).

The following values show a geographical section of Walldorf/Heidelberg:




top : 49.4304

left : 8.5082

bottom : 49.2000

right : 8.7922

The GeoMap UI element can only be used with a special software component that is provided by the geographical maps.

This software component which you can use to expand the Internet Graphics Service (IGS) is not included in the delivered SAP Web Application Server package. It must be purchased from a third-party provider. The GeoMap UI element cannot be displayed without this complementary software component.

Property Descriptions • accessibilityDescription


• bottom You can use this property to specify the value of a geographical coordinate in decimal numbers according to the standard World Geodetic System – 1984 (WGS84). Together with the value of the right property, the lower right position of the section is specified.

• geoObjectSource You can position so-called geo objects in the map and use them to highlight a specific position. These geo objects are used to provide specific information to the user. For example, you can mark the starting point or finishing point of a route on the map. This property must be bound to a context attribute.

• height Specifies the height of the UI element in pixels.

• igsURL You can use this property to specify the Web address (URL) of the server on which the Internet Graphics Service is to run. This means that you can overwrite the global URL for which the Web Dynpro System Configuration [External] in the default.properties file has been set.

• left You can use this property to specify the value of a geographical coordinate in decimal




numbers according to the standard World Geodetic System – 1984 (WGS84). Together with the value of the top property, the upper left position of the section is specified.

• moveType This property specifies whether the geographical border of a map can be interactively changed by the user. The moveType property can be filled with the following values and is represented by the enumeration type WDMoveType:

none You cannot change the geographical border.

panel Control elements allow you to change the geographical border.

• right You can use this property to specify the value of a geographical coordinate in decimal numbers according to the standard World Geodetic System – 1984 (WGS84). Together with the value of the bottom property, the lower right position of the section is specified.

• top You can use this property to specify the value of a geographical coordinate in decimal numbers according to the standard World Geodetic System – 1984 (WGS84). Together with the value of the left property, the upper left position of the section is specified.

• width Specifies the width of the UI element in pixels.

• zoomType Specifies the zoom behavior of the map. The zoomType property can be filled with the following values and is represented by the enumeration type WDZoomType:

none Zooming within the map is not possible, and no control elements for zooming are available.

panel Zooming within the map is possible.



Required

accessibilityDescription IWDGeoMap String (TranslatableText)

bindable No

bottom IWDGeoMap double 0.0 bindable No


geoObjectSource IWDGeoMap IWDGeoObject bindable_mandatory No

height IWDGeoMap int 300 not_bindable No

igsURL IWDGeoMap String not_bindable No

imageSource [External] IWDAbstractIgsElement String not_bindable No

left IWDGeoMap double 0.0 bindable No

mapSource [External] IWDAbstractIgsElement String not_bindable No

moveType IWDGeoMap WDMoveType none not_bindable No

right IWDGeoMap double 0.0 bindable No

tooltip [External] IWDUIElement String (TranslatableText)

bindable No




top IWDGeoMap double 0.0 not_bindable No

visible [External] IWDUIElement visibility visible bindable No

width IWDGeoMap int 300 not_bindable No

zoomType IWDGeoMap WDZoomType none not_bindable No

Events • onObjectAction

This property contains the action that is executed when the user activates a geo object.


ID String

For further information, refer to Parameter Mapping [External].

Data Binding For an example of data binding of the UI element properties, refer to Code Example of the Use of a Geographical Map [Page 117].

Methods in the Web Dynpro IWDGeoMap API Method Name Parameter Return Value Description

bindAccessibilityDescription

(String path) Binds the accessibilityDescription property to the context node specified by a path.

bindBottom (String path) Binds the bottom property to the context node specified by a path.

bindGeoObjectSource (String path) Binds the value of the geoObjectSource property to the context element specified by the path.

bindingOfAccessibilityDescription

String Returns the path of the context element to which the accessibilityDescription property is bound. Returns NULL if no binding exists.

bindingOfBottom String Returns the path of the content element to which the bottom property is bound. Returns NULL if no binding exists.

bindingOfGeoObjectSour String Returns the path of the




ce context element to which the geoObjectSource property is bound. Returns NULL if no binding exists.

bindingOfLeft String Returns the path of the content element to which the left property is bound. Returns NULL if no binding exists.

bindingOfRight String Returns the path of the content element to which the right property is bound. Returns NULL if no binding exists.

bindingOfTop String Returns the path of the content element to which the top property is bound. Returns NULL if no binding exists.

bindLeft (String path) Binds the value of the left property to the context element specified by the path.

bindRight (String path) Binds the right property to the context node specified by a path.

bindTop (String path) Binds the top property to the context node specified by a path.

getAccessibilityDescription

String Returns the value of the accessibilityDescription property.

getBottom double Returns the value of the bottom property.

getGeoObjectSource IWDGeoObject Returns the value of the geoObjectSource property.

getHeight int Returns the value of the height property.

getIgsUrl String Returns the value of the igsUrl property.

getLeft double Returns the value of the left property.

getMoveType WDMoveType Returns the value of the




moveType property.

getOnObjectAction IWDAction Returns the action that is executed if the onObjectAction event is raised.

getRight double Returns the value of the right property.

getTop double Returns the value of the top property.

getWidth int Returns the value of the width property.

getZoomType WDZoomType Returns the value of the zoomType property.

mappingOfOnObjectAction

IWDParameterMapping

Returns the parameter mapping for the onObjectAction action.

setAccessibilityDescription

(String accessibilityDescription)

Sets the value of the accessibilityDescription property.

setBottom (double bottom) Sets the value of the bottom property.

setGeoObjectSource (IWDGeoObject geoObjectSource)

Sets the value of the geoObjectSource property.

setHeight (int height) Sets the value of the height property.

setIgsUrl (String igsUrl) Sets the value of the igsUrl property.

setLeft (double left) Sets the value of the left property.

setMoveType (WDMoveType moveType)

Sets the value of the moveType property.

setOnObjectAction (IWDAction action)

Sets the action that is executed if the onObjectAction event is raised.

setRight (double right) Sets the value of the right property.

setTop (double top) Sets the value of the top property.

setWidth (int width) Sets the value of the width property.

setZoomType (WDZoomType zoomType)

Sets the value of the zoomType property.




Additional methods described in the following APIs are available using inheritance: IWDAbstractIgsElement [External], IWDUIElement [External], IWDViewElement [External].

4.1.17.1 Code Example of the Use of a Geographical Map

Use The following example demonstrates the use of a geographical map. It also explains the view structure, the required context structure, and the data binding of the UI element properties to the context structure defined at design time for the geographical map. A geographical object, with which you can also trigger an event, is placed on this map. You can use geographical objects to highlight a certain geographical position in the section of the map. In this example, the exact location of SAP headquarters in Walldorf is shown. When you select this geographical object, the address of SAP AG appears in a TextView user interface element at the lower edge of the map.

Prerequisites You created a Web Dynpro application and created a view (called TestGeoMapComponent in the example) within this Web Dynpro component, in which you want to insert the GeoMap UI element. For a detailed description of the procedure for creating Web Dynpro projects, Web Dynpro components, the context structure as well as the layout of the view, refer to the tutorial Creating Your First Web Dynpro Application.

Procedure

Creating the Layout of the Geographical Map: ...

Insert the GeoMap UI element with the ID TheMap into view TestGeoMapView.

Creating the Context Structure ...

Create the context node:

Context structure:

Create value node DataSource

Create value attribute




geoObject

Create value attribute Address

Properties of the value node DataSource

Properties of the value attribute geoObjec t

If you define first the context structure after creating the view, you can bind the UI element properties to the corresponding context elements directly after inserting of the UI element into the view.

Data Binding ...

Define the data binding for the UI element properties for the GeoMap UI element:

UI element property Value

Bottom 49.2000

geoObjectSource DataSource.geoObject (optional in this example)

Height 250

igsURL URL of your IGS service

Left 8.5082

moveType none

Right 8.7922

Top 49.4304

Width 250

zoomType none




Define data binding for the UI element properties for the label UI element: The UI element property text is bound to the root node attribute Address .


LabelFor TextView1

Text Address of the company

Define data binding for the UI element properties for the TextView UI element: The UI element property text is bound to the root node attribute Address .


text Address

Defining the OnObjectAction Event LinkToWebAddress A geographical object can trigger an onObjectAction event. This event is always bound to a geographical object on the map. You can do this by creating action LinkToWebAddress with parameter actionID in the View Designer. This automatically creates method onActionLinkToWebAddress in the controller implementation.

Within this method, you fill the context with the address by means of the source text wdContext.currentContextElement().setAddress( "SAP AG, Neurottstraße 16, 69190 Walldorf" ); . If you select the geographical object with the mouse button in this example, the address of SAP appears in a TextView UI element at the lower edge of the map.

To tell the action which geographical point triggers the event, you must map parameter id of the geographical point to parameter actionID of the action.

public static void wdDoModifyView(IPrivateTestGeoMapView wdThis, IPrivateTestGeoMapView.IContextNode wdContext, com.sap.tc.webdynpro.progmodel.api.IWDView view, boolean firstTime) { //@@begin wdDoModifyView IWDGeoMap map = (IWDGeoMap)view.getElement( "TheMap" ); map.mappingOfOnObjectAction().addSourceMapping( "id" , "actionID" ); //@@end } //@@begin javadoc:onActionLinkToWebAdress(ServerEve nt) /** Declared validating event handler. */ //@@end public void onActionLinkToWebAddress(com.sap.tc.webdynpro.progm odel.api.IWDCustomEvent wdEvent, java.lang.String actionID ) { //@@begin onActionLinkToWebAddress(ServerEvent) wdContext.currentContextElement().setAddress( "SAP AG, Neurottstraße 16, 69190 Walldorf" ); //@@end }




Controller Implementation of View TestGeoMapView

Several Web Dynpro classes are available for placing geographical objects, including WDGeoObject, WDGeoLine, WDGeoPoint, and WDGeoPolygon. The following source text displays a geographic object at position 8.6425, 49.2929 (WGS84 format) in the form of a blue ellipse with the label SAP upon initialization. Also see the screenshot of the result below. If method setTriggersEvent has the value true , the geographical object of type IWDGeoPoint can trigger an event. public void wdDoInit() { //@@begin wdDoInit() IPrivateTestGeoMapView.IdataSourceNode node = wdContext.nodeDataSource(); IWDGeoPoint point = WDGeoFactory.createGeoPoint ( "GeoPoint1" ); point.setLabel( "SAP" ); point.setStyle(WDGeoPointStyle.ELLIPSE); point.setTooltip( "SAP" ); WDGeoPosition geoPosition = new WDGeoPosition(8.6425, 49.2929); point.setPosition(geoPosition); point.setTriggersEvent( true ); point.setSize(20); point.setColor(java.awt.Color.blue); IPrivateTestGeoMapView.IDataSourceElement nodeEl ement = node.createDataSourceElement(); nodeElement.setGeoObject(point); node.addElement(nodeElement); //@@end

}

Calling the Web Dynpro Application and Result Before you can call the Web Dynpro application, you must build the Web Dynpro project and install the Web Dynpro application on the J2EE Engine.

You call the Web Dynpro application using a URL in the browser. The result is the display of a map section of the Heidelberg/Walldorf region, in which the location of SAP headquarters is marked with a blue ellipse.




If you select this geographical object, the address is displayed at the lower edge of the map.

For more information, see the description of the Web Dynpro GeoMap API.

4.1.17.2 Example for Displaying a Route

The following example illustrates the use of the IWDGeoCoder and IWDGeoRouter interfaces of the BusinessGraphics UI Element Library and describes how it can be used to display a geographic route on a map.

The interfaces are used to display a route from SAP AG in Walldorf (near Heidelberg) to the Frankfurt Airport. Then the example application is run, a map section that includes the cities of Walldorf and Frankfurt first appears. Pressing the button labeled show route displays the route from Walldorf to the Frankfurt Airport.

This example illustrates:

• How to build the GeoMap UI element


• The source text of the controller implementation

Procedure

Creating the Layout of View GeoRouteComponentView

1. Delete the UI element DefaultTextView that was automatically generated with the view.

2. Add GeoMap UI element GeoMap1.

3. Add text view UI element TextView1.

4. Add button UI element Button1.

Screenshot of view structure:

...





1. Create context node GeoData of collection type List

2. Create context attribute GeoObject of type com.sap.ide.webdynpro.uielementdefinitions.GeoObject

Defining Action ShowRoute

Defining Data Binding of the User Interface Element Properties

To display an initial map section from Heidelberg to Frankfurt, the corresponding values are assigned t the top/left and bottom/right properties of the GeoMap UI element.

Property geoObjectSource of UI element BG is bound to context attribute GeoData.GeoObject. At runtime, the GeoData node elements define the values to display the start and end points of the route.




The OnAction event of pushbutton Button1 is bound to action ShowRoute .

Implementing a Controller

In this example, the addresses of the departure point and destination of the route are written directly in the source text of the controller implementation. However, you can also develop an application that would allow the user to display any desired route. To do so, you have to provide appropriate input fields to enter the addresses for the departure and destination points of the route. You can develop an application that offers this enhanced functionality using the tutorial for the geographic service itself.

If you want to use the SAP icons as geographic objects, assign string "@<SAP icon ID>@" , such as "@AV@" for an airplane icon, to the setImage method of the geographic point for type IWDGeoPoint. For a description and a listing of all possible SAP icons, see the SAP Design Guild at sapdesignguild.org/ . Select the following path: Sitemap → Resources → Visual Design & Icons → SAP R/3 Icons → R/3 Icon Lists. The ID of the image appears in the table of ID names for the SAP icons.

...

... //@@begin javadoc:wdDoModifyView /** * Hook method called to modify a view just before rendering. * This method conceptually belongs to the view itself, not to the * controller (cf. MVC pattern). * It is made static to discourage a way of programming that * routinely stores references to UI elements in instance fields * for access by the view controller's event handlers, and so on. * The Web Dynpro programming model recommends that UI elements can * only be accessed by code executed within the call to this hook method. * * @param wdThis Generated private interface of the view's controller, as * provided by Web Dynpro. Provides access to the view controller's * outgoing controller usages, etc. * @param wdContext Generated interface of the view's context, as provided




* by Web Dynpro. Provides access to the view's data. * @param view The view's generic API, as provided by Web Dynpro. * Provides access to UI elements. * @param firstTime Indicates whether the hook is called for the first time * during the lifetime of the view. */ //@@end public static void wdDoModifyView(IPrivateGeoRouteComponentView wdThis, IPrivateGeoRouteComponentView.IContextNode wdContext, com.sap.tc.webdynpro.progmodel.api.IWDView view, boolean firstTime) { //@@begin wdDoModifyView IWDGeoMap geomap = (IWDGeoMap) view.getElement( "GeoMap1" ); geomap.setLeft(geomap.getLeft()); geomap.setRight(geomap.getRight()); geomap.setTop(geomap.getTop()); geomap.setBottom(geomap.getBottom()); //@@end } //@@begin javadoc:onActionShowRoute(ServerEvent) /** Declared validating event handler. */ //@@end public void onActionShowRoute(com.sap.tc.webdynpro.progmodel.ap i.IWDCustomEvent wdEvent ) { //@@begin onActionShowRoute(ServerEvent) // read the User Input from Context and Add it to the WDGeoCoder.WDAddress WDGeoCoderAddress addressStart = new WDGeoCoderAddress( "16" , "Neurottstraße" , "Walldorf" , "" , "69190" , "DE" ); WDGeoCoderAddress addressEnd = new WDGeoCoderAddress( "" , "Flughafen" , "Frankfurt" , "" , "60549" , "DE" ); // give the addresses to the geoCoder and let the geocoordinates calculate IWDGeoCoder geoCoder = WDGeoFactory.createGeoCoder(); try { geoCoder.setIgsUrl( new URL( "<The URL of the IGS>” )); try { geoCoder.addAddress( "0" , addressStart); geoCoder.addAddress( "1" , addressEnd); } catch (WDException e1) { e1.printStackTrace(); } } catch (MalformedURLException e) {




e.printStackTrace(); } geoCoder.execute(); // GeoPositions and MapBorder -------------------------------------------------------------------- WDGeoCoderResultAddress sResult = (WDGeoCoderResultAddress) geoCoder.getResultAddresses( "0" ).get(0); WDGeoPosition startPos = sResult.getGeoPosition( ); WDGeoCoderResultAddress eResult = (WDGeoCoderResultAddress) geoCoder.getResultAddresses( "1" ).get(0); WDGeoPosition endPos = eResult.getGeoPosition(); // Calculate Route ------------------------------------------------------------------------------- IWDGeoRouter geoRouter = WDGeoFactory.createGeoRouter(); try { geoRouter.setIgsUrl( new URL( "<The URL of the IGS>" )); } catch (MalformedURLException e) { e.printStackTrace(); } geoRouter.addStop( "0" , "0" , startPos); geoRouter.addStop( "1" , "1" , endPos); geoRouter.execute(); List routeList = geoRouter.getRoutePath(); // Add GeoObjects --------------------------------------------------------------------------------- -- // GeoLine: (Route) IWDGeoLine line = WDGeoFactory.createGeoLine( "route" ); line.setPositions(routeList); line.setColor(java.awt.Color.blue); line.setWidth(4); IGeoDataNode geoDataNode = wdContext.nodeGeoData (); IGeoDataElement geoDataElement; geoDataElement = wdContext.createGeoDataElement( ); geoDataElement.setGeoObject(line); geoDataNode.addElement(geoDataElement); //Start Point IWDGeoPoint geoStartPoint = WDGeoFactory.createGeoPoint( "0" ); geoStartPoint.setTooltip( "SAP" ); geoStartPoint.setPosition(startPos); geoStartPoint.setTriggersEvent( true ); geoStartPoint.setSize(15);




geoStartPoint.setColor(java.awt.Color.blue); geoStartPoint.setStyle(WDGeoPointStyle.ELLIPSE); geoStartPoint.setLabel( "SAP" ); geoDataElement = wdContext.createGeoDataElement( ); geoDataElement.setGeoObject(geoStartPoint); geoDataNode.addElement(geoDataElement); //End Point IWDGeoPoint geoEndPoint = WDGeoFactory.createGeoPoint( "1" ); geoEndPoint.setTooltip( "Airport" ); geoEndPoint.setPosition(endPos); geoEndPoint.setTriggersEvent( true ); geoEndPoint.setImage( "@AV@"); geoEndPoint.setLabel( "Airport" ); geoDataElement = wdContext.createGeoDataElement( ); geoDataElement.setGeoObject(geoEndPoint); geoDataNode.addElement(geoDataElement); //@@end } ... ...

Result When the application is started, a map section from Heidelberg to Frankfurt is displayed.

When the user presses the show route button in the lower-right corner of the image, the route from Walldorf (SAP) to the Frankfurt Airport is displayed. The position of the Frankfurt Airport is marked with an airplane icon, which represents a geographic object.




4.1.18 Web Dynpro IFrame API – IWDIFrame The IFrame UI element is deprecated and should no longer be used.

Definition The UI element IFrame is an internal frame within a view. This frame can be used to display external sources like HTML pages within a specific area of the user interface. In general, a vertical and horizontal scroll bar are activated to view the content of this UI element. You can scroll within the frame content, as is shown in the following graphic:

Description of UI Element Properties • border

Specifies whether or not the IFrame UI element is displayed with borders.

• height Specifies the height of an internal frame.




• scrollingMode Specifies how the scroll bar can be displayed within the IFrame UI element container. The scrollingMode property can be filled with the following values and is represented by the enumeration type WDScrollingMode .

auto The scroll bar within the container is activated automatically.

both A vertical and horizontal scroll bar are activated.

none Scrolling within the text context is not possible.

• source Specifies the source of the frame content to be displayed in this UI element.

• width Specifies the width of an internal frame.


Required

border IWDIFrame boolean false bindable No


height IWDIFrame int 300 bindable No

scrollingMode IWDIFrame WDScrollingMode

auto bindable No

source IWDIFrame String bindable Yes

tooltip [External] IWDUIElement String (TranslatableText)

bindable No


width IWDIFrame int 300 bindable No

The inherited properties enabled and tooltip are ignored and do not affect the browser.

Methods in the Web Dynpro IWDIFrame API Method Name Parameter Return Value Short Descriptio n

bindBorder (String path) Binds the border property to the context node specified by a path.

bindHeight (String path) Binds the height property to the context node specified by a path.

bindingOfBorder String Returns the path of the context element to which the border




property is bound. Returns NULL if no binding exists.

bindingOfHeight String Returns the path of the context element to which the height property is bound. Returns NULL if no binding exists.

bindingOfScrollingMode String Returns the path of the context element to which the scrollingMode property is bound. Returns NULL if no binding exists.

bindingOfSource String Returns the path of the context element to which the source property is bound. Returns NULL if no binding exists.

bindingOfWidth String Returns the path of the context element to which the width property is bound. Returns NULL if no binding exists.

bindScrollingMode (String path) Binds the value of the scrollingMode property to the context element specified by the path.

bindSource (String path) Binds the value of the source property to the context element specified by the path.

bindWidth (String path) Binds the value of the width property to the context element specified by the path.

getBorder boolean Returns the value of the border property.

getHeight String Returns the value of the height property.

getScrollingMode WDScrollingMode Returns the value of the scrollingMode property.

getSource String Returns the value of the source property.




getWidth String Returns the value of the width property.

setBorder (boolean value) Sets the value of the border property.

setHeight (String value) Sets the value of the height property.

setScrollingMode (WDScrollingMode value)

Sets the value of the scrollingMode property.

setSource (String value) Sets the value of the source property.

setWidth (String value) Sets the value of the width property.

Additional methods are available using inheritance: IWDUIElement [External], IWDViewElement [External].

For further information about all inherited methods, refer to the documentation for the relevant APIs.

4.1.19 Image API

Definition The UI element Image enables you to integrate graphics into the Web application in a format that is processed by the Web Server – for example, GIF, JPG, and PNG format. To specify the data source, use the source property.

You can assign a popup menu to the image which is visible as a little triangle at the bottom right-hand edge when the user places the cursor on the image.

Use When using an Image UI element, you should always add a label to ensure accessibility.

Description of UI Element Properties • adjustImageSize

Specifies whether the size of the image is adjusted proportionally. If this property is set to false , the image will be displayed according to the specified height and width, without keeping the proportions.

• alt

Determines an alternative text that is displayed when the graphic cannot be opened or found.

• border




Specifies whether the graphic is displayed with a border.

• height

Specifies the height of the graphic. You can specify the height in CSS units like em, ex, pixels, or percentage.

• isDecorative

Specifies whether an image serves for decorative purposes only. If it does not provide the user with any kind of information, set this property to true . When accessibility mode is active, this image will be ignored and removed from the tab sequence.

• source

Determines the Web address (URL) of the graphic through which the UI element receives the data. If you store the image file in your Web Dynpro project under → src → mimes → Components → <Name of Component>, you only have to specify the file name without a path.

• width

Specifies the width of the graphic. You can specify the width in CSS units like em, ex, pixel, or percentage.

Overview of Inherited and Additional Properties Name Interface Type Initial Value Bindable Value Re quired

adjustImageSize

IWDImage boolean false bindable No

alt IWDImage String (TranslatableText)

bindable Yes

border IWDImage int 0 bindable No


height IWDImage String (CSS size) bindable No

isDevorative IWDImage boolean false bindable No

source IWDImage String bindable Yes


bindable No


width IWDImage String (CSS size) bindable No

The inherited enabled property is ignored and does not affect the browser.




4.1.20 InputField API

Definition The InputField UI element allows the user to edit or display a single-line text. You cannot only edit the value of the type String but also the value of any simple data type using an input field. The conversion of the string representation into the data type – known as parsing – and the conversion of the data type into the string presentation – known as formating – are automatically executed.

Use When using an input field, you must always add a label to ensure accessibility.

Description of UI Element Properties • alignment

Specifies the horizontal alignment of the UI element in the grid. The default value of this property is auto . The alignment property can take the following values and is represented by the enumeration type InputFieldAlignment :

auto The alignment is specified by the usage of the UI element - for example, by the displayed data type.

left The content is displayed left-aligned.

right The content is displayed right-aligned.

• length

Specifies the maximum number of characters to be displayed in the input field.

• passwordField

Boolean value that controls the display of entered characters on the screen. If the value is true , the entered characters on screen are echoed with an asterisk (*). This attribute is usually used for password input fields.

• readOnly

Specifies whether the input field can be edited or read only. If the value is true , the displayed text can only be read.

• size


• state

Describes the state of the UI element. The data type of this property corresponds to the enumeration type State . You can use the following values in the application:



• textDirection

Specifies the text direction and allows you to use input fields for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type textDirection .








• value

Specifies the character string displayed in the input field area. This property must be bound to a context attribute (see Data Binding of UI Element Properties [Page 283]).

• width

Specifies the width of the input field that you can specify in CSS sizes, such as em, ex, pixels or percentage values.



Required

alignment IWDAbstractInputField InputFieldAlignment auto bindable No


length IWDAbstractInputField int 20 bindable No

passwordField IWDAbstractInputField boolean false bindable No

readOnly IWDAbstractInputField boolean false bindable No

state IWDAbstractInputField State normal bindable No

textDirection IWDAbstractInputField TextDirection inherit bindable No


bindable No

value IWDAbstractInputField String bindable_mandatory No


width IWDAbstractInputField String bindable No

Event This event onEnter - inherited from IWDAbstractInputField - is triggered when the user chooses ENTER.

Data Binding You can use the value property to bind data to an input field by assigning the path of the context attribute to this property.

4.1.21 ItemListBox API An ItemListbox provides different values for selection, similar to the DropDownBox. You can vary the number of displayed values and, in contrast to a DropDownBox, multiple selection is possible.





This property is used to specify the data source. You can use it to specify the path to the context node providing the data.

• descriptiveText This property defines a descriptive text that is displayed within the ItemListBox beside the text.

• textDirection This property specifies the text direction and allows you to use dropdown list boxes for texts in languages that require a specific text direction. The textDirection property can be filled with the following values and is represented by the listing type WDTextDirection .





• iconSource This property describes the Web address (URL) of the graphic to be displayed.

• multipleSelection This property enables the selection of several elements.

• readOnly This property controls whether the user can choose an element from the ItemListBox UI element.

• selectionChangeBehaviour The change of the lead selection can cause a data loss – for example, if the changed or new data was not written to the context due to syntax errors. You can avoid the data loss using the selectionChangeBehaviour property before changing the lead selection:

• auto • If the data was written to the context, the value auto specifies that the ItemListBox automatically changes the lead selection of its data source directly after an interaction by the user before the corresponding event is triggered.

• manual • Specifies that the ItemListBox does not change the lead selection of its data source after an interaction by the user but triggers the corresponding event. In this case, the event handler must change the lead selection to enable the ItemListBox to display the data in a main detail view, for example. This setting allows you to check the change of the lead selection.

• text This property specifies the text to be assigned to the ItemListBox .




• textDirection You can use this property to define the text direction. It thus enables the labels for all item list boxes to be read in other languages that require a specific text direction. The textDirection property can be filled with the following values and is represented by the listing type WDTextDirection .





• visibleItems This property defines the size of the item list box on the basis of the number of visible elements.

• width This property specifies the width of the item list box and can be specified in CSS units like em, ex, pixels, or percentage.


al Value


dataSource IWDItemListBox


No

descriptiveText IWDItemListBox

String bindable No

descriptiveTextDirection

IWDItemListBox

WDTextDirection inherit

bindable No

enabled IWDUIElement


explanation IWDItemListBox

String not_bindable No

iconSource IWDItemListBox

String bindable No

multipleSelection IWDItemListBox

boolean false

bindable No

readOnly IWDItemListBox

boolean false

bindable No

selectionChangeBehaviour

IWDItemListBox

WDLeadSelectionChangeBehaviour

auto

not_bindable No

text IWDItemListBox

String bindable No

textDirection IWDItemListBox


bindable No

tooltip IWDUIEle String bindable No




ment

visible IWDUIElement

WDVisibility visible

bindable No

visibleItems IWDItemListBox

int 10 bindable No

width IWDItemListBox

String bindable No

Ereignisse •

Events • onLeadSelect (int index)

Specifies the action that is executed when the user selects an element of the ItemListBox.

4.1.22 Label API The Label UI element represents the IWDLabel class.

The Label UI element is used for labeling other UI elements. Therefore, it is always associated with another UI elements. This UI element ensures accessibility of the Web Dynpro application. The appearance is defined by the design property.

You can also define other UI elements as label. These include the following UI elements:

• DropDownByIndex

• DropDownByKey

• ToolBarDropDownByIndex

• ToolBarDropDownByKey


Specifies the design of the UI element. The design property can be filled with the following values and is represented by the enumeration type WDLabelDesign .

emphasized The UI element is highlighted.

light

The UI element is displayed without the left design bar.

standard

A default design of the UI element.

• labelFor Specifies the ID of the UI element to be labeled.

• text Label text.




• textDirection Specifies the text direction and allows you to use Label UI elements for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type WDTextDirection .





• width Specifies the width of the Label UI element and can be specified in CSS units like em, ex, pixels, or percentage.

• wrapping Indicates whether or not the text is wrapped. If the value is false , the text is not wrapped.

Data Binding Since the relationship between Label UI element and associated UI element is specified by the static layout of a view, the labelFor property is not defined as bindable.

Overview of Inherited and Additional Properties Name Interface Type Initial Value Bindable Value Re quired


design IWDLabel WDLabelDesign standard bindable No

labelFor IWDLabel String not_bindable Yes

Text IWDLabel String (TranslatableText)

bindable No

textDirection IWDLabel WDTextDirection inherit bindable No


bindable No


width IWDLabel String bindable No

wrapping IWDLabel boolean false bindable No

4.1.23 Legend API

Definition The Legend UI element allows you to display a descriptive text for different colors used in an assigned UI element. The Legend element can be positioned anywhere in the view and be assigned to a table or a DateNavigator.




The screen shot below shows a DatNavigator element with assigned legend.

Assigning the Legend element

• to the DateNavigator element:

In the view, after the DateNavigator element insert a Legend element and assign it to the DateNavigator element by setting the ID of the Legend element as the legendId property of the DateNavigator element.

• to the table:

You can insert a Legend element after the table and use the legendId property to assign it to the table. To position the Legend element at the bottom of the table, you can use the LegendPopin. Insert a LegendPopin into the table and a content into the LegendPopin. Then insert a Legend element into the content.

The color-wise assignment of the LegendItem is done via the enumeration type TableCellDesign. The following properties are of this type:

• For the LegendItem, the property semantics

• For the DateNavigatorMarking, the property daySemantics

• For the table, the property cellDesign of the TableColumn.

Structure A Legend is composed of LegendItems.




ViewElement

name : String

(from uielement)

UIElement

enabled : Boolean = truetooltip : TranslatableTexttooltip_isDependent : Boolean = truevisible : Visibility = visible

(from uielement)

LegendItem

semantics : TableCellDesign = standardtextDirection : TextDirection = inherittext : TranslatableTextvisible : Boolean = true

Legend

colCount : Integer = 1width : String

0..*1

+Items

0..*1 <<default>>

TableCellDesign

standard : String = 0negative : String = 1positive : String = 2badvalue_dark : String = 3badvalue_medium : String = 4badvalue_light : String = 5criticalvalue_dark : String = 6criticalvalue_medium : String = 7criticalvalue_light : String = 8goodvalue_dark : String = 9goodvalue_medium : String = 10goodvalue_light : String = 11key_medium : String = 12group_level1 : String = 13group_level2 : String = 14group_level3 : String = 15one : String = 16two : String = 17three : String = 18four : String = 19

<<enum>>

Description of UI Element Properties • colCount

Determines the number of columns in which LegendItems are displayed.

• width

Determines the width of the Legend, which you can specify in relative CSS units like em, ex, or percentage.


Required

colCount IWDLegend int 1 bindable No







width IWDLegend String 100% bindable No

4.1.23.1 LegendItem API

Definition A LegendItem is an element of a Legend and consists of a color field and a text.

Description of UI Element Properties • semantics

Determines the color of the LegendItem. The semantics property can be filled with the following values and is represented by the enumeration type TableCellDesign.

























• text

Determines the text of the LegendItem.

• textDirection

Specifies the text direction and allows you to use a LegendItem for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type textDirection .





• visible

Determines whether the LegendItem is visible.


Required

semantics IWDLegendItem

TableCellDesign

standard bindable No

text IWDLegendItem

String bindable No

textDirection IWDLegendItem


visible IWDLegendItem


4.1.23.2 MultipleLegendItem API

Definition A MultipleLegendItem offers the option of providing several LegendItems by binding them to a context node.


Determines the context node that stores the LegendItem.

semantics

Determines the color of the LegendItem. The semantics property can be filled with the following values and is represented by the enumeration type TableCellDesign.

























• text

Determines the text of the LegendItem.

• textDirection

Specifies the text direction and allows you to use a LegendItem for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type TextDirection.





• visible

Determines whether the LegendItem is visible.





Required

dataSource IWDMultipleLegendItem


Yes

semantics IWDLegendItem

TableCellDesign


text IWDLegendItem

String bindable No

textDirection IWDLegendItem


visible IWDLegendItem


4.1.24 LinkToAction API

Definition The LinkToAction UI element is a hypertext link. The navigation to this link triggers a Web Dynpro action. You can assign a popup menu to LinkToAction which the user can recognize by this symbol: .


Specifies the graphical design of the UI element. The type property can be filled with the following values and is represented by the enumeration type WDLinkType .

function

Link is displayed underlined in the standard design.

navigation Link is displayed underlined and with a font color that is used for links already visited.

reporting Link is displayed not underlined in the standard design.

result Link is displayed not underlined.



Required


imageAlt IWDAbstractCaption


bindable No






imageHeight IWDLink String (CSS size) bindable No

imageSource

IWDAbstractCaption

String bindable No

imageWidth IWDLink String (CSS size) bindable No

size IWDLink WDLinkSize standard bindable No

text IWDLink String (TranslatableText)

bindable No

textDirection IWDAbstractCaption

WDTextDirection inherit bindable No

type IWDLinkToAction WDLinkType function bindable No


bindable No



Events • onAction

This attribute can assign the action that is to be executed when the user navigates to the link.

4.1.25 LinkToURL API

Definition The LinkToURL UI element is a hypertext link. The navigation to this link leads to a user-defined Web resource (URL).

You can assign a popup menu to LinkToURL which the user can recognize by this symbol: .

Description of UI Element Properties • reference

Describes the address of the Web page to be opened.

• target Specifies the browser window in which the page is to be opened. You can manually specify the name of the target window or use the following values:



• design Specifies the graphical design of the UI element. The type property can be filled with the following values and is represented by the enumeration type WDLinkType .




function

Link is displayed underlined in the standard design.

navigation Link is displayed underlined and with a font color that is used for links already visited.

reporting Link is displayed not underlined in the standard design.

result Link is displayed not underlined.

Overview of Inherited and Additional Properties Name Interface Type Initial Value Bindable Value Required




imageHeight IWDLink String (CSS size) bindable No

imageSource IWDAbstractCaption

String bindable No

imageWidth IWDLink String (CSS size) bindable No


reference IWDLinkToURL String bindable Yes

target IWDLinkToURL String bindable No

text IWDLink String (TranslatableText)

bindable No

textDirection IWDAbstractCaption



bindable No

type IWDLinkToURL WDLinkType navigation bindable No



4.1.26 MenuBar and Popup Menu

Definition You can use menus in a MenuBar as standalone elements or you can assign them to different UI elements as popup menus.

The following screenshot shows how a MenuBar looks like.




The popup menu is used to group actions in a space-saving way. After a user action, the menu is opened according to the UI element to which it is assigned. The following graphic shows the structure of a popup menu with the various elements:

The popup menu is displayed according to the UI ele ment to which it is assigned.

UI Element Display of the Icon for the Popup Menu

Description

LinkToAction LinkToURL

For interactive elements, a static icon indicates the existence of a popup menu.

Image ProgressIndicator

TextView

For interactive elements, an icon of an orange triangle appears for the popup menu when the user places the cursor on the image.

Tray

For the tray, the icon for the popup menu is located in the title bar.

TreeNode For a TreeNode, the popup menu is opened using the right mouse

button.

Table In a table, popup menus can be used when a UI element is used as a cell editor and when the UI element can be assigned a popup menu.




Structure A MenuBar and a popup menu consist of the following elements:

• Submenus for hierarchical menu structures, defined as a menu

• Different menu items which can be defined as the following elements:

� MenuActionItem

� MenuRadioButton

� MenuCheckBox

� MenuSeparator

The MenuSeparator element adds a separator between two menu items and thus provides a structure to the menu items.

The getMenu method can be used to determine the corresponding menu for all menu items and submenus.

The following UML class diagram shows the aggregated elements with the properties which can be used to create a a MenuBar or a popup menu.




MenuActionItem

onAction : Stringenabled : Boolean = trueim ageSource : StringneedsM oreInfo : Boolean = falsetext : T ranslatableT exttextDi rection : T extDirection = inheri t

MenuSeparator

ViewElement

name : String

(f rom uielement)

MenuCheckBox

onToggle : StringonToggle_checked : Boolean = falsechecked : Boolean = falseenabled : Boolean = trueneedsM oreInfo : Boolean = falsetext : T ranslatableT exttextDi rection : T extDirection = inheri t

MenuRadioButton

onSelect : StringonSelect_key : Stringenabled : Boolean = truekeyToSelect : StringneedsM oreInfo : Boolean = falseselectedKey : Stringtext : T ranslatableT exttextDi rection : T extDirection = inheri t

MenuBarDesign

standard : String = 0transparent : String = 1

<<enum >>

UIElement

enabled : Boolean = truetool tip : T ranslatableTexttool tip_isDependent : Boolean = truevisible : Visibi l i ty = visible

(f rom uielement)

MenuItem

Menu

enabled : Boolean = trueti tle : T ranslatableTexttextDi rection : T extDirection = inheri t

1

0..*

+Menu 1

+Items

0..*<<default>>

MenuBar

design : MenuBarDesign = standardwidth : String 0..*0..1

+Menus

0..*

+MenuBar

0..1

4.1.26.1 MenuBar API

Definition A MenuBar is used to present actions in a structure. The MenuBar is a toolbar that can be organized in different blocks, the menus. Under each block, you can organize individual menu items or other menus.


Determines the look of the MenuBar. design is represented by the enumeration type MenuBarDesign and can have the following values:




standard Standard display

transparent The MenuBar is displayed transparently and without frame

• width

Determines the width of the MenuBar, which you can specify in relative CSS units like em, ex, or percentage.


Required

design IWDMenuBar MenuBarDesign





width IWDMenuBar String bindable No

4.1.26.2 Menu API

Description of UI Element Properties • enabled

Specifies whether or not an event can be triggered by a user interaction.






• state Describes the title of the menu bar.


Required

enabled IWDMenu boolean true bindable No




textDirection IWDMenu WDTextDirection inherit bindable No

title IWDMenu String bindable No

4.1.26.3 MenuActionItem API

Definition The MenuActionItem element is a subelement of the MenuItem element. You can use this subelement to define an action for a menu item (or MenuItem object). You can link this view element to a graphic using the imageSource property.

Description of Properties • enabled

Indicates whether or not the menu item can be selected.

• imageSource Specifies the Web address (URL) of the graphic to be displayed.

• needsMoreInfo Adds … to the text of the menu item to indicate to the user that additional user input is required after selecting this menu item. The following screenshot illustrates this property:

• text Describes the text to be displayed.








Required

enabled IWDMenuActionItem boolean true bindable No

imageSource IWDMenuActionItem String bindable No

needsMoreInfo IWDMenuActionItem boolean false bindable No

text IWDMenuActionItem String (TranslatableText)

bindable No




textDirection IWDMenuActionItem WDTextDirection inherit bindable No

Events • onAction

This property assigns the action of the view controller that is executed when the user selects MenuActionItem element.

4.1.26.4 MenuCheckBox API


This property specifies whether or not the MenuCheckbox is selected. The Boolean value true indicates that the option is selected. A checkmark appears in the graphic that is displayed on the screen.

• enabled This property specifies whether or not an event can be triggered by a user interaction.

• needsMoreInfo This property adds … to the text of the menu item to indicate to the user that additional user input is required after selecting this menu item.

• text This property specifies the text that is associated with the MenuCheckbox graphic and displayed to the right of the box.

• textDirection With this property you can specify the text direction. It thus enables the labels for the MenuCheckBox to be read in other languages that require a specific text direction. The textDirection property can be filled with the following values and is represented by the listing type WDTextDirection .







Required

checked IWDMenuCheckBox boolean false bindable_mandatory No

enabled IWDMenuCheckBox boolean true bindable No

needsMoreInfo IWDMenuCheckBox boolean false bindable No

text IWDMenuCheckBox String bindable No

textDirection IWDMenuCheckBox WDTextDirection inherit bindable No




Events The event is triggered when the checkbox is switched. The parameter is the new status.


onToggle MenuCheckBox (boolean checked)

4.1.26.5 MenuRadioButton API

Definition The Web Dynpro class MenuRadioButton , which implements the IWDMenuItem interface, is the abstract base class of radio buttons within a menu.

Description of UI Element Properties • enabled

This property specifies whether or not an event can be triggered by a user interaction.

• keyToSelect This property specifies the value of the key used for the selection of this radio button.

• needsMoreInfo This property adds … to the text of the menu item to indicate to the user that additional user input is required after selecting this menu item.

• selectedKey This property specifies the path of the context attribute that stores the currently selected key.

• text This property describes the text next to the radio button.

• textDirection With this property you can specify the text direction. This enables texts for a MenuRadioButton to be read in other languages that require a particular text direction. The textDirection property can be filled with the following values and is represented by the listing type WDTextDirection .







Required

enabled IWDMenuRadioButton boolean true bindable No

keyToSelect IWDMenuRadioButton String bindable Yes




needsMoreInfo IWDMenuRadioButton boolean false bindable No

selectedKey IWDMenuRadioButton String bindable_mandatory Yes

text IWDMenuRadioButton String bindable No

textDirection IWDMenuRadioButton WDTextDirection inherit bindable No

Events The event onSelect determines the action that is to be executed whenever the MenuRadioButton is selected.


onSelect IWDMenuRadioButton (String key)

4.1.27 Network API

Definition A network is the graphical or tabular representation of flows and dependencies.

See also:

JNet – Introduction for Developers [External]

Properties • archive, classId, codeBase and type are properties the Framework sets

automatically; do not change any of them.

• dataSource

Determines the data source of the network. You can use it to specify the path to the context attribute, which makes the data available.

• height

Determines the height of the Network element, which you can specify in relative CSS units like em, ex, or percentage.

• layout

Determines the look of the Network. layout is represented by the enumeration type NetworkLayout and can have the following values:

� standard

� yworks determines a special display using a wrapper of yFiles.

• width

Determines the width of the Network element, which you can specify in relative CSS units like em, ex, or percentage.


Name Interface Type Initial Bindable Value




Value Required

archive IWDAbstractActiveComponent String not_bindable No

classId IWDAbstractActiveComponent String not_bindable No

codeBase IWDAbstractActiveComponent String not_bindable No

dataSource IWDNetwork Object bindable_mandatory Yes


height IWDAbstractActiveComponent String 300px bindable No

layout IWDNetwork NetworkLayout standard bindable No


type IWDAbstractActiveComponent String not_bindable No


width IWDAbstractActiveComponent String 300px bindable No

Events • onEdgePropsChanged

is executed after the edge properties have been changed. This applies only for those properties that involve the look of the edges; changes to the source or target of a link trigger the events onLinkAdded and onLinkRemoved .

• onEdgeSelected

is triggered after an edge has been clicked.

• onGeneric

allows user-defined events to be included.

• onGraphAdded

is triggered after a sub-graph has been added to the network.

• onGraphRemoved

is triggered after a sub-graph has been removed.

• onInitialized

is triggered after the JNet, which is the init method of the applet, has been triggered.

• onLayoutChanged

is triggered after the position of a node has been changed. It is triggered after the node has been moved to a different position.

• onLinkAdded

is triggered after a link has been added to the network, that is, an edge has been connected to a node.

• onLinkRemoved

is triggered after a link has been removed from the network, that is, the connection was split without removing the edge.

• onModelAdded

is triggered after the entire model has been replaced.




• onModelDirty

is triggered after the current model has been changed so that it is set to state dirty . dirty means that an event is triggered that results in the fact that the network no longer corresponds to the specification of the server application.

• onModelExtracted

is triggered after a new model has been extracted from the current model. This happens when the user has executed, for example, a graph analysis in order to filter a particular subset of the model. The new model is displayed in a new frame whose ID can be used as the target ID for commands to the new graph.

• onModelSaved

is triggered after the current model has been saved.

• onNodeAdded

is triggered after a node has been added to the Network.

• onNodeDoubleClicked

is triggered after a node has been double-clicked.

• onNodePropsChanged

is triggered after the properties of a node have been changed. This does not apply for the node position. If the node position is changed, the event onLayoutChanged is triggered.

• onNodeRemoved

is triggered after a node has been removed.

• onNodeSelected

is triggered after a node has been selected.

• onTraceLevelChanged

is triggered after the trace level of JNet has been changed.

Overview of Inherited and Additional Events

Name Class Parameters

onEdgePropsChanged Network (String edge, String graph)

onEdgeSelected Network (String edge, String graph)

onGeneric Network (String component, String graph, String name, String parameters)

onGraphAdded Network (String graph, String subGraph)

onGraphRemoved Network (String graph, String subGraph)

onInitialized Network (String graph)

onLayoutChanged Network (String graph, String node)

onLinkAdded Network (String graph, String link)

onLinkRemoved Network (String graph, String link)

onModelAdded Network (String graph)

onModelDirty Network (String graph)




onModelExtracted Network (String graph, String newGraph)

onModelSaved Network (String graph, String reply)

onNodeAdded Network (String graph, String node)

onNodeDoubleClicked Network (String graph, String node, String subComponents)

onNodePropsChanged Network (String graph, String node)

onNodeRemoved Network (String graph, String node)

onNodeSelected Network (String graph, String node, String subComponents)

onTraceLevelChanged Network (String graph, String level)

4.1.28 Web Dynpro OfficeControl API – IWDOfficeCont rol

Definition The OfficeControl UI element allows you to add an Office document to a view. This allows you to display the following Office documents in a Web Dynpro application:

• Microsoft Word documents

• Microsoft Excel documents

.

The OfficeControl UI element is made available as an ActiveX control, so that the UI element can be displayed in browsers that support ActiveX controls.

For browsers which do not support ActiveX controls, the following runtime exception is raised: Office Integration through Applet is not supported.

This means that:

• The ActiveX control enables display of the following documents:

� Microsoft Word documents with the doc file extension

� Microsoft Excel documents with the xls file extension

The implementation of the OfficeControl UI element supports:

• Opening a new document by calling the method ShowDocument : WDOfficeControlMethods.showDocument(IWDController refToTheController, String strControlId

• Opening a new document by calling the method ShowDocument : WDOfficeControlMethods.showDocument(IWDController refToTheController, String strControlId

• Saving the document by calling the method SaveDocument : WDOfficeControlMethods.saveDocument(IWDController refToTheController, String strControlId

• Closing the document by calling the method CloseDocument : WDOfficeControlMethods.closeDocument(IWDController refToTheController, String strControlId




Note that from SAP NetWeaver 04 Release SP11 onwards, you can exclusively open or close a document by setting the property visible of the OfficeControl UI element to visible resp. blank .

Prerequisites The prerequisite for using the OfficeControl UI element is the installation of one of the following software programs:

• Microsoft Office 2000

• or Microsoft Office XP

.

If you have Microsoft Internet Explorer installed, check your Internet Options to find our whether the ActiveX control elements for executing and initializing are enabled. To do this, choose Internet Options → Security → Custom level → ActiveX controls and plug-ins → Enable. Otherwise, the Microsoft Word or Excel document cannot be displayed.

Description of the UI Element Properties • activateInPlace

Controls whether the document appears in the browser window or the system opens the Office application linked to the document type in a separate window to display the document. If you have assigned the value false to the activateInPlace property and the value ms_word to the documentType property, the Microsoft Word application opens and display the content in the Microsoft Word user interface. The default value for this property is true .

If you have assigned the value false to this property, you should then make sure that you assign small values to the height and width properties, because these values are not ignored and act as placeholders in the view of the Web Dynpro application. In the view, the UI element takes up as much empty space as you have specified for the values of the height and width properties. You should therefore overwrite the default value of 300 with a smaller number, for example, 5. If you have assigned the value true to this property, you should use suitable values for displaying the document, so that the document is readable and the user does not have to scroll too often, because he or she cannot increase the size of the document in the browser window at runtime.

• controlID At the moment, you should not use this property.

• dataSource This property is used to specify the data source. You can use it to specify the path to the context attribute, which makes the data available. The context attribute must be of the binary type.

• documentName You can use this property to describe the document name.

• documentName You can use this property to describe the document type that is to appear. The




documentType property can take the following values and is represented by the list type WDOfficeDocumentType :

ms_word Microsoft Word document with the doc file extension

ms_excel Microsoft Excel document with the xls file extension

• enableReadWrite Determines the mode of the document to be opened and controls whether the user can edit the document and save it back with changed content.

• showDecoration This property does not currently affect the appearance of the document.


Value Bindable

activateInPlace IWDOfficeControl boolean true bindable

controlId IWDOfficeControl String not_bindable

dataSource IWDOfficeControl Object bindable_mandatory

documentName IWDOfficeControl String bindable

documentType IWDOfficeControl WDOfficeDocumentType ms_word bindable

enableReadWrite IWDOfficeControl boolean true bindable

enabled [External] IWDUIElement boolean true bindable

height [External] IWDAbstractActiveComponent String 300px bindable

showDecoration IWDOfficeControl boolean true bindable

tooltip [External] IWDUIElement String bindable

visible [External] IWDUIElement WDVisibility visible bindable

width [External] IWDAbstractActiveComponent String 300px bindable

Events • onClose

( obsolete from SAP NetWeaver 04 Release SP11 onwards): Describes the action that is performed when the document is closed. This is the case, when the document is displayed in a separate window and the user chooses either the key combination Alt + F4 or the Close icon on the toolbar of the Office application to close the document. The onClose event is also triggered when the Web Dynpro application calls the method WDOfficeControlMethods.closeDocument(IWDController refToTheController, String strControlId .

Event parameters Type Function

hasChanged boolean This parameter indicates whether the data has changed after closing the




document.

• onSave Describes the action that is executed when the document is saved. This is the case, when the user chooses either the key combination Cntl + S or the Save icon on the toolbar of the Office application. The onSave event is also triggered when the Web Dynpro application calls the method WDOfficeControlMethods.saveDocument(IWDController refToTheController, String strControlId .

Event parameters Type Function

hasChanged boolean This parameter indicates whether the data has changed after saving the document.

Data Binding The dataSource property must be bound to a context attribute. The context attribute to which the dataSource UI element property is bound, must be of type binary.

For information about binding the UI element properties, see Example of Using an Office Document [Page 162].

Methods in the Web Dynpro IWDOfficeControl API Method Name General Return Value Function

bindActivateInPlace (String path) Binds the value of the activateInPlace property to the content element specified by the path.

bindDataSource (String path) Binds the dataSource property to the context node specified by a path.

bindDocumentName (String path) Binds the value of the documentName property to the content element specified by the path.

bindDocumentType (String path) Binds the value of the documentType property to the content element specified by the path.

bindEnableReadWrite (String path) Binds the value of the enableReadWrite property to the




content element specified by the path.

bindingOfActivateInPlace String Returns the path of the content element to which the activateInPlace property is bound. Returns NULL if no binding exists.

bindingOfDataSource String Returns the path of the context element to which the dataSource property is bound. Returns NULL if no binding exists.

bindingOfDocumentName String Returns the path of the content element to which the documentName property is bound. Returns NULL if no binding exists.

bindingOfDocumentType String Returns the path of the content element to which the documentType property is bound. Returns NULL if no binding exists.

bindingOfEnableReadWrite String Returns the path of the content element to which the enableReadWrite property is bound. Returns NULL if no binding exists.

bindingOfShowDecoration String Returns the path of the content element to which the showDecoration property is bound. Returns NULL if no binding exists.

bindShowDecoration (String path) Binds the value of the showDecoration property to the content element specified by the path.




getActivateInPlace boolean Returns the value of the activateInPlace property.

getControlId String Returns the value of the controlId property.

getDataSource Object Returns the value of the dataSource property.

getDocumentName String Returns the value of the documentName property.

getDocumentType WDOfficeDocumentType Returns the value of the documentType property.

getEnableReadWrite boolean Returns the value of the enableReadWrite property.

getOnClose

( obsolete from SAP NetWeaver 04 Release SP11 onwards)

IWDAction Returns the action that is executed when the event onClose is triggered.

getOnSave IWDAction Returns the action that is executed when the event onSave is triggered.

getShowDecoration boolean Returns the value of the showDecoration property.

mappingOfOnClose


IWDParameterMapping Returns the parameter mapping for the onClose action.

mappingOfOnSave IWDParameterMapping Returns the parameter mapping for the onSave action.

setActivateInPlace (boolean activateInPlace) Sets the value of the activateInPlace property.

setControlId (String controlId) Sets the value of the controlId property.




setDataSource (Object dataSource) Sets the value of the dataSource property.

setDocumentName (String documentName) Sets the value of the documentName property.

setDocumentType (WDOfficeDocumentType documentType)

Sets the value of the documentType property.

setEnableReadWrite (boolean enableReadWrite)

Sets the value of the enableReadWrite property.

setOnClose


(IWDAction action) Sets the action that is executed when the event onClose is triggered.

setOnSave (IWDAction action) Sets the action that is executed when the event onSave is triggered.

setShowDecoration (boolean showDecoration)

Sets the value of the showDecoration property.

Additional methods described in the following APIs are available using inheritance: IWDAbstractActiveComponent [External], IWDUIElement [External], IWDViewElement [External].

Example You can find an example of creating the OfficeControl UI element at Example of Using an Office Document [Page 162].

4.1.28.1 Example for the Use of an Office Document

Note that the following description is only valid up to and including SAP NetWeaver Release SP10. From SAP NW 04 Release SP11 on, the APIs showDocument and closeDocument , including the methods of the closeDocument API, are obsolete. Instead, exclusively use the visible property of the OfficeControl UI element to display or close a document: To open a document, set the value of the property visible to visible ; to close the document, set it to blank .

Use The example below illustrates the use of Office documents in a Web Dynpro application. Here you will learn about the structure of the view, the associated context structure, and the data




binding of UI element property dataSource to a context attribute that contains the necessary data as a byte array and therefore must have data type binary .

In this example, pressing a pushbutton opens the Microsoft Word document example.doc in the browser window. The example.doc file is contained in directory C:\temp\; the SAP Java Engine must also be installed on the C:\ drive.

The UI element retrieves the required data from the corresponding view context. When using the fillNode supply function, a byte array is filled with the file content and the context attribute DocumentContent of the type binary is filled.

By pressing the pushbutton you trigger an event whose event handling calls the static method ShowDocument – which is delivered by the class WDOfficeControlMethods – to display the document.

You use the Office UI element properties, which refers to the Web Dynpro OfficeControl API .

Prerequisites • You have already created the Web Dynpro project TestOfficeControl which is

displayed in the Web Dynpro Explorer.

• You have created the Web Dynpro application OfficeControlExampleApplication in this project.

• You have created the Web Dynpro component OfficeControlExampleComponent within this application.

• The Web Dynpro component contains the view TestViewOfficeControl in which you want to insert the UI element OfficeControl.

For a detailed description of the procedure for creating Web Dynpro projects, Web Dynpro components, the context structure as well as the layout of the view, refer to the tutorial Creating Your First Web Dynpro Application.

Procedure

Designing the Layout for the View TestViewOfficeCon trol in Which You Will Display the Office Document ...

1. To open the view for editing in the View Designer, double-click the view TestViewOffice Control.

2. Specify the value of property text of the TextView UI element in the Properties tab. The TextView UI element with the ID DefaultTextView is used to label the office document and is generated during the view creation by default. In this example, the value “Show Office Document” is assigned to the text property of this UI element.

3. Insert an OfficeControl UI element with ID OfficeControl1 in the view. For this purpose, choose Insert Child in the context menu (right mouse button) for RootUIElementContainer in the outline window or drag the UI element over the corresponding UI element icon in the View Designer.

4. Insert the pushbutton UI element using the ID Button .




Creating the Context Structure for the View TestVie wOfficeControl ...

1. Switch to the Context tab page in the View Designer.

2. Choose New → Value and create the context node DocumentSourceNode . Choose Finish.

3. Choose New → Value Attribute and create the context attribute DocumentContent . This context attribute must be of the type binary . Choose Finish.

4. To define the supply function, assign the value fillNode to the property supplyFunction by selecting the icon .

Context structure

Properties of the value node DocumentSourceNode

Properties of the value attribute DocumentContent

If you define the context structure first after creating the view, you can bind the UI element properties to the corresponding context elements directly after the insertion of the UI element into the view.




Creating the Action getDocument

If you defined the action, the event handler onActiongetDocument is automatically created in the controller implementation.

Defining Data Binding of the User Interface Element Properties ...

1. Define data binding for the OfficeControl UI element properties (see the following screenshot).




2. Define the data binding of pushbutton UI element – binding for action getDocument .

Controller Implementation of the View TestViewOffic eControl: Supplying Data

The content of the documents is supplied by supply function fillNode during initialization of the view. In the process, the data is converted to a byte array and saved in this format in the context. The application reads the content of the document as a binary file and fills the node element with this byte array at runtime. In the example source code below, the document is read from directory path C:/temp/ and converted to a byte array with method getBytesFromFile . The getDocument action, which is executed by pressing the pushbutton, in turn converts the byte array using with method showDocument . It then displays it as a Word document in the browser window because the property activateInPlace is set to true . ...

Switch to the Implementation tab page and add the following source code: The source code shows only the most important parts of the controller implementation: public void fillNode(IPrivateTestViewOfficeControl.IDocumentSo urceNodeNode node, IPrivateTestViewOfficeControl.IContextElement parentElement) { //@@begin fillNode(IWDNode,IWDNodeElement) ISimpleTypeModifiable mod = node.getNodeInfo().getAttribute( "DocumentContent" ).getModifiableSimpleType(); ModifiableBinaryType bin = (ModifiableBinaryType) mod; bin.setMimeType( new WebResourceType( "doc" , "application/msword" , false ));




IPrivateTestViewOfficeControl.IDocumentSourceNode Element element = node.createDocumentSourceNodeElement(); node.addElement(element); try { byte [] bytes = getBytesFromFile( new File( "C:\\temp\\example.doc" )); element.setDocumentContent(bytes); } catch (IOException e) { // do something } //@@end } //@@begin javadoc:onActiongetDocument(ServerEvent ) /** Declared validating event handler. */ //@@end public void onActiongetDocument(com.sap.tc.webdynpro.progmodel. api.IWDCustomEvent wdEvent ) { //@@begin onActiongetDocument(ServerEvent) WDOfficeControlMethods.showDocument( this .wdThis.wdGetAPI(), "OfficeControl1" ); //@@end } /* * The following code section can be used for any Ja va code that is * not to be visible to other controllers/views or t hat contains constructs * currently not directly supported by Web Dynpro (s uch as inner classes or * member variables, and so on). </p> * * Note: The content of this segment is not managed/ controlled in any way * by the Web Dynpro Designtime or the Web Dynpro Ru ntime. */ //@@begin others public static byte [] getBytesFromFile(File file) throws IOException { FileInputStream is = new FileInputStream(file); long length = file.length(); byte [] bytes = new byte [( int )length]; long bytesRead = is.read(bytes); if (bytesRead < length) { throw new IOException( "Could not completely read file " +file.getName()); } is.close(); return bytes;




} //@@end }

Result

Before you can call the Web Dynpro application, you must build the Web Dynpro project and deploy the Web Dynpro application on the SAP Java Engine.

You call the Web Dynpro application in the browser using a Web address. When the pushbutton labeled Show document is pressed, a Microsoft Word document whose content is saved in the file example.doc is displayed in the browser window.

If you set the property enableReadWrite to true , you can edit the file contents and save the changed file.

4.1.29 PhaseIndicator

Definition Similar to the RoadMap UI element, the PhaseIndicator UI element displays the steps in a wizard. Each step is represented by a separate phase object. As opposed to using the




RoadMap UI element, the application development can display larger steps using the PhaseIndicator UI element which may require more time by the user.

Example The following figure shows the visual representation of a PhaseIndicator in several statuses:

The symbols show the following values for the PhaseStatus:

• Phase 1: completed

• Phase 2: warning

• Phase 3: unavailable .

Structure Several phase elements can be assigned to the PhaseIndicator.

UIElementM

ViewElementMM

PhaseIndicator

accessibil i tyDescription : TranslatableTextbackgroundDesign : PhaseIndicatorBackgroundDesign = em phasizedfi rstVisiblePhase : StringselectedPhase : StringonSelect : StringonSelect_phase : String

0..*

1

Phase

description : T ranslatableTextenabled : Boolean = truestatus : PhaseStatus = normaltool tip : TranslatableTexttextDi rection : T extDirection = inheri tvisible : Boolean = true

PhaseStatus

normal : String = 0completed : String = 1warning : String = 2unavailable : String = 3

<<enum >>




4.1.29.1 Web Dynpro PhaseIndicator API – IWDPhaseIn dicator



• backgroundDesign Specifies the background color. The backgroundDesign property can be filled with the following values and is represented by the enumeration type WDPhaseIndicatorBackgroundDesign .

emphasized The background is colored.

transparent The background is transparent.

• firstVisiblePhase Contains the ID of the first visible phase.

• selectedPhase Contains the ID of the selected phase.


Value Bindable

accessibilityDescription IWDPhaseIndicator String bindable

backgroundDesign IWDPhaseIndicator WDPhaseIndicatorBackgroundDesign emphasized bindable


firstVisiblePhase IWDPhaseIndicator String bindable

selectedPhase IWDPhaseIndicator String bindable

tooltip IWDUIElement String bindable


Events • onSelect

The property contains the action that is executed when the phase is selected. The event parameter is the ID of the selected phase.


phase String


4.1.29.2 Web Dynpro Phase API – IWDPhase

Definition The phase element is a step in a PhaseIndicator UI element [Page 170].




Description of UI Element Properties • description

Allows you to display a text on a phase.

• enabled Specifies whether or not the phase is activated.

• state Describes the status of the phase. The status property can be filled with the following values and is represented by the enumeration type WDPhaseStatus .

normal Describes the normal state of the phase.

completed Indicates that the phase is complete.

warning Describes a warning state of the phase.

unavailable Indicates that the phase is not available.

• textDirection Specifies the text direction and allows you to use a Phase element for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type WDTextDirection .





• tooltip Describes a note for the UI element that is displayed when the user places the cursor on the phase.

Overview of Inherited and Additional Properties Name Interface Type Initial Value Bindable Value Required

description IWDPhase String bindable No

enabled IWDPhase boolean true bindable No

status IWDPhase WDPhaseStatus normal bindable No

textDirection IWDPhase WDTextDirection inherit bindable No

tooltip IWDPhase String bindable No

visible IWDPhase boolean true bindable No

Methods in the Web Dynpro IWDPhase API Method Name Parameter Return Value Description

bindDescription (String path) Binds the value of the description property to the context element specified by




the path.

bindEnabled (String path) Binds the value of the enabled property to the context element specified by the path.

bindingOfDescription String Returns the path of the context element to which the description property is bound. Returns NULL if no binding exists.

bindingOfEnabled String Returns the path of the context element to which the enabled property is bound. Returns NULL if no binding exists.

bindingOfStatus String Returns the path of the context element to which the status property is bound. Returns NULL if no binding exists.

bindingOfTextDirection String Returns the path of the context element to which the textDirection property is bound. Returns NULL if no binding exists.


bindingOfVisible String Returns the path of the context element to which the visible property is bound. Returns NULL if no binding exists.

bindStatus (String path) Binds the status property to the context node specified by a path.

bindTextDirection (String path) Binds the textDirection property to the context node specified by a




path.


bindVisible (String path) Binds the value of the visible property to the context element specified by the path.

getDescription String Returns the value of the description property.

getEnabled boolean Returns the value of the enabled property.

getPhaseIndicator IWDPhaseIndicator Returns the PhaseIndicator element that contains this phase element.

getStatus WDPhaseStatus Returns the value of the status property.

getTextDirection WDTextDirection Returns the value of the textDirection property.


getVisible boolean Returns the value of the visible property.

setDescription (String description) Sets the value of the description property.

setEnabled (Boolean enabled) Sets the value of the enabled property.

setStatus (WDPhaseStatus status)

Sets the value of the status property.

setTextDirection (WDTextDirection textDirection)

Sets the value of the textDirection property.


setVisible (boolean visible) Sets the value of the visible property.





4.1.30 ProgressIndicator API

Definition The ProgressIndicator UI element shows how much progress an activity has made in the form of a horizontal bar, along with the value that you have assigned to the percentValue property. You can use the displayValue property to display a text in the progress bar on the left side of the UI element. This makes it possible to provide descriptions with specific percentage values. You can hide the DisplayValue value using the showValue property. You can display the ProgessIndicator UI element in different colors using the barColor property. You can assign a popup menu to a ProgressIndicator.

Use The ProgressIndicator can, for example, be used to display the completion status of a project as a percentage.

Description of UI Element Properties • barColor

Specifies the logical color of the UI element. The default value of this property is neutral . The barColor property can be filled with the following values and is represented by the enumeration type WDProgressIndicatorBarColor .

Value Appearance of UI element ((width = 100 Pixel; displayValue = no value)

Short Description

critical

Bar shown in orange.

negative

Bar shown in red.

neutral

Bar shown in blue.

positive

Bar shown in green.

• displayValue Used to display a text in the progress bar. You can set a value in the application to display a text such as “done” or “critical” for a specified percentage value. If you do not assign a value to this property, it takes by default the value you have assigned to percentValue , displayed as a text with a percentage sign – for example, 42%.

• percentValue Specifies the progress made as a percentage.

• showValue Specifies whether the value of the property displayValue – a text on the progress bar – is displayed or hidden.

• width Specifies the width of the ProgressIndicator. You can specify the width in CSS units like em, ex, pixel, or percentage.





Required

barColor IWDProgressIndicator

WDProgressIndicatorBarColor

neutral bindable No

displayValue IWDProgressIndicator

String bindable No


percentValue IWDProgressIndicator

int 0 bindable No

showValue IWDProgressIndicator



bindable No


width IWDProgressIndicator

String bindable No

The inherited enabled property is ignored and does not affect the browser.

4.1.31 Web Dynpro RadioButton API - IWDRadioButton

Definition The RadioButton UI element is a button with two states (on/off) that enables the user to select options. The RadioButton UI element allows you to spread the displayed radio buttons individually on the screen instead of grouping them in a table. You can toggle the radio button when you bind the UI elements to the same context attribute.

The radio button is selected if the context attribute to which the selectedKey property is bound, contains the value of the key that belongs to this radio button. The key is specified by the keyToSelect property.

Description of UI Element Properties • keyToSelect

This property specifies the value of the key used for the selection of this radio button.

• selectedKey This property specifies the path of the context attribute that stores the currently selected key.








• text This property describes the text next to the radio button.

• textDirection Specifies the text direction and allows you to use a radio button for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type WDTextDirection .




• The default value for this property is inherit .



Required

enabled [External]

IWDUIElement boolean true bindable No

keyToSelect

IWDRadioButton

String bindable Yes

selectedKey

IWDRadioButton

String bindable_mandatory

Yes

readOnly IWDRadioButton


state IWDRadioButton

WDState normal

bindable No

text IWDRadioButton


bindable No

textDirection

IWDRadioButton


tooltip [External]

IWDUIElement String (TranslatableText)

bindable No

visible [External]

IWDUIElement WDVisibility visible bindable No

Events • onSelect

This property can assign the action that is executed when the user selects the RadioButton UI element.


key String





Mobile Characteristics The UI element RadioButton supports the development of mobile applications for pocket PCs, BlackBerry wireless handhelds, and Nokia Series 80 devices (see Mobile Web Dynpro [External]).

However, several properties supported in the desktop browser cannot be used. These include:

Variances of the properties

Properties Pocket PC BlackBerry Wireless Handheld

Nokia Series 80 Devices

enabled ignored ignored supported

readOnly ignored ignored supported

state ignored ignored ignored

tooltip ignored ignored ignored

Methods in the Web Dynpro IWDRadioButton API Method Name Parameter Return Value Description

bindingOfKeyToSelect String Returns the path of the context element to which the keyToSelect property is bound. Returns NULL if no binding exists.

bindingOfReadOnly String Returns the path of the context element to which the readOnly property is bound. Returns NULL if no binding exists.

bindingOfSelectedKey String Returns the path of the context element to which the selectedKey property is bound. Returns NULL if no binding exists.

bindingOfState String Returns the path of the context element to which the state property is bound. Returns NULL if no binding exists.

bindingOfText String Returns the path of the context element to which the text




property is bound. Returns NULL if no binding exists.


bindKeyToSelect (String path) Binds the keyToSelect property to the context node specified by a path.

bindReadOnly (String path) Binds the readOnly property to the context node specified by a path.

bindSelectedKey (String path) Binds the value of the selectedKey property to the context element specified by the path.

bindState (String path) Binds the state property to the context node specified by a path.

bindText (String path) Binds the value of the text property to the context element specified by the path.

bindTextDirection (String path) Binds the textDirection property to the context node specified by a path.

getKeyToSelect String Returns the value of the keyToSelect property.

getOnSelect IWDAction Returns the action that is executed when the onSelect event is triggered.

getReadOnly boolean Returns the value of the readOnly property.




getSelectedKey String Returns the value of the selectedKey property.

getState WDState Returns the value of the state property.

getText String Returns the value of the text property.


mappingOfOnSelect IWDParameterMapping Returns the parameter mapping for the onSelect action.

setKeyToSelect (String keyToSelect)

Sets the value of the keyToSelect property.

setOnSelect (IWDAction action) Sets the action that is executed when the onSelect event is triggered.

setReadOnly (boolean readOnly) Sets the value of the readOnly property.

setSelectedKey (String selectedKey)

Sets the value of the selectedKey property.

setState (WDState state) Sets the value of the state property.

setText (String text) Sets the value of the text property.








4.1.31.1 Web Dynpro RadioButtonGroupByKey API - IWDRadioButtonGroupByKey

Definition The RadioButtonGroupByKey UI element groups multiple radio buttons in a table. Unlike the CheckBoxGroup UI element, this UI element allows the selection of one element only.



• colCount Specifies the number of columns in which the radio button UI elements are displayed.

• selectedKey Specifies the path to the context attribute that stores the currently selected key.

• readOnly Specifies whether or not the user can select a radio button within the radio button group.

• state Describes the error status of the UI element. The state property can be filled with the following values and is represented by the enumeration type WDState .



• textDirection Specifies the text direction and allows you to use a checkbox for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type WDTextDirection .





• width Determines the width of the UI element that you can specify in CSS sizes, such as em, ex, pixels or percentage values.



Required

accessibilityDescription IWDRadioButtonGroupByKey String (Translatable Text)

bindable No




colCount IWDRadioButtonGroupByKey int 1 bindable No

enabled [External] IWDUIElement Boolean true bindable No

selectedKey IWDRadioButtonGroupByKey String bindable_mandatory Yes

readOnly IWDRadioButtonGroupByKey boolean false bindable No

state IWDRadioButtonGroupByKey WDState normal bindable No

textDirection IWDRadioButtonGroupByKey WDTextDirection inherit bindable No

tooltip [External] IWDUIElement String bindable No


width IWDRadioButtonGroupByKey String (CSS size)

bindable No

Events • onSelect

This property contains the action that is executed when the RadioButtonGroupByKey UI element is selected.


key String


Data Binding The contex node must contain a context attribute y. The attribute is assigned to a data type that can contain a value set (key value pair). The selected keys of the RadioButtonGroupByKey UI element are the values of this value set. The texts to be displayed are the corresponding descriptions. The currently selected key is identical to the current value of the attribute y. The selectedKey property is bound to the context attribute y.

For further information, refer to Data Binding of a Dropdown List Box and Radio Button Group [Page 299]. For a code example, refer to Key Binding [Page 296].

Mobile Characteristics The UI element RadioButtonGroupByKey supports the development of mobile applications for pocket PCs, BlackBerry wireless handhelds, and Nokia Series 80 devices (see Mobile Web Dynpro).












Methods in the Web Dynpro IWDRadioButtonGroupByKey API Method Name Parameter Return Value Description

bindAccessibilityDescription (String path) Binds the accessibilityDescriptionproperty to the context node specified by a path.

bindColCount (String path) Binds the colCount property to the context node specified by a path.

bindingOfAccessibilityDescription String Returns the path of the context element to which the accessibilityDescriptionproperty is bound. Returns NULL if no binding exists.

bindingOfColCount String Returns the path of the context element to which the colCountproperty is bound. Returns NULL if no binding exists.

bindingOfReadOnly String Returns the path of the context element to which the readOnlyproperty is bound. Returns NULL if no binding exists.

bindingOfSelectedKey String Returns the path of the context element to which the selectedKey property is bound.Returns NULL if no binding exists.

bindingOfState String Returns the path of the context element to which the stateproperty is bound. Returns NULL if no binding exists.


bindingOfWidth String Returns the path of the context element to which the widthproperty is bound. Returns NULL if no binding exists.


bindSelectedKey (String path) Binds the value of the selectedKey property to the context element specified by the path.

bindState (String path) Binds the state property to the context node specified by a




path.

bindTextDirection (String path) Binds the textDirectionproperty to the context node specified by a path.

bindWidth (String path) Binds the value of the widthproperty to the context element specified by the path.

getAccessibilityDescription String Returns the value of the accessibilityDescription property.

getColCount int Returns the value of the colCount property.

getOnSelect IWDAction Returns the action that is executed when the onSelectevent is triggered.


getSelectedKey String Returns the value of the selectedKey property.

getState WDState Returns the value of the stateproperty.


getWidth String Returns the value of the widthproperty.

mappingOfOnSelect IWDParameterMapping Returns the parameter mapping for the onSelect action.

setAccessibilityDescription (String accessibilityDescription)


setColCount (int colCount) Sets the value of the colCountproperty.

setOnSelect (IWDAction action) Sets the action that is executed when the onSelect event is triggered.

setReadOnly (boolean readOnly) Sets the value of the readOnlyproperty.

setSelectedKey (String selectedKey) Sets the value of the selectedKey property.

setState (WDState state) Sets the value of the st ateproperty.



setWidth (String width) Sets the value of the widthproperty.






4.1.31.2 Web Dynpro RadioButtonGroupByIndex API - IWDRadioButtonGroupByIndex

Definition The RadioButtonGroupByIndex UI element groups multiple radio buttons in a table. Unlike the CheckBoxGroup UI element, this UI element allows the selection of one element only.



• colCount Specifies the number of columns in which the RadioButton UI elements are displayed.

• readOnly Specifies whether or not the user can select a radio button within the radio button group.

• state Describes the status of the UI element. The state property can be filled with the following values and is represented by the enumeration type WDState .

normal Describes the default state of the UI elemen t.

required Specifies whether the entered value is req uired.

• textDirection Specifies the text direction and allows you to use a checkbox for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type WDTextDirection .

inherit The text direction is inherited from the pa rent element. Therefore, the text direction is identical to the one of the p arent element.




• texts Specifies the path to the context attribute that provides the texts of the radio buttons. The context attribute must be an attribute of a multiple context node which stores the data of the radio buttons. Each node element represents a radio button.




• width Determines the width of the UI element that you can specify in CSS sizes, such as em, ex, pixels or percentage values.



Required

accessibilityDescription IWDRadioButtonGroupByIndex

String (Translatable Text)

bindable No

colCount IWDRadioButtonGroupByIndex

int 1 bindable No


readOnly IWDRadioButtonGroupByIndex


state IWDRadioButtonGroupByIndex

WDState normal

bindable No

textDirection IWDRadioButtonGroupByIndex

WDTextDirection

inherit bindable No

texts IWDRadioButtonGroupByIndex


Yes

tooltip [External] IWDUIElement String bindable No

visible [External] IWDUIElement WDVisibility visible

bindable No

width IWDRadioButtonGroupByIndex

String bindable No

Events • onSelect

This property contains the action that is executed when the RadioButtonGroupByIndex UI element is selected.


index int





Method Name Parameter Return Value Description

bindAccessibilityDescription (String path) Binds t he accessibilityDescription property to the context node specified by a path.

bindColCount (String path) Binds the colCount property to the context node specified by a path.



bindingOfColCount String Returns the path of the context element to which the colCount property is bound. Returns NULL if no binding exists.


bindingOfState String Returns the path of the context element to which the state property is bound . Returns NULL if no binding exists.


bindingOfTexts String Returns the path of the context element to which the texts property is bound. Returns NULL if no binding exists.




bindTextDirection (String path) Binds the textDirection property to the context node specified by a path.

bindTexts (String path) Binds the texts property to the context node specified by a path .


getAccessibilityDescription String Returns the val ue of the accessibilityDescription property .

getColCount int Returns the value of the colCount property .




Data Binding The context must provide a context node X that can contain 0 to n elements (X.cardinality=0..n). The context node must contain a context attribute y that is of a simple type and provides the texts for the radio buttons. For the data binding, the property texts is bound to the attribute y. Each node element represents a radio button. The selected index is specified by the lead selection of the node X. For further information, refer to Data Binding of a Dropdown List Box and Radio Button Group [Page 299] and Code Examples of Data Binding [Page 292].

Mobile Characteristics The UI element RadioButtonGroupByIndex supports the development of mobile applications for pocket PCs, BlackBerry wireless handhelds, and Nokia Series 80 devices (see Mobile Web Dynpro).









Methods in the Web Dynpro IWDRadioButtonGroupByInde x API Additional methods are available using inheritance: IWDUIElement [External], IWDViewElement [External].


4.1.32 RoadMap API

Definition The RoadMap UI element displays the steps in a wizard. Each step is represented by a separate RoadMapStep Object [Page 189]. You can tag the starting point and endpoint of this UI element using different symbols, which are defined by the enumeration type WDRoadMapEdgeDesign. Assigning the value more to the property startPointDesign or endPointDesign indicates to the user that there are other steps before the first visible step, or after the last visible step.

Use The RoadMap UI element is used to display step by step workflows. This enables the application development to display small steps of a clearly defined work process.






• endPointDesign Specifies the design of the last step of the RoadMap element. The endPointDesign property can take the following values and is represented by the enumeration type WDRoadMapEdgeDesign.

disabled

No event can be triggered with this value when selecting the end point. Therefore, the end point is displayed as not activated.

more

Indicates that there are more steps still to come in the process.

moreDisabled

No event can be triggered with this value when selecting the end point. Therefore, the end point is displayed as not activated However, this value indicates that there are more preceding steps.

selected

You can highlight the end point in a different color (that is, as if it were selected) – for example, to show that there is an informative text attached to it.

standard

The default display for the end point of a RoadMap UI element.

• selectedStep Contains the ID of the selected step.

• startPointDesign Specifies the design of the first step of the RoadMap UI element. The startPointDesign property can be filled with the following values and is represented by the enumeration type WDRoadMapEdgeDesign.

disabled

No event can be triggered with this value when selecting the starting point. Therefore, the starting point is displayed as not activated.

more

Indicates that more steps preceded this step.

moreDisabled

No event can be triggered with this value when selecting the starting point. Therefore, the starting point is displayed as not activated However, this value indicates that there are more preceding steps.




selected

You can highlight the end point in a different color – that is as if it were selected), to show that there is an informative text attached to it.

standard

The default display for the starting point of a RoadMap UI element.



Required

accessibilityDescription IWDRoadMap String (Translatable Text) bindable No

enabled IWDUIElement Boolean true bindable No

endPointDesign IWDRoadMap WDRoadMapEdgeDesign bindable No

selectedStep IWDRoadMap String bindable No

startPointDesign IWDRoadMap WDRoadMapEdgeDesign bindable No



Events • onLoadSteps (boolean atEnd)

Describes the action that is executed when the RoadMap UI element contains more steps that are displayed and the user selects the icon for more steps. The parameter atEnd specifies whether the RoadMap UI element contains more steps at the end or at the beginning.

• onSelect (String step) Describes the action that is executed when the user selects a RoadMap step. The event parameter of the type String corresponds to the ID of the selected step.

4.1.32.1 RoadMapStep API

Definition The RoadMapStep element represents a step in a RoadMap UI element. The following graphic shows how the UI element is displayed:

Description of UI Element Properties • description

Allows you to display a text underneath the individual RoadMap steps.




• design

disabled The RoadMapStep is displayed as disabled – for example, it is grayed out.

roundtrip The RoadMapStep is displayed with a design symbolizing a round trip.

selected The RoadMapStep is displayed as selected – for example, it is highlighted in orange.

standard The RoadMapStep is displayed with the default color.

• enabled Specifies whether or not the RoadMap step is activated. Only an activated RoadMap step can trigger events.

• name Allows you to specify a label for the RoadMapStep, which is displayed in the RoadMapStep itself.

• textDirection Specifies the text direction and allows you to use a RoadMap step for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type WDTextDirection .

Inherit The text direction is inherited from the parent element. Therefore, the text direction is identical to the one of the parent element.




• tooltip Describes a note for the RoadMapStep. The note is displayed when the user places the cursor on the UI element.

• type Specifies the type of the RoadMap step. The type property can be filled with the following values and is represented by the enumeration type WDRoadMapStepType.

roundtripClosed Specifies a step in the RoadMap UI element which contains substeps. These substeps are not displayed on the user interface.

roundtripEnd Specifies the end point of a round trip.

roundtripStart Specifies the starting point of a round trip.

standard Specifies the standard step of a RoadMap UI element.

substep Specifies the substep used for round trips.

• visible Specifies whether or not the RoadMap step is displayed. This property enables you to easily hide a RoadMap step.




Overview of Inherited and Additional Properties Name Interface Type Initial Value Bindabl

e Value Required

design IWDRoadMapStep WDRoadMapStepDesign standard bindable No

description IWDRoadMapStep String (TranslatableText) bindable No

enabled IWDRoadMapStep boolean true bindable No

name IWDRoadMapStep String (TranslatableText) bindable No

textDirection IWDRoadMapStep WDTextDirection inherit bindable No

tooltip IWDRoadMapStep String (TranslatableText) bindable No

type IWDRoadMapStep WDRoadMapStepType standard bindable No

4.1.32.2 MultipleRoadMapStep API

A MultipleRoadMapStep is bound to a context node and enables the application developer to dynamically adapt the RoadMap. Depending on how many elements are assigned to the context node, the number of displayed RoadMapSteps can vary.




Required

dataSource IWDMultipleRoadMapStep


Yes

description IWDRoadMapStep

String bindable No

design IWDRoadMapStep

WDRoadMapStepDesign


enabled IWDRoadMapStep


name IWDRoadMapStep

String bindable No

textDirection IWDRoadMapStep

WDTextDirection

inherit bindable No

tooltip IWDRoadMapStep

String bindable No

type IWDRoadMapStep

WDRoadMapStepType





visible IWDRoadMapStep


4.1.33 Table The Table UI element allows the two-dimensional display of data in cells arranged into rows and columns. The UI element consists of a header area, context text area, and footer area. The lead selection of a row is highlighted in color when displayed on the screen. The Table UI element can contain any number of GroupedTableColumn elements. The following graphic shows how the UI element is displayed.

Display of a Table

Pushbuttons provided in the footer of the table allow navigation. The following scroll bar functions are available:

First page Page up Line up

Last page Page down Line down

Table Structure

Columns

A table – which is an element of the IWDTable – consists of grouped table columns which can be of the type IWDTableColumn or IWDTableColumnGroup. Each group can contain additional groups and columns. You can use the TableColumnGroup to group columns under a common header. You can use the fixedPosition property to fix a column at the left or right side and thereby take out the column of the scroll area.

When using the table template assistent, only TableColumn elements are created which you cannot group at a later time.

A specific table column is the IWDTreeByNestingTableColumn which allows you to display a tree structure within a column. A table can only contain one of these columns.




Cell Editors

A table column contains a header and a TableCellEditor which specifies the UI element in which the cells of this column are displayed.

Cell editors are, for example, Button, Caption, CheckBox, DropDownByKey, DropDownByIndex, FileDownload, FileUpload, Image, Inputfield, LinkToAction, LinkToURL, ProgressIndicator, RadioButton, TextView, and ValueComparison. The ValueComparison element is used to display various numerical values line by line.

Cell Variants

You can insert various cell variants in a column. The TableStandardCell enables you to highlight single cells in color or to select a different cell editor. The TableSingleMarkableCell can be used to mark and execute actions at cell level. For the TableSingleMarkableCell, the following cell editors can be used: Image, Inputfield, TextView, DropDownByIndex, DropDownByKey.

Specific cells can be taken out of the scroll area of the table and be fixed at the top or bottom edge. To do this, you can use the interfaces IWDFixedBottomCell and IWDFixedTopCell.

Enhancements

The following enhancements of a table are possible:

• TablePopin. A TablePopin can be assigned to the table or a single column. When the user clicks the TablePopinToggleCell, the TablePopin opens as an enhancement below the corresponding row. You can arrange additional UI elements in a TablePopin - for example, for the display of detail information of a data record.

• Legend A legend enables you to add descriptions for single cells highlighed in color. You can use the semantics property of a LegendItem and the cellDesign property of the table column or cell variant to assign the highlightings to each other.

• Toolbar

• Popup menu For the integration of popup menus, you can use UI elements as cell editors. They can be assigned a popup menu - for example, Image or TextView.

Data binding The data of a table is bound at two locations:

• The dataSource property of the table must be bound to a context node.

• A TableCellEditor is assigned to each column. The text property or value property of the TableCellEditor is bound to a context attribute.

At runtime, the number of rows is determined by the number of node elements.

Selection of Rows and Cells The selection of single or multipe rows or of single cells is possible.

You can use the selectionMode property to specify whether a selection of rows is possibe and whether one or multiple rows can be selected. However, only one row can have the LeadSelection [External].

Alternatively, you can use cell variants of the type TableSingleMarkableCell to select single cells.




4.1.33.1 Web Dynpro Table API - IWDTable

Definition The Table UI element allows the two-dimensional display of data in cells arranged into rows and columns. The UI element consists of a header area, context text area, and footer area. The lead selection of a row is highlighted in color when displayed on the screen. The Table UI element can contain any number of TableColumn elements [Page 203]. The following graphic shows how the UI element is displayed.

Display of a Table

Pushbuttons provided in the footer of the table allow navigation. The following scroll bar functions are available:

First page Page up Line up

Last page Page down Line down

onFilter Action

The display of rows in a table can be restricted using the onFilter action. This can improve the overview of the information contained in a table.

The Table UI element and the TableColumn element provide the application developer with an interface to display a so-called filter row. The filter row is displayed right below the column header area and does not change position when the user browses.

The filtering of table entries requires:

1. ^The option to specify a criterion for each table column to restrict the result list

2. The option to start the filter process

Restricting the size of the result list

Each table column enables you to bind its filterValue property to a context attribute that defines the value to be filtered. Due to the binding of this property to a context attribute, an input element, which can be used to enter the value to be filtered, is displayed in the column below the column header area. At runtime, the filter input of the user is located in the context attribute to which the property is bound.

Starting the filter process

The Table UI element provides the onFilter property, which is associated with an action. Due to the association with an action, the filter row is displayed in the table. The filter row

contains the button as the first element on the left side. When the user chooses this button, the associated action is executed.




The logic of the filter process is not implemented in Web Dynpro. The application developer must implement the action to be executed.



• compatibilityMode This property allows application developers to adapt applications to the behavior in a new release. compatibilityMode is of the enumeration type WDTableCompatibilityMode and can be filled with the following values:

auto Specifies the behavior of the table according to the release in which the application was created.

nw04Plus The behavior of the table is the default behavior for releases after NW04.

• dataSource This property is used to specify the data source. You can use it to specify the path to the context node providing the data.

• design Describes the appearance of the table in abstract terms. The design property can be filled with the following values and is represented by the enumeration type WDTableDesign .

alternating The table rows are displayed alternately in a different color.

standard The table background has one color. The individual table rows are displayed with grid net lines.

transparent The table background is transparent. The individual table rows are displayed without grid net lines.

• firstVisibleRow Specifies which row of the table is to be displayed as the first row.

• footerVisible Specifies whether or not a footer is displayed.

• readOnly Specifies whether or not the table can be edited. If the value is true , the data in the table cannot be edited.

• selectionMode Specifies in which way the table rows can be selected. In general, the selection of table rows is specified by the definition of the context node selection. However, you can change the selection using the selectionMode property. The selectionMode property can be filled with the following values and is represented by the enumeration type WDTableSelectionMode.

auto The selection of the table is specified by the selection of the context node.

multi Multiple table rows can be selected if the context node allwos multiple selection.

single Only one row can be selected at a time.




If you assign the single value to the selectionMode property, you can only select one row at a time, even if multiple is defined for the context node.

• visibleRowCount Specifies the number of rows of a table which is to be displayed without leaves. The value -1 does not restrict the number of rows and displays all table rows without leaves.

• width Specifies the width of the table and can be specified in relative CSS units like em, ex, or percentage.




accessibilityDescription IWDTable String (Translatable Text) bindable No

compatibilityMode IWDTable WDTableCompatibilityMode auto bindable No

dataSource IWDTable Object bindable_mandatory Yes

design IWDTable WDTableDesign standard bindable No


firstVisibleRow IWDTable int 0 bindable No

footerVisible IWDTable boolean true bindable No

readOnly IWDTable boolean false bindable No

selectionMode IWDTable WDTableSelectionMode auto not_bindable No

tooltip [External] IWDUIElement String (TranslatableText) bindable No


visibleRowCount IWDTable int 5 bindable No

width IWDTable String (CSS size) bindable No

Events • onFilter

This property contains the action that is executed when the user selects the filter

function – that is, the icon in the first table column. See a detailed description of this function further above under Definition.

• onLeadSelect This property contains the action that is executed when the lead selection of the table changes. The event parameters are the ID of the column and the row number (starting at 0).


col String

row int

For further information, refer to Parameter Mapping [External].




Associated Interfaces IWDTableColumn []

IWDTreeByNestingTableColumn [Page 210]

Data Binding A table receives its data from a context node – that is, the table property dataSource must be bound to a multiple context node.

At runtime, each node element of the node collection is a table row.

The number of table rows is identical to the number of node elements. The selected table rows correspond to the node selection. If the selection of the context node changes, the selected table rows also change.

The table columns correspond to the context attributes and are described by the aggregation of TableColumn objects [Page 203]. They specify the number and order of columns as well as the headers and the width of the columns.

The content of a table cell to be displayed is specified by the table cell editor (TableCellEditor) of the column. You can use one of the following table cell editors:

• Button UI element, LinkToAction UI element, LinkToURL: UI element: UI elements that can be used to trigger events.

• Caption UI element, Image UI element, TextView UI element: UI elements that can be used to display texts or graphics.

• CheckBox UI element, RadioButton UI element, DropDownByKey UI element: UI elements that can be used to select elements of a specific value set.

• DropDownByIndex UI element

• InputField UI element: This UI element allows the editing of a cell content.

The text property is bound to a context attribute of the context node, which represents the dataSource of the table.

Mobile Characteristics The UI element Table supports the development of mobile applications for pocket PCs, BlackBerry wireless handhelds, and Nokia Series 80 devices (see Mobile Web Dynpro).





design ignored ignored ignored

enabled ignored ignored ignored

readOnly ignored ignored ignored


width ignored ignored ignored




For BlackBerry wireless handhelds, the multiple selection is not supported. The contents of the first column of a table are rendered as links in BlackBerry wireless handhelds. You can only use the UI elements LinkToAction, LinkToURL, and TextView as table cell editors.

Methods in the Web Dynpro IWDTable API Method Name Parameter Return Value Description

addColumn (IWDTableColumn column)

Adds a column element at the end of the column elements list.

addColumn (IWDTableColumn column, int index)

Adds a column element at the specified index position of the column elements list.

bindAccessibilityDescription (String path)

Binds the accessibilityDescription property to the context node specified by a path.

bindDataSource (String path)

Binds the dataSource property to the context node specified by a path.

bindDesign (String path)

Binds the value of the design property to the context element specified by the path.

bindFirstVisibleRow (String path)

Binds the firstVisibleRow property to the context node specified by a path.

bindFooterVisible (String path)

Binds the footerVisible property to the context node specified by a path.



bindingOfDataSource String Returns the path of the context element to which the dataSource property is bound. Returns NULL if no binding exists.

bindingOfDesign String Returns the path of the context element to which the design property is bound. Returns NULL if no binding exists.

bindingOfFirstVisibleRow String Returns the path of the context element to which the firstVisibleRow property is




bound. Returns NULL if no binding exists.

bindingOfFooterVisible String Returns the path of the context element to which the footerVisible property is bound. Returns NULL if no binding exists.


bindingOfVisibleRowCount String Returns the path of the context element to which the visibleRowCount property is bound. Returns NULL if no binding exists.


bindReadOnly (String path)

Binds the readOnly property to the context node specified by a path.

bindVisibleRowCount (String path)

Binds the visibleRowCount property to the context node specified by a path.

bindWidth (String path)

Binds the value of the width property to the context element specified by the path.

destroyAllColumns Removes all column elements. These are destroyed and no longer exist, so that the associated IDs can be used for new elements.

destroyHeader Removes and deletes the headers for this table element.

destroyMasterColumn Removes and deletes the MasterColumn for this table element.

destroyToolBar Removes and deletes the ToolBar for this table element.

getAccessibilityDescription String Returns the value of the accessibilityDescription property.

getColumns IWDTableColumn[]

Returns an array of the column elements.

getDesign WDTableDesign

Returns the value of the design property.




getFirstVisibleRow int Returns the value of the firstVisibleRow property.

getFooterVisible boolean Returns the value of the footerVisible property.

getHeader IWDCaption Returns the header for this table element.

getMasterColumn IWDAbstractMasterTableColumn

Returns the MasterColumn for this table element.

getOnFilter IWDAction Returns the action that is executed when the onFilter event is triggered.

getOnLeadSelect IWDAction Returns the action that is executed when the onLeadSelect event is triggered.


getSelectionMode WDTableSelectionMode

Returns the value of the selectionMode property.

getToolBar IWDToolBar Returns the ToolBar for this table element.

getVisibleRowCount int Returns the value of the visibleRowCount property.

getWidth String Returns the value of the widt h property.

hasColumns boolean Checks whether or not column elements exist in this table element.

iterateColumns Iterator Returns an iterator about all column elements in this table element.

mappingOfOnFilter IWDParameterMapping

Returns the parameter mapping for the onFilter action.

mappingOfOnLeadSelect IWDParameterMapping

Returns the parameter mapping for the onLeadSelect action.

numberOfColumns int Returns the number of the column elements.

removeAllColumns Removes all column elements. They remain and can be added to this table element.

removeColumn (int index) IWDTableColumn

Removes the column element at the specified index position.

removeColumn (String id) IWDTableColumn

Removes the column element with the specified ID.




setAccessibilityDescription (String accessibilityDescription)


setDesign (WDTableDesign design)

Sets the value of the design property.

setFirstVisibleRow (int firstVisibleRow)

Sets the value of the firstVisibleRow property.

setFooterVisible (boolean footerVisible)

Sets the value of the footerVisible property.

setHeader (IWDCaption header)

Sets the header for this table element.

setMasterColumn (IWDAbstractMasterTableColumn masterColumn)

Sets the MasterColumn for this table element.

setOnFilter (IWDAction action)

Sets the action that is executed when the onFilter event is triggered.

setOnLeadSelect (IWDAction action)

Sets the action that is executed when the onLeadSelect event is triggered.

setReadOnly (boolean readOnly)

Sets the value of the readOnly property.

setSelectionMode (WDTableSelectionMode selectionMode)

Sets the value of the selectionMode property.

setToolBar (IWDToolBar toolBar)

Sets the ToolBar for this table element.

setVisibleRowCount (int visibleRowCount)

Sets the value of the visibleRowCount property.

setWidth (String width)

Sets the value of the width property.

swapColumns (int i, int j) Swaps the table columns with the corresponding indices.





4.1.33.2 Filtering and Sorting in a Table

Filtering The display of rows in a table can be restricted using the onFilter action. This can improve the overview of the information contained in a table.

The Table UI element provides the application developer with an interface to display a so-called filter row. The filter row is displayed right below the column header area and does not change position when the user browses.

The filtering of table entries requires:

3. The option to specify a criterion for each table column to restrict the result list

4. The option to start the filter process

Restricting the size of the result list

Each table column enables you to bind its filterValue property to a context attribute that defines the value to be filtered. Due to the binding of this property to a context attribute, an input element, which can be used to enter the value to be filtered, is displayed in the column below the column header area. At runtime, the filter input of the user is located in the context attribute to which the property is bound.

Starting the filter process

The Table UI element provides the onFilter property, which can be associated with an action. Due to the association with an action, the filter row is displayed in the table. The filter

row contains the button as the first element on the left side. When the user chooses this button, the associated action is executed.

The logic of the filter process is not implemented in Web Dynpro. The application developer must implement the action to be executed.

Sorting You can trigger a sorting process using the onSort event. This process can be used to sort in ascending or descending order after a selected table column.

When you assigned a method to the onSort event, the user can click the header of a column at runtime to display the corresponding icons.

unsorted

ascending

descending

The logic of the sorting process is not implemented in Web Dynpro. The application developer must implement the action to be executed.




4.1.33.3 TableColumnGroup API

Definition The TableColumnGroup allows yout to combine several columns and give them one common heading. Into a TableColumnGroup, you can insert TableColumns or other TableColumnGroups.

Description of UI Element Properties • fixedPosition

Determines whether the TableColumnGroup is fixed at the left or right margin.

left Column is fixed at the left margin.

notFixed Column is not fixed and can be scrolled.

right Column is fixed at the right margin.

• visible Specifies the visibility of the UI element. The default value of this property is set to visible .




Overview of Inherited Properties Name Interface Type Initial


Required

fixedPosition IWDAbstractTableColumn WDTableColumnFixedPosition notFixed bindable No

visible IWDAbstractTableColumn WDVisibility visible bindable No

Events Name Class Parameters

onAction IWDAbstractTableColumn (String col)

4.1.33.4 Web Dynpro TableColumn API - IWDTableColum n

Definition The TableColumn element is a column within a table [Page 194].

Description of Properties • design

Specifies the design of the cell background. The default value of this property is transparent . You can use the background colors fill1 , fill2 , and fill3 as separators between the individual semantically different cell contents. The design




property can be filled with the following values and is represented by the enumeration type WDCellBackgroundDesign .

border The color of the cell borders.








• filterValue You can use this property to define the value to be filtered and to bind it to a corresponding context attribute. Before using this property, read the description of the table property onFilter [Page 194], which you can use to define an action for filtering table entries.

• hAlign Describes the horizontal alignment of the table column. The hAlign property is represented by the enumeration type WDTableColumnHAlign and can be filled with the following values:

auto Automatic alignment of the text content. The alignment is specified by the usage of the UI element - for example, by the data type of the value to be represented.

beginOfLine The text content is always displayed at the beginning of line. Therefore, the text content for the value ltr of the textDirection property is left-justified. The text content for the value rt l is right-justified.

center Centered alignment.

endOfLine The text content is always displayed at the end of the line. Therefore, the text content for the value ltr of the textDirection property is right-justified. The text content for the value rtl is left-justified.

forcedLeft The text content is always left-justified, regardless of whether the value is ltr or rtl for the textDirection property.

forcedLRight The text content is always right-justified, regardless of whether the value is ltr or rtl for the textDirection property.

left Left-justified alignment. This value is deprecated. Use beginOfLine instead.

right Right-justified alignment. This value is deprecated. Use forcedRight instead.

The default value for this property is auto .

• resizable Specifies whether the width of the table column can be modified by the user.




• visible Specifies whether or not the column is displayed. The visible property can be filled with the following values and is represented by the data type WDVisibility.

blank The table column is not visible on the screen. This value has the same visibility effect for the table column on the screen as the value none .

none The table column is not visible on the screen.

visible The table column is displayed on the screen.

• width Specifies the width of the table column in a table.

Properties Overview Name Interface Type Initial

Value Bindable

Value Required

design IWDTableColumn


transparent

bindable No

filterValue

IWDTableColumn

String bindable No

hAlign IWDTableColumn

WDTableColumnHAlign auto bindable No

resizable IWDTableColumn


visible IWDTableColumn

WDVisibility visible bindable No

width IWDTableColumn

String (CSS size) bindable No

Events • onAction

This property contains the action that is executed when the user selects the header of a table column. The event parameter is the ID of the table column in which the event occurs


col String


Data Binding The content of a table cell to be displayed is specified by a table cell editor (TableCellEditor) of the column.

Methods in the Web Dynpro IWDTableColumns API Method Name Parameter Return Value Short

Description




bindDesign (String path) Binds the value of the design property to the context element specified by the path.

bindFilterValue (String path) Binds the filterValue property to the context node specified by a path.

bindHAlign (String path) Binds the hAlign property to the context node specified by a path.

bindingOfDesign String Returns the path of the context element to which the design property is bound. Returns NULL if no binding exists.

bindingOfFilterValue String Returns the path of the context element to which the filterValue property is bound. Returns NULL if no binding exists.

bindingOfHAlign String Returns the path of the context element to which the hAlign property is bound.




Returns NULL if no binding exists.

bindingOfResizable String Returns the path of the context element to which the resizable property is bound. Returns NULL if no binding exists.

bindingOfVisible String Returns the path of the context element to which the visible property is bound. Returns NULL if no binding exists.


bindResizable (String path) Binds the value of the resizable property to the context element specified by the path.

bindVisible (String path) Binds the value of the visible property to the context element




specified by the path.


destroyHeader Removes and deletes the header for this TableColumn element.

destroyTableCellEditor

Removes and deletes the table cell editor for this TableColumn element.

getDesign WDCellBackgroundDesign

Returns the value of the design property.

getFilterValue String Returns the value of the filterValue property.

getHAlign WDTableColumnHAlign Returns the value of the hAlign property.

getHeader IWDCaption Returns the header for this TableColumn element.

getOnAction IWDAction Returns the action that is executed if the onAction event is raised.

getResizable boolean Returns the value of the resizable property.

getTable IWDTable Returns the




Table element in which this TableColumn element is contained.

getTableCellEditor IWDTableCellEditor Returns the table cell editor for this TableColumn element.

getVisible WDVisibility Returns the value of the visible property.



setDesign (WDCellBackgroundDesign design)

Sets the value of the design property.

setFilterValue (String filterValue) Sets the value of the filterValue property.

setHAlign (WDTableColumnHAlign hAlign)

Sets the value of the hAlign property.

setHeader (IWDCaption header) Sets the header for this TableColumn element.


setTableCellEditor (IWDTableCellEditor tableCellEditor)

Sets the table cell editor for




this TableColumn element.

setResizable (boolean resizable) Sets the value of the resizable property.

setVisible (WDVisibility visible) Sets the value of the visible property.

setWidth (String width) Sets the value of the width property.


4.1.33.5 TreeByNestingTableColumn API

Definition The TreeByNestingTableColumn element allows the integration of a tree structure in a table column.

For further information, see the tutorial Integration of a Tree Structure in a Web Dynpro Table [External].




Description of UI Element Properties • cellDesign

Specifies the background color of the cell. The cellDesign property can be filled with the following values and is represented by the enumeration type WDTableCellDesign .


















• childrenLoaded Specifies whether the lower-level nodes are loaded.

• design Specifies the design of the cell background. The default value of this property is transparent. You can use the background colors fill1 , fill2 , and fill3 as separators between the individual semantically different cell contents. The cellBackgroundDesign property can be filled with the following values and is represented by the enumeration type WDCellBackgroundDesign .


border This is the color of the cell borders. This value is used for nested grid layouts to create grid net lines.

fill1 The color corresponds to the value primarycolor of the design property of the Group UI element.

fill2 The color corresponds to the value secondarycolor of the design property of the Group UI element.

fill3 This color corresponds to the color value of the third level of a Tree UI element.








• expanded Specifies whether a tree node is expanded.

• isLeaf Identifies a node element as an end node. The value true indicates that no other subelements exist.

• resizable Specifies whether the width of the table column can be modified by the user.

• visible Specifies whether or not the column is displayed. The visible property can be filled with the following values and is represented by the data type WDVisibility .

blank The table column is not visible on the screen. This value has the same visibility effect for the table column on the screen as the value none .

none The table column is not visible on the screen.

visible The table column is displayed on the screen.

• width Specifies the width of the table column and can be specified in relative CSS units like em, ex, or percentage.


Value Bindable

cellDesign IWDAbstractMasterTableColumn WDTableCellDesign standard bindable

childrenLoaded IWDAbstractTreeTableColumn boolean false bindable

design IWDAbstractMasterTableColumn WDCellBackgroundDesign transparent bindable

expanded IWDAbstractTreeTableColumn boolean false bindable_mandatory

isLeaf IWDAbstractTreeTableColumn boolean false bindable

resizable IWDAbstractMasterTableColumn boolean true bindable

visible IWDAbstractMasterTableColumn WDVisibility visible bindable

width IWDAbstractMasterTableColumn String bindable

Events • onLoadChildren (String path)

This event is triggered when a tree node is expanded for the first time.




4.1.33.6 Cell Variants

Definition As cell variants, the interfaces IWDTableSingleMarkableCell, IWDTableStandardCell, and IWDTablePopinToggleCell derived from IWDAbstractTableCellVariant are available.

To TableSingleMarkableCell and TableStandardCell, a cell editor must be assigned, which is used to bind the data to the context attribute. TablePopinToggleCell does not require a cell editor.

For the TableSingleMarkableCell, as cell editors (IWDTableMarkableCellEditor) the following editors are available: DropDownByIndex, DropDownByKey, Image, InputField and TextView.

Use TableStandardCell is mainly used to define cells that are meant to have an individual design, such as being highlighted by color.

TableSingleMarkableCell allows you to select an individual cell to, for example, perform actions on it. The x and y coordinates of the cell can be determined using the markedData property. They allow you to uniquely identify a cell.

TablePopinToggleCell is a cell variant which is only used to open and close a TablePopin. It is inserted in the first column of a table.

4.1.33.6.1 Defining Cell Variants: TableSingleMarka bleCell

You need the option to select a single cell to provide a value help for individual cells, for example.

The interface TableSingleMarkableCell allows you to group cell variants in any way as you like and to make a single cell selectable in this group. The following example shows how to proceed if you want to implement a selection of a single cell from an entire table.




Prerequisites You have created an applicaton with a component and view in your Web Dynpro project.

Procedure

Creating the Context ...

1. Create a value node TableNode for the data of the table and insert three value attributes of the type String for the table columns.

2. Create a value attribute selectedCellVariant of the type String in the TableNode .

3. Create a value attribute attributePointer , switch to the Properties , click … for the property type , and select the Java Simple Type . Enter com.sap.tc.webdynpro.progmodel.api.IWDAttributePoin ter and confirm with Ok.

Creating the View ...

1. Open the context menu in the Outline , select Apply Template and then Table . In the subsequent dialog box from the context, select three attributes for the columns (col1, col2, col3). Confirm by choosing Finish

2. Set the property selectionMode of the table to none .

Repeat the steps for each column.

3. Highlight the column and open the context menu. Select Insert Cell Variant , TableSingleMarkableCell and confirm with Finish .

4. Enter the same value for each TableSingleMarkableCell for the property variantKey - for example, variant1

5. Insert a cell editor of the type TextView in each TableSingleMarkableCell.




Binding the UI Elements ...

1. Bind the text property of each TextView to the column in which the property is contained.

2. Bind the attributeToMark property of the corresponding TableSingleMarkableCell to the column in which the element is contained.

3. Bind the selectedCellVariant property of each TableColumn to the context attribute selectedCellVariant .

4. Add the following source code to the wdDoInit method.

wdDoInit()

1 2 3

IPrivateUseSingleMarkableCellsView.ItableNodeElemen t elem; int count = 10; // Fill dummy data

for ( int i=0; i<count; i++) { elem = wdContext.nodeTableNode().createTableNodeElement(); wdContext.nodeTableNode().addElement(elem);

elem.setCol1( “1.” + i); elem.setCol2( “2.” + i); elem.setCol3( “3.” + i); // set TableSingleMarkableCell as a variant for the table elem.setSelectedCellVariant( “variant1” );

}

For each element that is created in the for loop and is then added, the TableSingle MarkableCell is set as a cell variant in row 3.

5. Add the following source code to the wdDoModifyView method.

wdDoModifyView()




IWDAttributeInfo markedDataInfo = wdContext.currentContextElement().getAttributePoint er( “attributePointer” ).getAttributeInfo(); ((IWDTableSingleMarkableCell) view.getElement( “TableSingleMarkableCell1” )).bindMarkedData(markedDataInfo); ((IWDTableSingleMarkableCell) view.getElement( “TableSingleMarkableCell2” )).bindMarkedData(markedDataInfo);

1. ((IWDTableSingleMarkableCell) view.getElement( “TableSingleMarkableCell3” )).bindMarkedData(markedDataInfo)

The current AttributeInfo is now retrieved at every change of the view and is bound to the context using the markedData property.

Result Each single cell can be selected separately. You can define an action and in its method, you can determine the coordinates of the currently selected cell using the following code: IWDAttributePointer attPointer = wdContext.currentContextElement().getAttributePoint er();

4.1.33.6.2 TableSingleMarkableCell API

Definition TableSingleMarkableCell allows you to identify a single cell.

This cell type can only be used if the property selectionMode of the table is set to none .

Description of UI Element Properties • attributeToMark

Is bound to the context attribute of the TableColumn in which this TableSingleMarkableCell element resides.

• cellDesign

Specifies the background color of the cell. The cellDesign property can be filled with the following values and is represented by the enumeration type TableCellDesign.
























• hAlign

Specifies the horizontal alignment of the UI element in the cell. The default value of this property is beginOfLine . The hAlign property is represented by the enumeration type CellHAlign and can be filled with the following values:



char Specifies the alignment using a specific character. The assignment of the char value allows you to align the cell contents to a single character.



forcedRight The text content is always right-justified, regardless of whether the value is ltr or rtl for the textDirection property.

justify Justified - This value allows forced justification within a grid layout cell.



• markedData

The x and y coordinates of the cell can be determined using the markedData property. They allow you to uniquely identify a cell.




The binding of the property markedData must be identical for all TableSingleMarkableCells of a table, independent of the column in which they occur.

• variantKey

Determines the key to be used to identify the TableSingleMarkableCell.


Required

attributeToMark

IWDTableSingleMarkableCell


No

cellDesign IWDTableSingleMarkableCell

TableCellDesign


hAlign IWDAbstractTableCellVariant

TableColumnHAlign

auto bindable No

markedData IWDTableSingleMarkableCell

AttributePointer bindable_mandatory

No

variantKey IWDAbstractTableCellVariant

String not_bindable No

4.1.33.6.3 TableStandardCell API

Definition A TableStandardCell mainly serves the purpose of adapting the design for individual cells and also allows you to select a cell editor different from the one defined for the TableColumn.


Specifies the background color of the cell. The cellDesign property can be filled with the following values and is represented by the enumeration type WDTableCellDesign .





















• hAlign Specifies the horizontal alignment of the UI element in the grid layout cell. The default value of this property is beginOfLine . The hAlign property is represented by the enumeration type WDCellHAlign and can be filled with the following values:






forcedRight The text content is always right-justified, regardless of whether the value is ltr or rtl for the textDirection property.




• variantKey Determines the key to be used to identify the TableStandardCell.



Required

cellDesign IWDTableStandardCell WDTableCellDesign standard bindable No

hAlign IWDAbstractTableCellVariant

WDTableColumnHAlign auto bindable No

variantKey IWDAbstractTableCellVariant

String not_bindable

No




4.1.33.7 TablePopin API

Definition A TablePopin enables you to enhance a table row. The TablePopin is displayed underneath a row. If you assign the TablePopin to a table column, it is also displayed underneath the row and the respective row is highlighted.

You can use the cell variant TablePopinToggleCell, which you insert in the first column of the table, to implement opening and closing of a TablePopin. When the user clicks the TablePopinToggleButton, the TablePopin opens underneath the row; when the user clicks again, it closes.

You can display a TablePopin also by setting it in the selectedPopin property of the table. To do this, in the context under the node that contains the table data, you define an attribute selectedPopin of type String . If you set an empty string as value, no TablePopin will be displayed. To display a TablePopin, set the ID of the desired TablePopin as value.


When accessibility is activated, the assigned text is added to the quick info. This description provides semantic details of the UI element and is only read by the screen reader if the user focuses the complete Ul element.

• design

Determines the look of the content area of the TablePopin. design is represented by the enumeration type PopinDesign and can have the following values:

fill Content area with background color

plain Content area with white background and frame.

transparent Content area with transparent background and no frame.

• hasContentPadding

Determines whether the content area is surrounded by an inner indent.

• titleDesign




Determines the symbol that illustrates the message type of the title area. The titleDesign property can be filled with the following values and is represented by the enumeration type TablePopinTitleDesign.

critical A symbol for a critical message appears in the title.

error A symbol for an error/stop message appears in the title.

ok A symbol for an okay message appears in the title.

text The title appears without any symbol.

The default value for this property is text .

• titleText

Determines the text to be displayed for this popin. You can statically specify this property value at design time or bind it to a context attribute so that the value is provided automatically by the context at runtime.

Overview of Inherited Properties Name Interface Type Initial Value Bindable Value

Required

accessibilityDescription IWDAbstractPopin String bindable No

design IWDAbstractPopin PopinDesign fill bindable No

hasContentPadding IWDAbstractPopin boolean true bindable No

titleDesign IWDAbstractPopin TablePopinTitleDesign text bindable No

titleText IWDAbstractPopin String bindable No

Events Name Class Parameter

onClose IWDTablePopin

If you define an action for this event, a Close button is displayed in the TablePopin. When the user clicks this button, the event onClose is triggered.

4.1.33.7.1 TablePopinToggleCell API

Definition The TablePopinToggleCell is inserted as a cell variant in the first column of a table and enables the user to open and close a TablePopin as an enhancement of a table row by selecting the row,


Specifies the background color of the cell. The cellDesign property can be filled with the following values and is represented by the enumeration type TableCellDesign.
























• hAlign

Determines the horizontal alignment of the UI element in the grid layout cell. The default value of this property is beginOfLine . The hAlign property is represented by the enumeration type CellHAlign and can be filled with the following values:






forcedRight The text content is always right-justified, regardless of whether the value is ltr




or rtl for the textDirection property.




• variantKey

Determines the key to be used to identify the TablePopinToggleCell.



Required

cellDesign IWDTablePopinToggleCell TableCellDesign standard bindable No

hAlign IWDAbstractTableCellVariant TableColumnHAlign auto bindable No

variantKey IWDAbstractTableCellVariant String not_bindable No

Event • onToggle (boolean expanded)

The onToggle event is triggered when the user clicks the TablePopinToggleCell. The transfer parameter expanded is the new status.

4.1.33.7.2 TextBar API

Description of UI Element Properties • text

Determines the text of the TextBar.

• visible

Controls whether the TextBar is displayed. The visible property can be filled with the following values and is represented by the data type Visibility.

blank The TextBar is not visible on the screen. This value has the same visibility effect for the TextBar on the screen as the value none .

none The TextBar is not visible on the screen.

visible The TextBar is displayed on the screen.


Required

text IWDTextBar String bindable No




visible IWDTextBar Visibility visible bindable No

4.1.34 Tabstrip The TabStrip UI element (IWDTabStrip) allows the display of a tab. The user can toggle between several tab pages by selecting a specific tab title. The same window is shared by all tab pages and used for displaying the content. The user can display the content of a tab by selecting a tab title.

The following graphic shows the visual representation of a TabStrip with an integrated toolbar:

If the width of the TabStrip element is not sufficient to display all tabs, as shown in the example above, the user can navigate through the tabs using the two integrated scroll tabs with little arrows.

Structure A TabStrip consists of the desired number of tab elements. A tab element consists of a header and a content area. This area can contain other UI elements - for example, an additional TabStrip element can be inserted. A toolbar can be added to a tab.




ViewElement(from Core)

TabStrip

onSelect : StringonSelect_tab : StringonSelect_oldTab : Stringheight : Stringwidth : StringselectedTab : StringselectionChangeBehaviour : TabStripSelectionChangeBehaviour = autoaccess ibilityDescription : Trans latableTexttabAlignment : TabAlignment = fast

Caption

text : Trans latableText

UIElement

enabled : Boolean = truetooltip : Trans latableTextvis ible : Vis ibility = vis ible

(from Core)

Tab

enabled : Boolean = truehasContentPadding : Boolean = truevis ible : Boolean = true

1

0..*

+TabStrip 1

+Tabs 0..*

<<default>>

0..1

1

+Tab0..1

+Header1

1

0..1

+Tab

1

+Content

0..1

<<default>>

ToolBar

1

0..1

+Tab 1

+ToolBar0..1




4.1.34.1 TabStrip API



• height Specifies the height of the tab and its tab pages. You can specify the height in CSS units like em, ex, pixels, or percentage.

• selectedTab The ID of the selected tab page.

• selectionChangeBehaviour The selectionChangeBehaviour property can be filled with the following values and is represented by the enumeration type WDTabStripSelectionChangeBehaviour .

auto Specifies that the UI element automatically changes the lead selection after an interaction by the user before the corresponding event is triggered.

manual Specifies that the UI element does not change the lead selection after an interaction by the user but triggers the corresponding event. In this case, the event handler must change the lead selection to enable the UI element to display the data. This setting allows you to check the change of the lead selection.

• tabAlignment

exact: Forces the exact specification of height and width of the tabs. Each tab has the same height and width which result from the specification of a minimum size and the size specified by the label.

fast Enables the client to efficiently align height and width.

There is no alignment for browser-based clients. Height and width are specified by the tab label. Height and width of the tabs can be aligned for Web Dynpro clients to optimize the window structure.

• width Specifies the width of the register and its tab pages. You can specify the width in CSS units like em, ex, pixel, or percentage.


al Value

Bindable

Value Required


IWDTabStrip

String (Translatable Text) bindable No



height IWDTabStrip


selectedTab IWDTabStr String bindable No




ip


IWDTabStrip

WDTabStripSelectionChangeBehaviour

auto not_bindable

No

tabAlignment IWDTabStrip

WDTabAlignment fast not_bindable

No

tooltip IWDUIElement


visible IWDUIEelement

WDVisibility visible

bindable No

width IWDTabStrip


The tooltip property is ignored and does not affect the browser.

Events • onSelect (String oldTab, String tab)

Describes the action that is executed when the user selects a tab page. Transfer parameters are the previously selected and the newly selected tab.


4.1.34.2 Tab API

Definition The Tab UI element is an individual tab page within a tab. The tab consists of a header area, a content area, and an optional toolbar.

Description of the View Element Properties • enabled

Specifies whether or not the tab can be activated to display its content.

• hasContentPadding Controls whether there is a padding around the content of the tab page..

• visible Specifies whether or not the tab is displayed.

Properties Overview Name Class Type Initial Value Bindable Value

Required

enabled IWDTab boolean true bindable No

hasContentPadding IWDTab boolean true bindable No

visible IWDTab boolean true bindable No




4.1.35 Web Dynpro TextEdit API - IWDTextEdit

Definition The TextEdit UI element allows the entry and display of a multiline text. The text in this UI element uses a uniform font, font size, and font style.The UI element is displayed with borders and the frame size is specified by the properties col and row . If the number of rows exceeds the value of the row property, a vertical scroll bar is displayed.

If the value of the wrapping property is off, the scroll bar is only be displayed if the text row length exceeds the value of the col property.

The following graphic shows the TextEdit UI element in the SAP standard design:

Description of UI Element Properties • cols

Specifies the width of the TextEdit UI element as quantity of characters.

• width Specifies the width of the UI element and can be specified in CSS units like em, ex, pixels, or percentage. This property value overwrites the value of the row property.

• readOnly Specifies whether or not the UI element can only be used for the display or also for the input of text.

• rows Specifies the height of the TextEdit UI element as quantity of characters.

• state Describes the state of the TextEdit UI element. The state property can be filled with the following values and is represented by the enumeration type WDState .



• value Describes the text to be displayed. The text can be edited.

• wrapping Specifies whether or not the text can be wrapped. The wrapping property can be filled with the following values and is represented by the enumeration type WDTextWrapping.

hard Wraps the text if the value specified by the col property is reached. A carriage control is inserted for each wrapping. A horizontal scroll bar is not displayed for this value.

off The text is not wrapped. If the text row length exceeds the width specified by the




col property, a horizontal scroll bar is displayed.

soft Wraps the text if the value specified by the col attribute is reached. A carriage control is not inserted for the wrapping, and a horizontal scroll bar is not displayed for this value.

• width Determines the width of the UI element that you can specify in CSS sizes, such as em, ex, pixels or percentage values. This property value overwrites the value of the row property.


Required

Cols IWDTextEdit int 40 bindable No

Height IWDTextEdit String (CSS size) bindable No

enabled [External]


readOnly IWDTextEdit boolean false bindable No

Rows IWDTextEdit int 5 bindable No

State IWDTextEdit WDState Normal bindable No

tooltip [External]

IWDUIElement String (TranslatableText)

bindable No

Value IWDTextEdit String bindable_mandatory No

visible [External]


Width IWDTextEdit String (CSS size) bindable No

wrapping IWDTextEdit WDTextWrapping soft bindable No

Mobile Characteristics The UI element TextEdit supports the development of mobile applications for pocket PCs, BlackBerry wireless handhelds, and Nokia Series 80 devices (see Mobile Web Dynpro).







State ignored ignored ignored


Width ignored ignored supported

wrapping ignored ignored supported




Height ignored ignored supported

The readOnly property is to be used carefully, as the value true is, in contrast to a desktop PC, not considered in the visual display of the user interface element. The user of the mobile Web Dynpro application cannot know that for the value true, the TextEdit user interface element is read-only.

Methods in the Web Dynpro IWDTextEdit API Method Name Parameter Return Value Short Descriptio n

bindCols (String path) Binds the cols property to the context node specified by a path.

bindHeight (String path) Binds the value of the height property to the context element specified by the path.

bindingOfCols String Returns the path of the context element to which the cols property is bound. Returns NULL if no binding exists.

bindingOfHeight String Returns the path of the context element to which the height property is bound. Returns NULL if no binding exists.


bindingOfRows String Returns the path of the context element to which the rows property is bound. Returns NULL if no binding exists.

bindingOfState String Returns the path of the context element to which the state property is bound. Returns NULL if no binding exists.

bindingOfValue String Returns the path of the context element to




which the value property is bound. Returns NULL if no binding exists.


bindingOfWrapping String Returns the path of the context element to which the wrapping property is bound. Returns NULL if no binding exists.


bindRows (String path) Binds the rows property to the context node specified by a path.




bindWrapping (String path) Binds the wrapping property to the context node specified by a path.

getCols int Returns the value of the cols property.

getHeight String Returns the value of the height property.


getRows int Returns the value of the rows property.




getState WDState Returns the value of the state property.



getWrapping WDTextWrapping Returns the value of the wrapping property.

setCols (int cols) Sets the value of the cols property.

setHeight (String height) Sets the value of the height property.

setReadOnly (boolean readOnly) Sets the value of the readOnly property.

setRows (int rows) Sets the value of the rows property.

setState (WDState state) Sets the value of the state property.


setWidth (String width) Sets the value of the width property.

setWrapping (WDTextWrapping wrapping)

Sets the value of the wrapping property.


4.1.36 TextView API

Definition The TextView UI element provides an area for displaying a multiline text.

You can assign a popup menu to a TextView which is visible when the user places the cursor

on the TextView:

Use When using a TextView element, you should always add a label to ensure accessibility of an application.





Describes the look of the TextView element. The Cascading Style Sheet (CSS) provided by SAP describes the variations of the design attribute display. The design property can be filled with the following values and is represented by the enumeration type TextViewDesign.

Emphasized Highlights the text in the standard font size.

groupTitle Highlights the text in the standard font size.

This value is set when the TextView element is used as the title of a container, which is not a layout container (property isLayoutContainer false ). The value of the accessibilityDescription property of the container must contain the same information as the TextView element. In this case, when the accessibility mode is active, the TextView will not be read and is removed from the tab sequence.

header 1 Highlights the text in the font size +4 as related to the standard font size.

header 2 Highlights the text in the font size +2 as related to the standard font size.

header 3 Highlights the text in the standard font size.

header 4 Highlights the text in the font size -1 (small) as related to the standard font size --> (like value “legend“, but highlighted).

label

Displays the text in the standard font; always includes one additional blank after the text.

label_small

Displays the text in the standard font like value “label“, but with font size -1 like font size for value “header4“.

legend Displays the text in the standard font, but with font size –1.

monospace Displays the text in a non-proportional font. Every letter occupies the same amount of space.

reference Displays the text in italics in the standard font size.

standard Displays the text in standard font size. No text attributes are defined for this value.

• hAlign

Specifies the horizontal alignment of the content within the TextView element. The value native for the layout property is ignored. The hAlign property can take the following values and is represented by the enumeration type InputFieldAlignment:

auto Automatic alignment of text content. The alignment is determined by the use of the UI element, for example, by the data type of the value to be displayed.

beginOfLine The text content is always displayed at the beginning of the line. For the value ltr of the textDirection property, the text content is left-aligned. For the value rtl , the text content is right-aligned.


endOfLine The text content is always displayed at the end of the line. For the value ltr of the textDirection property, the text content is right-aligned. For the value rtl , the text content is left-aligned.

forcedLeft The text content is always displayed on the left, independent of whether the textDirection property has the value ltr or rtl .




forcedRight The text content is always displayed on the right, independent of whether the textDirection property has the value ltr or rtl .

left Left-justified alignment. This value is deprecated, use beginOfLine instead.

right Right-justified alignment. This value is deprecated, use forcedRight instead..

The default value for this property is auto .

• layout

Describes the alignment of the text. The layout property can be filled with the following values and is represented by the enumeration type TextViewLayout.

block Displays the TextView element in a <div> tag.

native Displays the TextView element in a <span> tag.

paragraph Displays the TextView element in a <p> tag.

• text

Describes the text to be displayed.

• semanticColor

critical Displays the TextView element in a color that indicates a critical state, for example, orange.

diminished Displays the TextView element in a color that indicates a diminished state.

marked1 Displays the TextView element in a color whose meaning you can define yourself.

marked2 Displays the TextView element in a second color, whose meaning you can define yourself.

negative Displays the TextView element in a color that indicates a negative state, for example, red.

positive Displays the TextView element in a color that indicates a positive state, for example, green

standard Displays the TextView element in the standard color.

• textDirection

Specifies the text direction and allows you to use input fields for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type TextDirection.





• wrapping

Specifies whether or not text can be wrapped to the next line.





Required

design IWDTextView TextViewDesign standard bindable No


hAlign IWDTextView InputFieldAlignment auto bindable No

layout IWDTextView TextViewLayout native bindable No

semanticColor IWDTextView TextViewSemanticColor standard bindable No

text IWDTextView String (TranslatableText) bindable No

textDirection IWDTextView TextDirection inherit bindable No



wrapping IWDTextView boolean false bindable No

The enabled property is ignored and does not affect the browser.

4.1.37 Web Dynpro TimedTrigger API - IWDTimedTrigge r

Definition The TimedTrigger UI element automatically and periodically triggers an event with a specified delay. The TimedTrigger UI element is not displayed on the user interface. Therefore, it ignores the tooltip and the visibilty property. However, in specific layouts such as the matrix layout it takes up space. To trigger an action, you must bind the onAction property to an action. You use the delay property to specify the delay in seconds.

If events are not to be triggered by the TimedTrigger UI element, you do the following:

• Disable the action that is bound to the onAction property of the UI element

• Set the value of the delay to 0 seconds

• Disable the TimedTrigger UI element

Every user interaction is interrupted when the onAction is triggered.

Use In the Web Dynpro application, you can use, with restrictions, periodical server requests and the TimedTrigger UI element to trigger push events – that is, the controlled triggering of events, for example, as a message for the user. When using the TimedTrigger UI element, the client actively retrieves the data from the server. Due to the considerable server load, you should only use this option if a small number of clients exists.

Description of UI Element Properties • delay

The delay property describes the delay in seconds before a specific action is triggered. The value of this property cannot be negative. A delay of 0 seconds means




that the timer is turned off and no action is executed. The delay starts at the point of the time at which the client receives the response. After each round trip to the server – that is, after each user action, the timer is restarted.

Note that in case of very short delays (delays of less than 5 seconds), it might be impossible to operate user interfaces.



Required

delay IWDTimedTrigger int 0 bindable No

enabled [External]


tooltip [External]

IWDUIElement String (Translatable Text)

bindable No

visible [External]


Events • onAction

This property contains the action that is executed when a specific delay terminated.

Data Binding You can use the onAction property to specify the action that is to be triggered after a specific delay.

Methods in the Web Dynpro IWDTimedTrigger API Method Name Parameter Return Value Description

bindDelay (String path) Binds the delay property to the context node specified by a path.

bindingOfDelay String Returns the path of the context element to which the delay property is bound. Returns NULL if no binding exists.

getDelay int Returns the value of the delay property.

getOnAction IWDAction Returns the action that is executed




when the onAction event is triggered.


setDelay (int delay) Sets the value of the delay property.



4.1.38 ToggleButton API

Definition • checked

Specifies whether or not the ToggleButton is toggled.

• checkedImageSource Specifies the Web address of the icon that appears when the ToggleButton is toggled.

• design The design property can be filled with the following values and is represented by the enumeration type WDToggleButtonDesign .

standard Displays the ToggleButton with the default colors for the background and text. When values are assigned to the properties imageSource and checkedImageSource, the corresponding icon is displayed.

toggle Displays the ToggleButton with a triangle symbol: If the ToggleButton is toggled, the triangle points down: If you select this value, no further icons should be assigned.


• imageSource Specifies the Web address (URL) of the graphic to be displayed.

• text Specifies the text to be assigned to the AbstractToggleButton.

• textDirection Specifies the text direction and allows you to use the toggle element for texts in languages which require a specific text direction. The textDirection property can




be filled with the following values and is represented by the enumeration type WDTextDirection .





• width Specifies the width of the ToggleButtons. You can specify the width in CSS units like em, ex, pixel, or percentage.

Overview of Inherited Properties Name Interface Type Initial

Value Bindable

checked IWDAbstractToggle boolean false bindable_mandatory

checkedImageSource IWDAbstractToggleButton String bindable

design IWDAbstractToggleButton WDToggleButtonDesign standard bindable


imageFirst IWDAbstractToggleButton boolean true bindable

imageSource IWDAbstractToggleButton String bindable

text IWDAbstractToggleButton String bindable

textDirection IWDAbstractToggle WDTextDirection inherit bindable



width IWDAbstractToggleButton String bindable

Events The onToggle event is executed when the ToggleButton is toggled. The parameter is the new status of the element.


onToggle IWDAbstractToggle (boolean checked)

4.1.39 ToggleLink API A ToggleLink is a link that can display two different states. They are displayed with a triangle symbol:

checked = false

checked = true





Specifies whether or not the ToggleLink is toggled.

• text Describes the text to be displayed.








Required

checked IWDAbstractToggle boolean false bindable_mandatory No


text IWDToggleLink String bindable No

textDirection IWDAbstractToggle WDTextDirection inherit bindable No



Events The onToggle event is executed when the ToggleLink is toggled. The parameter is the new status of the element.


onToggle IWDAbstractToggle (boolean checked)

4.1.40 Toolbar

Definition The Toolbar UI element is a collection of tools that can be accessed using UI elements. Therefore, toolbars provide are an additional way of grouping UI elements functionally.

A toolbar can contain the following elements:




• ToolBarButton, ToolBarButtonChoice, ToolBarLinkToAction, ToolBarLinkToURL, ToolBarDropDownByIndex, ToolBarDropDownByKey, ToolBarInputField, ToolBarSeparator, ToolBarToggleButton.

These toolbar elements are horizontally arranged in one row of the toolbar. The size and position of the individual UI elements are automatically calculated. You can use the wrapping property to determine whether a line break can be applied to the elements in a row.

Each individual element has the collapsible property, with which it can be hidden. If you have set at least one of these elements to collapsible, a triangle symbol appears in the toolbar at runtime via which the user can hide these elements. This is demonstrated by the following screenshots:

collapsed

not collapsed

You can also create all elements as ToolBarRightItems; These are then arranged starting from the right. ToolBarRightItems cannot be collapsed.

Use A toolbar is no independent user interface element and can only be used in the following elements:

• Group, Tab, Table, Tray

Structure The following UML class diagram illustrates the usage of the items in a toolbar:




ToolBarSeparator

visible : Visibi l i ty = visiblecol lapsible : Boolean = false

ToolBarButton

design : ToolBarButtonDesign = standardcol lapsible : Boolean = false

ToolBarDropDownByIndex

col lapsible : Boolean = falselabelT ext : T ranslatableText

ToolBarDropDownByKey

col lapsible : Boolean = falselabelT ext : T ranslatableText

ToolBarInputField

labelT ext : T ranslatableTextcol lapsible : Boolean = false

ToolBarItem<<Interface>>

ToolBar

design : ToolBarDesign = standardenabled : Boolean = truevisible : Visibi l i ty = visiblewrapping : Boolean = trueaccessibili tyDescription : T ranslatableText

0..*

1

+ToolBarItems

0..*

+ToolBar

1

<<default>>

0..*

1

+ToolBarRightItem s

0..*

+ToolBar

1

ToolBarLinkToAction

col lapsible : Boolean = falseonAction : String

ToolBarLinkToURL

col lapsible : Boolean = falsereference : Stringtarget : String

ToolBarToggleButton

col lapsible : Boolean = false

ToolBarButtonChoice

col lapsible : Boolean = falseim ageSource : StringrepeatSelectedAction : Boolean = trueselectedActionItem : Stringtext : T ranslatableT ext

MenuActionItem

onAction : Stringenabled : Boolean = trueim ageSource : StringneedsM oreInfo : Boolean = falsetext : T ranslatableT exttextDi rection : T extDirection = inheri t

0..1

0..*

+ToolBarButtonChoice 0..1

+Choices 0..*

<<default>>

4.1.40.1 ToolBar API



• design Specifies the display style of the toolbar on the screen. The design property is represented by the enumeration type WDToolBarDesign and has the values:




emphasized Highlights the toolbar.

Standard Displays the toolbar in the standard design.

• enabled Specifies whether or not the toolbar is activated. If you deactivate the toolbar, all elements of the toolbar are deactivated. Some renderer implementations can ignore this behavior.

• visible Specifies whether or not the toolbar is displayed on the screen.

blank The UI element is not visible on the screen. This value has the same visibility effect for the UI element on the screen as the value none .

none The UI element is not visible on the screen.

visible The UI element is visible on the screen.

• wrapping Specifies whether or not the ToolBar elements can be wrapped.


Required

accessibilityDescription IWDToolBar String bindable No

design IWDToolBar WDToolBarDesign Standard bindable No

enabled IWDToolBar boolean true bindable No

visible IWDToolBar WDVisibility visible bindable No

wrapping IWDToolBar boolean true bindable No

4.1.40.2 ToolBarButton API

Definition The ToolBarButton element (IWDToolBarButton) is a pushbutton in a toolbar.

Description of Properties • collapsible

Specifies whether the ToolBarButton can be collapsed.

• design Specifies the design of the ToolBarButton element. The design property can be filled with the following values and is represented by the enumeration type WDToolBarButtonDesign .

next Display of a toolbar button that refers to a subsequent step.

previous Display of a toolbar button that refers to a previous step.

standard Displays the toolbar button with default background and default text color.





Required

collapsible IWDToolBarButton boolean false bindable No

design IWDToolBarButton WDToolBarButtonDesign standard bindable No



imageSource

IWDAbstractCaption String bindable No

text IWDAbstractButton String (TranslatableText) bindable No



4.1.40.3 ToolBarButtonChoice API

A ToolBarButtonChoice is a button that offers to choose among several options via a small triangle symbol, as is illustrated in the following figure.

If the user clicks on the triangle symbol, a menu opens from which an action can be selected. When the user has selected an action, this action is set to the button and can then be executed by the user. The repeatSelectedAction property makes it possible that the last selected action remains on the button after execution of an action:

Description of UI Element Properties • collapsible

Specifies whether the ToolBarButtonChoice can be collapsed.

• imageSource Specifies the Web address (URL) of the symbol to be displayed.

• repeatSelectedAction Determines that the last selected action remains assigned to the button as long as there is no other one selected.

• selectedActionItem Determines the selected action element.

• text Determines the labeling of the ToolBarButtonChoice.






collapsible IWDToolBarButtonChoice boolean false bindable No


imageSource IWDToolBarButtonChoice String bindable No

repeatSelectedAction

IWDToolBarButtonChoice boolean true bindable No

selectedActionItem IWDToolBarButtonChoice String bindable No

text IWDToolBarButtonChoice String bindable No



4.1.40.4 ToolBarDropDownByIndex API

The ToolBarDropDownByIndex element is a dropdown box in a toolbar. Index Binding [Page 292] is used for data binding. For an example, refer to Code Examples of Data Binding [Page 292].


Specifies whether the ToolBar element can be collapsed. A little icon is displayed in a ToolBar which contains those elements. When the user selects this icon, all toolbar elements with the collapsible property set to true are hidden.

• labelFor This property enables you to assign the ToolBarDropDownByIndex element to another UI element as a label.

• labelText Specifies the label text.

• readOnly Specifies whether the user can modify the selection in the toolbar dropdown list box.

• selectionChangeBehaviour The selectionChangeBehaviour property can be filled with the following values and is represented by the enumeration type WDLeadSelectionChangeBehaviour .

• auto • Specifies that the UI element automatically changes the lead selection after an interaction by the user before the corresponding event is triggered.

• manual • Specifies that the UI element does not change the lead selection after an interaction by the user but triggers the corresponding event. In this case, the event handler must change the lead selection to enable the UI element to display the data. This setting allows you to check the change of the lead selection.

• state Describes the status of the dropdown list box. The data type of this property corresponds to the enumeration type WDState . You can use the following values in the application:





required Indicates that value selection is mandatory.

• textDirection Specifies the text direction and allows you to use dropdown list boxes for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type WDTextDirection .





• texts Determines the content of the list entries.

• width Specifies the width of the dropdown list box and can be specified in CSS units like em, ex, pixels, or percentage.


al Value


collapsible IWDToolBarDropDownByIndex

boolean false

bindable No

enabled IWDUIElement Boolean true bindable No

labelFor IWDAbstractDropDown

String not_bindable

No

labelText IWDToolBarDropDownByIndex

String bindable No

readOnly IWDAbstractDropDown

Boolean false

bindable No


IWDAbstractDropDownByIndex


auto

not_bindable

No

state IWDAbstractDroopDown

WDState normal

bindable No

textDirection IWDAbstractDropDown


bindable No

texts IWDAbstractDropDoenByIndex


Yes


visible IWDUIElemente WDVisibility visible

bindable No

width IWDAbstractDrop String bindable No




Down

4.1.40.5 ToolBarDropDownByKey API

Definition The ToolBarDropDownByKey-element represents a dropdown list box in a toolbar. Key Binding [Page 299] is used for data binding. For an example, refer to Code Example for Key Binding [Page 296].



• keyVisible Specifies whether the keys are displayed with the texts in the ToolBarDropDown box.

• labelFor This property enables you to assign the ToolBarDropDownByKey element to another UI element as a label.


• readOnly Specifies whether the user can modify the selection in the ToolBarDropdown box.

• selectedKey Describes the key that specifies the selection of the DropDown box.


auto Specifies that the UI element automatically changes the lead selection after an interaction by the user before the corresponding event is triggered.

manual Specifies that the UI element does not change the lead selection after an interaction by the user but triggers the corresponding event. In this case, the event handler must change the lead selection to enable the UI element to display the data. This setting allows you to check the change of the lead selection.

• state Describes the status of the ToolBarDropdown list box. The data type of this property corresponds to the enumeration type WDState . You can use the following values in the application:


required Indicates that value selection is mandatory.




• textDirection Specifies the text direction and allows you to use dropdown list boxes for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type WDTextDirection .





• width Specifies the width of the dropdown list box and can be specified in CSS units like em, ex, pixels, or percentage.


al Value


collapsible IWDToolBarDropDownByKey

boolean false

bindable No


labelFor IWDAbstractDropDown

String not_bindable

No

labelText IWDToolBarDropDownByKey

String bindable No

readOnly IWDAbstractDropDown

boolean false

bindable No

selectedKey IWDAbstractDropDownByKey

boolean false

bindable_mandatory

No


IWDAbstractDropDownByKey


auto

not_bindable

No

state IWDAbstractDroopDown

WDState normal

bindable No

textDirection IWDAbstractDropDown


bindable No


visible IWDUIElemente WDVisibility visible

bindable No

width IWDAbstractDropDown

String bindable No




4.1.40.6 ToolBarInputField API

Definition The ToolBarInputField-element represents an input field in a toolbar. It enables the user to enter or display a single-line text in the toolbar.

Description of UI Element Properties • alignment

Specifies the horizontal alignment of the UI element in the grid. The default value of this property is auto . The alignment property can take the following values and is represented by the list type WDInputFieldAlignment :

auto The alignment is specified by the usage of the UI element - for example, by the displayed data type.

left The content is displayed left-aligned.

right The content is displayed right-aligned.

• collapsible This property enables you to assign the ToolBarInputField element to another UI element as a label.


• length Determines the maximum number of characters to be displayed in the input field.

• passwordField Boolean value that controls the display of entered characters on screen. If the value is true , the entered characters on screen are echoed with an asterisk (*). This attribute is usually used for password input fields.

• readOnly Specifies whether the input field can be edited or only read. If the value is true , the displayed text can only be read.

• state Describes the status of the UI element. The data type of this property corresponds to the enumeration type WDState . You can use the following values in the application:



• textDirection Specifies the text direction and allows you to use input fields for texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type WDTextDirection .








• value Specifies the character string displayed in the input field area. This property must be bound to a context attribute (see Data Binding of UI Element Properties [Page 283]).

• width Determines the width of the input field that you can specify in CSS sizes, such as em, ex, pixels or percentage values.


Required

alignment IWDAbstractInputField

WDInputFieldAlignment

auto bindable No

collapsible IWDToolBarDropDownByIndex

Boolean false bindable No


labelText IWDToolBarInputField

String bindable No

length IWDAbstractInputField

int 20 bindable No

passwordField IWDAbstractInputField


readOnly IWDAbstractInputField


state IWDAbstractInputField

WDState normal bindable No

textDirection IWDAbstractInputField

WDTextDirection

inherit bindable No


bindable No

value IWDAbstractInputField


No


width IWDAbstractInputField

String bindable No

4.1.40.7 ToolBarLinkToAction API


Specifies whether the ToolBar element can be collapsed. A little icon is displayed in a




ToolBar which contains those elements. When the user selects this icon, all toolbar elements with the collapsible property set to true are hidden.


• imageHeight Specifies the height of the graphic next to the link. You can specify the height in CSS units like em, ex, pixels, or percentage.

• imageSource Specifies the Web address (URL) of the icon to be displayed. You can assign an absolute Web address – http:// … to this property. If you store the icons in the directory mimes/Components/<component class> of the Web Dynpro project in the Navigator using the menu item Import, you must only enter the icon name - for example, icon.gif. The URL Generation Service automatically determines the URL of the icon (see also URL Generation Service ). You can also store the icons in the directory mimes/Applications/<application class> . In this case, you must manually create the URL using the URL Generation Service. If you use the SAP icons and want to refer to them, you use the alias ~sapicons . If you assign the alias ~sapicons/<name>.gif to the imageSource property, you refer to an icon called <name>.gif of the SAP icons. For a description and a listing of all possible SAP icons, see the SAP Design Guild under http://www.sapdesignguild.org/. Select the following path: Sitemap → Resources → Visual Design & Icons → SAP R/3 Icons → R/3 Icon Lists. The filename of the icon consists of the bitmap name entered in the table and the prefix “s_”. If the bitmap name in the table is F_CUTO, you must enter the value


• imageWidth Specifies the width of the graphic next to the link. You can specify the width in CSS units like em, ex, pixel, or percentage.

• size Specifies the size of the Link UI element. The size property can be filled with the following values and is represented by the enumeration type WDLinkSize .


standard A default size is displayed.

• text Describes the label text.









• wrapping Indicates whether or not the link text is wrapped. If the initial value is false, the link text is not wrapped.

If the value of this property is false, the link text is not wrapped.



Required

collapsible IWDToolBarLinkToAction boolean false bindable No


imageAlt IWDAbstractCaption String bindable No


imageHeight IWDLink String bindable No


imageWidth IWDLink String bindable No







Events • onAction

The onAction action of the class IWDToolBarLinkToAction is executed when the link is activated.

4.1.40.8 ToolBarLinkToURL API

Definition The Web Dynpro class ToolBarLinkToURL implements the IWDToolBarLinkToURL interface.







• imageHeight Specifies the height of the graphic next to the link. You can specify the height in CSS units like em, ex, pixels, or percentage.

• imageSource Specifies the Web address (URL) of the icon to be displayed. You can assign an absolute Web address – http:// … to this property. If you store the icons in the directory mimes/Components/<component class> of the Web Dynpro project in the Navigator using the menu item Import, you must only enter the icon name - for example, icon.gif. The URL Generation Service automatically determines the URL of the icon (see also URL Generation Service). You can also store the icons in the directory mimes/Applications/<application class> . In this case, you must manually create the URL using the URL Generation Service. If you use the SAP icons and want to refer to them, you use the alias ~sapicons . If you assign the alias ~sapicons/<name>.gif to the imageSource property, you refer to an icon called <name>.gif of the SAP icons. For a description and a listing of all possible SAP icons, see the SAP Design Guild under http://www.sapdesignguild.org/. Select the following path: Sitemap → Resources → Visual Design & Icons → SAP R/3 Icons → R/3 Icon Lists. The filename of the icon consists of the bitmap name entered in the table and the prefix “s_”. If the bitmap name in the table is F_CUTO, you must enter the value


• imageWidth Specifies the width of the graphic next to the link. You can specify the width in CSS units like em, ex, pixel, or percentage.

• reference Describes the address of the Web page to be opened.

• size Specifies the size of the Link UI element. The size property can be filled with the following values and is represented by the enumeration type WDLinkSize .


standard A default size is displayed.

• target Specifies the browser window in which the page is to be opened. You can specify the name of the target window yourself or use the following values, which comply with the W3C-HTML standard:



• text Describes the label text.









• wrapping Indicates whether or not the link text is wrapped. If the initial value is false, the link text is not wrapped.

If the value of this property is false, the link text is not wrapped.


Required

collapsible IWDToolBarLinkToURL boolean false bindable No



imageHeight IWDLink String bindable No


imageWidth IWDLink String bindable No

reference IWDToolBarLinkToURL String bindable Yes


target IWDToolBarLinkToURL String “” bindable No






4.1.40.9 ToolBarSeparator API

Definition The ToolBarSeparator element is used for the optical separation of ToolBar elements within a toolbar.






• visible Specifies the visibility of the UI element. The default value of this property is visible .





Required

collapsible IWDToolBarSeparator boolean false bindable No

visible IWDToolBarSeparator WDVisibility visible bindable No

.

4.1.40.10 ToolBarToggleButton API




Value Bindable

checked IWDAbstractToggle boolean false bindable_mandatory

checkedImageSource IWDAbstractToggleButton String bindable

collapsible IWDToolBarToggleButton boolean false bindable

design IWDAbstractToggleButton WDToggleButtonDesign standard bindable


imageFirst IWDAbstractToggleButton boolean true bindable

imageSource IWDAbstractToggleButton String bindable

text IWDAbstractToggleButton String bindable

textDirection IWDAbstractToggle WDTextDirection inherit bindable






width IWDAbstractToggleButton String bindable

Events The onToggle event of the class IWDAbstractToggle is executed when the Toggle element is toggled. The parameter is of the type boolean and transfers the new status.

4.1.41 Tree API

Definition Hierarchies defined in the context can be visualized using the Tree UI element. The hierarchy to be displayed is defined in the context. You can describe this context structure in two ways:

• If the number of levels is not known at design time, a recursive node is used (see Code Example of the Use of a Recursive Node [Page 300]).

• If the number of levels is already specified at design time, a recursive node is not used (see Code Example for Creation of a Tree UI Element [Page 274]).

The following graphic shows how the UI element is displayed:

The Tree UI element is bound against the top-level context node to be displayed.

You use nodes (TreeNodeType elements) or leaves (TreeItemType-Elemente) to specify which subnodes are to be displayed and which context atttributes are to be displayed on these subnodes as a text or tooltip. The dataSource property of the TreeNodeType element or TreeItemType element is bound to the corresponding context node and the properties text , tooltip , and so on, are bound to the corresponding context attributes on this context node.

TreeItemType elements cannot have children. Therefore, they are always displayed as leaves. They are used when it is decided at design time that the corresponding node does not have children. When using TreeNodeType elements, the decision of whether to use children is dynamically made at runtime.

Hierarchy levels defined in the context cannot be left out when displaying the UI element. For example, a TreeNodeType element that is bound to the Orders must also exist to display the items for the hierarchy Customers → Orders → Items, which is defined in a context.

All nodes that are not directly below the context root node must be non-singleton nodes, because all elements should be displayed in a tree regardless of the lead selection.






• defaultItemIconAlt Describes an alternative text for the graphic of a leave that is displayed when the corresponding graphic is not available or cannot be loaded.

• defaultItemIconSource Describes the Web address (URL) of the graphic to be displayed for a leave.

• defaultNodeIconAlt Describes an alternative text for the graphic of a node that is displayed when the corresponding graphic is not available or cannot be loaded.

• defaultNodeIconSource Describes the Web address (URL) of the graphic to be displayed for a node.

• minHeight Specifies the minimum height of the tree.

• rootText Describes the text for labeling the root node.

• rootVisible Specifies whether the root node of the tree structure is visible.


• auto • Specifies that the UI element automatically changes the lead selection after an interaction by the user before the corresponding event is triggered.

• manual • Specifies that the UI element does not change the lead selection after an interaction by the user but triggers the corresponding event. In this case, the event handler must change the lead selection to enable the UI element to display the data. This setting allows you to check the change of the lead selection.

• title Describes the tree header.

• titleVisible Specifies whether the tree label is visible.

• width Specifies the width of the tree and can be specified in CSS units like em, ex, pixels, or percentage.


al Value


dataSourc e IWDTree Object bindable_mandatory

No

defaultItemIconAlt IWDTree String (TranslatableText) bindable No




defaultItemIconSource

IWDTree String bindable No

defaultNodeIconAlt

IWDTree String (TranslatableText) bindable No

defaultNodeIconSource

IWDTree String bindable No



minHeight IWDTree String (CSS size) bindable No

rootText IWDTree String (TranslatableText) bindable No

rootVisible IWDTree boolean true bindable No


IWDTree WDLeadSelectionChangeBehaviour

auto

not_bindable No

title IWDTree String (TranslatableText) bindable No

titleVisible IWDTree WDVisibility visible

bindable No

tooltip IWDUIElement


visible IWDUIElement

WDVisibililty visible

bindable No

width IWDTree String (CSS size) bindable No

The tooltip property is ignored and does not affect the browser.

Data Binding See Data Binding of a Tree UI Element [Page 273].

4.1.41.1 Web Dynpro TreeNodeType API

Definition The TreeNodeType object describes a tree node type that, unlike the TreeItemType object [Page 272], can contain additional tree nodes. They represent the nodes of the tree [Page 255].

Property Descriptions • expanded

Specifies whether or not a tree node can be collapsed or expanded. The binding of this property is not mandatory, however, we recommend the binding of the property to a context attribute. In this case, this context attribute must be contained in a context node to which the dataSource property is bound. You can now specify the initial expansion status of the tree node.




• hasChildren Specifies whether or not a tree node has children. If you define an onLoadChildren event handler, the corresponding tree element is displayed as a tree node by default – that is, the tree element has an expansion symbol that can be used to expand or collapse the tree. If you know beforehand or during the LoadOnDemand that a tree element does not contain children, you can set the hasChildren property to false. The default value of this property is true. The tree element is then displayed as a leave without expansion symbol.

The hasChildren property is only evaluated if no data for children of the corresponding tree element is available. Tree elements are always displayed as tree nodes if data for their children is available.



Required

dataSource [External]

IWDAbstractTreeNodeType


No

design [External]


WDTreeNodeDesign

standard

bindable No

expanded IWDTreeNodeType boolean false bindable No

hasChildren

IWDTreeNodeType boolean true bindable No

iconAlt [External]



bindable No

iconSource [External]


String bindable No

ignoreAction [External]



text [External]



bindable No

tooltip [External]



bindable No

Events • onAction (String path)

Specifies the action that is executed when the user selects a node of this type.

• onLoadChildren (String path) This property contains the action that is executed when the data for a compressed tree node that initially has no children is read from the back end only if required. This




requires the implementation of a corresponding event handler. At runtime, this event handler is called when a tree node without data for its children is expanded. The Web Dynpro application can use the event handler to read data for the children of the expanded tree node and add this data to the tree. The node element that corresponds to the expanded tree node is passed as an event parameter in the event handler to the Web Dynpro application. This requires a parameter mapping, so the Web Dynpro framework can execute the automatic type conversion from the type of the event parameter to the type of the event handler parameter. See Parameter Mapping [External].

The event handler of the event onLoadChildren is only triggered during the expansion if no data for the children of the expanded node exists. If the application adds data during the expansion, the event is not triggered when the tree node is opened again.

Parameter Type Description

path String Path of the context element to which the tree node that triggered this event corresponds.

Example of parameter mapping for the onLoadChildren event that passes the parameter element to the application:

Implementation of the view controller, context elem ent, and parameter-mapping The Web Dynpro application creates a parameter of the type of the node element whose context node is bound to the tree node. If the context node is, for example, TreeLevel1 in the SAP NetWeaver Developer Studio, the Web Dynpro application chooses ITreeLevel1Element as the type of the parameter. This means that the ITreeLevel1Element represents an interface that extends IWDNodeElement .

This parameter can only be filled by the Web Dynpro framework if the application creates another parameter mapping. Since the parameter mapping is defined at UI element event level, the parameter mapping must be implemented in the doModifyView method of the controller implementation of the view. See the following code example:

//@@end

public static void wdDoModifyView(IPrivateTreeView wdThis, IPrivateTreeView.IContextNode wdContext, com.sap.tc.webdynpro.progmodel.api.IWDView view, boolean firstTime)

{

//@@begin wdDoModifyView

if (firstTime)

{

IWDTreeNodeType nodeType = (IWDTreeNodeType )view.getElement("NodeTypes_1");

nodeType.mappingOfOnLoadChildren().addSourceMapping ("path","element");

nodeType.mappingOfOnAction().addSourceMapping( "path" , "selectedElement" );

}




//@@end

}

The name of the event parameter to which is mapped must correspond to the parameter of the event handler. In this example, the parameter is called element .

Implementation of the event handler onActionLoadChi ldren

The corresponding event handler of the onActionLoadChildren event has the following source code:

//@@begin javadoc:onActionLoadChildren(ServerEvent)

/** declared validating event handler */

//@@end

public void onActionLoadChildren(com.sap.tc.webdynpro.progmodel .api.IWDCustomEvent wdEvent, com.sap.test.wdp.IPrivateTreeView.ITreeLev el1Element element )

{

//@@begin onActionLoadChildren(ServerEvent)

int level = element.getLevel();

if (level < 6){

level++;

for ( int i = 0; i < 4; i++) {

IPrivateTreeView.ITreeLevel1Element el = element.nodeRecNode().createTreeLevel1Element();

el.setText( "New Node on Level " + level);

el.setLevel(level);

if (level == 6)

el.setHasChildren( true );

else

el.setHasChildren( true );

element.nodeRecNode().addElement(el);

}

}

//@@end

}




The same applies to the event onAction . Again, the application can define a parameter in the event handler that corresponds to the selected context element. A parameter mapping is also required (see above).

Methods in the Web Dynpro IWDTreeNodeType API Method Name Parameter Return Value Short Descriptio n

bindExpanded (String path) Binds the expanded property to the context node specified by a path.

bindHasChildren (String path) Binds the hasChildren property to the context node specified by a path.

bindingOfExpanded String Returns the path of the context element to which the expanded property is bound. Returns NULL if no binding exists.

bindingOfHasChildren String Returns the path of the context element to which the hasChildren property is bound. Returns NULL if no binding exists.

getExpanded boolean Returns the value of the expanded property.

getHasChildren boolean Returns the value of the hasChildren property.

getOnLoadChildren IWDAction Returns the action that is executed when the onLoadChildren event is triggered.

mappingOfOnLoadChildren IWDParameterMapping Returns the parameter mapping for the onLoadChildren action.

setExpanded (boolean expanded)

Sets the value of the expanded




property.

setHasChildren (boolean hasChildren)

Sets the value of the hasChildren property.

setOnLoadChildren (IWDAction action)

Sets the action that is executed when the onLoadChildren event is triggered.

Additional methods described in the following APIs are available using inheritance: IWDAbstractTreeNodeType [External], IWDViewElement [External].

4.1.41.2 reeItemType API

Definition The TreeItemType object describes a tree node type that, unlike the TreeNodeType Object [], cannot contain additional tree nodes. They represent the leaves of the Tree [Page 255].

Events • onAction (String path)

Specifies the action that is executed when the user selects a node of this type.

4.1.41.3 Data Binding of a Tree UI Element

Overview The Tree UI element displays hierarchical structures. Each Tree UI element contains a number of tree nodes either of the type TreeNodeType or TreeltemTyp. They describe which data is displayed below the top-level context node. The context node is bound by the Tree property dataSource . The only difference between the TreeNodeType element and the TreeltemType element is that the tree node type TreeNodeType can have children, whereas the type TreeltemType can display the leaves of a tree, but cannot have children.

The hierarchical structure of the tree UI element must be represented in the context. This is possible by specifying a certain number of levels in the context at design time. For example: Customer � Order � OrderItems. An example of this type of Tree UI element data binding is available under Code Example for Creation of a Tree UI Element [Page 274].




Design Time

Folder

Folder

Document

Runtime

Folder

Folder Document

Folder Folder

Node

Element

Document

Document

Recursive Nodes – Basis for Data Binding of a Tree

Or you can create a recursive node in the context. In this case, a virtual node points to a parent node at design time. At runtime, a specific property of the context node allows to add non-singleton child nodes that need to be of the same type as the ones they are pointing to. In so doing, you specify – at design time - a context structure with recursive nodes that can have any number of levels at runtime. For an example, refer to Code Example of the Use of a Recursive Node [Page 300].

4.1.41.4 Code Example for Creation of a Tree UI Ele ment

Use The following example shows the data binding of a Tree UI element to a context structure for which a determined number of levels is specified at design time.

Prerequisites You created a Web Dynpro application and within a Web Dynpro component you created the view „NonRecursiveTree“, in which you can add a tree UI element and its sub-elements TreeNodeType or TreeItemType.

Procedure

Tree Creation in the NonRecursiveTree View ...

1. You edit the view by double-clicking the NonRecursiveTree view or by choosing Edit in the context menu of the view.




2. At the left bottom edge of the SAP NetWeaver Developer Studio appears the outline window with the default container “RootUIElementContainer”. This container can be filled with UI elements.

3. Right-click the Insert Child menu item. A new window appears. Select a UI element of the type Tree from the dropdown list box and specify a name (ID) for the selected UI element. You can use this ID to call the UI element. You can also create a UI element in the View Designer using little icons, which you can drag and drop directly into the View Designer.

4. Choose Finish.

5. After inserting the UI element into the view you can edit the properties of the individual UI elements in the properties window. If you have already defined the context structure for this view, you can assign context nodes and context attributes to these UI elements in the properties window. To create a complete Tree UI element, use the procedure described above: You add the required subelements of the type TreeNodeType and/or TreeltemType to the Tree UI element, which then represent the complete tree. See the graphic below on the left:

Refer to item 5 under Tree Creation in the NonRecursiveTree View Creation of the Tree_0 UI element in the NonRecursiveTree view.

Refer to item 5 under Context Creation Structure of the context that provides the data and must support the creation of the tree UI element.

Context Creation

Each view contains a corresponding context that provides the data. ...

1. Choose the Context tab in the right editor area.

2. Right-click Context. A context menu appears in which you can create the value nodes and value attributes to create the context structure.




3. Choose New → Value Node. For example, enter the name “Customer” for this context node and specify the context properties of the node in the properties window. Use the values listed in the graphic below.

Confirm by choosing Finish

4. Repeat this procedure until the context structure looks like the one in the graphic.

You can also create the context structure before the creation of the view. In this case, you can already bind the bindable properties of the UI element to the context nodes and context attributes while inserting the UI elements.

Data Binding

To display the data in a UI element, the appropriate properties of the UI element must be bound to the context nodes or context attributes. This requires the following steps: sss

1. Select the Layout tab and edit the properties of the UI element Tree_0 and its subelements.

2. Navigate to a property and choose the graphic in the properties window. The button appears. It enables you to access the Context Viewer dialog box.

3. Select a context node or the context attribute in the dialog box.

4. Confirm by choosing OK.

5. The UI element property is now bound to a context element. The following table lists the main data binding relationships of the Tree example Tree_0. In the same way, the individual associated subelements TreeNodeType and TreeItemType are bound to the corresponding context nodes and context attributes.

Objekt Objekt- ID Datenbindung Pfad innerhalb der Context-Struktur

Tree Tree_0 dataSource property → value node customer

NonRecursiveTree.Customer

TreeNodeType Customer dataSource property → value node customer


TreeNodeType Customer text property → value attribute id

NonRecursiveTree.Customer.id

TreeItemType PurchaseItem dataSource property → value node purchaseItem


PurchaseOrder.purchaseItem

TreeItemType PurchaseItem text property → value attribute





text PurchaseOrder.purchaseItem.text

TreeNodeType PurchaseOrder dataSource property → value node PurchaseOrder


PurchaseOrder

TreeNodeType PurchaseOrder text property → value attribute text

NonRecursiveTree.Customer.PurchaseOrder.text

TreeNodeType Order dataSource property → value node Order

NonRecursiveTree.Customer.Order

TreeNodeType Order text property → value attribute id

NonRecursiveTree.Customer.Order.id

TreeItemType Item dataSource property → value node Item

NonRecursiveTree.Customer.Order.Item

TreeItemType Item text property → value attribute id

NonRecursiveTree.Customer.Order.Item.id

Filling Context with Data

The wdDoInit method in the controller implementation enables you to fill the context of a view with data. The wdDoInit method is a Hook method whose source code is executed when the view controller is initialized. ...

1. Select the Implementation tab. The implementation of the controller is generated directly afterwards.

2. The source code that is to be called when initializing the controller can be inserted into the user coding area that starts with the character string //@@begin wdDoInit() and ends with the character string //@@end . The source code in the wdDoInit method for this example is: /** Hook method called to initialize controller. */ public void wdDoInit() { //@@begin wdDoInit() IPrivateNonRecursiveTree.IContextElement el = wdContext.currentContextElement(); el.setSelectedCustomerIdx(-1); el.setSelectedOrderIdx(-1); el.setSelectedItemIdx(-1); el.setSelectedPurchaseOrderIdx(-1); el.setSelectedPurchaseItemIdx(-1); el.setIdx(0); IPrivateNonRecursiveTree.ICustomerNode customer Node = wdContext.nodeCustomer(); for ( int i = 0; i < 3; i++) { IPrivateNonRecursiveTree.ICustomerElement cust omer = customerNode.createCustomerElement(); customer.setId( "Customer No:" + i); customerNode.addElement(customer); IPrivateNonRecursiveTree.IOrderNode orderNode = customer.nodeOrder();




for ( int j = 0; j < 3; j++) { IPrivateNonRecursiveTree.IOrderElement order = orderNode.createOrderElement(); order.setId( "Order Id:" + i + ":" + j); order.setText( "Order Text:" + i + ":" + j); orderNode.addElement(order); IPrivateNonRecursiveTree.IItemNode itemNode = order.nodeItem(); for ( int k = 0; k < 5; k++) { IPrivateNonRecursiveTree.IItemElement item = itemNode.createItemElement(); item.setId( "Item Id:" + i + ":" + j + ":" +k); item.setText( "Item Id:" + i + ":" + j + ":" +k); itemNode.addElement(item); } } IPrivateNonRecursiveTree.IPurchaseOrderNode pu rchaseOrderNode = customer.nodePurchaseOrder(); for ( int j = 0; j < 3; j++) { IPrivateNonRecursiveTree.IPurchaseOrderElemen t purchaseOrder = purchaseOrderNode.createPurchaseOrderElem ent(); purchaseOrder.setText( "Purchase Order:" + i + ":" + j); purchaseOrderNode.addElement(purchaseOrder); IPrivateNonRecursiveTree.IPurchaseItemNode purchaseItemNode = purchaseOrder.nodePurchaseItem(); for ( int k = 0; k < 5; k++) { IPrivateNonRecursiveTree.IPurchaseItemElemen t purchaseItem = purchaseItemNode.createPurchaseItemEle ment(); purchaseItem.setText( "Purchase Item Id:" + i + ":" + j + ":" +k); purchaseItemNode.addElement(purchaseItem); } } } //@@end

3. }

Calling the Web Application

Before you call the Web application, you must build the Web Dynpro project and install the Web application on the SAP J2EE Engine. Build and deploy the application and call it by choosing Run.

You can call the Web application using a Web address in the browser. The following graphic shows the resulting tree in the browser:




Result

The resulting tree displays three customers (No: 0 to No: 2), each of them containing:

• Three purchase orders (0:0 to 0:2) with five purchase item IDs (0:1:0 to 0:1:4)

• Three orders (0:0 to 0:2) with five item IDs (0:1:0 to 0:1:4)

4.1.42 TriStateCheckBox API A TriStateCheckBox is an extension of a checkbox which can have the values true and false and also the state undecided . The UI element consists of a graphic with text. The checkmark in the box indicates that the option is selected and the value is set to true , and an asterisk indicates the status undecided , as the following graphic illustrates:




Definition The Web Dynpro class TriStateCheckbox which implements the IWDTriStateCheckBox interface is the base class of checkboxes which can have three different statuses.

Description of UI Element Properties • state

Describes the status of the TriStateCheckBox. Checked is represented by the enumeration type WDTriState and can have the following values:

� true

� undecided

� false


• state The data type of this property corresponds to the enumeration type WDState . You can use the following values in the application:


required Specifies whether the entered value is required. A red asterisk appears next to the text.

• text Specifies the text that is associated with the checkbox graphic and displayed to the right of the box.

• textDirection Specifies the text direction and allows you to read texts in languages which require a specific text direction. The textDirection property can be filled with the following values and is represented by the enumeration type WDTextDirection .







Required

checked IWDTriStateCheckBox WDTriState false bindable_mandatory No


readOnly IWDTriStateCheckBox boolean false bindable No

state IWDTriStateCheckBox WDState normal bindable No

text IWDTriStateCheckBox String (TranslatableText)

bindable No




textDirection IWDTriStateCheckBox WDTextDirection inherit bindable No


bindable No


Events • onToggle (WDTriState newChecked, WDTriState oldChec ked)

The onToggle event of the type IWDTriStateCheckBox is executed by clicking the TriStateCheckbox. The transfer parameters are the old and the new status. See Event Parameters and Parameter Mapping [External].

4.1.43 ValueComparison API

Definition The UI element ValueComparison (IWDValueComparison) can be used to compare the graphic display of several values. You can use the properties boxValue , markerValue and barValue to visualize the relation of up to three comparison values. In addition, you can set two threshold values and thus define three differently colored areas.

Use Typically, the ValueComparison element is used within a table. You can visualize the comparison of up to three values on a row-by-row basis.




The ValueComparison-Element in its representation in a table column is always justified to the left.

Description of UI Element Properties • barValue

Specifies the width of the bar.

• boxValue Specifies the width of the box.

• colorAboveThreshold Specifies the color of the bar above the upper threshold value.

• colorBelowThreshold Specifies the color of the bar below the lower threshold value.

• colorBetweenThresholds Specifies the color between the threshold values. colorAboveThreshold , colorBelowThreshold and colorBetweenThresholds are of enumeration type WDBarColor and can accept the following values:

� critical

� negative

� neutral1

� neutral2

� neutral3

� positive

• lowerThresholdValue Specifies the lower threshold value.

• markerType Specifies the type of the marker line. markerType is of enumeration type WDMarkerType and can accept two different values:

� critical for a critical value and

� neutral for a neutral value.

• markerValue Specifies the position of the marker line.




• maxValue Defines a maximum value, which is needed if you want to display several ValueComparison elements, for example, in a table. The maxValue property allows you to define a common maximum value which allows the comparison between the different ValueComparison elements.

• text Specifies the text of the ValueComparison element.

• upperThresholdValue Specifies the upper threshold value.

• width Specifies the width of the ValueComparison element in pixels.


Required

barValue IWDValueComparison

double -1 bindable No

boxValue IWDValueComparison


colorAboveThreshold

IWDValueComparison

WDBarColor negative bindable No

colorBelowThreshold

IWDValueComparison

WDBarColor neutral1 bindable No

colorBetweenThresholds

IWDValueComparison

WDBarColor critical bindable No


lowerThresholdValue

IWDValueComparison


markerType IWDValueComparison

WDMarkerType neutral bindable No

markerValue IWDValueComparison


maxValue IWDValueComparison


text IWDValueComparison

String bindable No


upperThresholdValue

IWDValueComparison



width IWDValueComparison

int 0 bindable No


Data Binding of User Interface Element Properties


4.2 Data Binding of User Interface Element Properties

Overview

Mutual data binding enables interaction between UI elements and context elements. The view, which contains the UI elements, is always bound against the context of its assigned controller. If a data binding of context element and UI element property is defined, the changes of the UI element property are directly transferred to the context and vice versa. These changes are also adopted by the properties of other UI elements of the same view if the are bound to the same context element. More complex UI elements – for example, the Table UI element or Tree UI element – can be bound to a context node that represents a collection. Therefore, these UI elements can display the complete data and content of the node.

By storing a reference to a context element, data can be passed directly from the context to the UI element and back. This reference is created by specifying an entry that is similar to a path – for example, MonthsOfYear.MonthName – as a value of a bindable UI element property. A period separates the individual context elements – for example, MonthsOfYear.MonthName . See Code Examples for Data Binding [Page 292].

The SAP NetWeaver Developer Studio provides graphical support of the context elements and allows application developers to assign the context nodes and context attributes to the corresponding UI element properties. This means that the data transport between the context element and the UI element does not require an explicit implementation.

Different Data Binding Approaches There are different data binding concepts for the individual UI elements. The following general rules apply: ... ... ...

1. Data binding with the same data types or convertibl e data types The type of context attribute must be compatible with the property type. This means that the types must be either identical or the property of the UI element must be of the type String and convertible. In the latter case, the type of the context attribute (for example, InputField value) does not matter.

2. Data binding of UI elements with dynamic or static characteristics It is pointless to bind certain UI elements - for example, properties with a static characteristic - to a corresponding context. This is why the ID of a UI element, which a label control refers to, cannot be bound to a context. However, the data source of a table UI element, which is usually created dynamically and also represents a structure, must be bound to a context.

3. Data binding of UI elements with non-scalar charact eristics Several properties of UI elements do not have scalar characteristics, but resemble a collection of elements. These elements are not bound to an individual root attribute but to the context attribute of a multiple node. A multiple node can be a dropdown list box, for example. Each element of the multiple node contains a different instance of the context attribute. Therefore, several elements appear in the selection list.

4. Data binding to the context node There are also properties that refer to a complete node and not only to one of its attributes. This applies to the data source of a table: The elements of the bound node correspond to the table rows, its attributes to the columns.




Note that the IDs of the UI elements are not bound. The same applies to these properties that represent the names of an action and can be executed when an event occurs – for example, CheckBox.onToggle.

Certain properties, however, can be bound to any type of the context attribute if they are defined as convertible. These include:

� InputField.value

� Label.text

� TextEdit.value

� TextView.text

All other properties can only be bound to a context attribute of the same data type.

Example of the Data Binding Principle The checkbox group UI element can be bound, for example, to the context attribute MonthName of the context node MonthsOfYear using the bindTexts property.

The CheckBoxGroup UI element stores the reference to the context attribute. Therefore, it automatically receives the context values and can overwrite the context with new values. The application developer can initializes the value of the context attribute in the wdDolnit method.

4.2.1 Bindable Data Types

Overview Data binding is possible within Web Dynpro when using data types that can be used in the context definition. The following basic data types can be used:

Value node

Value attribute




• String

• Date

• Double

• Boolean

• Timestamp

• Binary

• Integer

• Time

• Float

• Binary

• Decimal

In addition, business data types (BDT) that are defined in the Java Dictionary can be used in the context definition and for data binding.

All business data types can be derived from the basic types already mentioned.

In SAP NetWeaver Developer Studio, you can define a simple business data type [External] and use it as a data type for a context attribute.

Since UI elements in Web Dynpro should be reusable, business data types cannot be used as data types for UI element properties or UI element parameters. However, a general metadata type interface in Web Dynpro allows the dynamic creation of metadata at runtime. The data type interface provides a method for data types that can be edited, and this method checks whether or not a string display of the data type in a business data type can be converted according to the conversion rules and validation rules. See also Dynamic Metadata [Page 291].

4.2.2 Typing Context Attributes for Data Binding

Controller contexts are storage locations for structured data in the Web Dynpro programming model. At runtime, values or objects of different types can be stored in context attributes.

Context elements (nodes and attributes) can be defined for different purposes:

• As local or global storage locations for UI data: In Web Dynpro, the concept of data binding represents a simple means of supplying view layouts (generally the user interface or UI) with context data. To be able to use UI data in multiple view layouts, you can create corresponding context mapping chains. The original data is stored globally in a non-view context (custom or component context).

• As local or global storage locations for any other data: Controller contexts can generally also store any Java objects that are not used for data binding between the UI and view context.

If context attributes are used for data binding, the following rule must be observed when typing them (whether statically at design time or dynamically at runtime):




All context attributes used for data binding betwee n the UI and context must be typed with Dictionary types.

Data binding between the UI and the context is not possible when using native Java types.

In addition to the reasons for this rule, this section also describes the different Dictionary types as well as their counterparts in Web Dynpro for Java. The information serves as a basis for the typing of context attributes at design time (statically using the Web Dynpro tools) and at runtime (dynamically using controller code).

Platform-Independent Typing of Context Attributes The Dictionary provides special data types, with which you can define data binding between UI element properties and context attributes in the Web Dynpro programming model platform-independently. These data types are not mapped onto the corresponding types of the relevant platform (for example, Web Dynpro for Java in the SAP Web Application Server) until runtime.

You can thus type context attributes independently of a specific runtime type (Java type or ABAP type) at design time. At runtime, the context attributes then have the type corresponding to the underlying Dictionary type within the platform-independent controller implementation. This runtime type is also used in the generated context APIs.

Runtime

(Platform-Specific)Design Time (Platform-Independant)

UI ElementInputField

Propertyvisibility

UI Context Definition Context State

Data Binding

Attribute NameFieldVisibility

Attribute Type ddic:com.sap.ide.webdynpro.uielementdefinitions.Visibility

Attribute Value Typecom.sap.tc.webdynpro.progmodel.api.WDVisibility

Attribute ValueWDVisibility.BLANK

Platform

Dictionary Web Dynpro For Java

The figure above shows the connection between the design time and runtime type of a context attribute. To bind the visibility property of an input field to a corresponding context attribute FieldVisibility in the view layout, it must be typed with the Dictionary type com.sap.ide.webdynpro.uielementdefinitions.Visibili ty . If the application is started in Web Dynpro for Java, the FieldVisibility attribute is stored in the context as value of the Java type com.sap.tc.webdynpro.progmodel.WDVisibility .

Dictionary Types Dictionary types can be divided into the following categories:




5. Predefined types: By default, the Dictionary already contains predefined or built-in types – for example, string, integer, or time – in the Dictionary package com.sap.dictionary.* . Furthermore, the package com.sap.dictionary.predefined.objecttypes.* contains types, with which context attributes can be stored object-based instead of value-based (for example, as java.lang.Integer object instead of int value).

6. Types for Web Dynpro UI elements: Web Dynpro expands the Dictionary to include types required for specific UI element properties. In particular, these are the various enumeration types like Visibility as well as different Design or Size types.

7. User-defined local types: In the local Dictionary, application developers can, when necessary, define their own Dictionary types based on other Dictionary types.

8. Types in logical Adaptive RFC models: When an Adaptive RFC model is imported, the used ABAP Dictionary types are stored as corresponding data types in the logical Dictionary so that they can then be used for data binding purposes.

The assignments of the predefined and Web Dynpro UI-specific Dictionary types to the corresponding Java types are shown in the tables in the next section [Page 288].

Typing Context Attributes for Data Binding at Desig n Time

In the standard case, you will define a context attribute at design time so that you can then bind a specific UI element property to it. Depending on the UI element property, the context attribute type must be a suitable predefined Dictionary type (selection list for context attribute property type) or any other Dictionary type (Dictionary Simple Type – Dictionaries – <Logical or Local Dictionary> – <Package Name> – Dictionary Type). ..

1. In the SAP NetWeaver help, open the UI element description.

2. Find the type of the relevant property in the UI element description.

3. The appropriate Dictionary type for the corresponding context attribute matches the Java type, with the exception of the prefix WD.

More information about the definition of context attribute types is available in the section Defining Controller Contexts [External].

Typing Context Attributes for Data Binding at Runti me

When dynamically adding context attributes to a context node for purposes of data binding, note that in this case you must also use a suitable Dictionary type and not the corresponding Java type for the typing with the methods addAttribute() and addValueAttribute() in the IWDNodeInfo API.

• Predefined, Web Dynpro UI-specific, and user-defined Dictionary types all have the prefix ddic :.

wdContext.getNodeInfo() .addAttribute( "Visibility", " ddic:com.sap.ide.webdynpro.uielementdefinitions.Vis bility ")

• Logical Dictionary types from Adaptive RFC models have the prefix extern: .




Note that no new Dictionary types can be created at runtime. However, it is possible to carry out dynamic type modifications for individual context attributes using the IWDAttributeInfo API. Calling the method IWDAttributeInfo.getModifiableSimpleType() gives you access to the com.sap.dictionary.runtime.IsimpleTypeModifiable API, with which you can alter the type information of a context attribute (for example, add new key/display text pairs or set the field label). In all cases, the changes are based on the Dictionary type with which the context attribute was statically or dynamically typed. An example of this is described under Including an Extended Value Selector [External].

4.2.3 Assignment of Dictionary Types and Java Types The following tables show the assignments of runtime-dependent Dictionary types and the corresponding Java types in Web Dynpro for Java.

Predefined Dictionary Types

Design Time Runtime (Web Dynpro for Java)

Dictionary Type Java Type Comment

com.sap.dictionary.*

boolean boolean Primitive

double double Primitive

float float Primitive

integer integer Primitive

long long Primitive

short short Primitive

date java.sql.Date Class

decimal java.math.BigDecimal Class

string java.lang.String Class

time java.sql.Time Class

timestamp java.sql.Timestamp Class

com.sap.dictionary.predefined .objecttypes

java.lang.*

booleanObject java.lang.Boolean Class

doubleObject java.lang.Double Class

floatObject java.lang.Float Class




integerObject java.lang.Integer Class

longObject java.lang.Long Class

shortObject java.lang.Short Class

Dictionary Types for Web Dynpro UI Elements

Design Time Runtime (Web Dynpro for Java)

Dictionary Type Java Type Comment

com.sap.ide.webdynpro .uielementdefinitions.*

com.sap.tc.webdynpro.clientserver.uielib.standard.a pi

ButtonDesign WDButtonDesign Enumeration

ButtonSize WDButtonSize Enumeration

CellBackgroundDesign WDCellBackgroundDesign Enumeration

CellHAlign WDCellHAlign Enumeration

CellVAlign WDCellVAlign Enumeration

DateMarkingCategory WDDateMarkingCategory Enumeration

DateSelectionMode WDDateSelectionMode Enumeration

DropDownListBoxSize WDDropDownListBoxSize Enumeration

GroupDesign WDGroupDesign Enumeration

HorizontalDividerRuleHeight WDHorizontalDividerRuleHeight Enumeration

InputFieldAlignment WDInputFieldAlignment Enumeration

InputFieldSize WDInputFieldSize Enumeration

LabelDesign WDLabelDesign Enumeration

LayoutCellDesign WDLayoutCellDesign Enumeration

LayoutCellSeparator WDLayoutCellSeparator Enumeration

LinkSize WDLinkSize Enumeration

LinkType WDLinkType Enumeration

PhaseIndicatorBackgroundDesign

WDPhaseIndicatorBackgroundDesign Enumeration

PhaseStatus WDPhaseStatus Enumeration

ProgressIndicatorBarColor WDProgressIndicatorBarColor Enumeration

RoadMapEdgeDesign WDRoadMapEdgeDesign Enumeration

RoadMapStepDesign WDRoadMapStepDesign Enumeration

RoadMapStepType WDRoadMapStepType Enumeration

ScrollingMode WDScrollingMode Enumeration




State WDState Enumeration

TabAlignment WDTabAlignment Enumeration

TableColumnHAlign WDTableColumnHAlign Enumeration

TableCompatabilityMode WDTableCompatibilityMode Enumeration

TableDesign WDTableDesign Enumeration

TableSelectionMode WDTableSelectionMode Enumeration

TextDirection WDTextDirection Enumeration

TextViewDesign WDTextViewDesign Enumeration

TextViewLayout WDTextViewLayout Enumeration

TextViewSemanticColor WDTextViewSemanticColor Enumeration

TextWrapping WDTextWrapping Enumeration

ToolBarButtonDesign WDToolBarButtonDesign Enumeration

ToolBarDesign WDToolBarDesign Enumeration

TrayDesign WDTrayDesign Enumeration

TreeNodeDesign WDTrayNodeDesign Enumeration

com.sap.tc.webdynpro.clientserver.uielib.graphics.a pi

BusinessGraphicsDimension WDBusinessGraphicsDimension Enumeration

BusinessGraphicsType WDBusinessGraphicsType Enumeration

GeoPointStyle WDGeoPointStyle Enumeration

MoveType WDMoveType Enumeration

ValueTypeEnumeration WDValueTypeEnumeration Enumeration

ZoomType WDZoomType Enumeration

GeoLine IWDGeoLine Interface

GeoObject IWDGeoObject Interface

GeoPoint IWDGeoPoint Interface

GeoPolygon IWDGeoPolygon Interface

com.sap.tc.webdynpro.progmodel.api

Visibility

WDVisibility Enumeration

com.sap.ide.webdynpro .uielementdefinitions.adobe

com.sap.tc.webdynpro.clientserver.uielib.adobe.api

InteractiveFormMode WDInteractiveFormMode Enumeration

com.sap.ide.webdynpro .uielementdefinitions.mobile

com.sap.tc.webdynpro.clientserver.uielib.mobile.api

BarCodeReaderType WDBarCodeReaderType Enumeration




com.sap.ide.webdynpro .uielementdefinitions .officeintegration

com.sap.tc.webdynpro.clientserver.uielib.adobe.api

OfficeControlMethods WDOfficeControlMethods Enumeration

OfficeDocumentType WDOfficeDocumentType Enumeration

4.2.4 Dynamic Metadata

Overview Non-typed metadata is information that is added directly to the instance of a content element without having defined a specific data type in the Java Dictionary. The main differences between typed metadata and non-typed metadata are that the life cycle of the typed metadata is determined by the life cycle of the context and that its name cannot conflict with the names of other data types.

If a context attribute is a simple data type of the type Simple Types and a program sequence of the application modifies metadata at runtime, this modification is only visible for this context attribute. All other attributes of the application still use the metadata definitions in the Java Dicitionary.

For data binding, the use of non-typed metadata has no disadvantages compared to the use of a typed metadata. A UI element must only be provided with the information of how to access this metadata. This is possible when using a data binding reference to a context attribute that provides the metadata. Therefore, there is no difference in the handling of metadata, and it is not important how the metadata is assigned to the context. All generic services work the same way, including the input help and the validation.

Example The node described below can be filled with metadata at runtime, as follows:

1. Context description at design time:

Value-Node "myNode", collection type=list, cardinal ity=0..n, selection=0..n

and the attribute:

Value attributes “myValue”, type="String".

2. The corresponding Java source code example that you create in the wdDoInit method of the controller implementation:

// The ISimpleTypeModifiable interface enables access to

//a data type instance that can be modified at runtime: ISimpleTypeModifiable myType = wdThis.wdGetAPI().getContext.getModifiableTypeOf (“.myNode.myValue”); //Sets the label text for this data type. myType.setFieldLabel(“New label”) //Sets the valid values of this data type. The individual elements are inserted

//when the put method is called and

//and the value set is filled with the appropriate




//key value pair.

IModifiableSimpleValueSet values = getSVService().myType.getModifiableValueSet(); values.put(“key_1”,”Mister”); values.put(“key_2”,”Mistress”); values.put(“key_3”,”Miss”);

4.2.5 Code Examples of Data Binding The following code source is an example of the interaction between a UI element and a context. The hierarchical structure of the context is defined - that is, the value nodes and value attributes are created and their properties are described (see graphic below).

Describing and Initializing a Context

Context definition at design time

Context example: Name list with the 12 months of a year.

The value node in the example below is defined as follows:

Value node "MonthsOfYear", collection type=list, ca rdinality=0..n, selection=0..n

and the attribute:

Value attribute "MonthName”, type=”String” .

You can define this description in the Web Dynpro perspective of the SAP NetWeaver Developer Studio at design time, as shown in the following graphic.




Initializing the node elements

The node elements are initialized as view context of a Main View view within the wdDolnit method of the context.

At runtime, the context node is filled with values using the source code shown below.

In the example, a constant string array consisting of the 12 month names is declared. This array is used to create a list to which a monthOfYear element is added until the property value of the monthNames object (in this example: length) is greater than 12. In the next step (see 2. in the source code), this list is bound to the MonthsOfYear node. In addition, the selection is initialized and the lead selection is set. In this example, the lead selection is set to the month June.

Source code:


Value node

Value attribute

Value node with thecorresponding properties

�




String[] monthNames = new String [] {

"January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December", };

//1. Create context elements for node "MonthsOfYear " List monthsOfYear = new ArrayList(); for (int i = 0; i < monthNames.length; ++i) {

IPrivateMainView.IMonthsOfYearElement month = wdContext.createMonthsOfYearElement();

month.setMonthName(monthNames[i]); monthsOfYear.add(month);

}

//2. Bind node to element list wdContext.nodeMonthsOfYear().bind(MonthsOfYear);

//3. Initialize selection for (int i = 0; i < wdContext.nodeMonthsOfYear(). size(); ++i) {

//select summer months wdContext.nodeMonthOfYear().setSelected(i, i>=5 & & i<=7 ); }

//set lead selection

wdContext.nodeMonthsOfYear().setLeadSelection(5);

Since the context is initialized, you can bind the property of a UI element to this context by assigning the path of the context attribute to the property of the UI element. Example: checkBoxGroup.bindTexts("MonthsOfYear.MonthName");

Data Binding of the Context Example to Different UI Elements You can already bind a UI element to this context at design time. The wdDoModifyView method for binding a UI element at runtime is provided.

Creating a checkbox group within the wdDolnitModify View method

Each checkbox represents a month and the selection corresponds to the one of the context node:

//CheckBoxGroup

IWDTransparentContainer container = (IWDTranspare ntContainer) view.getElement(IWDTransparentContainer.class, "RootUIElementContainer"); IWDCheckBoxGroup checkBoxGroup = (IWDCheckBoxGrou p) view.createElement(IWDCheckBoxGroup.class, "My CheckBoxGroup"); checkBoxGroup.bindTexts ("MonthsOfYear.MonthNa me");

container.addChild(checkBoxGroup);

Creating a dropdown list box within the wdDoModifyV iew method

Each entry represents a month and the selected entry corresponds to the lead selection of the context node:




//DropDownByIndex

IWDTransparentContainer container = (IWDTranspare ntContainer) view.getElement(IWDTransparentContainer.class, "RootUIElementContainer");

IWDDropDownByIndex dropDownList = (IWDDropDownByI ndex) view.createElement(IWDDropDownByIndex.class, " MyDropDownByIndex"); dropDownList.bindTexts ("MonthsOfYear.MonthNa me");

container.addChild(dropDownList);

Creating a radio button group within the wdDolnitMo difyView method

Each entry represents a month and the selected entry corresponds to the lead selection of the context node:

//RadioButtonGroup


IWDRadioButtonGroupByIndex radioButtonGroup = (IW DRadioButtonGroupByIndex) view.createElement(IWDRadioButtonGroupByIndex. class, "MyRadioButtonGroup"); radioButtonGroup.bindTexts ("MonthsOfYear.Mon thName"); radioButtonGroup.setColCount(12);

container.addChild(radioButtonGroup);

Creating a single-column table within the wdDolnitM odifyView method

For the data binding of a table, a table cell editor (in this example: a TextView UI element) is created and bound to the MonthOfYear node. The table column is defined and the table cell editor is set for it. The table is created and bound to the MonthOfYear node. A column is added to the table using the addColumn method. Each row represents a month and the selected rows correspond to the selection of the context node:

//Table


IWDTextView editor = (IWDTextView) view.createElement(IWDTextView.class, "monthNameC olumnEditor"); editor.bindText("MonthOfYear.MonthName");

IWDTableColumn column = (IWDTableColumn) view.createElement(IWDTableColumn.class, "monthNa meColumn");

column.setTableCellEditor(editor);

IWDTable table = (IWDTable) view.createElement(IWDTable.class, "MyTable");

table.bindDataSource("MonthsOfYear"); table.addColumn(column);

container.addChild(table);

4.2.6 Code Example of Key Binding This binding concept can only be used for data types that can provide a value set to key/value pairs. This requires either the definition of a specific data type in the Java Directory or the extension of the data type String with metadata at runtime. We recommend to define new




data types if the data type in the application is used frequently or the Web application is to be executed using the Java Dictionary.

Example A The following source code is an example of key binding, where the data type String is modified at runtime.

1. Defining the Context at Design Time (Creating a Context Attribute as a Root Node Attribute):

Value-Attribut "MonthName”, type=”String” .

2. Initializing Node Elements Within the wdDolnit Method:

//Get access to runtime modifiable data type instance

ISimpleTypeModifiable myType=wdThis.wdGetAPI().getContext().getModifiable TypeOf( "MonthName");

//Set allowed values for this data type

IModifiableSimpleValueSet values=myType.getSVServices().getModifiableSimpleVa lueSet(); values.put( "0" , "January" ); values.put( "1" , "February" ); values.put( "2" , "March" ); values.put( "3" , "April" ); values.put( "4" , "May" ); values.put( "5" , "June" ); values.put( "6" , "July" ); values.put( "7" , "August" ); values.put( "8" , "September" ); values.put( "9" , "October" ); values.put( "10" , "November" ); values.put( "11" , "December" ); wdContext.currentContextElement().setMonthName( "10" );

If you bind the selectedKey property of a radio button group to a context attribute that is not defined as a root node attribute, you must observe the cardinality of the associated context node when implementing the above source text (see example B).




3. Binding the Context Example to a Radio Button Gr oup

You can bind a UI element that allows key binding to this context (in this case, the RadioButtonGroupByKey UI element) by assigning the context path to a radio button group at design time or by dynamically binding the radio button group to the above mentioned example context at runtime and generating it. You can use the wdDoModifyView method in the controller implementation provided by Web Dynpro.

Controller implementation for dynamic generation of a radio button group: public static void wdDoModifyView(IPrivateMainView wdThis, IPrivateMainView.IContextNode wdContext, com.sap.tc.webdynpro.progmodel.api.IWDView view, boolean firstTime) { //@@begin wdDoModifyView if (firstTime) { IWDRadioButtonGroupByKey radioButtonGroup =(IWDRadioButtonGroupByKey) view.createElement(IWDRadioButtonGroupByKey. class , "MyRadioButtonGroupByKey" ); radioButtonGroup.bindSelectedKey( "MonthName" ); radioButtonGroup.setColCount(3); IWDTransparentContainer container=(IWDTransparentContainer) view.getElement( "RootUIElementContainer" ); container.addChild(radioButtonGroup); } //@@end

}

Example B

1. Defining the Context at Design Time (Creating a Context Attribute as a Context Attribute of the NodeX Node):

Value node NodeX

Value-Attribut "MonthName”, type=”String” .

2. Initializing Node Elements Within the wdDolnit M ethod:

If the cardinality of the NodeX node has been declared with O..n or O..1, there is no node element at runtime, therefore the system must generate a node element in the controller implementation.

//Get access to runtime modifiable data type instance

public void wdDoInit() { IPrivateMainView.INodeXElement newElement = wdContext.createNodeXElement(); ISimpleTypeModifiable myType=wdThis.wdGetAPI().getContext().getModifiable TypeOf( "NodeX.MonthName" ); IModifiableSimpleValueSet




values=myType.getSVServices().getModifiableSimpleVa lueSet(); values.put( "0" , "January" ); values.put( "1" , "February" ); values.put( "2" , "March" ); values.put( "3" , "April" ); values.put( "4" , "May" ); values.put( "5" , "June" ); values.put( "6" , "July" ); values.put( "7" , "August" ); values.put( "8" , "September" ); values.put( "9" , "October" ); values.put( "10" , "November" ); values.put( "11" , "December" ); wdContext.nodeNodeX().addElement(newElement); wdContext.currentNodeXElement().setMonthName( "0" ); wdContext.currentRadioButtonsElement().setMonthNam e("10"); */ //@@end

}

If the cardinality of the NodeX node has been declared with 1..n or 1..1, a node element is present at runtime and you can use the controller implementation in example A, however, you must specify the exact path of the context attribute as a parameter of the getModifiableTypeOf method:

ISimpleTypeModifiable myType=wdThis.wdGetAPI().getContext().getModifiable TypeOf( "NodeX.MonthName");

3. Binding the Context Example to a Radio Button Gr oup

See example A

However, even in this case an exact description of the context attribute path is required:

radioButtonGroup.bindSelectedKey( "NodeX.MonthName" );

4. Result

In both cases, the user sees a radio button group over three columns with the names of the months:




4.2.7 Data Binding of a Dropdown List Box and Radio Button Group

Index Binding This type of data binding enables you to bind a UI element property that represents a list to a context attribute of a node that consists of a data object group at runtime. The context provides the content to be displayed within the UI element and the selection of an element.

The context must have a node, which contains 0 to n values (cardinality=0..n). For this context node, you can specify one or more attributes that provide the node elements at runtime. For data binding, the property of the UI element that is to display the content is bound to the corresponding attribute.

Language dependency of the context content must be taken into account when programming.

There are no requirements for the object type in the value set, whereas key binding requires the object type of the key value pair to be of type String. For further information, refer to Code Examples of Data Binding [Page 292].

Key Binding This type of data binding is provided for data types that were specifically defined in the Java Dictionary or are created at runtime using the dynamic metadata API. The structure of the value set is predefined as a collection of key value pairs by the Web Dynpro Framework. The DropDownByKey UI element can be bound to a context attribute that is either of the type String or contains a String-based and simple data type.

The context provides the content to be displayed with the UI element, the corresponding keys and the selected key for an element.

The context can have any node. For this context node, you can specify one or more attributes that provide the node elements at runtime and that are assigned to a data type with a fixed value set (key value pair). The possible keys are the keys of this value set. The texts to be displayed are the corresponding values of these keys. The selected key is identical to the corresponding value of the attribute.

For data binding, the property of the UI element that is to display the content is bound to the attribute. For an example, refer to Code Example of Key Binding [Page 296].

We recommend that you bind every property of a UI element to be controlled dynamically by the Web application. At runtime, you should modify the value of the bound attribute instead of the property value. A UI element state should only be modified using the Web Dynpro context, because the Web Dynpro runtime environment is optimized for this variant. In addition, this type of data binding supports the separation of layout and data. This makes it easier to exchange UI elements at a later time.




4.2.8 Code Example of the Use of a Recursive Node

Use The example below shows the data binding of a Tree UI element to a context structure whose hierarchical structure is not known at design time and for which, therefore, a fixed number of levels cannot be determined at design time. The context provides a special node for this case, the recursive node.

Prerequisites You created a Web Dypro application and you created the view „RecursiveTree“ within a Web Dynpro Component, which you can include into a Tree UI element and its subelement TreeNodeType.

Procedure

Create a tree in the “RecursiveTree” view as follow s: ...

1. Add the tree UI element with the ID Tree.

2. Add the node element of type TreeNodeType with the ID Node.

Creating a tree UI element: Creating the tree UI element in the “RecursiveTree” view.

Creating the corresponding context: Structure of the appropriate context that provides the data and supports creating the tree UI element.

Context Creation:

The context that provides the data is created as follows: ...

1. Creating the singleton node TreeNode with cardinality 0..n.

2. Creating the context attribute text.

3. Creating the recursive node Child.

You can also create the context structure before the creation of the view. In this case, you can already bind the bindable properties of the UI element to the context nodes and context attributes while inserting the UI elements.

Data Binding

To display the data in a UI element, the appropriate properties of the UI element must be bound to the context nodes. sss

1. To do this, select the Layout tab page and edit the properties of the UI element Tree with the ID Tree and its subelement Node.




2. Navigate to the dataSource property and choose in the Properties window. The

button appears. It enables you to access the Context Viewer dialog box.

3. Select the desired context node.

4. Confirm by choosing OK.

5. The UI element property is now bound to a context element. The following table lists the main data binding relationships of the Tree example. The associated TreeNodeType subelement Node is bound to the corresponding context node in the same way.

Object Object ID Data Binding Path Within the Context Structure

Tree Tree dataSource property → value node TreeNode

RecursiveTree.TreeNode

TreeNodeType Node dataSource property → value node TreeNode

RecursiveTree.TreeNode

Filling Context with Data

The wdDoInit method in the controller implementation enables you to fill the context of a view with data. The wdDoInit method is a Hook method whose source code is executed when the view controller is initialized. ...

1. To do this, go to the Implementation tab page. The implementation of the controller is generated directly afterwards.

2. The source code that is to be called when initializing the controller can be inserted into the user coding area that starts with the character string //@@begin wdDoInit() and ends with the character string //@@end . The source code in the wdDoInit method for this example is: public void wdDoInit() { //@@begin wdDoInit() IPrivateRecursiveTree.ITreeNodeElement level1el ement; for ( int i = 0; i < 2; i++) { level1element = wdContext.createTreeNodeElemen t(); level1element.setText( "Node " + i); wdContext.nodeTreeNode().addElement(level1elem ent); for ( int j = 0; j < 4; j++) { IPrivateRecursiveTree.ITreeNodeElement level2 element = level1element.nodeChild().createTreeNodeElement() ; level2element.setText( "SubNode " + i + "." + j); level1element.nodeChild().addElement(level2element ); for ( int k = 0; k < 6; k++) { IPrivateRecursiveTree.ITreeNodeElement level3element = level2element.nodeChild().createTreeNodeElement(); level3element.setText( "SubNode " + i + "." + j + "." + k); level2element.nodeChild().addElement(level3element) ;




for ( int l = 0; l < 8; l++) { IPrivateRecursiveTree.ITreeNodeElemen t level4element = level3element.nodeChild().createTreeNodeElement(); level4element.setText( "SubNode " + i + "." + j + "." + k + "." + l); level3element.nodeChild().addElement(level4element) ; } } } } //@@end }

Calling the Web Application

Before you call the Web application, you must build the Web Dynpro project and install the Web application on the SAP J2EE Engine.

You can call the Web application using a Web address in the browser. The screen captures below show how the resulting tree is displayed in the browser:

Tree example in the browser in collapsed state

Tree example in the browser in expanded state


Dynamic UI Generation


Result

The resulting tree displays three customers, customer no:0 to customer no:2, each of them containing:

• Three purchase orders (0:0 to 0:2) with five purchase item IDs (0:1:0 to 0:1:4)

• Three orders (0:0 to 0:2) with five item IDs (0:1:0 to 0:1:4)

4.3 Dynamic UI Generation Web Dynpro enables you to statically declare objects at design time. This considerably reduces the programming effort. Dynamic UI Generation, however, enables you to develop programming sequences declared at design time and to develop source code that overwrites existing declarations.

Dynamic Modification of a View Web Dynpro provides the wdDoModifyView Hook method in the controller implementation of the view. In this way you can add source text to the controller implementation of the view in order to program the parts of the user interface that are not yet known at design time. This could be for example configuration-driven parts of the user interface. The wdDoModifyView method is called for every view before it is displayed on the screen. The wdDoModifyView method was defined as a static method because you want to prevent the application development from routinely creating references to UI elements in class variables in order to access for example event handlers. It should only be used to modify a view and therefore should not contain any source text that references controllers. The method is used to modify UI elements of a view in order to enhance the possibilities for UI development at design time. For example, the Hook method is used if a UI element is to be rendered only at runtime.

You can find an example under Dynamic Generation of a User Interface Element [External]. /** * Hook method called to modify a view just before rendering. * This method conceptually belongs to the view itself, not to the * controller (cf. MVC pattern). * It is made static in order to discourage a way of programming that * routinely stores references to UI elements in instance fields * for access by the view controller's event handlers etc. * The Web Dynpro programming model recommends to restrict access to * UI elements to code executed within the call to this hook method! * * @param wdThis generated private interface of the view's controller as * provided by Web Dynpro; provides access to the view controller's * outgoing controller usages etc. * @param wdContext generated interface of the view's context as provided * by Web Dynpro; provides access to the view's data * @param view the view's generic API as provided by Web Dynpro; * provides access to UI elements * @param firstTime indicates whether the hook is called for the first time * during the lifetime of the view */ public static void wdDoModifyView(IPrivate<view name> wdThis, Iprivate<view name>.IContextNode wdContext, com.sap.tc.webdynpro. progmodel.api.IWDView view, boolean firstTime) {


Event Handling of UI Elements


//@@begin wdDoModifyView //@@end

}

Parameter firstTime specifies whether the Hook method was called for the first time during the lifetime of the view.

Note that the implementation of the wdDoModifyView method must always be defined between the comment lines //@@begin and //@@end, which is the user coding area. Otherwise, a runtime error occurs.

You should not define any class variables such as private static IWDView myView in the areas //@@begin others and //@@end of the controller implementation and then use the source text in the wdDoModifyView method as follows: myView = view; . With this source text, no copy of view is created. The reference to myView is overwritten with the reference to view so that there are two references to view . The source text myView = view; thus works in the single user test, but not in production.

The interfaces IWDView and IWDViewElement provide the methods required for modifying the UI elements.

• IWDView provides a method for creating new UI elements: IWDButton submitButton = (IWDButton) view.createElement(IWDButton. class , null ); In this case a pushbutton is created with a unique ID or IWDButton submitButton = (IWDButton) view.createElement(IWDButton. class , "submitButton" );

• IWDView provides a method for accessing existing UI elements using the ID: IWDButton submitButton = (IWDButton) view.getElement( "submitButton" );

• By default, a view contains a TransparentContainer UI element, whose ID is RootUIElementContainer. This element is the top UI element in the hierarchy of the UI elements of a view. This condition cannot be changed, modifications can only be defined for the UI element children of this container.

Note that exactly one view is assigned to a UI element. Therefore, it is not possible to separate UI elements from multiple views or transfer them from one view to another.

4.4 Event Handling of UI Elements

Overview In general, events are situations or incidents that can be recognized by the application and cause corresponding reactions within the application.




Events occur during the interaction between the user and the UI element. Web Dynpro provides specific events for several UI elements. You can assign specific properties to the UI elements that affect the display of the UI elements and by implementing event handling code you can also specify the reaction to an event triggered by an interaction between the user and the UI element. In the Web application, the interaction results in a request sent to the server by the browser. The Web Dynpro Framework analyses the event and calls the corresponding source code in the controller – that is, the event handler. Event handlers are functions that are executed when an event occurs.

Definition In Web Dynpro, events are called actions if they are sent from the client to the server. A typical event of this type is selecting a button. Actions are also the selection of an entry in a dropdown list box (onSelect action) and the toggling to a checkbox (onToggle action).

The code of the event handling, known as Action Event Handler in Web Dynpro, is implemented in the view controller.

The controller interface provides methods that allow access to every action defined in the controller. The wdGetActionNameAction() method (for example, wdGetSaveAction() ) returns the corresponding action instance. In addition, the controller interface lists all actions that are defined for a controller. The listing is displayed as an internal class within the controller interface. The class name is IPrivateControllerName.WDActionEventHandler . It contains a constant value with the names of all actions defined for the controller - for example, the Save action.

A controller with only one action named Save would contain the following action listing:

/** List of all available action event handlers */

public final class WDActionEventHandler extends ActionEventHandlerEnum

{

public static final WDActionEventHandler SAVE =

new WDActionEventHandler( "onActionSave" , true );

private WDActionEventHandler(String value, boolean isValidating) {

super (value, isValidating);

}

}

The controller can deactivate an action named MyAction and consequently a UI element that triggers a specific action using the following code sequence:

wdThis.wdGetMyAction().setEnabled( false );

...

An action event handler is declared when creating an action at design time. You can then bind the action to a UI element or UI element event. The action is executed when an event occurs that was triggered by a specific UI element.




For more information about event handling within a Web Dynpro application, refer to

� Creating an Action at Design Time [Page 310]

� Web Dynpro Action at Runtime – Interface IWDAction [Page 309]

� Event Parameter and Parameter Mapping [Page 316]

.

4.4.1 UI Element Event Model

The Web Dynpro event model associates a UI element event with an action. The action is associated with an action event handler. The role of this model is to bind actions and their event handlers to UI element events in a way that enables the use of the same event handler for several different UI element events and to decouple the event handler implementation from UI element events.

The general procedure for the creation and execution of action event handlers is as follows. From within the Web Dynpro tools, an action and its event handler is created and bound to a UI element event. Parameters for the action event handler are supplied by means of parameter mapping. At runtime, the Web Dynpro runtime framework receives a request from the browser and extracts the UI element event. From this UI element event, the framework knows which action is associated with the UI element event. Next, the action event handler is determined from the action and executed.

The following figure shows the dependency from UI element events to action event handlers.

UI Element

UI Element Event

*

1

Action

0..1

*

Action Event Handler

1

*

Next Section: Generic Validation Service [Page 307]




4.4.2 Generic Validation Service The above description represent the best-case scenario and does not take the generic error handling features provided by the Web Dynpro runtime framework into account. There are many situations where executing an action event handler is not desirable in case the end user has entered invalid data.

Typical Error Behavior for a Save Action Imagine the Web Dynpro model behind the following Web Dynpro UI:

The input field Date of birth is of the type date . When the Save button is pressed, the associated action event handler is only to be called if the user has entered valid data. Entering any invalid data like MyBirthday should inhibit the execution of the event handler and display an error message to the end user. After correcting the invalid data, the user can press the Save button again. The Web Dynpro runtime framework automates this behavior (generic validation service). If the end user enters invalid data, the execution of the action event handler is blocked.

Typical Error Behavior for a Change Action As an alternative, imagine the model behind this Web Dynpro UI:

The end user expects a change in the marital status to enable or disable the input field for married since, which is bound to a context attribute of the type date . An action event handler that is bound to the onSelect event of a RadioButtonGroupByKey UI element can easily implement this behavior. The action event handler simply disables the input field by writing true or false to a context attribute, which is bound to the input field’s enabled property.

Action event handler in view controller FormView.ja va

public void onActionIsMarriedChanged( com.sap.tc.webdynpro.progmodel.api.IWDCustomEve nt wdEvent, String isMarried) { //@@begin onActiononMarriedChanged(ServerEvent) wdContext.currentContextElement() .setMarriedSinceEnabled(isMarried.equals( "IsMarried_Key" ))); //@@end }




Parameter Mapping

How does the action event handler onActionIsMarriedChanged() receive the parameter value isMarried of the type String ? The answer is based on parameter mapping.

Parameter mapping implementation in view controller FormView.java

public static void wdDoModifyView(IPrivateFormView wdThis, IPrivateFormView.IContextNode wdContext, com.sap.tc.webdynpro.progmodel.api.IWDView view, boolean firstTime) { //@@begin wdDoModifyView if (firstTime) { // Access UI element with id “IsMarriedRadioButtonG roupByKey” IWDRadioButtonGroupByKey theRadioButtons = (IWDR adioButtonGroupByKey) view.getElement( "IsMarriedRadioButtonGroupByKey" ); // Map event parameter 'key' to parameter 'isMarrie d' in action // event handler. theRadioButtons.mappingOfOnSelect() .addSourceMapping( "key" , "isMarried" ); } //@@end }

The parameter mapping between the UI element event and the action event handler is implemented in the view controller’s wdDoModifyView() method. By calling the API method IWDParameterMapping.addSourceMapping() , the UI element event parameter key is mapped onto the isMarried parameter of the action event handler.

In addition, the parameter isMarried of the type String has to be declared for the action IsMarriedChanged as well as for its action event handler onActionIsMarriedChanged() (see figure below).

At runtime, the parameter mapping is carried out as follows (see next figure). When a radio button in the RadioButtonGroupByKey UI element is selected, an onSelect event is fired and the key parameter value of the selected item is sent to the server (1). This key parameter value is stored in the context attribute to which the RadioButtonGroupByKey UI element is bound. The key value is then read by the Web Dynpro Java runtime (2). On the basis of the parameter mapping information, the Web Dynpro Java runtime matches UI event parameters (key) with action event handler parameters (isMarried). Finally, the action event handler is invoked using the key parameter value of the RadioButtonGroupByKey UI element based on the given parameter mapping information (3).




Web Dynpro Client User Interface

View Layout

RadioButtonGroupByKey

onSelect

key=“ Key"

UI Element

Event

Parameter

SAP J2EE Engine

Web Dynpro Java Runtime

View Controller

Action Event Handler(String isMarried=“ Key”)

String"Key"

String"Key"

Entering Invalid Data

Now, what happens if somebody enters invalid data?

As shown in the previous figure, the result is not what the end user would expect. Changing the marital status to not married results in a UI element event for the radio button. However, since the input for married since is not valid, the action event handler is not executed and thus the code for disabling the input field does not run.

Next Section: Non-Validating and Validating Actions [Page 314]

4.4.3 Web Dynpro Action at Runtime – Interface IWDA ction

Definition At runtime, the action is represented by the IWDAction interface that allows access to actions in a view controller.

Use A UI element can be bound to an action. The action is executed when an event occurs that was triggered by a specific UI element. If an event occurs, the event handler implemented within the corresponding view controller is called (see Creating an Action at Design Time [Page 310]).

Description of Methods • getActionParameters

This method enables you to access the action parameters of the action if they are required for the next call of the event handler. This method should only be used if a non-validating action returns a validating action and the returned validating action




requires parameters. In this case, the parameters of the returned validating action within a non-validating event handler can be specified (see Action Types [Page 312]).

• getController This method returns the controller of the action.

• isEnabled This method specifies whether or not an action is currently active.

• isValidating This method specifies whether or not an action is a validating action.

• setEnabled Sets the enabling status of the action. If an action is not active, the Web Dynpro Framework ensures that the event handler is also not available for other UI element events.

Method Overview of the Web Dynpro Action API Method Name Parameter Return Value Short Descriptio n

getController IWDController Returns the controller of the action.

getActionParameters IWDParameters Returns the action parameter of the action.

isEnabled Boolean Returns the Boolean value that indicates whether or not the action is enabled.

isValidating Boolean Returns the Boolean value that indicates whether or not the action is a service request.

setEnabled (Boolean enabled) void Sets the Boolean value that activates or deactivates the action.

4.4.4 Creating an Action at Design Time

Use To assign an action to a UI element, you must create the action in the SAP NetWeaver Developer Studio, bind it to the UI element, and manually implement the event handler in the controller of the corresponding view.

Procedure ...

1. You can create an instance of a UI element at design time using the View Designer. In the SAP NetWeaver Developer Studio, you drag a button UI element from the UI element toolbox to the editor area of the View Designer.




2. You can then create the action and select the action tab page (indicated by the white frame in the toolbar of the following graphic). In the edit area, you can:

� Assign a name to the action

� Specify the validation

� Define possible parameters

The Web Dynpro generator automatically creates the event handler. If you assigned the name Save to the action, the corresponding event handler is onActionSave (see graphic below).

3. You also declare the binding of a UI element to an action at design time. When declaring an action in the SAP NetWeaver Developer Studio, a function area – known as the user coding area – is generated in the controller of the corresponding view. You can program the event handler in this function frame. The following code example shows the user coding area that was generated for the Save action. The actions OnClear and OnSearch are already implemented:

/** declared event handler */ public void onActionOnClear() { //@@begin onActionOnClear(ServerEvent) wdContext.currentNodeSearchElement().setEmployee_I d(""); wdContext.currentNodeSearchElement().setFstname_M( ""); wdContext.currentNodeSearchElement().setLastname_M (""); wdContext.currentNodeSearchElement().setOrgtxt_Lg( ""); wdContext.currentNodeSearchElement().setRoom_No(" "); //@@end } /** declared event handler */




public void onActionOnSearch() { //@@begin onActionOnSearch(ServerEvent) wdThis.NavToResults(); //@@end } /** declared event handler */ public void onActionSave() { //@@begin onActionSave(ServerEvent) //@@end } //@@end }

The program code of the event handler should only be inserted into the user coding area – that is, between the comment lines //@@begin and //@@end. Otherwise, the Web Dynpro generator overwrites or deletes the code during the creation.

4. The UI element (in this case: the button) is bound to the action. The properties of the UI element are processed in the property editor, and the previously created action is selected for the onAction property of the button. The action event handler is called at runtime when the user selects the button.

Having defined an action, you can use it for other UI element events and other UI elements.

Result You have defined an action at design time and bound it to a UI element.

4.4.5 Action Types Web Dynpro provides two action types for the description of actions.

Validating Actions The event handler of a validating action is only called after all user data entered is validated, the validated data is passed to the context, and the data entered is also valid.

The event handler of a validating action assumes that:

• The data saved in the context is valid

• The data saved in the context matches the data entered by the user

• Using the event handler of a validating action, the system can:

• Trigger navigation links by calling an outbound plug




• Use the data saved in the context for other processes. If they are bound to a UI element, they are visible to the user.

• Call a Web Dynpro Message Manager to display error messages or throw exceptions that originate from a WDNonFatalRuntimeException .

Example of a Validating Action

The source code of a typical event handler of a validating action: /** declared validating event handler */ public void onActionSave(IWDCustomEvent wdEvent ) { //@@begin onActionSave(ServerEvent) this .getSomeOtherContoller.Save(); this .wdThis.wdFirePlugAddresseSaved(); //@@end

}

Non-Validating Actions The event handler of a non-validating action is called before the user data entered is validated and the validated data is passed to the context.

The event handler of a non-validating action is also called if the invalid data was already entered. This ensures that the event handler of a non-validating action is called without checking whether the user entries are valid.

The event handler of a non-validating action must be capable of processing invalid data saved in the context. To check the validity of the context data, the IWDComponent interface provides the getValidationCheck() method. The method returns an instance of IWDValidationCheck.

The IWDValidationCheck interface makes available methods, with which you can check the validity of the context data.

The event handler of a non-validating action can both write the values to the context and read values from the context.

Use

Non-validating actions are used when the user quits an application, for example, because otherwise the user remains in the application if the entries are invalid. In addition, you can use it to reset the entries in all fields of a view at runtime.

Determining a Non-Validating Action

To define an action as a non-validating action, you must select the checkbox “Without validation” when creating the action and save this setting.




Example of a Non-Validating Action

The source text of a typical event handler of a non-validating action resets the control context of a view and could be written as follows: public onActionClear(IWDCustomEvent wdEvent ) { //@@begin onActionClear(ServerEvent) //Initialize this view’s context this .InitializeContext(); //@@end

}

The application developer must implement the InitializeContext method on the same level as the Web Dynpro component.

4.4.6 Non-Validating and Validating Actions In Web Dynpro, how is it possible that an action event handler is processed despite the fact that the user has entered invalid data?

The answer lies in the use of a non-validating action for this scenario. The distinction between validating and non-validating actions is simple.




A validating action is only executed if all data entered by the end user is valid. If a single validation error occurs, the action event handler is blocked and the relevant error message(s) are displayed.

A non-validating action is always executed, regardless of whether or not the end user entered invalid data. The action event handler must be prepared to deal with invalid data. It is highly recommended to re-initialize invalid context attributes as soon as they are no longer required. Otherwise, any subsequent validating actions could be prevented by old validation errors.

Procedure The above example can now be corrected. First, declare the action as a non-validating action. To do so, open the action’s properties and select the check box Without validation.

Result If you run the application again, the result almost represents the expected behaviour. Invalid data in the input field married since does not block the action event handler execution and thus the input field can be disabled.

Next Section: Re-Initialization of Invalid Context Attributes [External]




4.4.7 Event Parameter and Parameter Mapping

Overview Action event handlers are independent from the UI element that was used to trigger an event. They are independent, because a UI element event is bound to the event handler of an action and this event handler uses an instance of the action class.

Parameters can be passed to certain UI element events. For example, the onSelect event of the DropDownByIndex UI element contains the parameter index .

These event parameters are not defined in the event source - that is, the UI element - but in the implementation of the event handler. Therefore, the implementations in the controller remain independent from the UI element.

If an action is bound to such a UI element, it is also specified which event parameters are to be used as the parameters for the action event handler. This process is known as parameter mapping. It is the mapping of event parameters in the event source, the UI element, to the signature of the event handler.

This is needed, for example, if you want to replace a table with a dropdown list box without modifying the source code of the event handler in the controller. The onLeadSelect event, which occurs when a table cell is selected, provides the parameters col and row . The onSelect event of a dropdown list box contains the parameter index . If you want to exchange the UI elements, you must define a parameter mapping (see example).

The parameter mapping represents an instance of the UI element event. Therefore, the parameter mapping is defined at UI element level. The wdDoModifiyView method is provided to describe the parameter mapping of a UI element event.

Example The following source code example provides the UI element and the corresponding parameter mapping: ...

1. public static void wdDoModifyView(IPrivateMyView wdThis,

2. IPrivateMyView.IContextNode wdContext,

3. IWDView view, boolean firstTime)

4. {

5. //@@begin wdDoModifyView

6. if (firstTime)

7. {

8. // Access UI element with id “theTable”

9. IWDTable theTable = (IWDTable) view.getElement("theTable");

10.

11. // Map parameter row to parameter newSelection. We do not care

12. // about the second parameter “col” also defined for UI event

13. // OnLeadSelect

14. theTable.mappingOfOnLeadSelect().

15. addSourceMapping("row","theNewIndex");

16. }




17. //@@end

18. }

If you replace the table with a DropDownByIndex UI element, you can use the same action event handler without modifying it. However, you must redefine the parameter mapping, because the DropDownByIndex UI element triggers the event onSelect, and this event contains the parameter index . ...




4. {


6. if (firstTime)

7. {

8. // Access UI element with id “theTable”

9. IWDDropDownByIndex theDropDown = (IWDDropDownByIndex)

10. view.getElement("theDropDown");

11.

12. // Map parameter index to parameter newSelection.

13. theDropDown.mappingOfOnSelect().

14. addSourceMapping("index","theNewIndex");

15. }

16. //@@end

17. }

Mapping Constants

You can also map constants using parameter mapping.

In a Web Dynpro application, you can create different buttons at runtime whose maximum number cannot be specified at design time. You can create the buttons and the actions at runtime. However, you can bind all dynamically created buttons to a single action event handler. This special function is based on constant mapping. Without having a reference to a runtime information of the UI element in an action event handler, a Web Dynpro application can determine which button the user selected. This is possible, because constant parameters are mapped to an action event handler.

The event handler can read these parameters and therefore determine which UI element triggered the event. You can replace a button with a link without having to change the source code in the event handler. See the following example source code:

...




4. {





6. if (firstTime)

7. {

8. for (int index = 0;index < 10;index ++)

9. {

10. IWDButton theButton = (IWDButton)

11. view.createElement(IWDButton.class ,"theButton"+index);

12.

13. theButton.setText(getSomeText(index));

14. theButton.setOnAction(wdThis.wdGetGenericAction());

15. theButton.mappingOfOnAction().addParameter("commandId",index);

16. }

17. }

18. //@@end

19. }

20.

21. /** declared validating action event handler */

22. public void onGenericAction (IWDCustomEvent wdEvent , int commandId )

23. {

24. //@@begin onGenericAction(ServerEvent)

25. switch (commandId)

26. {

27. case 0: ExecuteCommand_1();

28. break;

29. case 1: ExecuteCommand_2();

30. break ;

31. ...

32. }

33. //@@end

34. }

Common Event Parameter nodeElement

The parameter nodeElement of the type IWDNodeElement can be used for all events. This parameter must explicitly added for parameter mapping. Use the following code:

...

<Instanz des UI-Elements>.mappingOf<name of the event>().addParameter("nodeElement","nodeElement");

The parameter nodeElement references to the corresponding node element in the context to which the UI element is assigned. For example, when you use a button as a cell editor in a




table, this parameter can be used to determine in which table row the button was pressed without having to analyze the lead selection.

Type Conversion of Complicated Event Parameter Data Types

The Web Dynpro Framework supports type conversion from the type of the event parameter to the type of the event handler parameter. Above all, this affects those event parameters that represent complicated data types, for example, the path parameter of the onAction event of a TreeNodeType element. When triggering the onAction action, the event passes path the parameter on as data type String, which corresponds to the path to the context node that triggered the event. However, at runtime, a node element of type IWDNodeElement corresponds to the tree node in the context. The Web Dynpro Framework can convert the event parameter data type (in this case: String) to the IWDNodeElement data type, if you declare a Java class or interface as the type of the event handler parameter that implements or extends the IWDNodeElement interface. You can find an example of this in the description of the onLoadChildren event for IWDTreeNodeType [Page 268].

See also IWDParameterMapping [Page 319].

4.4.8 Web Dynpro ParameterMapping API - IWDParameterMapping

Overview The parameter mapping is an instance of the UI element event. Therefore, it is defined at UI element level. You describe the parameter mapping for a UI element event using the wdDoModifyView method (see also Event Parameter and Parameter Mapping) [Page 316].

Since the parameter mapping is defined at UI element event level, each UI element event has a corresponding mapping information. Therefore, each UI element that can trigger events returns the mappingOf<UIElementEventName> method. This method returns an instance of the IWDParameterMapping interface. A button UI element with the onAction event provides the mappingOfOnAction that returns the current parameter mapping for the button instance.

Overview of Methods in the Web Dynpro ParameterMapp ing API Method Name

API

Parameter Return Value

Short Description

Method name: addSourceMapping

API:

IWDParameterMapping

(java.lang.String SourceName, java.lang.String NewName)

void Adds a new parameter to the mapping list. The parameter is a constant value. It is read from the mapping source and stored in the IWDParameterMapping instance. The mapping source for actions is the number of UI element event parameters of a specific event. SourceName is the name of the parameter in the mapping source object. NewName is the parameter name after the mapping.

Programming User Messages October 2005

Error Handling


Method name:

addParameter

API:

IWDParameters

(String name, String value)

void Adds a new value to the parameter list.

Name is the name of the parameter in the object. Value is the name of a constant value used as a parameter.

Method name:

addParameter

API:

IWDParameters

(String name, int value)

void Adds a new value to the parameter list.

Name is the name of the parameter in the object. Value is the name of a constant value used as a parameter.

5 Programming User Messages The Web Dynpro programming model allows you to create messages that contain important information for the end user of the Web Dynpro application. For programming these user messages – such as information, error messages, and warnings – the Web Dynpro runtime of the SAP Web Application Server provides a runtime service. The development tools provide support for implementing these messages in form of a graphical tool, the Message-Editor [External].

User messages are displayed as links in the status bar. The user can then use the link to navigate to the user interface element that can be used to remove the error reported in an error message. The input focus is thus transferred automatically, which significantly increases the efficiency of the messages. It is also possible to display multiple messages on the screen. In this case, the messages are sent to the end user in a table.

For information on the procedure for creating these messages, refer to Creating a User Message [Page 325].

5.1 Error Handling The Message Manager, represented by the interface IWDMessageManager, enables you to handle messages and can be used to display information or report errors on the screen. Using relevant methods and depending on the message type, the runtime environment provides the user with a dialog with the Web Dynpro application. Error messages and other messages can be displayed by calling a method of the Message Manager. The Message Manager also provides a number of methods that allow the generation of different error messages and different user interactions to correct the errors.

Error and message handling is closely linked with event handling, validation, and a cycle of questions/answers for a query sent to the server. The runtime environment processes a specific sequence of phases – that is, specific program steps – that are executed within a question/answer cycle. If errors occur when the Message Manager IWDMessageManager is called or when an exception WDNonFatalRutimeException is raised, the subsequent phases of a current question/answer cycle are no longer processed. For example, the system highlights the errors so that the user can easily correct errors caused by incorrect input (see


Error Handling


following description). Afterwards, all subsequent phases of the question/answer cycle can be executed.

For more detailed information about creating, editing and changing messages and for a source text example for using messages, see

• Messages [Page 341]

• Message Editor [External]

• Processing a Message [Page 343]

• Example for Using Messages [Page 330]

.

Description of Interface IWDMessageManager

Simple, String-Based Methods of the Message Manager /**

* Report error message <code> message </code> ..

*

* @param message is the human readable message that will be * displayed on the client. Success phase of the Web Dynpro * request / response cycle are not executed anymor e

*/

public void reportException(String message, boolean cancelNavi gation);

/**

* Report warning message <code> message </code> .

*

* @param message is the human readable message that will be displayed * on the client

*/

public void reportWarning(String message);

/**

* Report an message <code> message </code> .

*

* @param message is the human readable message that will be displayed * on the client

*/

public void reportSuccess(String message);

Context-Specific Methods of the Message Manager

In many cases, an error is caused by invalid data input by the user. To help the user correct invalid data, the Message Manager IWDMessageManager provides a number of methods that allow you to link errors or warnings with a specific context attribute. In this case, the error is


Error Handling


not signified by a simple error message, but instead the UI element that is linked with the invalid context attribute is highlighted – that is, is framed in red. Furthermore, you can simply choose the error message and are then automatically taken to a UI element. You can then correct the error. To link a context attribute with a specific warning or error, the Message Manager provides a number of methods with which you can pass a node element and the name of the context attribute as a parameter. The naming convention for methods that can be linked with a context attribute is: reportInvalidContextAttribute<method suffix> .

For example:

public void reportInvalidContextAttributeException(

IWDNodeElement element,

String attributeName,

WDNonFatalException ex

boolean cancelNavigation);

public void reportInvalidContextAttributeException(

IWDNodeElement element,

String attributeName,

String message


Message-Based Methods of the Message Manager

A message-based method of the Message Manager is described below:

/**

* Report a message item caused by an invalid context attribute * value. *

* @param element is a reference to the context node element * containing the invalid attribute

* @param attributeName is the name of the attribute which is invalid

* @param messageItem is the message associated with the context * attribute

* @param args are the arguments for the message parameters in the * same way as used in @see java.text.MessageFormat

*/

public void reportContextAttributeMessage(

IWDNodeElement element, IWDAttributeInfo attrInfo, IWDMessage messageItem, Object[] args, boolean cancelNavigation);

/**

* Raises a message caused by an invalid context attribute value. This * method internally raises a Runtime exception and execution

* continues in the Web Dynpro framework. It is not recommended to


Error Handling


* call this method with warnings

* and success messages.

*

* @param messageItem is the message associated with the context

* attribute


*/

public void raiseMessage(IWDMessage messageItem, Object[] args ,


/**

* Report a message item caused by an invalid context attribute * value.Depending on the type of the message item

* and on user settings this method may either return or raise a * runtime exception in order to return to the

* framework error handling.

*

*

* @param messageItem is the message associated with the context * attribute


*/

public void reportMessage(IWDMessage messageItem, Object[]args ,


Error Handling and Navigation

All the methods of interface IWDMessageManager that refer to error messages have parameter cancelNavigation . This parameter is of type boolean. If you set the parameter to true , all subseqquent navigation links and doModifyView methods are not called and are executed for the current question-answer cycle. In this way you can protect the system against a loss of unstored data.

In some cases, however, navigation is also required if there is an error. In this case you msut set the parameter to false . The error will not have an effect on subsequent phase processing, but the error is displayed.

Resetting Messages:

The Web Dynpro runtime environment resets the Message Manager for each question-answer cycle. The contents of the Message Manager are not changed for system and service events. Once the action has been performed, the Web Dynpro runtime environment deletes the contents of the Message Manager.


Error Handling


Note that

� the Message Manager is reset if a UI element event triggers an action that is activated

� the Message Manager for service events of the Web Dynpro runtime environment such as load-on-demand events or the input help are not reset

General Rules Concerning Behavior in Case of Errors :

Since Web Dynpro divides a question/answer cycle into various phases, the behavior of the runtime services depends on the phase that is currently running. For example, you cannot trigger an exception and thereby cancel execution of the application if navigation is being performed. The explanation for this is very simple: While navigation is being perforemd, the view group is only in a consistent state before navigation is started and after navigation has been performed. The view group can have any value in between. At this time the Web Dynpro runtime environment therefore cannot determine if navigation was performed if an exception is triggered at this time. This is also true if a doModifyView method is executed.

In this phase the source text of the application can modify the hierarchic UI element structure of a view dynamically. If an exception now occurs, you cannot be sure that this structure is in a consistent state.

Note that exceptions are triggered for error handling if they are edited during event handling for actions. Otherwise the Web Dynpro framework ends the application. The same is true for all methods of the interface of the IWDMessageManager that can output a message on the screen.

Ideally the methods of the Message Manager should only be called within the implementation of an action event handler. However, other methods are often called in the action event handler. The Message Manager should not call these methods directly, but only trigger tested exceptions. These exceptions should be caught by the implementation of an action event handler and reported to the Message Manager.

When handling errors, note that

• Source text that is not called with an action event handler cannot trigger a WDNonFatalRuntimeException. Instead, the source text should trigger an exception that is caught by the calling method.

• Source text that is not called from an action event handler cannot call raise and report methods of the Message Manager. Instead, the source text should trigger an exception that is caught by the calling method.

• Supply functions do not trigger a WDNonFatalRuntimeException and cannot call raise methods of the Message Manager.

• Inbound plugs and methoden within the wdDoInit method do not trigger a WDNonFatalRuntimeException or cannot call raise methods of the Message Manager.

Raise and Report Methods

Most of the methods provided by the Message Manager are available both as raise and as report methods. The difference between these methods is that:

• Report methods save the message and pass it back to the object that called the method


Creating a User Message


• Raise methods also save the message, but do not pass it back to the object that called the method. Instead, they interrupt the current execution phase and proceed directly to the error handling. The raise methods are not returned to the object that called them, since the runtime environment raises a private exception.

Other methods should not be used for the error handling of a Web Dynpro application.

If you use report methods, you can output several errors within a single one. This means that all errors are displayed at the same time. The user can correct errors in a single step and does not have to process any additional requests.

5.2 Creating a User Message

Procedure To create a message, proceed as follows: ...

1. In the Web Dynpro Explorer, place the cursor on the Message Pool subnode of the relevant Web Dynpro component and start the edit mode by choosing Open Message Editor in the context menu.

2. To create a message, choose Add Message. Enter a name for the message key and select the message type using the dropdown list box or the possible entries help (F4). The following message types exist:

Standard, Warning, Error, Text

3. Enter the message text and choose OK to confirm.

You can edit an existing message by choosing Edit this Message –Open Editor Dialog.

Result When the messages are saved, the Web Dynpro Generator creates the interface IMessage<myWebDynproComponent>.java in the target directory for the generated Web Dynpro files; the default directory is <gen_wdp> . The interface class contains the keys of these messages as constants.

Additionally, the following two XML files are created in the <src> directory.

• <myWDComponent>MessagePool.wdmessagepool

� This file contains all messages of the Web Dynpro component as parameters.

• <myWDComponent>MessagePool.wdmessagepool_en.xlf


Messages


� S2X file that is relevant for translation. In this file, the messages are stored in a format readable for the SAP translation process and with additional information such as the maximum length of the message text.

Deleting a User Message

In the Message Editor, you can delete a message by choosing Delete this message.

5.3 Messages

Overview Messages are language-specific texts that are displayed on the screen if an error occurred during the execution of an application. The messages are defined at the level of a Web Dynpro component. Normally, a message is displayed in the status bar. If several messages are to be displayed, they are shown in a table. You can create and edit the messages using the Web Dypro Tool Message Editor [External]. As is the case with other language-specific resources, the Web Dynpro framework generates specific interfaces and XML files that enable you to access the texts created in the Message Editor. See also Message Editor [External].

For more information see

• Creating and Editing a Message [Page 343]

• Handling Errors and Error Messages [Page 320] and


Use ...

1. Displaying Messages to the User The runtime environment offers users a dialog with the Web Dynpro application using the appropriate methods and depending on the message type. Three different message types, which also appear differently on the user interface, are available to display messages :

• error

• standard

• warning

For more information see Example for Using Messages [Page 330].

One or more errors are reported to the user if:

• The Message Manager is called, which is represented by the interface IWDMessageManager


Messages


• An exception is raised that originates from an object of the class WDNonFatalRuntimeException.

The Message Manager provides a number of methods that generate different error messages and allow different user interactions to correct the errors.

Some raise and report methods of interface IWDMessageManager pass the keys of the error messages as parameters, as shown in the following source text for method reportMessage . The keys are generated as constants of the type IWDMessage in the interface IMessage<Web Dynpro component name>.java.

public void reportMessage(IWDMessage messageItem, Object[] args ), boolean cancelNavigation;

Example

You can see an example in Example for Using Messages [Page 330].

2. Displaying Texts

You can use messages of type text for example to label a UI element that was created dynamically. If you only want to show a pushbutton at runtime, you cannot label the pushbutton at design time:

1. You therefore create the text to be displayed at runtime in the message editor as described in Creating and Editing a Message [Page 343].

2. You specify a message key, enter the text to be displayed, and select text as the message type, for example

3. You save all the metadata.

4. With the following source text for the controller implementation of an example view MainView you can create a pushbutton at runtime whose label is read with message key KEY1 and for which “Save input” is displayed as the text of the pushbutton

(see the screen copy of the pushbutton: ). public static void wdDoModifyView(IprivateMainView wdThis, IPrivateMainView.IContextNode wdContext, com.sap.tc.webdynpro.progmodel.api.IWDView view, boolean firstTime) { //@@begin wdDoModifyView if (firstTime) { IWDButton button =(IWDButton) view.createElement(IWDButton. class , "MyButton" ); button.setText(wdComponentAPI.getTextAccessor().ge tText( "KEY1" )); IWDTransparentContainer container=(IWDTransparentContainer) view.getElement( "RootUIElementContainer" ); container.addChild(button); }


Processing a Message


Calling the Messages The messages can be called with the following source text. The text or tooltip is set for a root node element. public void wdDoInit() { IWDTextAccessor textAccessor = wdComponentAPI().get TextAccessor(); wdContext.currentContextElement.setText(textAccesso r.getText( "TEST_KEY_FOR_TEXT", new Object[]{ "test" } )); wdContext.currentContextElement().setTooltip(textAc cessor.getText( "TEST_KEY_FOR_TOOLTIP" )); //@@end }

5.4 Processing a Message

Use You want to display a message for the user on the screen, which will inform the user that an error has occurred, for example. If several messages are to be displayed, these will not be shown in the status bar, but in a table. With the Message Editor [External] you can create, change and delete messages.

Procedure

Creating a Message ...

1. Start the Message Editor in subnode Message Pool of the appropriate Web Dynpro component by double-clicking or by selecting the entry Message editor in the context menu. The user interface of the Message Editor appears.

2. If you choose Add Message, a dialog box appears in which you can create a message. Enter any name that is unique in this Message Pool for the message key, and select the message type from the dropdown box or using the input help F4.

3. Now enter the corresponding message text. Save the messages by placing the cursor on the project name in the Web Dynpro Explorer and choosing Save all Metadata in the context menu. See also Message Editor [External].

Changing a Message ...




1. Open the Message Editor as described above. A dialog box appears that contains the messages already created. See the following examples:

2. Click on an entry to select it.

3. If you choose Edit this Message –Open Editor Dialog, a dialog box appears in which you can edit or change an existing message.

4. After you have made your modifications, choose OK to confirm the changes. To save the modifications, choose Save all Metadata in the context menu for the Web Dynpro project in the Web Dynpro Explorer.

Deleting a Message ...

1. Open the Message Editor as described above.


3. If you choose Delete this Message, the system deletes the message immediately without asking for confirmation. After you have deleted the entry, you save the modifications by choosing Save all Metadata in the context menu for the Web Dynpro project in the Web Dynpro Explorer.


Example for Using Messages


Result Using the wizard support of the Message Editor, you have created messages that are available for error handling in Web Dynpro applications and inform the user if errors occur during the execution of the application.

5.5 Example for Using Messages The following example shows how you can use messages created in the Message Editor. In the example, both messages with static text and messages that are dependent on user inputs – that is, messages with dynamic text – are defined.

Description of Example Users can create a domain in this sample application. They can then enter a number in the next input field and press Click here to validate. If the specified number lies in the previously specified range, the user is informed of this fact in a standard message. If the number does not lie within this domain, the user sees a warning message.

Prerequisites You have created a Web Dynpro application and defined view “MainView” within a Web Dynpro component.

Procedure

Creating the View ...

Define the view as illustrated below:




Context Creation:

The context that provides the data is created as follows: ...

1. Create a context node, UIElem

2. Set the property cardinality to 1..1 for the context node.

3. Create the context attributes a, b, and TypeField.

4. Set the Type of the context attributes to Integer.

Data Binding

To make the messages dynamic with regard to specification of the domain, the user inputs have to be saved. To do this, the input fields have to be bound to the context. sss

Object Object ID Data Binding to Attribute Path Wit hin the Context Structure

a Input Field A MainView.UIElem.a

b Input Field B MainView.UIElem.b

Children_2 Input Field TypeField MainView.UIElem.TypField

In addition, bind the Children_3 pushbutton to action ValidateAction, which you also have to create.

Creating Messages in the Message Pool

The Web Dynpro tools provide a special message editor for defining messages of different types.




A message is defined by a specified key, message type, and message text. The message types error , warning , and standard are predefined.

Create the following messages:

Messages Defined in the Message Editor

Message Key Message Type Message text

key1 warning Please enter a number between the range of {0} and {1}!

{0} and {1} are placeholders for the user input (the domain), which changes dynamically.

key2 standard The value entered is within the valid range.

Implementation

Because the messages are only displayed when the user Chooses Click here to validate, the messages must be implemented in the method onActionValidateAction:

Implementierung der Methode onActionValidateAction() //@@begin imports import com.sap.tc.webdynpro.progmodel.controller.MessageM anager; import com.sap.test.errorhandlingtest1.wdp.IMessageErrorh andlingTest1; import com.sap.test.errorhandlingtest1.wdp.IPrivateMainVi ew; //@@end //... public void onActionValidateAction( com.sap.tc.webdynpro.progmod el.api.IWDCustomEvent wdEvent) { //@@begin int i = wdContext.currentUIElemElement().getTypField() ; int a = wdContext.currentUIElemElement().getA(); int b = wdContext.currentUIElemElement().getB(); MessageManager msgMgr = (MessageManager)wdThis.wdGetAPI().getCompo nent().getMessageManager(); if (a < i && i < b) { msgMgr.reportMessage(IMessageErrorhandlingTest1. KEY2, null, true ); } else {




Object[] arg ={ new Integer(a), new Integer(b)}; msgMgr.reportMessage(IMessageErrorhandlingTest1. KEY1, arg, true ); } //@@end }

The following tasks have been implemented in this m ethod:

1. Read user inputs: int I = wdContext.currentUIElemElement().getTypField() ; int a = wdContext.currentUIElemElement().getA(); int b = wdContext.currentUIElemElement().getB();

1. Read messages from the Message Manager: MessageManager msgMgr = (MessageManager) wdThis.wdGetAPI().getComponent().getMessageManager( );

2. Does the input lie within the defined domain? if (a < i && I < b)

3. Call the standard message when the input lies within the domain: MsgMgr.reportMessage(IMessageErrorhandlingTest1.KEY 2, null );

Method reportMessage can be used to read the messages from the Message Manager. In this way you define the key and the objects that you want to change dynamically in the messages. Because no dynamic text was defined in your standard messages, you define null as a parameter.

4. Call the warning messages when the input does not lie within the domain: Object[] arg ={ new Integer(a), new Integer(b)}; MsgMgr.reportMessage(IMessageErrorhandlingTest1.KEY 1, arg);

Because the warning messages ( Please enter a number between the range of {0} and {1}! ) contain text that depends on the user input, you also have to define the parameters for the domain in an object array. In the messages, the first object is then called from the array with {0} (and the second with {1}, and so on).

Result After you have built and deployed your application, you can call it by choosing Run.

If the user enters a number that lies within the defined domain, a standard message is displayed:

Internationalization of Web Dynpro Projects October 2005

Use


If the user enters a number that does not lie within the defined domain, a warning message is displayed:

6 Internationalization of Web Dynpro Projects

6.1 Use To separate language-dependent text elements from the source code, Web Dynpro uses the Java classes java.util.ResourceBundle und java.text.format. The Java class PropertyResourceBundle, a class derived from the class java.util.ResourceBundle, serves to isolate the language-dependent resources (text elements) and to store their contents in language-specific properties files. For an example of a properties file, refer to the one shown below. This enables you to develop source code that does not contain language-specific texts and therefore does not dependent on the language key used. You can develop Web Dynpro applications that can be easily internationalized and translated into several languages.

At runtime, the relevant properties file is loaded dynamically, depending on the language ID of the current user.

Use An internationalized program contains no language-specific text elements in the source text. These elements include error messages and texts that are used to label UI elements. The text elements are defined outside the application and grouped into isolated resource bundles by the application. If you use translated properties files, you do not need to compile the application again.


Use


Within Web Dynpro, the language-specific text elements are divided into three types:

• Texts that are defined when you create simple data types such as Simple types

• Language-Specific Resources [Page 338] that you specify declaratively at design time These include texts that you assign to the UI element properties or define when you create actions, methods, or simple data types.

• Messages [Page 341]

• Language-dependent resources of the message type text that are used in dynamic programming You can create these text elements also at design time using the message editor [External].

Furthermore, the SAP NetWeaver Developer Studio supports the following:

• The creation of texts and messages that are added to the properties file using the Message Editor [External]

• The modification of S2X files already created using the S2X Document Editor [External]

• The conversion of properties files into S2X files and vice versa The S2X Editor also allows you to add context information to S2X files that is essential for the correct translation of the text elements.

These Web Dynpro tools simplify the process of the creation of international applications and hence the translation process of the language-specific resources.

You can therefore develop applications that suit different languages without having to recompile an application for each individual language when a new language is to be supported.

The Internationalization Service of the Web Dynpro Runtime Services [Page 347] supports this PropertyResourceBundle concept and allows easy access to the classes java.util.ResourceBundle and java.text.format. With the class com.sap.tc.webdynpro.services.sal.localization.api.WDResourceHandler, you can read the language-specific text elements using the following source code:

// Load the resource bundle “MyResourceBundle.properties” located // in the package “com.sap.test” for locale set in the resource handler. // Therefore, the resource handler also needs the classloader that has // the package “com.sap.test” in its scope resourceHandler.loadResourceBundle(“com.sap.test.MyResourceBundle”, this.getClass() ); // get the message of the “press save” button

String saveMessage = resourceHandler.getString( “press_save” );

Example of a Properties File A properties file contains simple name/value pairs for a specific language ID, as the following example of a properties file ResourceTest.properties (generated automatically by the SAP NetWeaver Developer Studio) shows:

# ---------------------------------------------------------------------------

# This file has been generated by the Web Dynpro Code Generator

# DON'T MODIFY!!! CHANGES WILL BE LOST WHENEVER THE FILE GETS GENERATED AGAIN

# ---------------------------------------------------------------------------


Internationalization Concepts for a Web Dynpro Project


# Resource bundle for Test

# message pool

message.error1 = Runtime error

message.warning1 = You have to re-deploy your application!

# view TestViewInternationalization

view.TestViewInternationalization.DefaultTextView.text = Hello World!

For further information about the handling of texts declared at design time, refer to Determining Language-Dependent Resources at Design Time [Page 338].

Additional Information Refer also to the tutorial Developing International Web Dynpro Applications [External], if you wish to program a Web Dynpro application that is to be made available in several languages.

6.2 Internationalization Concepts for a Web Dynpro Project

Internationalization is the process by which the language-specific parts of a program are separated from the other parts. A central aspect of internationalization (I18N) is the translation of texts that are used, for example, to label user interface elements or display messages on user interfaces. The internationalization of a Web Dynpro project is based on the resource bundle concept in which the Web application accesses the resource bundle for the user’s appropriate language at runtime.

To separate the language-specific text elements from the source code, the Java programming language provides the classes java.util.ResourceBundle and java.text.format, which are also used within the Web Dynpro for the internationalization of a Web Dynpro application and are included in the WDResourceHandler class. The Java class PropertyResourceBundle, which is derived from the ResourceBundle class, is used to isolate the language-specific resources (text elements) and store the contents in properties files.

The creation of a resource bundle or properties file is supported by both the Web Dynpro framework and the Web Dynpro tools Message Editor [External] und S2X Document Editor [External]. When you store metadata in the SAP NetWeaver Developer Studio, all the declarative texts are transmitted into the properties file of a Web Dynpro component through the support of the Web Dynpro framework. You can create other texts, such as error messages, with the Web Dynpro tool Message Editor [External]. These are subsequently added to the resource bundle of a Web Dynpro component.

At runtime, the relevant properties file can be loaded dynamically, depending on the language ID of the current user. However, this requires user authentication because the language key is determined through user authentication. If the Web Dynpro application does not require user authentication, the language key of the used browser is used for the selection of the


Translation of the Texts


properties file. For more information on searching for the required properties file, refer to Search Process for Determining the Required Resource Bundle [Page 345].

For information about translation management in the translation backend, refer to the SAP Library under → SAP NetWeaver → Application Platform (SAP Web Application Server) → ABAP-Technology → Documentations and Translation Tools.

6.3 Translation of the Texts

Purpose Properties files cannot be translated immediately because they are generated during the creation of the Web Dynpro project. When creating language-dependent text elements, different S2X files with the extension .xlf are generated for each Web Dynpro component Within a Web Dynpro component, S2X files are created when you

• Use the Message Editor [External] to enter texts and add them to the message pool • Create texts that are used, for example, for the labeling of UI elements and are

assigned to UI element as fixed properties in the SAP NetWeaver Developer Studio. Example : <Web Dynpro component>wdView.xlf

• Create texts that are used as meta information for a defined action, for example • Create texts that are generated during the creation of simple data types

By default, the application development fills these S2X files with the context infomation relevant for the translation using the S2X Document Editor [External].

For the translation process, you must manually create the corresponding language-specific S2X file from scatch and process it . The Web Dynpro tool S2X Document Editor [External] is used to translate language-dependent text elements for the resource bundle of a Web Dynpro component and the properties files.

Note that you do not process the properties files, because they are always generated using S2X files and therefore are overwritten.

Process Flow ...

The following steps describe how to create language-specific S2X files:

1. Copy S2X file To translate the relevant texts contained in the S2X files into a specific language, you must use the Package Explorer of the SAP NetWeaver Developer Studio to copy the requested S2X file in the directory /src/packages using the right mouse button.

2. Insert S2X file with language-specific name Insert the S2X file in the same directory with the additional extension: _<language ID according to the ISO standard 639> after the file name. Example: If you want to translate the S2X file of the Web Dynpro component <Web Dynpro component> for the view MainView <View Name>.wdView.xlf into English, you must enter the file name as follows: <view name>.wdView_en.xlf .


Creating Language-Dependent Resources at Design Time


You must enter the language ID in lower case and must not modify the original name of the S2X file except for this language-specific addition. The language-specific addition is a language ID according to the ISO standard 639. For additional information, refer to the World Wide Web.

3. Store the metadata to save the newly created file. Navigate to File in the uppermost toolbar and select Save all metadata or navigate into the second toolbar and select the

icon Save all metadata.

4. Open the file in the S2X Document Editor for processing.

Only if you process the newly created file in the S2X Document Editor, the encoding tables that are required for the translation are available and Unicode-enabled.

5. After translating the corresponding texts, you save the metadata to save the modifications in the file with the translated texts. Navigate to File in the uppermost toolbar and select Save all metadata or navigate into the second toolbar and select the

icon Save all metadata.

To generate the corresponding properties file, choose Reload in the context menu of the Web Dynpro project. A dialog box appears. Choose Reload+Rebuild to confirm your entries. Choose Deploy New Archive and Run in the context menu to redeploy the Web Dynpro application. Only then the system creates the new properties file and the Web Dynpro application can be called in the appropriate language.

Result You have created a language-specific S2X file that can be used for the generation of an additional language-specific properties file. Therefore, also this resource bundle can be provided at runtime of the Web Dynpro application.

6.4 Creating Language-Dependent Resources at Design Time

6.5 Overview Language-specific resources that you specify as a declaration at runtime include text elements that you assign to a UI element, for example. These declaratively specified texts are stored in a properties file. The SAP NetWeaver Developer Studio supports the creation of the resource bundles or the properties files and generates corresponding properties files and S2X files that are relevant for the SAP translation process. While the properties files are loaded at runtime and are therefore available to the Web Dynpro application, the S2X files are used solely for the translation process.


Overview


Use Within a Web Dynpro project, you create – on the one hand – a properties file with the name Resource+<Web-Dynpro-Component-Name>.properties . This contains texts that were defined within a Web Dynpro component. On the other hand, you create a properties file with the name simpleTypesResource.properties . This contains texts that were defined when data types were created in the Dictionary.

The following language-dependent files are generated when data types are created in the Dictionary.

• An appropriate properties file that has the name simpleTypesResource.properties

• An S2X file for each created data type with the name <Simple-Type-Name>.dtsimpletype.xlf

The following language-dependent files are generated for a Web Dynpro component:

• A corresponding properties file that has the name Resource+<Web-Dynpro-Component-Name>.properties For example, this file runs under the name ResourceTest.properties if you have created a Web Dynpro component with the name “Text”.

At runtime, the relevant properties file can be loaded dynamically, depending on the language ID of the current user. If the Web Dynpro application requires user authentication, the language indicator is determined through the user who is logged on. If no user authentication is required for the Web Dynpro application, the language indicator of the Browser is used for selection of the properties file. For more information on the search for the required properties file, refer to Determining the Required Resource Bundle [Page 345].

• Various S2X files that support the translation process with the name:

� View Layout: <View Name>.wdview.xlf when creating a Web Dynpro component (for example, text for pushbuttons)

� View Controller: <View-Name>.wdcontroller.xlf (for example, text for actions)

� Message Pool: <Web-Dynpro-Component-Name>MessagePool.wdmessagepool.xlf for creating a message pool

These S2X files contain context information required for a correct translation. The context information tells you which user interface element is to display the text and how long the text is allowed to be for the relevant UI element. For example, for the UI element TextView, the text can be no longer than 16384 characters. Then, the properties files are automatically converted to S2X files with the extension .xlf. The resources can be processed in the translation process supported by SAP in this format only. The S2X files contain additional context information that is very important for the correct translation of the resources.

Storage Location of the Properties Files

The properties files for a Web Dynpro component are in the directory /gen_wdp/packages under the name of the respective Web Dynpro component.

The properties files for the Dictionary data types are in the directory /gen_ddic/datatypes .

See also: Internationalization of a Web Dynpro Application [Page 334].


Messages


Example A properties file contains simple name/value pairs for a specific language ID, as the following example of a properties file ResourceTestMessagePool.properties (generated automatically by the SAP NetWeaver Developer Studio) shows:

--------------------------------------------------- ------------------------

# This file has been generated by the Web Dynpro Co de Generator

# DON'T MODIFY!!! CHANGES WILL BE LOST WHENEVER THE FILE GETS GENERATED AGAIN

# ------------------------------------------------- --------------------------

# Resource bundle for TestMessagePool

# message pool

message.error1 = Meldungstext f\u00fcr Meldungstyp "error"

message.standard1 = Meldungstext f\u00fcr Meldungst yp "standard"

message.warning1 = Meldungstext f\u00fcr Meldungsty p "warning"

# view TestViewInternationalization

view.TestViewInternationalization.Button_1.text = S ave

view.TestViewInternationalization.DefaultTextView.t ext = Test to Describe the Internationalization Process

The properties file in the Web Dynpro example component TestMessagePool contains all messages created using the Message Editor and all texts assigned to the UI elements as key/value pairs. For example, the value „Test to Describe the Internationalization Process” is assigned to the text property of the pushbutton UI element with the name Button_1, which is inserted into the view “TestViewInternationalization”.

6.6 Messages

Overview Messages are language-specific texts that are displayed on the screen if an error occurred during the execution of an application. The messages are defined at the level of a Web Dynpro component. Normally, a message is displayed in the status bar. If several messages are to be displayed, they are shown in a table. You can create and edit the messages using the Web Dypro Tool Message Editor [External]. As is the case with other language-specific


Messages


resources, the Web Dynpro framework generates specific interfaces and XML files that enable you to access the texts created in the Message Editor. See also Message Editor [External].

For more information see

• Creating and Editing a Message [Page 343]

• Handling Errors and Error Messages [Page 320] and


Use ...

1. Displaying Messages to the User The runtime environment offers users a dialog with the Web Dynpro application using the appropriate methods and depending on the message type. Three different message types, which also appear differently on the user interface, are available to display messages :

• error

• standard

• warning

For more information see Example for Using Messages [Page 330].

One or more errors are reported to the user if:

• The Message Manager is called, which is represented by the interface IWDMessageManager

• An exception is raised that originates from an object of the class WDNonFatalRuntimeException.

The Message Manager provides a number of methods that generate different error messages and allow different user interactions to correct the errors.

Some raise and report methods of interface IWDMessageManager pass the keys of the error messages as parameters, as shown in the following source text for method reportMessage . The keys are generated as constants of the type IWDMessage in the interface IMessage<Web Dynpro component name>.java.

public void reportMessage(IWDMessage messageItem, Object[] args ), boolean cancelNavigation;

Example

You can see an example in Example for Using Messages [Page 330].

2. Displaying Texts


Messages


You can use messages of type text for example to label a UI element that was created dynamically. If you only want to show a pushbutton at runtime, you cannot label the pushbutton at design time:

1. You therefore create the text to be displayed at runtime in the message editor as described in Creating and Editing a Message [Page 343].

2. You specify a message key, enter the text to be displayed, and select text as the message type, for example

3. You save all the metadata.

4. With the following source text for the controller implementation of an example view MainView you can create a pushbutton at runtime whose label is read with message key KEY1 and for which “Save input” is displayed as the text of the pushbutton

(see the screen copy of the pushbutton: ). public static void wdDoModifyView(IprivateMainView wdThis, IPrivateMainView.IContextNode wdContext, com.sap.tc.webdynpro.progmodel.api.IWDView view, boolean firstTime) { //@@begin wdDoModifyView if (firstTime) { IWDButton button =(IWDButton) view.createElement(IWDButton. class , "MyButton" ); button.setText(wdComponentAPI.getTextAccessor().ge tText( "KEY1" )); IWDTransparentContainer container=(IWDTransparentContainer) view.getElement( "RootUIElementContainer" ); container.addChild(button); }

Calling the Messages The messages can be called with the following source text. The text or tooltip is set for a root node element. public void wdDoInit() { IWDTextAccessor textAccessor = wdComponentAPI().get TextAccessor(); wdContext.currentContextElement.setText(textAccesso r.getText( "TEST_KEY_FOR_TEXT", new Object[]{ "test" } )); wdContext.currentContextElement().setTooltip(textAc cessor.getText( "TEST_KEY_FOR_TOOLTIP" )); //@@end }




6.7 Processing a Message

Use You want to display a message for the user on the screen, which will inform the user that an error has occurred, for example. If several messages are to be displayed, these will not be shown in the status bar, but in a table. With the Message Editor [External] you can create, change and delete messages.

Procedure

Creating a Message ...

1. Start the Message Editor in subnode Message Pool of the appropriate Web Dynpro component by double-clicking or by selecting the entry Message editor in the context menu. The user interface of the Message Editor appears.

2. If you choose Add Message, a dialog box appears in which you can create a message. Enter any name that is unique in this Message Pool for the message key, and select the message type from the dropdown box or using the input help F4.

3. Now enter the corresponding message text. Save the messages by placing the cursor on the project name in the Web Dynpro Explorer and choosing Save all Metadata in the context menu. See also Message Editor [External].

Changing a Message ...

1. Open the Message Editor as described above. A dialog box appears that contains the messages already created. See the following examples:



Search Process for Determining the Required Resource Bundle


3. If you choose Edit this Message –Open Editor Dialog, a dialog box appears in which you can edit or change an existing message.

4. After you have made your modifications, choose OK to confirm the changes. To save the modifications, choose Save all Metadata in the context menu for the Web Dynpro project in the Web Dynpro Explorer.

Deleting a Message ...

1. Open the Message Editor as described above.


3. If you choose Delete this Message, the system deletes the message immediately without asking for confirmation. After you have deleted the entry, you save the modifications by choosing Save all Metadata in the context menu for the Web Dynpro project in the Web Dynpro Explorer.

Result Using the wizard support of the Message Editor, you have created messages that are available for error handling in Web Dynpro applications and inform the user if errors occur during the execution of the application.

6.8 Search Process for Determining the Required Resource Bundle

A resource bundle consists of a set of properties files that contain language-specific keys/value pairs. Each properties file in the resource bundle has a shared name (see Creating Language-Dependent Resources at Design Time [Page 338]) and the respective language key. The following naming convention is used for a Web Dynpro application: Resource+<Web Dynpro component name>_<language key>_<country>.properties.

At runtime, the relevant properties file is loaded dynamically, depending on the language ID of the current user. If the Web Dynpro application requires user authentication, the language indicator is determined through the data of the user who is logged on. If the Web Dynpro


Search Process for Determining the Required Resource Bundle


application does not require user authentication, the language key of the used browser is used for the selection of the properties file.

Search Process Web Dynpro determines the language used for each application instance in accordance with the following rules: ...

• With user authentication In the case of applications that require a user logon (that is, authentication), Web Dynpro uses the language that is assigned to this user as the language indicator.

• Without user authentication If the Web Dynpro application does not require a user authentication, the language key that is used for the selection of the properties file is:

� the indicator of the portal – provided the Web Dynpro application runs in the portal.

� the indicator of the browser used – provided the Web Dynpro application does not run in the portal.

The search for the required properties file is done in accordance with the standard mechanisms for Java resource bundles through the suffixes of the properties files. This means that the text search is begun in the properties file using the determined language indicator for the language indicator of the Web browser. If the search is unsuccessful, the properties file with the default language indicator of the started Web Dynpro application is searched for. Afterwards, the properties file with the default language indicator of the system used and the properties file with the default language indicator of the Java Virtual Machine are searched for. If this search is still unsuccessful, the search for the properties file without language indicator is terminated – that is, the search order is as follows:

1. Resource+<Web Dynpro component name> or simpleTypesResource+”_”+<language indicator of the Web browser>

2. Resource+<Web Dynpro component name> or simpleTypesResource+”_”+<language indicator of the Web Dynpro application>

3. Resource+<Web Dynpro component name> or simpleTypesResource+”_”+<language indicator of the system used>

4. Resource+<Web Dynpro component name> or simpleTypesResource+”_”+<default language indicator of the Java Virtual Machine>

5. Resource+<Web Dynpro component name> or simpleTypesResource

Example

The following table shows the search order for different language indicators:

User Language indicator of the user

Language preference of the browser

Language indicator of the Web Dynpro Application

Language preference of the system

Language preference of the JVM

Language indicator

used

Authenticated user

de en fr it ru de

Anonymous user

- en fr it ru en

Anonymous - - fr it ru fr


Internationalization Service


user

Anonymous user

- - - it ru it

Anonymous user

- - - - ru ru

Determining the Language Indicator for JCo Links

The system variable SY-LANGU for the language in an ABAP-based SAP system is determined from the language that is linked to the JCo connection.

The language that is linked with the JCo connection is determined in different ways:

• If the JCo connection has been set up manually through API at run time, then – as a rule – the language that was specified when the JCo client was created is used.

This procedure should only be used in exceptional cases.

• If the JCo connection was created in the Web Dynpro Content Administrator using DefinedUser , then – as a rule - the configured language in the JCo destination is used, irrespective of the language of the user currently logged on. It is also possible to not define any language; in this case, the current language of the user or the application is determined at runtime.

• If the JCo destination was created in the Web Dynpro Content Administrator using SSOUser or SNCUser , then – as a rule – the language of the current user will be used. This is specified in the User Management logon screen when the user is registered. This procedure is generally used by applications in productive operation that required authentication.

6.9 Internationalization Service

Purpose The internationalization service enables you to access language-dependent resources like messages or texts to be displayed in a UI element. It enables you to easily access these resources using the java.util.ResourceBundle class and the java.text.Format class.

Language-dependent resources – like the text of a UI element that can be translated – can be split into two types.

• Language-dependent resources that you specify at design time. Texts that you assign to a UI element in the SAP NetWeaver Developer Studio are automatically passed to the property resource bundles and are then connected to the SAP translation process. This translation process provides additional resource bundles, which have a language key for the corresponding language. The naming convention is as follows: Resource + < Web Dynpro component name>_<language key>.properties - for example, ResourceTestComponent_en.properties. A property resource bundle is created for each Web Dynpro component that uses a language-dependent text source. The bundle is called Resource + < Web Dynpro component name>.properties. These resource bundle properties files are in the directory structure of the Package Explorer under /gen_wdp/packages in the Web Dynpro component package subdirectory <Web Dynpro component package>.




• Language-dependent resources that are used dynamically – that is, that are programatically specified in the source text of the Web Dynpro application. If you want to use language-dependent resources for dynamic programming, the application programmer must ensure that these resources are entered in the corresponding resource bundles. You can also access the resource bundles that you created yourself using the interface of the internationalization service.

You should store all resource bundles of a Web Dynpro application in the same development component in which the Web Dynpro application is located. This avoids problems that might occur when a development component is updated. In addition, you should create only one resource bundle for all locally dependent resource bundles of a Web Dynpro application, because this reduces the maintenance effort required for the resource bundles.

After you have created the resource bundle that is to support dynamically displayed messages, the application programming must manually import this resource bundle into the S2X translation system and the SAP NetWeaver Developer Studio. In the Web Dynpro Explorer, you open the directory /src/packages and import the resource bundle to the corresponding Java package.

You can also use the Message Editor [External] for maintaining texts that are used dynamically. For more details on how to enter and edit messages, refer to Creating a Message [].

Example The following source code shows the methods provided by the IWDResourceHandler interface. that enable you to access the internationalization service: // All used classes of the internationalization ser vice are contained in package // com.sap.tc.webdynpro.services.sal.localization.a pi // Get the locale of the current session Locale sessionLocale = WDResourceHandler.getCurrent SessionLocale(); // Get the resource handler for the specified sessi on locale by // using the factory class WDResourceHandler. IWDResourceHandler resourceHandler = WDResourceHandler.createResourceHandler(session Locale); // Alternativlely, use the following method: IWDResourceHandler secondResourceHandler = WDResourceHandler.createResourceHandlerForCurre ntSession(); // Load the resource bundle “MyResourceBundle.prope rties” located // in the package “com.sap.test” for locale set in the resource handler. // Therefore, the resource handler also needs the c lassloader that has // the package “com.sap.test” in its scope resourceHandler .loadResourceBundle( “com.sap.test.MyResourceBu ndle”, this .getClass() ); // get the message for the “press save” button String saveMessage = resourceHandler.getString( “pr ess_save” );

evelopment of Interactive Adobe Forms for the Web Dynpro UI October 2005



7 evelopment of Interactive Adobe Forms for the Web Dynpro UI

You can define an interactive form based on Adobe technology for the Web Dynpro user interface. For an efficient and straightforward development of the user interface, you can integrate the Adobe Designer tool with editor and the Adobe UI elements into the SAP tool environment for the Web Dynpro development. In addition, special Web Dynpro form UI elements are available for the form development in the SAP environment. They can be selected by the form developer on a Web Dynpro tab page of the element library of the Adobe Designer:

• Pushbuttons

� CheckFields

� SubmitToSAP

• Input help

� ValueHelpDropDownList

� EnumeratedDropDownList

� EnumeratedDropDownListNoSelect

• Disabling the Adobe toolbar

� HideReaderToolbar

When designing a WD form using the Adobe form template, a manual import of a scheme definition is not required. The SAP system generates a scheme definition file with an associated form context and provides this file to the designer. In the Adobe designer tool, the form developer finds the logical context level in the Data View of the Adobe Designer environment. This Data View is then available for the form definition, together with the Body Pages editor.

Data Flow To define the data, you have to create the required nodes and attributes in the Web Dynpro perspective in the View context structure and assign appropriate values. This context definition is part of the XML file .wdview and to be carried out in the Controller /Context Editor [External] in the Web Dynpro perspective of the SAP NetWeaver Developer Studio.

With the value definition in the SAP tool Controller/Context Editor, the logical data source in the integrated Adobe Designer tool is also available. The names of the nodes and attributes are transferred automatically. There is one exception to this rule if only one node with one or several attributes was defined for the interactive form. In this case, not the value node but exclusively the value attributes defined in the Controller/Context Editor are mapped onto the data view of the Adobe Designer. The form context mapped in the Designer shows the logical view to the XML file .xdp .




The structure of the .wdview file is as follows:

Context

<DataSource>

<ValueNode1>

<ValueAttribute1>

<ValueAttribute2>

…

<ValueNode2>

<ValueAttribute4>

<PdfSource>

According to the structure of the .wdview file, the structure of the xdp file is as follows:

<DataSource>

<ValueNode1>

<ValueAttribute1>

<ValueAttribute2> <ValueAttribute3>

<ValueNode2>

<ValueAttribute4>

<PdfSource>

When creating the Web Dynpro form UI elements, the names of the value objects are transferred automatically from the data source or the context definition. The .xdp file (see tab page XML Source) contains the node and attribute values in the form of elements the XML file. All Web Dynpro form UI elements., such as list box fields, check or submit pushbuttons, are bound to the form UI using the tag <bind match="dataRef"></bind> with a reference (ref="$record.) .

Source Code of the .xdp File


Adobe Library


…

<template xmlns=“http://www.xfa.org/schema/xfa-temp late/2.1/“>

<subform name=“DataSource“ …>

<field name=“ValueAttribute1Name“…>

<bind match=“dataRef“ ref==“$record.<ValueNo de1>[*].<ValueAttribute1>“/>

…

</field>


…

</field>


…

</field>

</subform>

</template>

…

When you define the InteractiveForm UI element, the XML file <ViewName>_<FormName>.xdp is generated and locally saved in the workspace directory /<AdobeProjectName>/src/configuration/Components/<P ackageName>.<ComponentName>.

Additional Information The usage of the form API as well as the procedure when programming a form is described step by step in the Example of the Use of an Interactive Form [Page 358] . You can find a description of the individual form elements provided by SAP in the Adobe Library [Page 351], which is a part of the Reference Guide for the Java Web Dynpro UI elements.

7.1 Adobe Library

Use The user interface elements of the Adobe library support the development of interactive PDF forms in a Web Dynpro application. On the one hand, you have the generic InteractiveForm user interface element in the Web Dynpro tool View Designer at your disposal. With the help of this, you can define a PDF document within a Web Dynpro interface. The user interface element InteractiveForm uses the WD InteractiveForm API of the Web Dynpro runtime.

In addition, you have various elements for designing and implementing the form interface at your disposal. These elements are called form user interface elements and are, technically speaking, XFA (XML Forms Architecture)® objects. Seamless integration of the Adobe Designer® tool within the SAP Web Dynpro development environment makes for efficient design and quick development of interactive Adobe forms in the SAP environment. For example, it is possible to integrate a check procedure into the form that would compare the


Adobe Library


values entered by the end user with those in an existing SAP system. Furthermore, there are various input helps available as well as an element for suppressing the Adobe tools list in the browser during form output. In this way, local downloading or printing of the content of a form by the end user can be prevented.

Prerequisites You have installed the SAP NetWeaver 4.0 Developer Workplace. You must also have Acrobat Reader 7.0 or a full version of Adobe Acrobat 7.0 if you want to use the InteractiveForm UI element. In addition, the Adobe component of the SAP NetWeaver Developer Studio must be installed as this component is not installed in the standard version. However, it is very easy to install it if you want to use interactive PDF forms.

Web Dynpro Form UI Elements With the integrated Adobe Designer tool, you have at your disposal – through Library → Web Dynpro – the following elements:

• CheckFields

• EnumeratedDropDownListNoSelect

• EnumeratedDropDownList

• HideReaderToolbar

• SubmitToSAP

• ValueHelpDropDownList

7.1.1 Web Dynpro InteractiveForm API - IWDInteractiveForm

Definition You can use the InteractiveForm UI element to insert an interactive PDF form into a view. This enables you to create and design a form from scratch. The layout of the PDF form is designed using the tool Adobe Designer (a software product by Adobe). The required Adobe-specific standard objects are provided by a library. These standard objects are subdivided into field objects and text module objects. They represent layout elements like text fields, time fields, push buttons, or checkboxes. They can be inserted into the PDF form template. Field objects like push buttons, radio buttons, checkboxes, and dropdown list boxes enable the user to interact with the application. On the other hand, text module objects like circles, rectangles, and static texts have a static characteristic and can only be used for presentations with a static content. The function of the field objects is similar to that of Web Dynpro UI elements and, like Web Dynpro UI elements, they can also be bound to context attributes of the context of the corresponding view that is filled with the data. However, the standard objects are not displayed in SAP Standard Design 2002 on the PDF form. For information about the use of Adobe Designer, refer to the online help of this tool.

The Adobe Designer is automatically called when you edit the InteractiveForm UI element inserted into the view. You edit the InteractiveForm UI element by selecting Edit in the context menu of the UI element.

You must install Acrobat Reader 7.0 or a full version of Adobe Acrobat 7.0 if you want to use the InteractiveForm UI element. In addition, the required Adobe component in the SAP NetWeaver Developer Studio must be installed. This


Adobe Library


component is not installed by default. However, it is very easy to install it if you want to use interactive PDF forms.

Note that when using the InteractiveForm UI element you cannot display two InteractiveForm UI elements at the same time in the browser window.

For detailed information on the forms based on PDF, refer to the SAP Library under

SAP NetWeaver → Application Platform (SAP Web Application Server) → Business Services → PDF-based Forms.


This property is used to specify the data source. You can use it to specify the path to the context node providing the data. The structure of this context node is displayed in the tab Data View of the Adobe Designer. The context attributes of the node can be bound to the Adobe-specific layout elements defined in the form. These elements are the standard objects and provide the data at runtime.

• mode Specifies the mode of the UI element. At design time, you can specify how the PDF document is created. The mode property can be filled with the following values and is represented by the enumeration type WDInteractiveFormMode .

generatePdf This mode value is used to generate a new PDF document from the data source and the template.

updateDataInPdf This mode value is used to update a PDF document with the data provided by the data source or to create a new PDF document from the data source and the template if no PDF document exists.

usePdf This mode value does not change the original PDF document. The data source and the template for the creation of the PDF document are ignored.

• pdfSource Specifies the path of the context element that contains the PDF document. You must bind this property to a context attribute of the type binary . The application development can then access the binary file and download it to the local hard disk or read and send the data to a back-end using a Remote Function Call (RFC) and the data type XSTRING.

Make sure that the context attribute bound to the pdfSource property is not inserted into the structure of the context node that is to be used for the data of the PDF form. Otherwise the structure of this context attribute is also displayed in the tab Data View of the Adobe Designer:

• templateSource Specifies the unique name of the template. The name is automatically generated when the InteractiveForm UI element is inserted into the view. The element contains the name of the view and the ID of the InteractiveForm UI element.

Overview of Inherited and Additional Properties Name Interface Type Initial Value


Adobe Library


archive IWDAbstractActiveComponent String

classId IWDAbstractActiveComponent String

codeBase IWDAbstractActiveComponent String

dataSource IWDInteractiveForm Object

enabled [External]

IWDUIElement boolean true

height [External] IWDAbstractActiveComponent String 300px

mode IWDInteractiveForm WDInteractiveFormMode updateDataInPdf

pdfSource IWDInteractiveForm Object

templateSource IWDInteractiveForm String <ViewName>_<FormUIElement_Id>.xdp

tooltip [External] IWDUIElement String

type IWDAbstractActiveComponent String

visible [External] IWDUIElement WDVisibility visible

width [External] IWDAbstractActiveComponent String 300px

Events • onCheck

Describes the action to be executed when the user selects the Check pushbutton.

• onSubmit Describes the action to be executed when the user selects the Submit pushbutton.

Data Binding For an example of data binding of the UI element properties, refer to Example of the Use of an Interactive PDF Form [Page 358].

Methods in the Web Dynpro IWDInteractiveForm API Method Name Parameter Return Value Description

bindDataSource (String path) Binds the dataSource property to the context node specified by a path.

bindingOfDataSource

String Returns the path of the context element to which the dataSource property is bound. Returns NULL if no binding exists.


Adobe Library


bindingOfMode String Returns the path of the context element to which the mode property is bound. Returns NULL if no binding exists.

bindingOfPdfSource String Returns the path of the context element to which the pdfSource property is bound. Returns NULL if no binding exists.

bindMode (String path) Binds the value of the mode property to the context element specified by the path.

bindPdfSource (String path) Binds the pdfSource property to the context node specified by a path.

getDataSource Object Returns the value of the dataSource property.

getMode WDInteractiveFormMode

Returns the value of the mode property.

getOnCheck IWDAction Returns the action that is executed if the onCheck event is raised.

getOnSubmit IWDAction Returns the action that is executed if the onSubmit event is raised.

getPdfSource Object Returns the value of the pdfSource property.

getTemplateSource String Returns the value of the templateSourc


Adobe Library


e property.

mappingOfOnCheck

IWDParameterMapping Returns the parameter mapping for the onCheck action.

mappingOfOnSubmit

IWDParameterMapping Returns the parameter mapping for the onSubmit action.

setDataSource (Object dataSource) Sets the value of the dataSource property.

setMode (WDInteractiveFormMode mode)

Sets the value of the mode property.

setOnCheck (IWDAction action) Sets the action that is executed when the onCheck event is triggered.

setOnSubmit (IWDAction action) Sets the action that is executed when the onSubmit event is triggered.

setPdfSource (Object pdfSource) Sets the value of the pdfSource property.

setTemplateSource (String templateSource) Sets the value of the templateSource property.

Additional methods described in the following APIs are available using inheritance: IWDAbstractActiveComponent [External], IWDUIElement [External], IWDViewElement [External].

7.1.2 Web Dynpro Form – UI Element CheckFields If you wish to set up the requirement that the end user has to send his/her entered form data to an SAP system for verification, enter the Web Dynpro form UI element CheckFields from Library → Web Dynpro into the work area of the Adobe Designer, the Body Pages editor.

Using the definition of this form UI element, the Adobe Designer tool generates an XML element <field><field/> for the check itself and for the event with the default name click . This event is executed using the following script:

<script contentType= "application/x-javascript">app.eval("event.target.S APCheckFields();");</script>


Adobe Library


You can edit the form UI element subsequently in the Body Pages editor and also change the layout. The following properties of the CheckFields pushbutton can be adapted by the form developer:

• Pushbutton Text

� Overwrite the default text directly in the editor.

• Border Display

� Choose the context menu entry Border on the form UI element.

• Size and Position

� Choose the context menu entry Layout on the form UI element.

7.1.3 Web Dynpro Form – UI Element EnumeratedDropDownList

The form UI element EnumeratedDropDownList is a Web Dynpro-specific checkbox element. It contains the script that is required for the link to the server in order to retain the elements of the list field from the back end at runtime. This Library object enables the end user to set up an input help request to the SAP server.

Note that the input help request always works in online and offline mode within this UI element. A server-side update of the input help is not possible.

Using Drag&Drop, enter the Web Dynpro form UI element EnumeratedDropDownList from Library → Web Dynpro into the work area of the Adobe Designer, the Body Pages editor, at the required place.

7.1.4 Web Dynpro Form – UI Element EnumeratedDropDownListNoSelect

The form UI element EnumeratedDropDownListNoSelect is a Web Dynpro-specific checkbox element. It contains the script that is required for the link to the server in order to retain the elements of the list field from the back end at runtime. This Library object enables the end user to set up an input help request to the SAP server.

Note that the input help request always works in online and offline mode within this UI element. A server-side update of the input help is not possible.

Using Drag&Drop, enter the Web Dynpro form UI element EnumeratedDropDownListNoSelect from Library → Web Dynpro into the work area of the Adobe Designer, the Body Pages editor, at the required place.

7.1.5 Web Dynpro Form – UI Element HideReaderToolba r Using the form UI element HideReaderToolbar, you can prevent the Adobe tool list from being displayed in the browser. In this way, the end user cannot store a PDF form locally or print it out. Another advantage of using this form element is that the screen output area for the form enlarges itself automatically whenever the Adobe tool list is not displayed.

To insert the HideReaderToolbar UI element, proceed as follows:


Adobe Library


6. Using Drag&Drop, enter the form UI element HideReaderToolbar from the Designer pallet Library → Web Dynpro into the work area of the Adobe Designer, the Body Pages editor. You can position the element at any position within the editor. To be able to quickly get the definition of this element from the form at a later time, we recommend that you enter the element in the upper input area of the editor.

7. Store the changes using Save All Metadata; you can then start the Web preview using the function PDF Preview (see relevant tab in the Adobe Designer) and check whether the tool list is displayed in the browser during form output. In the XML Source tab page, you can also see that this form UI element is a Field element of the XML file <ViewName>.wdview . The following script is responsible for executing the function:

<script contentType="application/x-javascript">var stopToolbar = app.setTimeOut("app.eval(\"SAPToolbarHide();\");", 1);</script>

7.1.6 Web Dynpro Form – UI Element SubmitToSAP With the help of the Web Dynpro form UI element SubmitToSAP, the input data of a PDF form is sent – for storage – to an SAP backend system. The UI element also provides an automatically generated event.

Using Drag&Drop, enter the form UI element SubmitToSAP from the Designer pallet Library → Web Dynpro into the work area of the Adobe Designer, the Body Pages editor. The file contains the element <field><field/> with the definition of the event. This event is executed using the following script:

<event activity="click">

<script contentType="application/x- javascript">app.eval("event.target.SAPSubmit();");< /script>

</event>

You can edit the form UI element subsequently in the Body Pages editor and also change the layout. The following properties of the SubmitToSAP pushbutton can be adapted by the form developer:

• Pushbutton Text

� Overwrite the default text of the UI element directly in the Body Pages editor.

• Border Display

� Choose the context menu entry Border on the form UI element.

• Size and Position

� Choose the context menu entry Layout on the form UI element.

7.1.7 Web Dynpro Form – UI Element ValueHelpDropDownList

The form UI element ValueHelpDropDownList is a Web Dynpro-specific checkbox element. It contains the script that is required for the link to the server in order to retain the elements of the list field from the back end at runtime. This Library object enables the end user to set up an input help request to the SAP server. This request always works in online mode, but not in offline mode. A server-side update of the input help is possible.

Using Drag&Drop, enter the Web Dynpro form UI element ValueHelpDropDownList from Library → Web Dynpro into the work area of the Adobe Designer, the Body Pages editor.

In the XML file <ViewName>.wdview , the element


Example of the Use of an Interactive PDF Form


<bind match="dataRef" ref="$record.<ContextNode>[*] .<ContextAttribute>"/>

is responsible for this function. Each context attribute that you have defined in the WD View context in the Controller/Context Editor [External] and in the Adobe Designer on the DataView tab for DataSource of your form is represented in the view file through a separate tag.

7.2 Example of the Use of an Interactive PDF Form

Use The following example demonstrates the use of an interactive PDF form. It also explains the view structure, the required context structure, and the data binding of the UI element properties to the context structure defined at design time for the PDF form layout. In addition, it contains a procedure for creating and designing an interactive PDF form using the Adobe Designer. For information about the use of Adobe Designer, refer to the online help of this tool.

This example uses a simple PDF document containing two field objects of the type Text Field that display the last name and first name of a person. The PDF document retrieves the required data from the view context. The document is saved as example.pdf on the local hard disk using the Submit button. The source code for the storage is contained in the onActionSubmit method of the controller implementation. For more information, refer to the chapter below: Controller Implementation.

For a description of the individual UI element properties, refer to the Web Dynpro InteractiveForm API documentation.

Prerequisites You have created a Web Dypro application and also a view (in this example called TestInteractivePDFForm ) within the Web Dynpro component into which you want to insert the InteractiveForm UI element. For a detailed description of the procedure for creating Web Dynpro projects, Web Dynpro components, the context structure as well as the layout of the view, see the tutorial Creating Your First Web Dynpro Application.

You will find the system prerequisites in the Adobe library.

Procedure

Creating the view layout in which you want to displ ay the PDF document ...

1. Insert the InteractiveForm UI element with the ID InteractiveForm2 into the view. Choose Insert Child in the Outline window of the RootUIElementContainer in the context menu (right mouse button). Then select the value InteractiveForm in the dropdown list box. The TextView UI element with the ID DefaultTextView is used to label the PDF document and is automatically generated during view creation. In this example, the value Show interactive form is assigned to the text property of this UI element.




Creating the Context Structure ...

1. Create the context node AdressNode .

2. Create the context attributes FirstName and Name.

3. Create the context attribute pdfSource as a root node element. It contains the PDF document at runtime. This context attribute must be of the type binary .

4. Create the supply function fillNode .

Context structure

Properties of the value node AdressNode

Properties of the value attribute FirstName

Properties of the value attribute Name




Properties of the root node attribute pdfSource

If you define the context structure first after creating the view, you can bind the UI element properties to the corresponding context elements directly after the insertion of the UI element into the view.

Creating the actions check and submit

Note that binding the events check and submit is required for the availability of the corresponding pushbuttons in the Web Dynpro tab of the Adobe Designer library. Refer to the screenshot in the chapter entitled Design of the PDF Template.

Data Binding ...

1. Define data binding of the UI element properties (see the following screenshot).

2. Binding the actions




Controller Implementation

The following source code contains only the most important parts of the controller implementation: //Implementation of the supply function fillNod e. The code is called when the view is initialized. public void fillNode(IPrivateTestViewInteractivePDFForm.IAddre ssNodeNode node, IPrivateTestViewInteractivePDFForm.IContextEl ement parentElement) { //@@begin fillNode(IWDNode,IWDNodeElement) IPrivateTestViewInteractivePDFForm.IAddressNodeEle ment element = wdContext.nodeAddressNode().createAddressNodeElemen t(); element.setFirstName( "John" ); element.setName( "Smith" ); wdContext.nodeAddressNode().bind(element); //@@end } .. .. //Implementation of the event submit public void onActionsubmit(com.sap.tc.webdynpro.progmodel.api. IWDCustomEvent wdEvent ) { //@@begin onActionsubmit(ServerEvent) IPrivateTestViewInteractivePDFForm.IContextElement contextElement = wdContext.currentContextElement(); byte [] bytes = contextElement.getPdfSource(); try { File file = new File( "C:\\temp\\example.pdf" ); FileOutputStream os = new




FileOutputStream(file); os.write(bytes); os.close(); } catch (IOException e) { // do something e.printStackTrace(); } wdThis.wdGetAPI().getComponent().getMessageManager ().reportSuccess( "You have pressed Submit! FirstName is: " + wdContext.currentAddressNodeElement().getFirstName( )); //@@end }

After the data binding is completed, you can design the PDF document. Call the Adobe Designer to design and edit the InteractiveForm UI element by choosing Edit in the context menu of this UI element. The Adobe Designer opens in the SAP NetWeaver Developer Studio. The template for the PDF document is provided within the body page. There you can insert the required standard objects, such as Text Field, using the tab Library and the drag and drop function. The Data View of the Adobe Designer provides the context node AddressNode to which you have bound the dataSource property of the InteractiveForm UI element.

Designing the PDF Template : ...

1. For this example, insert two field objects of the type Text Field into the PDF document.

a. Use the Drag&Drop function to insert text field 1, in which the last name is to be displayed




b. Use the Drag&Drop function to insert text field 2, in which the first name is to be displayed

2. Drag and drop the corresponding context attributes FirstName and Name under the context node AddressNode into the two field objects of the type Text Field . If the context attribute or the context node is bound to the standard object, they are marked

by the icon .

3. As is the case in this example, by binding the actions check and submit , you have at your disposal SAP-defined pushbuttons in the Web Dynpro tab which you can use to store the PDF document on your local hard disk. Choose Submit to SAP, then drag and drop this selection to the template (body pages). When this pushbutton is selected, the action that you defined in the onActionsubmit method of the controller implementation is executed.


Configuring the Destination URL for the Adobe Document Services


4. Save the metadata by choosing Save all metadata in the context menu of the pushbutton File in the toolbar.

Result Before you can call the Web Dynpro application, you must build the Web Dynpro project and install the Web Dynpro application on the J2EE Engine.

You start the Web Dynpro applications by choosing Deploy new archive and run in the context menu of the example application ExampleInteractiveFormApplication.

The Web Dynpro application is called in the browser from a Web address. As a result, a simple, interactive PDF document is displayed containing the last name and first name of the person John Smith (see the following screenshot). Since the PDF document is interactive, you can edit these text fields. The current data is saved in the view context.

If you choose the Submit button, the PDF document is stored as example.pdf in the directory C:\temp\ of the server (see source code of the onActionsubmit method in the controller implementation).

7.3 Configuring the Destination URL for the Adobe Document Services

Use With the InteractiveForm UI element you can design and create interactive PDF forms. To do this you need the Adobe document services. These services are installed as Web services on a J2EE Engine and have the destination URL as default.




We recommend that you install the Adobe document services on the J2EE Engine on which the Web Dynpro runtime environment is deployed. In this case the default settings for the destination URL are copied from the Adobe document services.

If the Adobe document services are not provided on the J2EE Engine on which the Web Dynpro runtime environment is deployed, you must change the destination URL of the Adobe document services using the Visual Administrator.

Prerequisites • You have access to the J2EE Engine with administrator authorization.

• To better understand the below sections, read Creating a User for Basic Authentication in the document Adobe Document Services – Configuration Guide. You can find this guide in the SAP Service Marketplace under Quick Link /instguidesNW04.

Procedure ...

1. Start the Visual Administrator by double-clicking on file go.bat in the file directory C:\usr\sap\<System ID>\<System Number>\j2ee\admin , in which the J2EE Engine is installed. For example, the background file can be stored in directory C:\usr\sap\J2E\JC00\j2ee\admin .

2. In the logon screen of the Visual Administrator, select a connection and choose Connect.

3. Enter the password for the connection. You are now connected with the Visual Administrator.

4. Navigate to directory Server → Services → Web Services Security → Web Service Clients → sap.com → tc~wd~pdfobject → com.sap.tc.webdynpro.adsproxy.AdsProxy*ConfigPort_D ocument . The name of the Web service for the Adobe document services is com.sap.tc.webdynpro.adsproxy.AdsProxy*ConfigPort_D ocument .

5. To change the default URL http://localhost:50000/AdobeDocumentServices/Config ?style=document , select Custom in the dropdown listbox next to label URL for the destination URL.

6. Enter the host name and port number <Host Name>:<Port Number> in place of the character string localhost:50000 .

7. Define the user name and password. To find out how to create the user name and password for the Adobe document services, see Creating a User for Basic Authentication in the document Adobe Document Services – Configuration Guide. You can find this guide in the SAP Service Marketplace under Quick Link /InstguidesNW04.

8. Save your entries. You can do this by choosing Save, at the bottom of the left navigation frame.

9. To copy and refresh the changed data in the J2EE Engine, navigate to Services → Deploy.

10. Choose Application.

11. Select sap.com/tc~wd~pdfobject.

12. To stop the application, first choose Stop Application.

13. Then choose Start Application.




Result You defined the URL of the Adobe document services required to create interactive PDF forms.

WD UI Navigation

Documents

Transcript of WD UI Navigation