WD4A Guidelines by rajesh g

SAP NetWeaver Developers Guide Release 2004s

Web Dynpro ABAP Programming Guidelines

SAP AG Dietmar-Hopp-Allee 16 69190 Walldorf Germany T +49/18 05/34 34 24 F +49/18 05/34 34 20 www.sap.com SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP NetWeaver, © Copyright 2006 SAP AG. All rights reserved.

and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of

No part of this publication may be reproduced or transmitted in

SAP AG in Germany and in several other countries all over the

any form or for any purpose without the express permission of

world. All other product and service names mentioned are the

SAP AG. The information contained herein may be changed

trademarks of their respective companies. Data contained in this

without prior notice.

document serves informational purposes only. National product specifications may vary.

Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. These materials are subject to change without notice. These Microsoft, Windows, Outlook, and PowerPoint are registered

materials are provided by SAP AG and its affiliated companies

trademarks of Microsoft Corporation.

("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP

IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex,

Group shall not be liable for errors or omissions with respect to

MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iSeries,

the materials. The only warranties for SAP Group products and

pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner,

services are those that are set forth in the express warranty

WebSphere, Netfinity, Tivoli, and Informix are trademarks or

statements accompanying such products and services, if any.

registered trademarks of IBM Corporation in the United States

Nothing herein should be construed as constituting an additional

and/or other countries.

warranty.

Oracle is a registered trademark of Oracle Corporation. Disclaimer UNIX, X/Open, OSF/1, and Motif are registered trademarks of

Some components of this product are based on Java™. Any code

the Open Group.

change in these components may cause unpredictable and severe malfunctions and is therefore expressively prohibited, as is any

Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame,

decompilation of these components.

VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc.

Any Java™ Source Code delivered with this product is only to be used by SAP’s Support Services and may not be modified or

HTML, XML, XHTML and W3C are trademarks or registered

altered in any way.

trademarks of W3C®, World Wide Web Consortium, Massachusetts Institute of Technology.

Any software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to

Java is a registered trademark of Sun Microsystems, Inc.

be used in a productive system environment. The Code is only intended better explain and visualize the syntax and phrasing

JavaScript is a registered trademark of Sun Microsystems, Inc.,

rules of certain coding. SAP does not warrant the correctness and

used under license for technology invented and implemented by

completeness of the Code given herein, and SAP shall not be

Netscape.

liable for errors or damages caused by the usage of the Code, except if such damages were caused by SAP intentionally or

MaxDB is a trademark of MySQL AB, Sweden.

grossly negligent.

Typographic Conventions

Icons

Type Style

Represents

Icon

Example Text

Words or characters quoted from the screen. These include field names, screen titles, pushbuttons labels, menu names, menu paths, and menu options.

Example

Cross-references to other documentation.

Recommendation

Example text

Emphasized words or phrases in body text, graphic titles, and table titles.

Syntax

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.

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.

Meaning Caution

Note

Contents WEB DYNPRO ABAP: DEVELOPMENT IN DETAIL .............................................................. 1 1

BASICS.............................................................................................................................. 1 1.1

Component................................................................................................................ 2

1.2

Web Dynpro View ..................................................................................................... 3 1.2.1 UI Elements of the View ................................................................................. 5 1.2.2 Structure of the View Context......................................................................... 7 1.2.3 Data Binding ................................................................................................... 8 1.2.4 UI Element Actions ....................................................................................... 10 1.2.5 Action Event Handlers.................................................................................. 12

1.3

Component Controller ............................................................................................. 15 1.3.1 Context Mapping .......................................................................................... 16

1.4

Programming Controller Methods ........................................................................... 18 1.4.1 Reference Variable WD_CONTEXT ............................................................ 19 1.4.2 Reference Variable WD_THIS and Local Controller Interface..................... 19 1.4.3 Methods of the Local Controller Interface .................................................... 20 1.4.4 Web Dynpro Runtime APIs .......................................................................... 32 1.4.5 Filling the Context......................................................................................... 34 1.4.6 Phase Model................................................................................................. 35 1.4.7 Client Implementation................................................................................... 39

1.5

Web Dynpro Window .............................................................................................. 40 1.5.1 Navigation Between Two Views ................................................................... 41

1.6

Web Dynpro Application.......................................................................................... 44

1.7

URL of a Web Dynpro Application .......................................................................... 45 1.7.1 Fully Qualified Domain Names (FQDN) ....................................................... 48 1.7.2 URLs and Namespaces ............................................................................... 53

1.8

Calling a Web Dynpro Application Using Parameters ............................................ 55

CROSS-COMPONENT PROGRAMMING....................................................................... 55 2.1

Controllers of a Web Dynpro Component ............................................................... 56

2.2

Component Usages ................................................................................................ 58 2.2.1 Component Usage without Controller Access.............................................. 59 2.2.2 Component Usage with Controller Access................................................... 62 2.2.3 Navigation Through Window Plugs .............................................................. 63 2.2.4 Cross-Component Context Mapping ............................................................ 64

2.3

Working with Web Dynpro Component Interfaces .................................................. 68 2.3.1 Creating a Web Dynpro Component Interface Definition ............................. 70 2.3.2 Implementing a Web Dynpro Interface Definition......................................... 71 2.3.3 Example for the Implementation of an Interface Definition .......................... 71

2.4

Working With Faceless Components...................................................................... 74

DYNAMIC PROGRAMMING ........................................................................................... 74 3.1

Dynamic Layout Manipulation ................................................................................. 75 3.1.1 Working Dynamically with Parameter Mappings.......................................... 77

3.2

Dynamic Context Manipulation ............................................................................... 79

3.3

Working Dynamically with Component Usages ...................................................... 80 3.3.1 Dynamically Creating Component Usages .................................................. 81 3.3.2 Dynamically Embedding an Interface View.................................................. 83 3.3.3 Method Call in a Dynamically Created Component Usage .......................... 85 3.3.4 Dynamically Registering an Event Handler to an Event............................... 86

ADVANCED CONCEPTS ................................................................................................ 86 4.1

Working with the Assistance Class ......................................................................... 87

4.2

Service Calls in a Web Dynpro Application............................................................. 88 4.2.1 Creating a Service Call................................................................................. 88 4.2.2 Using a Service Call ..................................................................................... 89

4.3

Working with Dialog Boxes ..................................................................................... 90 4.3.1 Calling Dialog Boxes of the Same Component ............................................ 91 4.3.2 Calling Dialog Boxes of a Used Component ................................................ 93 4.3.3 Calling a Confirmation Dialog Box................................................................ 94

4.4

Data Binding Concepts ........................................................................................... 95 4.4.1 Data Binding of User Interface Element Properties ..................................... 95 4.4.2 Data Binding Using Index and Key............................................................... 97 4.4.3 Fixed Values of Attributes ............................................................................ 98 4.4.4 Context Change Log (Recording User Entries).......................................... 100

4.5

Input Help .............................................................................................................. 102 4.5.1 ABAP Dictionary Search Help .................................................................... 102 4.5.2 OVS Input Help........................................................................................... 104 4.5.3 Freely Programmed Input Help .................................................................. 106

4.6

Messages .............................................................................................................. 107 4.6.1 Integration of Messages in the Message Log ............................................ 110

4.7

Handling Web Icons .............................................................................................. 112

4.8

File Export ............................................................................................................. 114

4.9

Portal Integration................................................................................................... 116 4.9.1 Binding to Portal: Prerequisites .................................................................. 117 4.9.2 Integrating an Application in the Portal....................................................... 117 4.9.3 Portal Events .............................................................................................. 120 4.9.4 Portal Navigation ........................................................................................ 123 4.9.5 Work Protect Mode..................................................................................... 131

4.10 Example ................................................................................................................ 133 4.11 Integrating Forms .................................................................................................. 133 4.11.1 Integrating a PDF Form in a Web Dynpro Application ............................... 134 4.11.2 Supported Elements of the Adobe Library ................................................. 136 4.11.3 Interactive Form Use .................................................................................. 137 4.11.4 Forms with Function Module-Based Interface............................................ 137 4.12 Personalization and Configuration ........................................................................ 138 4.12.1 Component Configuration .......................................................................... 139 4.12.2 Application Configuration ........................................................................... 141 4.12.3 Personalization ........................................................................................... 143 4.12.4 Delta Handling in Customization and Personalization ............................... 144

4.12.5 Notes on Working with Adjustment Data.................................................... 146 4.12.6 Configuration of an Included ALV Component........................................... 147 4.13 Modification-Free Enhancements ......................................................................... 148 4.13.1 Implementing Enhancements in a View ..................................................... 149 4.13.2 Implementing Enhancements in the Controller .......................................... 150 4.13.3 Implementing Enhancements in a Window ................................................ 151 4.14 Integration of Web Dynpro ABAP Applications in GUI Applications ..................... 151 4.15 Accessibility of a Web Dynpro Application............................................................ 153 4.16 Internationalization and Translation ...................................................................... 156 4.17 SAP List Viewer in Web Dynpro for ABAP............................................................ 158 4.17.1 Integration of the ALV in Your Application ................................................. 158 4.17.2 Managing ALV Output Areas...................................................................... 166 4.17.3 Appearance of ALV Output ........................................................................ 182 4.17.4 Predefining Standard ALV Functions ......................................................... 190 4.17.5 Functions, Interactions, and Events ........................................................... 205 4.17.6 Methods and Events of the Interface Controller......................................... 219 4.18 Screen Design Time Conversion .......................................................................... 231 4.18.1 Restrictions................................................................................................. 232 4.18.2 Transformation Rules ................................................................................. 233 4.19 Version Comparisons in Web Dynpro for ABAP ................................................... 247 4.20 Quality Assurance ................................................................................................. 248 4.20.1 Web Dynpro Trace Tool ............................................................................. 248 4.20.2 ICM Tracing ................................................................................................ 250 4.20.3 HTTP Browser Tracing ............................................................................... 252 4.21 System Logon ....................................................................................................... 258 4.21.1 Prerequisites............................................................................................... 261 4.21.2 Configuration Settings ................................................................................ 262 4.21.3 Password Logon Scenarios........................................................................ 265 4.21.4 User-specific Changes ............................................................................... 268 4.21.5 URL Generation in an AS-ABAP - Web Dispatcher Configuration ............ 271 4.21.6 Examples of the Logon Screen .................................................................. 280

Web Dynpro ABAP: Development in Detail

May 2006

Web Dynpro ABAP: Development in Detail This manual is an introduction to programming user interfaces for business applications using the UI technology Web Dynpro for ABAP. Four consecutive parts explain the most important basics and concepts with several illustrating examples. The programming manual is subdivided into the following sections: ●

Basics [page 1] This section contains the information on how to build a simple Web Dynpro application.

●

Cross-Component Programming [page 55] In this section, the previous topics are extended to allow communication across multiple components.

●

Dynamic Programming [page 74] This section contains information about the dynamic manipulation of the context or layout, for example. Dynamic programming requires good knowledge of ABAP Objects.

●

Advanced Concepts [page 86] This section covers different topics relevant to advanced projects with Web Dynpro for ABAP. These topics are self-contained and do not build on one another.

In addition to this programming manual for Web Dynpro for ABAP, the following documents are available in the SAP NetWeaver documentation: Architecture Manual Web Dynpro [externaly] This manual describes the Web Dynpro concept, irrespective of the selected programming language (ABAP or Java). Tool Maual for Web Dynpro for ABAP [externaly] Reference Guide Web Dynpro for ABAP [externaly] Here, you will find all information on UI elements, classes, and interfaces relevant for development.

Basics

In the ABAP development environment, you use the Web Dynpro Explorer to create and edit Web Dynpro applications. The Web Dynpro Explorer has been fully integrated into the ABAP Workbench [externaly] and does not have a separate transaction code. In the first processing step, you use the object list selection and display an existing Web Dynpro component or create a new one:

Web Dynpro ABAP: Development in Detail

Basics

May 2006

To create a new Web Dynpro component, enter a new name in the selection dialog of the object list, and select Display. In the dialog box that appears, you can enter a description of the new object and decide whether you want to create a Web Dynpro component or a Web Dynpro Component Interface [page 68]. You can find platform-independent information about Web Dynpro and an introduction to the terms that are used in general in the Web Dynpro [externaly] section of the Architecture Manual.

1.1

Component

The component is the central, reusable unit of the application project. You can create any number of views in a component and arrange them in any number of windows. For more information about the concept of the Web Dynpro component, refer to the Architecture Manual for Web Dynpro [externaly]. The creation of a component is the first step when you create a new Web Dynpro application. For a detailed description of how to create a component, refer to step 1 in the tutorial Creating Your First Web Dynpro Application [externaly]. Once a Web Dynpro component [externaly] has been created, the component appears as a node in the object list on the left side of the Workbench window below the node Web Dynpro Components. If you expand the node of the component, several automatically created parts of the component are displayed. You can double-click the component name to display the component on the right side of the screen. The component view lists the administrative details such as the name of the person who created it, the creation date, or the assigned development package. After saving the new component, you can display it in the object list. A first view is visible.

Advanced Concepts Accessibility of a Web Dynpro Application To ensure accessibility of a Web Dynpro application [page 153], you can perform a corresponding check in addition to the check and activation of a component. This check is activated by checking the checkbox Accessibility Checks Active.

Component Usages Web Dynpro components can be nested. This means that you can integrate any number of other, already existing components into a component. For more information, see Working with Component Usages [page 58].

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Implementing Interfaces On the Implemented Interfaces tab, you can enter existing component interface definitions for use in your currently processed component. For more information, see Working with Web Dynpro Component Interfaces [page 68].

1.2

Web Dynpro View

The view [externaly] is the smallest unit of a Web Dynpro application visible for the user. The layout elements and dialog elements - for example, tables, text fields, or buttons - required for the application are arranged in a view. The view contains a controller and a controller context in which the application data to be processed is stored in a hierarchical structure. This allows the linking of the graphical elements with the application data.

Creating a View To create a new view for your component, select the Views node of the component in the object list on the left side of the Workbench and choose Create from its context menu (right mouse button). Once the view is created, the View Editor appears on the right side of the Object Navigator in the tools area. You can now edit the graphical design of the view using the tools available in the Layout tab. To be able to see the view in the browser, you must embed it actively in a Web Dynpro window; the embedding never occurs automatically, not even if the component contains only one single window.

View Editor Once a view is created, the Layout tab of the View Editor is automatically called. The Layout tab is divided into three areas:

●

In the left column of the editor, you can find the UI element library, a set of small tabs with grouped UI elements - see chapter Web User Interfaces [externaly] in the reference part of the documentation.

●

A simple presentation of the view layout appears in the graphical View Designer in the middle part of the editor window. You can use the View Designer to directly edit the design of the view. Selected elements can be moved using drag and drop.

●

The right area of the editor window is divided into two areas: ○

UI Element Hierarchy In the upper part, the UI elements contained in the layout are displayed as nodes of a tree structure. You can change the order or nesting of the individual UI elements in this hierarchy.

○

UI Element Properties In the lower part, the properties of the currently selected UI elements are listed in a table.

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Layout

UI Element Library

View Designer Element 1

UI Element Hierarchy ROOTUIELEMENTCONTAINER

Element 1 Element 2

Element 2

Element 2a

Element 2a Element 2b

Element 2b

Properties: Element 2a

Inserting a UI Element The layout of a newly created view does not contain visible objects. Only the root element of the future UI element hierarchy is already created. The individual UI elements are to be embedded in this element called ROOTUIELEMENTCONTAINER, . In general, you can use two different procedures:

â&#x2014;?

Drag&Drop in the UI Element Library: You can use drag and drop for the corresponding icons to move the UI elements from the UI element library to the left of the View Editor to the View Designer area and place them to the desired position in the layout. If a new UI element from the UI element library is inserted to the layout using drag and drop, an automatically generated name is assigned to this element. You can change this name in the properties table of the element (see below).

â&#x2014;?

Context Menu of Elements in the Tree Structure: These UI elements can embed other UI elements - for example, Group, Table, or the ROOTUIELEMENTCONTAINER. They provide the context menu function Insert Element in the tree structure. You can specify the name and type of the new UI element in a subsequent dialog box.

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Layout

UI Element Library

View Designer Element 1

UI Element Hierarchy ROOTUIELEMENTCONTAINER

Element 1 Element 2

Element 2 Element 2aInsert Element

Element 2a

Element 2b

Properties: Element 2

1.2.1

UI Elements of the View

The provided UI elements are used to structure information and functions within the view. This means that they are crucial for the design of the screen layout. Therefore, multiple elements are available with a wide range of purposes: Some elements are used for the graphical arrangement of UI elements like Group or Tabstrip. You can embed other elements into these elements. Elements like Table or TextView display data, the element InputField can be filled with values entered by the user. Interactive elements like Button or CheckBox are also provided. The following graphic shows a possible arrangement of UI elements in a view:

Web Dynpro ABAP: Development in Detail

Basics

May 2006

myExampleView RootUIElementContainer Group

Table

InputField Button 1

Button 2

Tab 1 Tab 2 Tab 3 Tab 4 TextView

Image

UI Element Properties Each UI element has different properties. There are evident properties like background color or element width and several other properties used to specify a UI element. The properties are displayed in the View Designer in the properties table. This table is displayed for each UI element when the element is selected in the tree structure. In this chapter, the UI element properties will not be described in detail but only used in examples. Refer to the reference section of this programming manual to get a complete list of all available UI elements [externaly] including a description of their properties. All static properties can only be entered into the table directly - for example, the ID of a table column. Most of the properties, however, can be specified statically and also be bound to an element of the corresponding context. Example:

The enabled property of a button is usually specified by binding it to a context attribute. The attribute value specifies whether the button is active or inactive. For this kind of attributes, the Web Dynpro runtime offers a set of special data types. For more information, refer to Data Binding of UI Element Properties [page 95] in the section Advanced Concepts [page 86] in this documentation. For some properties, the binding to a context element is required. For example, the data source of a table can only be specified when it is bound to a context element. For more information on the structure of a view context and the binding of UI elements to elements of the view context, refer to the following sections: Structure of the View Context [page 7], Data Binding of UI Elements [page 8] in this programming manual, and the section Context [externaly] in the Architecture Manual for Web Dynpro [externaly].

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Actions In addition to the properties, possible events of UI elements - known as actions - are also managed in the table. Actions are provided for each UI element that expects an activity of the user - for example, a button or an input field. The corresponding event handler is created when you enter a name for the action in the properties table. When you double-click the action name, an ABAP Editor is called in which you can create the code for the event handler method. The newly created event handler method is automatically inserted into the Methods tab. If other event handler methods for other buttons have been created in the current view, these methods are already entered in the Methods tab. They are offered for selection when you enter the name for the new action. For more information on actions of UI elements, refer to: â&#x2014;?

Chapter Actions of UI Elements [page 10] in this programming manual

â&#x2014;?

Chapter Action [externaly] in the Architecture Manual for Web Dynpro [externaly].

1.2.2

Structure of the View Context

Every view contains a data container with the data to be displayed in the view. This data container is called context of a view. In the context of a view, the application data to be used by the view layout is structured and stored. This data, for example, is provided by the back-end and to be displayed in the view. It can also be predefined, empty data elements to be filled by user input. Other context elements are used for the internal structure of the context. Each context has a hierarchical structure. It contains a root node CONTEXT and the different context elements are arranged below it. You can create new context nodes and individual context attributes below each context node.

Editing the Context Structure Switch to the Context tab in the View Editor to edit the view context. You create a new context node or context attribute using the context menu of the corresponding embedded node.

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Context Context MY_VIEW Context Attribute A1 Node N1 Attribute NA1 Attribute NA2 Node N1.1 Attrâ&#x20AC;Ś. Node N2 Properties

Value

Below the tree structure of the context, the properties of the selected context element are listed in a table. The table contains obvious labels like node name or attribute type but also several important properties which make the context a powerful part of the Web Dynpro concept. Context Node For a detailed description of the context node creation and a listing of properties with their meanings, refer to Creating and Maintaining Context Nodes [externaly]. In the Architecture Manual for Web Dynpro, refer to a detailed description of the topic Properties of Context Nodes [externaly]. Context Attributes Since the concept of the context attributes is relatively simple, only a name and data type must be specified for them. Several other properties are available for optional use. For further information, refer to Creating and Maintaining Context Attributes [externaly].

1.2.3

Data Binding

UI elements have properties. Each of the UI elements that can be used for the transfer or display of data contains one property that describes the value a user input or the source of the data to be displayed. These properties can be specified at design time by specifying a fixed value or they can refer to a context element. The second option is called binding to a context element. In this case, the value of the context element is displayed at runtime or the content of the input field is passed from the screen to the context element of the view element. Two simple examples illustrate the principle:

Web Dynpro ABAP: Development in Detail

Basics

May 2006

The value of the input field (the value property) is bound to a context attribute which is filled with the value entered by the user. It keeps the value for further processing. View Layout

View Context CONTEXT

Input Field Value

Attribute A1

The value of the property DataSource of the UI element Table is bound to a context node. View Layout A1

View Context CONTEXT Table Node Attribute A1 Attribute A2 Attribute A3

The two examples shown above illustrate two typical cases - the transport of an input value and the filling of UI elements with application data. However, many other properties of a UI element can be bound to a context element. To mention just two more examples: The length of a text field and the width of a table. Whether the value of a UI element property is specified and consequently the same in every view presentation or whether the value is bound to a context element depends on the design of the Web Dynpro component. A binding to a context element is required for properties like value or dataSource of the two UI elements mentioned above. For a tabular list of all available UI elements including a usage description for each property, refer to the reference section of this documentation. In the context of the Advanced Concepts [page 86] of Web Dynpro for ABAP, the subject of Data Binding of UI Element Properties [page 95] is discussed in detail.

Setting Up Data Binding Data binding of a UI element property is set up in the view layout. For this purpose, you use the Binding column in the properties table of the embedded UI elements. You click the button to open a dialog box which provides the context structure of the corresponding view for an element selection. The properties that require the binding to a context element have a Binding button of the properties table with the following icon:

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Data Binding Using the Wizard A wizard is available for some UI elements to make it easier to specify the design of the UI element by including the structure of the corresponding context node in the layout design. Example: When a table is bound to a context node using a wizard, it is not necessary to create each table column individually. Instead the wizard provides the corresponding context and once you selected the context node, it also provides the available attributes. You can now select the node attributes to be actually displayed in the table. In addition, you can change several properties of the column elements. When the wizard operation is completed, the required table columns in the view layout are created and the required data binding is performed. You start the wizard by selecting the option Create Binding in the context menu of a UI element in the tree structure below the root container.

Attributes Flagged as "Nullable" For some UI elements (for example, those of a numeric type or of the type T) that are bound to a context attribute, any fields without a value are automatically output with the value null. In the case of the type NUM4C, this is the value “0000“, while for the type T it is “00:00:00“, and so on. This behavior may be undesirable in some cases and can therefore be stopped by carrying out the following steps: ●

First, you must use the method IF_WD_CONTEXT_NODE_INFO=>SET_NULLABLE( ) to flag the value in the node info as nullable. You can either set individual attributes or all attributes of a node as nullable.

●

In your second step, you must set the actual value to “null”. For this purpose, the interface IF_WD_CONTEXT_NODE provides the method set_attribute_null( '”Node_Name”' ). Another possibility is to enter an empty string in the input field (that is, delete any contents).

1.2.4

UI Element Actions

Several UI elements contain actions [externaly]. Actions are special events triggered by activities of the user on the user interface of an application. Corresponding event handlers specify the subsequent processes of the application. The following example illustrates the procedure: You create an action for UI element Button. In the event handler method of this action, you specify the response of the application when the user selects the UI element Button. An action is always linked to exactly one event handler method. In some cases, however, you might want to simultaneously use the same action for multiple UI elements in a view. For more information on the required parameterization for multiple-use actions, refer to Parameter Mapping [page 11].

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Creating Actions As is the case with data binding, actions of UI elements are created and maintained in the properties table of the View Editor.

Event Handler Methods When you create a new action, the corresponding event handler method is created automatically. It is empty at first and the application developer can insert source code using the ABAP Editor. The event handler methods are – like all other methods of the view - part of the view controller. Therefore, they are listed in the table of the Methods tab in the View Editor.

Controller Methods Event handler methods are special methods of a controller – in this case, of the view controller. From a technical point of view, they do not differ from other controller methods like the initial method WDDOINIT or the method WDDOEXIT. Due to a convention, however, their names have the prefix ONACTION followed by the action name specified by the application developer. Example: If an action of a UI element has the name GO, the corresponding event handler method is automatically called ONACTIONGO. For information on programming event handler methods and example programs, refer to Programming Controller Methods [page 12].

1.2.4.1

Parameter Mapping

Parameter mapping is used for multiple use of actions. If you use one action for several events - for example, multiple buttons - you require unique information to specify the desired assignment. You can get this information using parameter mapping. We do not recommend that you pass the action ID – that is, use the standard parameter IDs - since this method is not platform-independent. Parameter mapping is performed by a program: DATA PARAMETERS TYPE WDR_NAME_VALUE_LIST. DATA PARAMETER TYPE WDR_NAME_VALUE. DATA data_ref TYPE REF TO data. FIELD-SYMBOLS <data> TYPE any. " Parameters can PARAMETER-NAME PARAMETER-VALUE PARAMETER-TYPE INSERT PARAMETER

be simple values = 'LINES_TO_INSERT'. = '3'. = CL_ABAP_TYPEDESCR=>TYPEKIND_STRING. INTO TABLE PARAMETERS.

" Parameters can PARAMETER-NAME PARAMETER-OBJECT PARAMETER-TYPE INSERT PARAMETER

be object references = 'CUSTOMER'. = customer_object. = CL_ABAP_TYPEDESCR=>TYPEKIND_OREF. INTO TABLE PARAMETERS.

Web Dynpro ABAP: Development in Detail

Basics

May 2006

" Parameters can be deep data objects (structure/table) CREATE OBJECT data_ref LIKE table. ASSIGN data_ref->* TO <data>. <data> = table. PARAMETER-NAME = 'TABLE'. PARAMETER-DREF = data_ref. PARAMETER-OREF = CL_ABAP_TYPEDESCR=>TYPEKIND_DREF. INSERT PARAMETER INTO TABLE PARAMETERS. " Specify parameter mapping CL_WD_BUTTON->MAP_ON_ACTION( parameters ). " Read parameter mapping CL_WD_BUTTON->MAPPED_ON_ACTION( importing parameters = parameters ).

When the event is triggered, the linked action is called using the following parameters: ●

Web Dynpro ABAP standard parameters [externaly] (ID and CONTEXT_ELEMENT)

●

Special parameters of the UI element

●

Event parameters specified in the parameter mapping

The parameters can be defined as method parameters of the action. The type of method parameters must be MOVE-compatible with the parameter values. All method parameters are mandatory. If not all method parameters are filled with event parameters when calling the action, an exception is raised. Parameter values can also be read using the WDEVENT object: = WDEVENT->GET_INT( 'LINES_TO_INSERT' ). = WDEVENT->GET_OBJECT( 'CUSTOMER' ). = WDEVENT->GET_CONTEXT_ELEMENT( 'CONTEXT_ELEMENT' ).

or = WD_EVENT->GET_DATA( EXPORTING name = 'TABLE' importing value = table ).

1.2.5

Action Event Handlers

If an action [externaly] of a UI element is triggered on the user interface of a Web Dynpro application, the event handler of the view controller linked to this action is automatically called. In the event handler, the application developer adds the source code for the steps that will trigger the action. Examples for these steps: ●

Reading, editing, and resetting context elements

●

Calling function modules

●

Triggering navigation

Programming From a technical point of view, an event handler differs from other controller methods only in that it also responds to the event assigned to the event handler. For programming all controller methods, you can choose from several special classes with attributes and methods used to execute the processing steps specific to Web Dynpro. The following simple example describes in detail a possible structure of a controller method for the handling of an action.

Web Dynpro ABAP: Development in Detail

Basics

May 2006

For further information on frequently used interfaces and their methods and attributes, refer to chapter Programming of Controller Methods [page 18]. For a complete list of interfaces [externaly], refer to the reference section of this documentation.

First Example: Graphic Representation of a Simple Flight List The user of a Web Dynpro application enters a value in the input field of a view (in this case the abbreviation of an airline). The user selects a button. The following table is to be displayed including the data that corresponds to the user input.

View Layout Input Field IN1

View Context CONTEXT

Button GO Table T1 T2 T3

Input_Node Attribute IN1 Table_Node Attribute T1 Attribute T2 Attribute T3

The graphic above shows the design scheme of the view layout and the corresponding context. When you call the application for the first time, the table is empty. Once the user enters the value and selects the button GO, the corresponding action GO is automatically triggered and the event handler method ONACTIONGO is called. The following steps must be performed in this method: 1. The attribute of the context node INPUT_NODE is read and passed to an internal variable of the method ONACTIONGO. 2. An internal table is filled according to the value of the internal variable. 3. The context node is filled with the content of the internal table. How do these steps translate into source code in the method ONACTIONGO?

Data Declaration

method ONACTIONGO. data: INPUT_NODE type ref to IF_WD_CONTEXT_NODE, TABLE_NODE type ref to IF_WD_CONTEXT_NODE, CAR FLIGHTS

type STRING, type standard table of SPFLI.

Web Dynpro ABAP: Development in Detail

Basics

May 2006

First, all of the required internal variables are declared: ●

INPUT_NODE is declared as an internal variable for the context node of the user input

●

TABLE_NODE is declared as an internal variable for the context node of the result table

●

CAR is declared as an internal variable of the user input

●

FLIGHTS is declared as an internal table for the result representation

In this example, the table FLIGHTS refers to the Dictionary table SPFLI and therefore does not need be declared in more detail.

Importing the User Input The internal variable INPUT_NODE is bound to the context node INPUT_NODE:

INPUT_NODE = WD_CONTEXT->GET_CHILD_NODE( 'INPUT_NODE' ).

To do this, you use the attribute WD_CONTEXT and the method GET_CHILD_NODE of the interface IF_WD_CONTEXT_NODE [externaly] which is available in the Web Dynpro framework. The attribute WD_CONTEXT is always a reference to the local controller context: The method ONACTIONGO is a method of the current view controller. This means that WD_CONTEXT is the reference to the context of the current view in this case (see chapter Reference Variable WD_CONTEXT) [page 19] The method GET_CHILD_NODE returns the reference to the context node INPUT_NODE. The method GET_ATTRIBUTE of the same interface subsequently reads the context attribute:

INPUT_NODE->GET_ATTRIBUTE( exporting Name = 'IN1' importing Value = CAR ).

This method retrieves the value of the attribute IN1 from the context node INPUT_NODE and passes it to the internal variable CAR. This means that the value of the UI element Inputfield is passed to the method ONACTIONGO using the view context and can now be edited.

Filling the Result Table The internal table FLIGHTS is filled using a formatted class which, in this example, is called CL_WD_FLIGHT_MODEL and contains the method GET_FLIGHTS_BY_CARRID. Variable CAR is passed to this method.

FLIGHTS = CL_WD_FLIGHT_MODEL=>GET_FLIGHTS_BY_CARRID( CAR ).

Web Dynpro ABAP: Development in Detail

Basics

May 2006

In this step, no elements specific to Web Dynpro are used.

Passing the Result Table Once the internal table FLIGHTS is calculated, it must be linked to the context node TABLE_NODE. As for the reading of the input field, two steps are required:

TABLE_NODE = WD_CONTEXT->GET_CHILD_NODE( 'TABLE_NODE' ).

First, the context node TABLE_NODE of the view context is assigned to the internal variable TABLE_NODE. The required attribute or method has already been used for the linking of the node INPUT_NODE. Finally, the content of the internal table FLIGHTS is passed to the internal variable TABLE_NODE.

TABLE_NODE->BIND_ELEMENTS( FLIGHTS ). endmethod.

The method bind_elements is also a method of the interface IF_WD_CONTEXT_NODE. It creates new elements from the internal table FLIGHTS and adds them to the internal variable TABLE_NODE. The attributes for the context node TABLE_NODE are now filled with the values of the internal table and the UI element Table can display the values in the view layout.

1.3

Component Controller

Each Web Dynpro component contains exactly one component controller. This controller is automatically created during the component creation and contains a context, events, and methods. Unlike a view controller, the component controller is visible for all views in a component. This means, the controllers of different component views can access context elements or methods of the component controller. For this purpose, the component controller usage is automatically created for every view controller.

my Component

Component Controller

Controller View 1

Controller View 2

Web Dynpro ABAP: Development in Detail

Controller View 3

Basics

May 2006

This makes the component controller a central location for data exchange between different views of one component. The Web Dynpro framework provides the mechanism of context mapping [page 16] which is a declarative tool to easily perform this data exchange. In addition, the component controller allows cross-view method calls [page 31]. For example, it might be useful to add the call of a function module to a method of the component controller if the function module is to be used by methods of different views. You can then access the methods of the component controller in the controllers of the various views. This enables you to structure Web Dynpro components in a better way and to reuse frequently used program steps.

More Information ●

The Architecture Manual for Web Dynpro [externaly] contains a general section on the Controller [externaly] subject.

The reference manual Web Dynpro Tools in the ABAP Workbench [externaly] features a section on the processing of Controllers [externaly].

1.3.1

Context Mapping

Data stored in the context of the component controller can be used within a view if you link the node of the view context to the corresponding context node of the component controller. This procedure is called “defining a mapping”. For further information, refer to the chapter Data Binding and Mapping [externaly] in the architecture manual for Web Dynpro. The following graphic illustrates the principle of the procedure: Context View 1

Context Component Controller

Node 1

Local Node View1

Node 2

The context of View 1 of the example in the graphic contains two nodes below the root node: ●

The node Node 1 is mapped to the node of component controller context of the same name. This means that the structure within the node matches the structure within the node of the component controller or the structure is contained in it. At any time, the values of all attributes contained in Node 1 are identical to the corresponding attributes of the component controller. If the attribute value of the view context changes at runtime, - for example, due to a user input - , the change is directly passed to the component controller. The data is not passed to only one location which is the context to which is mapped.

●

The node Local Node View 1, however, is exclusively known within the view controller, and only the methods of the View 1 have access to the values of the node attributes.

Web Dynpro ABAP: Development in Detail

Basics

May 2006

For a description of a simple example for the creation of a flight list structure in the table of the user interface using a database table, refer to chapter Action Event Handlers [page 12]. This example is used again to illustrate the principle of mapping: Extending the Flight List Application The application decribed in the previous chapter uses the layout of your view for the graphical representation at the user interface and the corresponding view controller for retrieving and storing the involved data. The context and the methods of a view controller are only locally visible - that is, within the controller. Therefore, other views of the same component cannot use these contents. To allow them the use of the contents, the data and the methods to be retrieved are moved to the component controller. The following graphic shows the new context structure of the component:

View Context CONTEXT Input_Node Attribute IN1 Table_Node

Component Controller Context CONTEXT Input_Node Attribute IN1

Attribute T1

Table_Node Attribute T1

Attribute T2

Attribute T3

local to View

local to all Controllers inside the Component

Once both nodes with their attributes are created in the context of the component controller, the corresponding nodes of the view context can be mapped to the two new nodes. For a detailed description of the procedure and information on restrictions, refer to the tools manual in chapter Defining Mapping [externaly]. When the attribute value in one of the two contexts changes, the change automatically takes effect in both contexts. Now, you can also define mapping to the nodes of the component controller context for the corresponding context nodes of an optional second view. The second view context will also adopt all changes within the â&#x20AC;&#x153;mapping networkâ&#x20AC;?. In the next step of this extended example, the data retrieval for the flight table is also moved to the component controller. For a description of the required basic steps, refer to the next chapter Cross-Controller Method Call [page 31]. For more information on mapping [externaly], refer to the architecture manual for Web Dynpro.

Defining Mapping There are various ways in which you can define mapping for the context of a view controller. However, you always use the Context tab of the corresponding view. For more information, refer to the tools manual in chapter Defining Mapping [externaly].

Web Dynpro ABAP: Development in Detail

Basics

1.4

May 2006

Programming Controller Methods

In general, attributes and methods are used to specify the processes of programs in Web Dynpro applications and to edit the data contained in the context. The former chapters Action Event Handlers [page 12] and Cross-Controller Method Call [page 31] described simple examples of these program processes. In this chapter, you find general information on programming using methods of the Web Dynpro framework. In addition, frequently used methods are described and illustrated by source code examples. For further information on specific controller methods, refer to document Controller: Methods [externaly] in the tools manual and chapter Controller Classes and Controller Interfaces [externaly] in the reference section of this documentation. When you create a new Web Dynpro component, a component controller is automatically created for this component. When you create a view for a Web Dynpro component, a view controller is automatically created for this view. Each window of a component contains a window controller and you can create custom controllers for specific purposes. At least two attributes are automatically known to each controller, namely the following object references: â&#x2014;?

WD_CONTEXT [page 19]

â&#x2014;?

WD_THIS [page 19].

You can also create your own attributes for each controller. These attributes are used to store non-UI-relevant application data (UI-relevant data is stored in the context).

Constants for Context Nodes For every node you create in the context of a controller, a constant with the name WDCTX_<node name> is automatically created in the corresponding interface IG_<Controller_Name> and IF_<Controller_Name>. In the source code of the controller, this constant can then be used for the node name instead of a string literal. Example:

wd_context->get_child_node( wd_this->wdctx_my_node ). instead of wd_context->get_child_node( 'MY_NODE' ). The advantage of using constants is that the compiler knows the constant and, therefore, syntax errors are triggered if the name of the context node contains typing errors. However, it is also possible to pass a string literal.

Interface Controller The additional interface controller listed in the development environment is not an independent object but a specific subset of the component controller: The interface controller defines the interface of a Web Dynpro component for the use in another component. The methods are implemented in the component controller. When you

Web Dynpro ABAP: Development in Detail

Basics

May 2006

set the Interface flag for methods/events/context nodes in the component controller, these elements are copied into the interface controller.

1.4.1

Reference Variable WD_CONTEXT

WD_CONTEXT Attribute WD_CONTEXT is a reference to the controller context. Regardless of the edited controller, it is always a reference variable of the type IF_WD_CONTEXT_NODE [externaly]. You can use WD_CONTEXT and the interface methods to edit the content of a context node in your controller method. Example: The controller context contains the node MY_TABLE_NODE. You can use the method INVALIDATE_TABLE_NODE to invalidate the values of the node elements. method INVALIDATE_TABLE_NODE . data: TABLE_NODE type ref to IF_WD_CONTEXT_NODE. TABLE_NODE = WD_CONTEXT->GET_CHILD_NODE( 'MY_TABLE_NODE' ). TABLE_NODE->INVALIDATE( ). endmethod.

GET_CHILD_NODE and INVALIDATE are methods of the interface IF_WD_CONTEXT_NODE. Other frequently used methods are GET_ATTRIBUTE or BIND_ELEMENT, for example. For a complete list of methods and their functions, refer to the reference section of this documentation (link is above).

1.4.2

Reference Variable WD_THIS and Local Controller Interface

Each controller contains a local interface which can be accessed in the controller. The controller attribute WD_THIS is a reference to this local interface. Depending on the controller, a reference variable is of the following type:

●

IF_COMPONENTCONTROLLER

●

IF_<MY_CUSTOM_CONTROLLER>

●

IF_<MY_VIEW>

●

IF_<MY_WINDOW>

Web Dynpro ABAP: Development in Detail

Basics

May 2006

The methods and attribute of the local controller interfaces can be accessed using these reference variables. ●

Included are all self-defined methods that have been created and implemented [page 30] by an application developer for the current controller. Since the application developer can change the implementation, these methods are listed on the tab Methods of the Controller Editor. You switch to the ABAP editor for adding source code by double-clicking the method name. For further information on these methods, refer to chapter Methods of Local Controller Interfaces [page 20].

●

The application developer can call another group of methods but cannot change the implementation of these predefined methods [page 22]. For general information on different interface types and their visibility within one or more Web Dynpro components, refer to chapter Controllers of a Web Dynpro Component [page 56] in the tools manual of this documentation.

●

The application developer can implement a third group of methods, but these methods are exclusively called by the runtime [page 21].

●

All attributes of the controller are accessed using the reference variable WD_THIS.

Accessing the Web Dynpro Runtime API The generated interface of a controller (local and global) contains a restricted number of methods. It only contains methods and attributes that can directy or indirectly be defined or implemented by the application developer. Therefore, the Web Dynpro runtime provides a generic runtime API [page 32] for each controller type. In this API, several frequently used methods are implemented and can be used by the application developer. You can access general functions like the portal manager or message manager of the framework using these interfaces. The method WD_GET_API which is contained in all generic controller interfaces allows the access to the corresponding runtime API.

Attribute WD_COMP_CONTROLLER of the View Controller In most cases, it is useful to declare the usage of the component controller for a view controller. The development environment has therefore predefined this step. In addition, each view controller already contains the attribute WD_COMP_CONTROLLER, which is a reference variable of the type IG_COMPONENTCONTROLLER. In each view controller, you can use the attribute WD_COMP_CONTROLLER to access all publicly accessible methods of the component-global generated interface of the corresponding component controller.

1.4.3

Methods of the Local Controller Interface All methods that can be changed - that is, methods that can be implemented by the application developer - are listed on the Methods tab of each controller. When double-clicking the method name, you switch to an ABAP Editor which enables you to implement the source code.

Web Dynpro ABAP: Development in Detail

Basics

May 2006

In addition to the changeable methods, the local interface of each controller provides several methods which can be used but whose implementations cannot be edited by the application developer. It depends on the type and the implementation state of a controller when these methods are available in the interface. Since all methods of this group cannot be changed, they are not displayed on the Methods tab of the corresponding controller. As a part of the complete interface, you can display the existing methods using the following icon: Display Controller Interface If you click this icon, the interface of the controller you are currently working on is displayed in a separate window. You can also display the interface of any used controller. Note that for each view controller, the usage of the corresponding component controller is created automatically, since this usage is generally always appropriate. (Of course, you can also display the existing methods of the local controller by double-clicking the reference type IF_.................. of the attribute WD_THIS on the Attributes tab.)

1.4.3.1

Hook Methods: Methods Called by the Runtime

Along with the previously mentioned application methods, each local controller interface has a fixed number of methods that can only be called by the runtime. The application developer cannot specify when these methods are called, but can modify the implementation. The time when these methods are called is predefined. For a description, refer to the phase model [page 35] of Web Dynpro.

WDDOINIT and WDDOEXIT The simplest examples are the methods WDDOINIT and WDDOEXIT. WDDOINIT is called automatically when a controller is initialized for the first time. For each newly created controller, these methods are empty but can be filled with source code. These methods can contain the following steps, for example: ●

Creating instances of help classes

●

Initializing controller attributes If you need more attributes for the programming and these are also reference variables, they can be initialized here.

●

Triggering authorization checks (recommended for help classes)

●

Setting initial values of the controller context

Instantiation of used components (see Cross-Component Programming [page 55])

Example for the initialization of a controller context: method WDDOINIT . data: NODE type ref to IF_WD_CONTEXT_NODE,

Web Dynpro ABAP: Development in Detail

Basics

May 2006

FLIGHTS type SPFLI_TAB. * get node from context NODE = WD_CONTEXT->GET_CHILD_NODE( 'CARRIER_NODE' ). * get connections from help class FLIGHTS = CL_WD_GET_SPFLI=>GET_FLIGHTS( ). NODE->BIND_ELEMENTS( FLIGHTS ). endmethod.

WDDOEXIT is called by the runtime when exiting the controller and can be used for releasing locks, for example. Depending on the controller settings, the local controller interface also contains the methods WDDOBEFORENAVIGATION, WDDOPOSTPROCESSING, and WDDOMODIFYVIEW.

1.4.3.2

Predefined Methods of the Local Controller Interface

Each controller contains an additional set of methods provided by the runtime. They can be used for developing applications. You cannot change the implementation of the methods â&#x20AC;&#x201C; unlike the implementation of all the other controller methods. The content of the method set depends on the controller type and its implementation state. Some of these methods are described in more detail below.

Method GET_<MY_USED_CONTROLLER>_CTR The method GET_<MY_USED_CONTROLLER>_CTRAll is automatically generated into the local controller interface for each controller to which a usage of another controller of the same component is assigned. It is not relevant whether it is a view component or a custom controller.

Return Value The method GET_<MY_USED_CONTROLLER>_CTR always returns a reference variable of the component-global interface of the used controller. This means, the return value is a reference variable of the type IG_<MY_USED_CONTROLLER>. Example: If you want to use methods of the component-global interface of a custom controller called MY_CUST_CONTROLLER within a view controller, you can enter a usage of the desired custom controller in the Properties tab. You can then use the method GET_MY_CUST_CONTROLLER_CTR in the local interface of the current controller. method MY_CONTROLLER_METHOD . data:

L_REF_MY_CUST_CONTROLLER type ref to IG_MY_CUST_CONTROLLER.

L_REF_MY_CUST_CONTROLLER = WD_THIS->GET_MY_CUST_CONTROLLER_CTR( ). .

Web Dynpro ABAP: Development in Detail

Basics

May 2006

. endmethod.

For general information on different interface types and their visibility within one or more Web Dynpro components, refer to chapter Controllers of a Web Dynpro Component [page 56] in the tools manual of this documentation. In the case of a view controller, the usage of the corresponding is almost always recommended, and therefore, this usage is automatically entered when you create a new view. A reference variable of the type IG_COMPONENTCONTROLLER of the variable is also created automatically. It is the variable WD_COMP_CONTROLLER. This reference variable is known to every view controller. It is entered on the Attributes tab of the view controller and can be used by the application developer. This also means that all methods of the component-global interface of the corresponding component controller are available. For more information, refer to the following chapter Cross-Controller Method Call [page 31].

Method WD_GET_API This method contains all controller types. For detailed information on how to use this method, refer to the documentation on dynamic programming [page 74] in the third part of this documentation.

Methods WD_CPUSE_<MY_COMPONENT_USAGE> and WD_CPIFC_<MY_USED_COMPONENT> These two methods are important when using a component within another component. Refer to part 2 of this documentation under Component Usage Without Controller Access [page 59] or Component Usage with Controller Access [page 62]. These methods are created for each controller type, once a component usage or the usage of the interface controller of a used component is created.

Method FIRE_<MY_PLUG>_PLG This method is only contained in view controllers and window controllers when an outbound plug is created for the corresponding controller. The method can be used to call an outbound plug from which navigation to a subsequent view or window is started. Example: method MY_CONTROLLER_METHOD WD_THIS->FIRE_MY_OUTBOUND_PLG(

endmethod

For more information, refer to the chapter Navigation [page 41].

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Method FIRE_<MY_EVENT>_EVT This method allows each component controller or custom controller for which an event is defined to trigger this event.

1.4.3.3

Events and Event Handlers

You can define events for a component controller to allow cross-controller communication. These events can then be triggered using the predefined method FIRE_<MY_EVENT>_EVT. Once the event is triggered, the corresponding event handler is automatically called in another controller by the runtime. A usage of the component controller must be entered in the current controller to handle an event of a component controller. (The usage of the component controller within a view controller is automatically created.) The following graphic shows an example in which a method of the component controller triggers the event MY_EVENT.

Component Controller Event MY_EVENT method MY_CONTR_METHOD. WD_THIS->FIRE_MY_EVENT_EVT. endmethod.

View Controller Eventhandler MY_HANDLER

Event used Controller MY_EVENT COMPONENT CONTROLLER method MY_HANDLER. endmethod.

The event handler MY_HANDLER of a view controller responds to the event MY_EVENT, because this event of the component controller is assigned to this event handler. It has been assigned on the Methods tab of the view controller.

Cross-Component Events You can use one or more events of the component controller and use them as crosscomponent events. Check the Interface checkbox of the Events tab of the component controller in the table. The corresponding event is passed to the component interface and can be accessed by an event handler of another component (see Cross-Component Programming [page 55]).

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Parameter of Events Events can pass parameters. You can enter these parameters on the Events tab of the component controller and specify the type. When you then create an event handler in a used controller and assign an event of the component controller to it, the corresponding parameters are automatically added to the signature of the event handler method. Example: Component Controller An event is triggered in a method of the component controller and the created parameter is passed. Events tab Event MY_EVENT

Parameter type

MY_PARAMETER

WDY_BOOLEAN

WDY_BOOLEAN is an ABAP Dictionary type and has the function of a real Boolean variable. The value of WDY_BOOLEAN is ’X’ for true or ’ ’ for false. Methods tab: MY_CONTROLLER_METHOD method MY_COMP_CONTROLLER_METHOD . WD_THIS->FIRE_MY_EVENT_EV( MY_PARAMETER = ‘X’ ). endmethod.

View Controller An event handler is created in a view controller and assigned to the event MY_EVENT. The response of the event handler is according to parameter MY_PARAMETER Methods tab: Method MY_EVENT_HANDLER

Method Type Event Handler

Event MY_EVENT

Controller Component Controller

MY_EVENT_HANDLER Parameter

Declaration Type

WDEVENT

Importing Importing

MY_PARAMETER

Reference Type CL_WD_CUSTOM_EVENT WDY_BOOLEAN

method MY_EVENT_HANDLER . .

Web Dynpro ABAP: Development in Detail

Basics

May 2006

. . endmethod.

Additional Concepts: Passing Parameters Using an Event Object Each event handler method is automatically known to parameter WDEVENT of the type CL_WD_CUSTOM_EVENT. The class interface CL_WD_CUSTOM_EVENT [externaly] contains the attribute PARAMETERS of the type WD_EVENT_PARAMETER and several methods to read this parameter. Instead of statically specifying a parameter for an event and automatically add this parameter to the signature of the event handler method of the event handler, you can also dynamically specify the parameter using the event object. This means that if the parameter is not to be statically specified at design time, it can be read from the event object of the event handler method. For more information, see Dynamically Working with Parameter Mappings [page 77] in the third part of the programming manual.

1.4.3.4

Supply Function

Each context node [externaly] of a controller can be assigned a supply function. This supply function is called by the runtime when the data of the context node is used. This is the case when a UI element is to be displayed for the first time with the data of the corresponding context, for example. In general, the supply function is called when one or more elements of a context node are accessed and when â&#x2014;?

the context node is not filled yet or is initial, or

â&#x2014;?

the context node has been invalidated in a previous step.

Supply Functions of Singleton Nodes The supply function is especially useful in combination with singleton nodes [externaly]: The values of subnode elements of the type Singleton depend on the element of the parent node to which the lead selection is currently assigned. If the lead selection is changed by the user, the supply function can access the new lead selection element and recalculate the values of the subnode elements accordingly. For more information on the concept of singleton nodes and multiple context nodes, refer to the chapter Context Nodes: Properties [externaly] in the architecture manual for Web Dynpro. The following example explains how to use the supply function of a singleton node.

Example: Element-Based Detail Display A list of all available airline carriers is displayed in a table view called Carrier. To do this, the UI element of the type Table is bound to a context node which is filled in the method WDDOINIT of the view controller using an appropriate method. The method WDDOINIT is called when the application is executed for the first time and the data for the table elements is visible for the user at the time of the first display on the screen.

Web Dynpro ABAP: Development in Detail

Basics

May 2006

A second table (Connections) displays all flights offered for a specific airline carrier according to the selected element in the first table. The user can select any line in the first table and find the corresponding detail information in the second table. The second table must be filled according to the selected airline carrier, but the view must not be wholly recreated for each selection. The structure of the context view is as follows:

CARRIER_NODE

View Context

CARRIER_ID CARRIER_NAME URL CONNECTION_NODE (Singleton) CARRIER_ID CONNECTION_ID CITY_FROM CITY_TO DEPT_TIME ARR_TIME

The first table (Carrier) is bound to the context node CARRIER_NODE, the table Connections is bound to the context node CONNECTION_NODE. When calling the application for the first time, the WDDOINIT method fills the top node with all elements of the database table SCARR which is a list of all airline carriers, their IDs, and the URL of the corresponding homepage. The lead selection of the context node has been automatically created on the first element of the node, and the airline carrier at the top position of the table is the lead selection element.

All flights available for the airline carrier on the lead selection position are listed in the table Connections. The context node CONNECTION_NODE to which the second table is bound is filled by the supply function GET_CONNECTIONS from the database table SPFLI. The lead selection element of the Carrier table is read and all connection information on the corresponding airline carrier are displayed:

Web Dynpro ABAP: Development in Detail

Basics

May 2006

When you select another table element as the lead selection in the table Carrier,

the content of the table Connections automatically changes:

Supply Function of the Context Node CONNECTION_NODE You can only create such a view when the lead selection element of the node CARRIER_NODE is read in the supply function of the node CONNECTION_NODE: method GET_CONNECTIONS . data: CARR_ATTR type IF_MAINVIEW=>ELEMENT_CARRIER_NODE, FLIGHTS type SPFLI_TAB. * get filled structure for parent node PARENT_ELEMENT->GET_STATIC_ATTRIBUTES( importing STATIC_ATTRIBUTES = CARR_ATTR ).

Web Dynpro ABAP: Development in Detail

Basics

May 2006

* get connections from help class FLIGHTS = CL_WD_GET_SPFLI=>GET_FLIGHTS_BY_CARRID( CARRID = CARR_ATTR-CARRID ). NODE->BIND_ELEMENTS( FLIGHTS ). endmethod. ●

An internal variable of the type of a context element of the parent node CARRIER_NODE and another internal variable of the Dictionary type SPFLI_TAB are declared.

●

The attribute values of the lead selection element of the parent node CARRIER_NODE are then passed to the internal variable CARR_ATTR. For this transfer, each supply function uses the parameter PARENT_ELEMENT of the reference type IF_WD_CONTEXT_ELEMENT. PARENT_ELEMENT is a reference to the lead selection element of the parent node of the current node. The parameter is automatically displayed in the signature of the supply function.

●

In this example, the help class is used to import the connection data of the corresponding airline carrier from the database table SPFLI to the internal table FLIGHTS.

●

Finally, the internal table is bound to the current context node CONNECTION_NODE. This allows you to display the appropriate values in the table Connections on the screen.

Each time the user selects another table element as the lead selection in the table Carrier, the value of the parameter PARENT_ELEMENT changes. The supply function of the context node CONNECTION_NODE is called and the values of its attributes are newly filled according to the selected table line in the table Carrier. Supply functions can only access context data that ○

is contained in the corresponding parent node or

○

is contained in another node that is on a next-highest level compared to the node filled by the corresponding supply function.

If possible, avoid raising an exception in a supply function or in a method called by a supply function. Since supply function are often called during rendering, these exceptions cannot be processed sufficiently.

Supply functions are exclusively called by the runtime and therefore the time of their calls cannot be determined. The supply function is also called if the content of the corresponding context node has been invalidated before. This should be thoroughly checked for each individual case due to performance reasons. From a technical point of view, each node of a context can be filled using a supply function. However, this is not always useful. Alternatives for the supply function are the method WDDOINIT and the event handler of the controller. For each context

Web Dynpro ABAP: Development in Detail

Basics

May 2006

situation, the different time of the call and the call mechanisms of these methods need to be considered and only then decided which method to use. For further information on this subject, refer to chapter Filling the Context [page 34].

1.4.3.5

Free Methods of the Application Development

As an application developer, you can create and implement your own methods for each controller. These self-defined methods are typically used to read and edit data. These methods can be called within the controller by other methods which are also implemented by the application developer. Example: In the following example, the method GET_FLIGHTS has been implemented to read data from the back end for the current controller. This data is to be used in the second method of the same controller.

method GET_FLIGHTS . . . endmethod.

method FILL_CONTEXT_NODE . data: FLIGHTSTRUC type SPFLI. MY_NODE type ref to IF_WD_CONTEXT_NODE. FLIGHTSTRUC = WD_THIS->GET_FLIGHTS( ). MY_NODE = WD_CONTEXT->GET_CHILD_NODE( ‘MY_CONTEXT_NODE’ ). MY_NODE->BIND_STRUCTURE( NEW_ITEM = FLIGHTSTRUC ). endmethod.

The reference variable WD_THIS is used to call the controller method GET_FLIGHTS and to pass the return value to the internal variable FLIGHTSTRUC. In the next step, the context node MY_CONTEXT_NODE is passed to a second internal variable MY_NODE of the type IF_WD_CONTEXT_NODE (see above, section for WD_CONTEXT). The last step is to bind the internal variable FLIGHTSTRUC to MY_NODE.

Free Methods of the Component Interface Each free method you created and defined for the component controller can be added to the interface of the component. To do this, you can check the Interface checkbox of the Methods tab of the component controller in the table. Each method for which you checked the

Web Dynpro ABAP: Development in Detail

Basics

May 2006

checkbox is a part of the interface controller of the component and is available using controllers of other components (see also Cross-Component Programming [page 55]).

1.4.3.6

Cross-Controller Method Call

The Web Dynpro framework enables the application developer to develop source code beyond the controller boundaries. The example of the previous chapter Action Event Handlers [page 12] is used again to explain the procedure: In the chapter Context Mapping [page 16], a cross-view context in the component controller and the required mapping for the example component have already been created. Now, the functions of the event handler of the action GO are to be tranferred to a method of the component controller.

Method of the Component Controller In this example, the method is called SIMPLE_GET_FLIGHTS:

method SIMPLE_GET_FLIGHTS. data: INPUT_NODE type ref to IF_WD_CONTEXT_NODE, TABLE_NODE type ref to IF_WD_CONTEXT_NODE, CAR type STRING, FLIGHTS type standard table of SPFLI. INPUT_NODE = WD_CONTEXT->GET_CHILD_NODE( 'INPUT_NODE' ). INPUT_NODE->GET_ATTRIBUTE( exporting Name = 'IN1' importing Value = CAR ). FLIGHTS = CL_WD_FLIGHT_MODEL=>GET_FLIGHTS_BY_CARRID( CAR ). TABLE_NODE = WD_CONTEXT->GET_CHILD_NODE( 'TABLE_NODE' ). TABLE_NODE->BIND_ELEMENTS( FLIGHTS ). endmethod.

The content of the method does not change, but the context in which the method is called changes. This means that, for example, the attribute WD_CONTEXT which is the reference to the local context, is no longer the context of the view but the context of the component controller.

Method Call of the Component Controller in the Event Handler of the ViewController The newly created method in the component controller must now be called in the event handler of the action GO in the view controller.

method ONACTIONGO.

Web Dynpro ABAP: Development in Detail

Basics

May 2006

WD_COMP_CONTROLLER->SIMPLE_GET_FLIGHTS( ). endmethod.

The attribute WD_COMP_CONTROLLER is a reference variable of the reference type IG_COMPONENTCONTROLLER and therefore a reference to the corresponding component controller. This is automatically known to each view controller of the component.

1.4.4

Web Dynpro Runtime APIs

The application developer can use Web Dynpro APIs as a set of interfaces for an efficient design of controller programming. APIs can be accessed in several ways. For a complete list of all classes and interfaces of the framework [externaly] and the access methods, refer to the reference manual [externaly] in this documentation. The runtime interfaces offer multiple methods for different programming areas. These include, for example: ●

Access to the window manager API IF_WD_WINDOW_MANAGER for creation of popups using existing Web Dynpro windows

●

Access to the portal integration API IF_WD_PORTAL_INTEGRATION

●

Context processing

●

Creating messages

More areas apply when using dynamic programming [page 74]. Examples: ●

Dynamic manipulation of the layout

●

Dynamic navigation control

Example for Accessing a Runtime API The runtime API of the different controller types are mentioned in the chapter Reference Variable WD_THIS [page 19]. Depending on the type of the controller, the return value of the method WD_GET_API of the local controller interface is a reference variable of the interface ●

IF_WD_VIEW_CONTROLLER (for all view controllers),

●

IF_WD_COMPONENT (for all component controllers) or

●

IF_WD_CONTROLLER (for all interface controllers or custom controllers).

The following example is the source code of the access to the runtime API of the type of the local controller - in this case, a view controller: method MY_VIEW_CONTROLLER_METHOD . data:

L_RUNTIMEAPI

type ref to

IF_WD_VIEW_CONTROLLER.

L_RUNTIMEAPI = WD_THIS->WD_GET_API( ) . .

Web Dynpro ABAP: Development in Detail

Basics

May 2006

endmethod.

In this example method, you can use the methods of the runtime API IF_WD_VIEW_CONTROLLER using the attribute L_RUNTIMEAPI. You can also access the runtime API of the type of a used controller. Example: method MY_CONTROLLER_METHOD . data:

L_COMP_INTF L_RUNTIMEAPI

type ref to type ref to

IG_COMPONENTCONTROLLER, IF_WD_COMPONENT.

L_COMP_INTF = WD_THIS->GET_COMPONENTCONTROLLER_CTR( ). L_RUNTIMEAPI = L_COMP_INTF->WD_GET_API( ) . . endmethod.

In this case, a reference variable of the component-global interface of the component controller is created. A reference variable of the runtime API of the component controller is then created using the method WD_GET_API. Since the attribute WD_COMP_CONTROLLER of the type IG_COMPONENTCONTROLLER is already created by the development environment for each view controller, the source code for the access to the runtime API of the component controller is shorter: method MY_VIEW_CONTROLLER_METHOD . data:

L_RUNTIMEAPI

type ref to

IF_WD_COMPONENT.

L_RUNTIMEAPI = WD_COMP_CONTROLLER->WD_GET_API( ) . . endmethod.

All the other APIs of the Web Dynpro runtime are made accessible in different ways. Two examples: ●

The API IF_WD_VIEW can exclusively be accessed using the attribute VIEW of the method WDDOMODIFYVIEW of the local view controller interface.

●

The APIs IF_WD_CONTEXT_NODE and IF_WD_CONTEXT_NODE_INFO can be accessed using the attribute WD_CONTEXT of the type IF_WD_CONTEXT. They are required to set the Fixed Values of Attributes [page 98].

For a complete list of all classes and interfaces of the framework [externaly] and the access methods, refer to the reference manual [externaly] in this documentation.

Web Dynpro ABAP: Development in Detail

Basics

1.4.5

May 2006

Filling the Context

The values of the context elements play a crucial role in Web Dynpro for ABAP. Therefore, the filling and changing the context must be thoroughly planned. Depending on when the context is to be filled or updated, you can choose from the following methods.

WDDOINIT The method WDDOINIT is the initialization method of the controller. If you know beforehand that the context in your application is only filled once and not invalidated afterwards, this method is appropriate for filling the context. You can also use this method if you want to associate the data update with an action and transfer the update to the corresponding event handler. The method WDDOINIT should only be used to fill those context nodes when it is known that they must be filled. The order of calls for filling the context in this method is a bit more complex than in a supply function because the calls are not linked to a context node and the corresponding node must be first created as a reference. method WDDOINIT. data: NODE type ref to IF_WD_CONTEXT_NODE, FLIGHTS type SPFLI_TAB. * get node from context NODE = WD_CONTEXT->GET_CHILD_NODE( 'CARRIER_NODE' ). * get connections from help class FLIGHTS = CL_WD_GET_SPFLI=>GET_FLIGHTS( ). NODE->BIND_ELEMENTS( FLIGHTS ). endmethod.

Supply Function The filling of a context using a supply function is useful when the content of the node must be available on demand only. This is the case for singleton nodes, for example. The supply function is called when elements of the associated node are accessed. Very often, they are not accessed before rendering. From a technical point of view, the filling of the context in the supply function is the simplest, because the corresponding node is already available as a parameter (see example in chapter Supply Function [page 26]).

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Note that you always have to recreate the entire context node when updating the data using the supply function (you cannot use the supply function to fill individual elements of the context with new values). This may slow down the performance of a Web Dynpro application (see below).

Action Event Handlers The response to an action of the user often requires the filling or change of a context. In this case, you can program the context in the event handler method of the action. In general, you have two options: First option: The event handler only invalidates the node so that a supply function must be called automatically. The event handler method "assumes" that an appropriate implementation of the supply function exists. The second option: The event handler itself fills the context. (You need to ensure that the event handler method is not bound to a specific context node. As is the case with the WDDOINIT method, the node to be filled is not directly available as a parameter, but must be created in a previous programming step).

Regardless of the method you choose for filling a context, the following rule applies: When specifying the name of a node or attribute as a string in the source code of a method, you must use UPPERCASE.

Performance of the Context Since the context provides many design options, can have many split small objects, and must act dynamically, you can have a significant control over the performance of a Web Dynpro application.

1.4.6

Phase Model

Purpose This section provides information on the data transport during the request processing. The first request is not described as it only involves the reading of the metadata and the initial display of the user interface. At certain points of the phase model, application developers can influence the user interface layout themselves by programming dynamically.

Process Flow The following graphic schematically shows the process flow during data transport:

Web Dynpro ABAP: Development in Detail

Basics

May 2006

User input

my name

Client Data Container Data is accessible only to the runtime

Validation of user input

assigned

Controller Context WDDOBEFOREACTION

Event handling val. indep. handlers

standard handlers

Error message if validation failed

WDDOBEFORENAVIGATION

Navigation and View Initialization Application developers can modidfy the view dynamically

View modifying WDDOMODIFYVIEW

WDDOPOSTPROCESSING

Rendering

The process flow of event handling is shown in detail in the following graphic:

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Event handling in detail Val. Standard indep. handlers handlers

No error message found Error message found

Event handlers

WDDOBEFORENAVIGATION

View modifying WDDOMODIFYVIEW

...

Data Transport from Client to Data Container Data – for example, user input – is transported from the client to the data container. The data container is used for a temporary data storage. At this point, data in the data container is only available to the runtime environment, but not to the application developer.

Validation of the User Input All user entries are checked. The detection of an entry with errors, however, does not terminate the check. The transport of the remaining data is not stopped. If the data type is compatible, even data with errors is transported to the context. The following checks/conversions are performed: ●

Type-specific checks (for example, no letters in date fields)

●

User-specific conversions (for example, date format according to user settings).

●

Data Dictionary checks/conversions

●

Uppercase conversion

●

Conversion exits

●

It is taken into account when a context node with Data Dictionary reference to a currency field also contains the reference field.

Check against the value set of the attribute

An error message is created for each input with errors and is displayed after the data transfer to the controller context.

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Data Transport from the Data Container to the Context The data is now available for application programs.

WDDOBEFOREACTION Before an action is triggered, you can perform your own validations using this method. The method can only be used for view controllers. It is used for all visible views of the component assigned to the current phase model instance. These include all embedded components.

Handling of Actions and Events This step is performed independently from the data transport between data container and context. When an input with errors is found during the validation of the user input, a corresponding error message is displayed and the application developer can correct the data. In general, there are two different types of event handlers (see detailed graphic of the event handling): ●

Standard event handlers are only called if no errors were found in the user input during the validation. If errors were found, an event handler of this type is skipped without processing and the runtime continues with the next step.

●

Validation-independent event handlers are always called even if errors are found during validation. In this case, the corresponding error messages created during validation are not displayed.

Navigation is only possible when it is triggered by an event handler – that is, an event handler is called to trigger navigation.

WDDOBEFORENAVIGATION In this process phase, the method WDDOBEFORENAVIGATION can be used to perform an additional validation of those controller contexts that are required in the application but have not been validated in the request/response cycle yet. This is important for more complex Web Dynpro applications in particular. This method can only be used for the component controller. The method is used for the component assigned to the phase model instance and all embedded components. Navigation can be interrupted at this point if an error occurred during the event handling in the previous step. The method CANCEL_NAVIGATIION can be called in the interface IF_WD_COMPONENT to terminate navigation. This method call prevents navigation for the entire application within a request/response cycle. Navigation requests are deleted during the subsequent run of the phase model and must be reinitialized.

Navigation and Initialization of the Subsequent View A navigation triggered by a corresponding event is now executed. The inbound plug of the subsequent view is called and the corresponding event handler is processed.

View Modification Once the method WDDOINIT of the corresponding view is executed by the runtime and the view is created accordingly, the application developer can modify the UI tree of a view, for example, by dynamically adding view elements. The method WDDOMODIFYVIEW is used for all visible views of the component associated to this phase model instance and the embedded components.

Web Dynpro ABAP: Development in Detail

Basics

May 2006

WDDOPOSTPROCESSING This method is called in the last process step before rendering. Therefore, it allows you to add application-specific clean-up processes.

Rendering During rendering, the user interface is displayed on the screen â&#x20AC;&#x201C; that is, the structure of the UI tree and the filling of elements from the context. Due to the rendering, the entire data of the views to be displayed is retrieved. The corresponding context may only be filled at the time of rendering. This also requires the calling of the corresponding supply functions. The application developer should make sure that no exceptions are raised in supply functions.

Popups An instance of the phase model exists for each active window. This means that each phase model instance is assigned to exactly one window and one component. When opening an internal popup (a popup with Web Dynpro content), an additional phase model instance is automatically created. This internal popup is opened asynchronously after the last phase of the phase model instance of the currently active window. After the last phase of the phase model instance of the popup, this internal popup is also closed asynchronously. Finally, the phase model of the now active window is run one more time.

1.4.7

Client Implementation

The graphic below gives an outline of the concept of the client implementation: Web Dynpro Runtime Web Dynpro Core Runtime

Client SSR Implementation

Client XML Implementation

User-InterfaceUser-InterfaceUser Interface Bibliotheken Element Bibliotheken Libraries

ABAP Objects

Internet / Intranet HTML JavaScript XML

Browser

eCATT

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Depending on the rendering device that is selected, the central part of the Web Dynpro runtime works together with a certain client implementation. In the case of a browser, this is server-side rendering (SSR). SSR then takes over the task of communicating with the client device. When eCATT is used (see also Creating Test Cases with CATT and Extended CATT [externaly]), the client implementation is used in its XML version, and the data and the layout are transferred separately (unlike the browser). View elements are in user interface element libraries, see also Web User Interfaces [externaly]. With the Web Dynpro for ABAP, a browser is always used as the rendering device. Data, events and layout information are converted on the server into HTML and JavaScript and transferred together. In the case of the browser, this is usually done mostly on the server; the whole layout is placed on the server, for example. The browser itself does not take on many tasks. For example, it is responsible for ensuring that a tray or the nodes of a tree on the client can be expanded or collapsed. When they are called by the Web Dynpro runtime, specific adapter techniques are used to convert data and events as part of the request response cycle into the browserâ&#x20AC;&#x2122;s format, HTML and JavaScript or XML. Conversely, these data are then converted into ABAP Objects data structures.

1.5

Web Dynpro Window

The previously described simple application example contained a Web Dynpro component with one view only. In the tutorial of this documentation, the instructions include from the beginning the creation of applications with two views which are connected via navigation. This and the following chapter describe the communication between the different views of a component. Each Web Dynpro component contains at least one Web Dynpro window [externaly]. All views that are to be displayed when using a Web application are embedded in this window. The window is processed in the Window Editor [externaly] of the ABAP Workbench. The required navigation between the individual views can be set up in the window (see chapter Navigation [page 41]). Window

Navigation Link

The Web Dynpro window contains the structure of all views to be displayed and is also connected to the Web Dynpro application [page 44] via an interface view (see also below).

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Advanced Functions of Web Dynpro Windows Window Controller and Window Plugs Each Web Dynpro window contains a controller with context, methods, outbound plugs, and inbound plugs. You can use the plugs to set up cross-component navigation. In a simple application, the starting point of a navigation is the start view. It is created at design time. This is done in the Window Editor using the context menu of the window tree. In a more complex application, the event handler method of the used inbound plug can be used to dynamically decide which view is to be displayed first. For more information, refer to the section on Window Plugs [externaly] in the architecture manual.

Interface View An interface view with an identical name is automatically created for each window. It defines the cross-component interface of the window [externaly]. Inbound plugs and outbound plugs of a window are copied to the corresponding interface view when the interface flag is set. Event handlers are implemented in the window itself. Plugs of an interface view can be used for cross-component navigation, inbound plugs of an interface view can be used for the connection to the Web Dynpro application [page 44].

1.5.1

Navigation Between Two Views

All views within a window can be connected to each other using navigation links. When the user calls a Web Dynpro application, the start view is displayed first on the screen. You can trigger a specific action â&#x20AC;&#x201C; for example, by clicking a button â&#x20AC;&#x201C; which triggers navigation. As a consequence, the previously displayed view disappears from the screen and a second view is displayed.

Start View Go to subsequent view

Subsequent View

To set up navigation between two views, you must create an inbound plug for one view and an outbound plug for the other view. A plug is always a junction used for accessing or exiting a view. Window Start View http://.........

Out

Web Dynpro ABAP: Development in Detail

Navigation link

Subsequent View In

Basics

May 2006

For more information on Plugs and Navigation Links [externaly], refer to the architecture manual for Web Dynpro. For a description of the creation and maintenance of plugs as part of a view, refer to the chapter View: Inbound Plugs and Outbound Plugs [externaly] in the tools manual. For information on the maintenance of navigation links, which is a part of the window structure, refer to the window layout [externaly]. Outbound plugs and inbound plugs have different properties:

Outbound Plugs Outbound plugs are always starting points for navigation. They are called in any method of the view controller using the following call:

WD_THIS->FIRE_MY_OUTBOUND_PLG(

The attribute WD_THIS [page 19] is always a self-reference to the interface IF_<MY_VIEW> of the view controller. Each time you create an outbound plug for this view, a method FIRE_<MY_OUTBOUND_PLUG>_PLG is added to this interface. If you create three outbound plugs OUT1, OUT2, and OUT3 for the view View_1, the methods FIRE_OUT1_PLG, FIRE_OUT2_PLG, and FIRE_OUT3_PLG are created in the interface IF_VIEW_1.

The outbound plug itself, which is the controller of the view, does not contain information on the target of the triggered navigation. The connection to the selected inbound plug of a subsequent view is set up when creating the navigation link in the window layout.

Passing Parameters You use the method call FIRE_<MY_OUTBOUND>_PLG to pass a parameter. This parameter is entered in the parameter table on the Outbound Plugs tab. For the following example, the parameter editable has been added to the method FIRE_<MY_OUTBOUND>_PLG. This parameter of the type WDY_BOOLEAN has either the value ’X’ (true) or ’’ (false). Therefore, the method call is either

WD_THIS->FIRE_MY_OUTBOUND_PLG( EDITABLE = ‘X’ ).

or WD_THIS->FIRE_MY_OUTBOUND_PLG( EDITABLE = ‘’ ).

Inbound Plugs Inbound plugs within a Web Dynpro window are always called directly using a previously created navigation link which originates from an outbound plug (see chapter Window: Layout

Web Dynpro ABAP: Development in Detail

Basics

May 2006

[externaly] in the tools manual). When an inbound plug is called, an event handler method is called which is uniquely assigned to this inbound plug. This method is automatically created in the view controller when the inbound plug is created. The method is listed in the Methods tab. It is generically named HANDLEMY_INBOUND_PLUG: In case of an inbound plug IN1, the event handler method HANDLEIN1 is created. The event handler method is empty and can be filled by the source code of the application developer. From a technical point of view, this method does not differ from other event handler methods of the controller.

Evaluating Parameters The event handler method of an inbound plug can adopt parameter values of the method FIRE_<MY_OUTBOUND>_PLG. The parameter with the same name must be added to the signature of the event handler method. If the parameter EDITABLE is passed by an outbound plug, the parameter EDITABLE must be added to the signature of the event handler method assigned to the inbound plug to read this parameter. The parameter value is then known by the event handler method and can be used. The event handler of an inbound plug is used, for example, to process additional information for the new view. It is not to be used to pass application data or to call application logic.

Example for Navigation with Parameter Transfer In the first view, an outbound plug has been called in the event handler of an action and the parameter EDITABLE = ’X’ has been passed. The subsequent view connected by a navigation link contains an element that can be edited by the user due to the transferred value of the parameter EDITABLE.

Calling the Outbound Plug OUT in the Event Handler of the First View The parameter EDITABLE of the Dictionary type WDY_BOOLEAN has been created during the creation of the outbound plug OUT of the view. The value of this parameter is passed at runtime using the following method:

WD_THIS->FIRE_OUT_PLG( EDITABLE = ‘X’ ).

Evaluating the Parameter in the Event Handler HANDLEIN of the Inbound Plug IN of the Second View Each UI element contains the enabled property, which can be used to switch the functions of the element on or off. If this property of an element is not selected in its properties table of the View Designer, the element is still displayed on the screen, but entries, selections, or other interactions of the user are not possible. The UI element is disabled. (The default setting for

Web Dynpro ABAP: Development in Detail

Basics

May 2006

this property of a UI element newly added to the layout is always enabled.) The application developer has two options to specify the behavior of the UI element at runtime: ●

The enabled property can be statically specified at design time using the checkbox of the properties table in the View Designer. When the corresponding view is called, the behavior of the UI element always remains the same.

●

The enabled property can be bound to a context node which contains an attribute of the type WDY_BOOLEAN. The value of this attribute is passed at runtime. Therefore, the UI element is available with all functions or is only displayed, depending on the specification in the program.

In the following example, the latter case is described: The context of the second view contains context nodes with application data and a node for specifying the value of the enabled property for one or more UI elements of the view. In this example, the node is called STATUS and contains exactly one attribute ENABLED of the type WDY_BOOLEAN. The value of this attribute is set by the event handler method HANDLEIN of the second view. method HANDLEIN . data: L_CONTEXT_NODE type ref to IF_WD_CONTEXT_NODE. L_CONTEXT_NODE = WD_CONTEXT->GET_CHILD_NODE( 'STATUS' ). L_CONTEXT_NODE->SET_ATTRIBUTE( NAME = 'ENABLED' VALUE = EDITABLE ). endmethod.

Since the transferred parameter is to be used to specify the property of a context node with varying values, methods of the interface IF_WD_CONTEX_NODE [externaly] are used in the event handler method (see also chapter Action Event Handlers [page 12]). In this case, the method SET_ATTRIBUTE is called and the attribute ENABLED is set to the value of parameter EDITABLE. The attribute ENABLED of the context node STATUS now has the value ’X’, which is the value passed by the method WD_THIS->FIRE_OUT_PLG( EDITABLE = ’X’ ) of the previous view.

Result If the value of the attribute ENABLED is ’X’, UI elements that have their enabled property bound to the attribute ENABLED are available with all their functions. Once the method FIRE_OUT_PLG passes the value ’ ’, the attribute ENABLED is also set to the value ’ ’ by the event handler of the inbound plug of the subsequent view and the UI elements are displayed on the screen without their functions.

1.6

Web Dynpro Application

Another important task of the window is to establish the connection between the structured view group (or at least one individual view) and a URL that can be called by the user. The window is also a unit called by a user using a Web Dynpro application [externaly]. In general, only one view is displayed on the screen at a time. In the simplest case, the Web Dynpro application calls the view specified as the start view (default) within the window. The user can navigate [page 41] from this start view to a subsequent view.

Web Dynpro ABAP: Development in Detail

Basics

May 2006

The Web Dynpro application is an independent object in the object list of the ABAP Workbench. For more information on creating and editing an application, refer to the tools manual in chapter Web Dynpro Application [externaly]. For more information on the URL, refer to chapter URL of a Web Dynpro Application [page 45]. The connection between a Web Dynpro window and a Web Dynpro application is established by the interface view of a window. Exactly one interface view is automatically assigned to each window of a component and this interface view contains a default plug by default.

Window

Interface View

Application: http://……….

You can display each interface view in the ABAP Workbench [externaly]. The interface views do not only connect the application to the window, but they and their plugs have several more functions. As a part of the component interface [externaly], they are also used when multiple components are to communicate with each other. This is the reason why they are described in more detail in several chapters of the second part of the programming manual.

1.7

URL of a Web Dynpro Application

The URL of a Web Dynpro application is automatically generated by the system. You find the URL of your application in the Web Dynpro Explorer on the Properties tab. The URL of a Web Dynpro application has the following structure (default configuration), whereby the following formats are possible: ●

SAP namespace <schema>://<host>.<domain>.<extension>:<port>/sap/bc/webdynpro/< namespace>/<application name>

●

Customer namespace ○

<schema>://<host>.<domain>.<extension>:<port>/abc/klm/xyz/< namespace>/webdynpro/<application name>

○

<schema>://<host>.<domain>.<extension>:<port>/namespace>/we bdynpro/<application name>

<schema> stands for the URL schema (also known as protocol), which usually is the protocol http or https (if configured). Host is the name of the application server that should execute the application. Domain with the extension comprises several hosts under a common name and can either be an individual host or a network (see also Fully Qualified Domain and Host Names (FQDN/FQHN) [page 48]). The port number can be omitted if the standard port 80 (http) or 443 (https) is used. The namespace can be the standard namespace /SAP/ or customer namespaces (see below).

Web Dynpro ABAP: Development in Detail

Basics

May 2006

The application name is the name of the Web application as defined in the Web Dynpro explorer by the Web Dynpro component. See also: Calling a Web Dynpro Application Using Parameters [page 55] URL Parameters [externaly]

Applications in the SAP Namespace Web Dynpro applications are stored in the ICF Internet service tree under the path /sap/bc/webdynpro/<namespace>/<application name> (see also Creating and Configuring an ICF Service [externaly]). If only the component name is specified, the standard namespace /SAP/ is used. SAP applications are always delivered in the /SAP/ namespace. If you create your Web application in a separate namespace, it must be used in the URL (see also Setting Up a Namespace for Development [externaly]). Components are specified in the format /<namespace>/<application name>, for example, /TEST40P/MYFIRSTAPP. Examples Application

URL

Application1a

http://us4049.wdf.sap.corp:1080/sap/bc/webdynpro/sap/myFirstAp

Application1b

http://us4049.wdf.sap.corp:1080/sap/bc/webdynpro/sap/mySecondA

Application2a

http://us4049.wdf.sap.corp:1080/sap/bc/webdynpro/test40p/myFir

Application2b

http://us4049.wdf.sap.corp:1080/sap/bc/webdynpro/test40p/mySec

In these two examples the Web Dynpro application mySecondApp belongs to the component myFirstApp.

Pictures Note that images are always loaded using the application URL (see below). Examples Application

URL

Application1a

http://us4049.wdf.sap.corp:1080/sap/bc/webdynpro/sap/myFirstAp

Application1b

http://us4049.wdf.sap.corp:1080/sap/bc/webdynpro/sap/mySecondA

Applikation2a

http://us4049.wdf.sap.corp:1080/sap/bc/webdynpro/test40p/myFir

Applikation2b

http://us4049.wdf.sap.corp:1080/sap/bc/webdynpro/test40p/mySec

For mySecondApp/img.gif the incoming request must be changed so that it points to myFirstApp/img.gif, before the MIME handler is called. If no further actions are performed, Web Dynpro applications are normally placed under /sap/bc/webdynpro. Understandably, many customers prefer to place their applications under a different URL namespace to /sap/bc.

Applications in the Customer Namespace Normally customers create their own branches in the ICF Internet service tree and place their applications there. For example, company XYZcorp has a registered namespace and has

Web Dynpro ABAP: Development in Detail

Basics

May 2006

created the following entry in the ICF: /xyzcorp/webdynpro/. The Web Dynpro handler is stored in this ICF node. Then the customer can create an application under this ICF path. For a new Web Dynpro component /XYZCORP/MYFIRSTAPP you would find the following path in the ICF service tree: .../xyzcorp/webdynpro If this path exists, the application is stored under this ICF tree, and also in the MIME Repository. Examples Application

URL

Application3a

http://us4049.wdf.sap.corp:1080/1wda/webdynpro/myFirstApp/

Application3b

http://us4049.wdf.sap.corp:1080/1wda/webdynpro/mySecondApp

Keep in mind that namespaces are not allowed to begin at the root node of the HTTP service tree. Instead they begin with the signature <namenspace>/webdynpro, that can be anywhere in the ICF tree. For example, SCM has created the “Internet Communication Hub” project in the namespace /ICH/. In this case the URL format would look like: /sap/scm/ich/webdynpro/myFirstApp See also: URLs and Namespaces [page 53]

FQDN The fully qualified domain name (FQDN) must be specified in the URL of Web Dynpro applications. For more information see Fully Qualified Domain Names (FQDN) [page 48].

Loading Images Usually images are loaded via the URL of the application in question. For Web Dynpro ABAP images are stored in the MIME Repository [externaly]. For each component there is usually a corresponding identical Web Dynpro application, for example, component abc is assigned to application abc. For example, if URL .../sap/abc is assigned to the application, the associated images are loaded as .../sap/abc/img.gif. Component abc may be assigned to a second application xyz. In so this application has the URL .../sap/xyz, and any associated images should also be loaded using .../sap/xyz/img.gif. The image however is stored under .../sap/abc/img.gif. Instead of using relative paths, images should be loaded via the application URL, and not via the component name. This has the following advantages: ●

Customer view All the components of an application should also be stored in the relevant directory under this application. For customers using, for example, the application SalesOrder, it is easiest to store everything under SalesOrder/*.

●

Load Balancing When load balancers is used customers normally configure them so that they use URL paths to reach specific computers, and reject all requests that point to other paths.

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Here it is important that all images are loaded via the URL under which the application is also running. For information about the various URL formats that can be resolved by Web Dynpro ABAP, see Handling Web Icons [page 112].

URL with “/” Attached When relative URLS are used to load images keep in mind how URLs behave in the browser. For example, if an image img.gif (or ./img.gif) is to be loaded with a URL of the format .../sap/app, the browser removes the last segment and generates a new URL with the format .../sap/img.gif. The app segment therefore no longer exists. The only way to get the browser to generate correct URLs is to attach a “/” character at the end of the URL. For example, if an application is started with .../sap/app, change the URL in .../sap/app/, either using a redirect command, or implicitly at the time when the frameset is loaded.

Special Cases External URLs Customers often define external URLs in the HTTP service tree of the ICF. A corresponding URL could look like: Example Application

URL

Application 1a

http://us4049.wdf.sap.corp:1080/superApp/

Note that internal links function the same in the ICF tree. Since relative URLs are used for images, theses are always loaded correctly. As soon as an application has been started, the internal name in the ICF tree must be used for the application so that it is clear what is going on behind it (pointer in the ICF tree).

Homepages If a Web Dynpro application for a homepage is running directly under the root URL, the URL looks like: Example Application

URL

Special case 1a

http://us4049.wdf.sap.corp:1080/

1.7.1

Fully Qualified Domain Names (FQDN)

In Web Dynpro ABAP it is imperative that a client browser with a fully qualified domain name (FQDN) has access to the AS-ABAP. For this reason the full URL must be assigned to a Web Dynpro ABAP application when it is called. The URL must not be shortened (for instance, no domain specification).

Web Dynpro ABAP: Development in Detail

Basics

May 2006

The domain used must also satisfy the requirements of the cookie specification (see http://wp.netscape.com/newsref/std/cookie_spec.html). To check the FQDN/FQHN, in the Web Dynpro explorer in the ABAP development environment (SE80), choose the relevant Web Dynpro application from the navigation tree for your Web Dynpro component/interface, and check the URL in the administration data. Check whether the path details in field URL also contain the full domain and host name.

Note that neither IP addresses nor underscore characters are allowed in host names (see below).

Purpose FQDN is necessary for the following reasons: â&#x2014;?

One domain is required with which cookies can be set domain-wide, for instance, SSO2 cookies.

Domain relaxation code is required for cross-frame JavaScript. This is particularly important for Portal Integration [page 116] (see below). â&#x2014;?

In an HTTPS environment, client and server names must correspond with each other for certificates and for the SSL protocol.

Note that the domain in which the AS-ABAP is run is not necessarily the FQDN used to access the AS-ABAP from the browser. A typical example is an AS-ABAP which runs both in the Intranet and in the Internet. In a case like this the FQDN is determined by the position of the browser relative to the AS-ABAP and not by the AS-ABAP itself.

Configuration of Fully Qualified Domain Names If the host name simply specifies the host and port but not the domain (including the extension), the shortened URL of a Web application looks like:

<schema>://<host name>:<port>/sap/... Example: http://pwdf0487:1080/sap/bc/webdynpro/sap/wdr_test_events Whereas the full URL should look like:

<schema>://<host name>.<domain> <extension>:<port>/sap/... Example: http://pwdf0487.wdf.sapag.de:1080/sap/bc/webdynpro/sap/wdr_test_events

IP Addresses Not Supported URLs that contain IP addresses are not supported.

<schema>://<IP address>:<port>/sap/...

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Example: http://10.21.81.0:1080/sap/bc/webdynpro/sap/xyz The following notation is required:

<schema>://<host name>.<domain> <extension>:<port>/sap/... Example: http://hs0059i.wdf.sap.corp:1080/sap/bc/webdynpro/sap/xyz To map IP addresses correctly, the following is required: ●

A minimal form of DNS at the customer location with the name of the AS-ABAP and a mapping to an IP address.

●

Alternatively, a pseudo AS-ABAP name can be used, and the HTTP proxy configured at the firewall in such a way that this URL is sent to the correct IP address.

●

For smaller installations you can use the following quick solution: Update the hosts file on each workstation. Insert the line 10.17.73.210 hostname.domain.ext into file \WINNT\system32\drivers\etc\hosts.

No Support for “_” in Host Names The browser does not accept cookies if a host name contains the underscore character “_”. Since Microsoft Internet Explorer 6.0 and MS Internet Explorer 5.5 including security patch MS01-055 cannot accept any domain names with underscore characters, session cookies cannot be saved. This will result in terminations when navigating within a Web application.

Example: The development system is called dev_sys, and the quality security system, qsys. This means the fully qualified domain name is: qsys.company.co.xx In comparison, the following notations are not accepted: dev_sys.company.co.xx qsys.my_company.co.xx For this reason, host and domain names must never contain the underscore character, “_”. See also: http://support.microsoft.com/default.aspx?scid=kb;EN-US;316112

Domain Restrictions in Accordance with the Cookie Specification The portal must be started with a domain that complies with the domain specification of the Internet standard cookie specification. Otherwise the portal cannot create the MYSAPSSO2 cookie. So that the browser can decide which servers a cookie can be sent to, the URL must contain the domain specification, since the decision is based on this information. In accordance with the Netscape cookie specification (available under http://wp.netscape.com/newsref/std/cookie_spec.html), cookies can be set for one domain

Web Dynpro ABAP: Development in Detail

Basics

May 2006

only, and a domain must contain two or three dots (.) due to security restrictions. Each of the seven top level domains (.COM,.EDU,.NET,.ORG,.GOV,.MIL,.INT) must contain at least one further domain component (usually the name of the company or organization), amounting to two dots. Each domain with a different ending (this includes the top level domains for countries, such as UK, DE, FR, and so on) must consist of two further domain components, that is, these domains must contain at least three dots. For more information see the cookie specification.

Examples of valid domains: â&#x2014;?

<host>.sap.com Top level domain -> two domain components

â&#x2014;?

<host>.portal.sap.de No top level domain -> three domain components

Some browsers (for instance, Microsoft Internet Explorer) are less strict and permit domains that violate the cookie specification rules listed above. The Internet Explorer would allow the following domain:

<host>.sap.de This is not a top level domain, yet it only has two domain components. Domains appear to be accepted whose penultimate component consists of at least three characters, because otherwise there would be problems, for instance with all British domains, due to there being insufficient restrictions on how cookies are sent. Examples URL

Description

http://www.xy.com

Compliant with specification

http://www.xy.co.uk

Compliant with specification

http://<host>.epd.de

For MS IE ok

http://www.sap.de

For MS IE ok

http://<host>.ep.de

For MS IE not ok

http://www.co.uk

Not ok (compliant with specification)

Useful links to Microsoft knowledge base: <http://support.microsoft.com/default.aspx?scid=kb; en-us;310676> <http://support.microsoft.com/default.aspx?scid=kb;EN-US;316112>

SAP generally recommends that you always comply with the definitions of the cookie specifications.

Web Dynpro ABAP: Development in Detail

Basics

May 2006

HTTPS The use of SSL (with HTTPS), as well as ensuring encrypted data transfer, should also ensure that the server being contacted (for example, a company or organization) is authentic. This is done using SSL server certificates. For each HTTPS URL the browser checks whether the full host name contained in the URL corresponds to the relevant specification (such as common name, CN) in the checked SSL server certificate. If the browser ascertains a difference, it triggers an error warning. Examples The SSL server certificate was issued on "CN=tcs.mysap.com, OU=SAP Trust Community, O=SAP AG, L=Walldorf, C=DE". The following URLs are checked:

URL

Behavior/Description

.../com.mysap.tcs//:http

HTTPS/No SSL

.../com.mysap.tcs//:https

Compliant with specification

.../com.mysap.01tcs//:https

error/Warning

With an SSL server certificate issued on "CN=mysap.com, ..." all the URLs listed above return an error. With an SSL server certificate issued on "CN=*.mysap.com, ..." all the URLs listed above return an error. A certification authority (CA), however, usually establishes its own rules for components that it issues and for verified certificates. The use of wildcards (*) in the common name is generally not permitted.

When you use SSL terminating reverse proxies (in front of the Web Server/ASABAP), make sure that the SSL server certificate of the reverse proxy corresponds to the host name of the reverse proxy that is visible for the browser. For more information about security see Security in AS-ABAP [externaly].

Setting the FQDN The following variables and parameters are used to set the host and domain names: ●

SAPLOCALHOST

●

SAPLOCALHOSTFULL

●

icm/host_name_full

The ICM sets the FQHN in accordance with the hierarchy below: ...

1. Parameter SAPLOCALHOSTFULL in the SAP profile (recommended for high availability configurations) has top priority. If it is set in the profile file, the ICM takes this as the FQHN value.

Note that the system default value of SAPLOCALHOSTFULL contains the host name without the domain, which is why the system default is ignored by the ICM . Note that the system default value of SAPLOCALHOSTFULL contains the host name without the domain, which is why the ICM ignores the system default.

If the parameter is not set, the value in iicm/host_name_full [externaly]sapurl_li is used. This is particularly suitable for situations where multiple application servers are operating with one instance profile.

1. If this parameter is also not set, the ICM takes the FQHN of the operating system.

Web Dynpro ABAP: Development in Detail

Basics

May 2006

Parameter SAPLOCALHOST is not fully qualified and is not used by the ICM for services. SAP recommend you set either SAPLOCALHOSTFULL (for high availability configurations), or icm/host_name_full.

1.7.2

URLs and Namespaces

When you use your own Namespaces [externaly] (see also Reservation of Namespaces [externaly]) there are some peculiarities to note with regard to the paths in the ICF Internet service tree and in the MIME repository.

When creating your own name spaces follow the rules set out in Defining Naming Conventions [externaly]. Normally a Web Dynpro application is created in SE80 either in the SAP namespace using its simple name, for example, myapp, or in a customer namespace using the complex name specification, /<Namespace>/<Application name>, for example, /test40p/myapp. Accordingly, the ICF path is under both /sap/ and your own namespace, as in the examples below: Examples Application name

ICF Path

myapp

myapp/sap/webdynpro/bc/sap/

myapp/p40test/

myapp/p40test/webdynpro/bc/sap/

If the ICF path hierarchy in the SAP namespace (/sap/bc/webdynpro/sap/myapp) or in the customer namespace (/sap/bc/webdynpro/acme/myapp) is too long-winded, you can create the customer namespace to the highest level directly below the default host. (/acme/webdynpro/myapp). To do this the following prerequisites must be met: •

The relevant highest-level node in the ICF and for the subnode webdynpro must be created for the respective namespace (see Creating and Configuring the ICF Service [externaly].)

For the webdynpro subnode the HTTP Request Handler [externaly] CL_WDR_MAIN_TASK must be defined in the handler list. For this subnode the System Logon [page 258] must also be configured. As soon as this has been configured, the system logon is automatically available for all subnodes of webdynpro. If applications already exist under the long ICF path, they have to be moved accordingly: ○

For all existing applications under the old path, new application nodes have to be created manually in the ICF under the new path: /acme/webdynpro/myapp1.

○

Then you should delete path /sap/bc/webdynpro/acme/ together will all the subapplications.

Web Dynpro ABAP: Development in Detail

Basics

â&#x20AC;˘

May 2006

In addition, the folder for the namespace and a subfolder for webdynpro must be set up in the MIME Repository [externaly] If there are images belonging to existing applications in the corresponding path, they have to be moved.

Once these prerequisites are met, the ICF path is on the highest level, as shown in the example below: Examples Application name

ICF Path

myapp/wda1/

yappm/webdynpro/wda1/

myapp/acme/

myapp/webdynpro/acme/

Preparatory Settings So that the Web Dynpro runs smoothly in a customer namespace, you need to make the following settings: ...

1. Start the ICF in transaction SICF. 2. Create a new root node for your namespace, (for example, /acme) in the service tree directly under the default host. Note that you only enter and save the name here. 3. Below your new root node create a subnode with the name webdynpro. The path is then /acme/webdynpro. Note that the name of the subnode must be webdynpro (without any spaces). 4. For the subnode webdynpro create the handler, CL_WDR_MAIN_TASK, under the register Handler List. 5. If you have existing applications that have a node under the long ICF path, for each of these old applications create a new node under the new path and delete the old path completely. 6. In the MIME repository tree create a new root node for your namespace and underneath it a subnode for webdynpro. Method CREATE_ROOT_FOLDER of class CL_MIME_REPOSITORY_API is provided for this. In the MIME repository the path is then: /acme/webdynpro Move existing images under the long/old path in the MIME repository to the relevant place in the new path.

Check Settings ...

1. Call transaction SE38. 2. Go to your test application. 3. Check the URL for the Characteristics of the application, whether the syntax has the following notation: http://host.domain.ext:port/1wda/webdynpro/helloworld

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

1.8

May 2006

Calling a Web Dynpro Application Using Parameters

Use The URL parameters [externaly] of a Web Dynpro application are defined by the main component. The componentâ&#x20AC;&#x2122;s window has an inbound plug. This inbound plug can have parameters, which have to be specified as URL parameters. Default values that are overwritten by the URL parameters can be set in the application for these parameters. If neither a default value nor a URL parameter is specified, a runtime error is triggered. See also: URL of a Web Dynpro Application [page 45]

Procedure ...

1. In the component, switch to the window editor. Here you can change the predefined inbound plug or create a new inbound plug. a. Specify the plug as a startup plug (Start). b. The data type should be string since data conversion and data checking are currently not performed. c. Activate the component. 2. For the application, specify the component to be called, the window, and the startup plug. You can now specify the parameters. Apart from the default parameters, the startup plug parameters are also available and can be assigned a default value. If no default value is specified, the parameters have to be specified as URL parameters when calling the application. 3. Call the application. The URL parameter overwrites the application parameter.

Cross-Component Programming

Web Dynpro components are reusable modules. This allows you to build Web Dynpro applications that consist of different components. From within a component, an interface enables you to use the data and functions of another component. The prerequisite for this is that the second component must be available at runtime in an active version. Within a distributed development project, it makes sense to create generic components to be used by different developers. For more information, see Working with Component Usages [page 58]. In addition, it may be useful to create own components only as suppliers of the data required in other components. Such components are called model components [page 74]; they only make sense whenever several components must access the same set of application data. Model components are components without graphical elements but with the full controller functionality.

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

May 2006

The Web Dynpro framework additionally offers the possibility of defining component interfaces independently of concrete components [page 68]. These separately defined interfaces can then be used and implemented in an application component. The advantage is that all used components have a – at least in parts – uniform interface. Developers who use such components for their applications can then rely on the existence of particular elements in the component interfaces. For a better understanding of the use of component-internal and cross-component elements, section The Different Controllers of a Web Dynpro Component [page 56] once more discusses the different controller interfaces and their naming conventions.

2.1

Controllers of a Web Dynpro Component

Component Controller The component controller provides data and processing logic that it should be possible to display or change for all views of a component. It has three interfaces:

●

Interface IF_<controller_name> for coding within the controller

●

Interface IG_<controller_name> for cross-controller coding within the current component.

●

Interface IWCI_<component_name> for cross-component coding. On the ABAP language level it represents the interface controller (see below).

Within the component, mapping is possible to any context element of the component controller. (See also Data Binding and Mapping [externaly]). The attributes of a component controller are known to all methods that are called within a component and can be used by them, provided they have the Public property. Otherwise, their visibility is restricted to the component controller. Events and methods assigned to the component controller are visible throughout the component. So, for example, any action of a view of the component can call such a method of the component controller. The visibility of a specially marked number of methods, events and context nodes of a component controller can be extended beyond the borders of one’s own component. They then form the interface controller of the component.

Interface Controller The interface controller is used for cross-component communication. It defines the controller part of the interface of a Web Dynpro component [externaly]. The interface controller itself does not contain any implementation. ●

For the interface controller of a Web Dynpro controller, the methods are implemented in the related component controller.

●

For the interface controller of a component interface definition, the implementation is performed in the component controller of the embedding component.

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

May 2006

For every interface controller there is a related ABAP interface IWCI_<component_name> or IWCI_<Comp.Interf.Def-Name>. For information on how to use component interface definitions in programming, see Working with Component Interface Definitions [page 68].

Interface Controller of a Component Events, methods and context nodes of the component controller can be made visible for other components; mark the Interface checkbox to assign them to the component interface. They are then included into the related ABAP interface IWCI_<component_name>. Component Controller

Context root node

method 1 method 2

node 1

method 3 (interface) method 4 (interface)

node 2 (interface)

Interface Controller

In the object list of the ABAP Workbench, these special component controller elements are displayed additionally in the Interface Controller node, but they cannot be changed there. For elements of the context of a controller from another component a mapping [externaly] can be defined to the elements of the component controller context assigned to the component interface. In the object list of the ABAP Workbench, the interface controller is displayed as a separate object of the related Web Dynpro component. In spite of this fact, the interface controller of a component is implemented and edited as part of the component controller (see above).

Interface Controller of a Component Interface Only if an interface controller is part of a component interface [page 68], the controller editor is in change mode and the context, the events and the methods can be implemented and edited directly. The global interface IWCI_<Comp.Interface-Name > is stored in the class library and can be displayed using SE24.

Custom Controller The properties and use of the custom controller that can be added optionally correspond exactly to those of the component controller. This means that it is visible to all elements of the component and the lifetime of the elements is the lifetime of the component. The custom controller gives you the option of structuring functions and data within a component. It makes sense to create and maintain a custom controller if a certain subset of views of a component should be equipped with a special function or with a special set of data.

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

May 2006

View Controller

Layout and flow logic are very closely connected to each other in a view [externaly]. As part of a view, the view controller – unlike other controllers – is therefore not edited in the Controller Editor. Instead, the necessary tools have been integrated into the View Editor, which can be used to edit the view as a whole. Just like the component controller, the view controller contains data and functions. Furthermore, the view controller also has ●

An IF_<Controllername> interface, which means that these data and functions are visible within the same view only.

The lifetime of the controller element of a view is restricted to the lifetime of the view. To create simple Web Dynpro applications, it is sufficient if you maintain the component controller and the view controller of a view. The two controllers described below are optional and help you to structure complicated components and applications, thereby increasing their reusability.

Window Controller For every window created in a Web Dynpro component, a window controller is generated. Such a window controller is visible throughout the component – it behaves like a component or custom controller. As part of a Web Dynpro window [externaly] the window controller – just like the view controller – is not edited in the Controller Editor but in the Window Editor instead.

2.2

Component Usages

Embedding a Used Component To be able to use an external component (regardless of whether it is a faceless component [page 74] or a complete component), you must first define a component usage. Follow the steps described below:

Procedure Select the component that you want to process by double-clicking on it in the object list. The Component Editor is displayed. 4. Select a name for the new component usage and enter it in the first column in the table. 5. Select the component to be used (F4 help).

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

May 2006

MYCOMPONENT Component Usage

Component

MYCOMPUSAGE

FOREIGN_COMPONENT

6. You should now consider the following: •

If the external component should be used by a single view of your component, it makes sense to create the instance of the external component in a controller method of this view.

•

If the external component should be accessible for several views, however, the instance of the external component should be created at a central location. The WDDOINIT method of the component controller is available for this.

(For general information about controllers, see Controller Editor [externaly]). Regardless of whether you have selected the controller of a view or a cross-view controller as the instantiation point for the external component, the external component must now also be entered on the Properties tab page for this controller. To do this, proceed as follows: 7. Double-click the required object in the object list (that is, on a view or a controller entry). These are listed by object in the Controller Editor or the View Editor. 8. Switch to the Properties tab. 9. To create a new usage in the Used Controller/Components table, choose Create. Make sure that the Editor is in change mode. 10. The following dialog window lists all components and controllers that are available for use. Besides all global controllers of your own component, this list also includes the externalyal component and its interface controller. Whether you now select only the external component or both the external component and its interface controller depends on how you want to proceed ●

If you merely want to display the used component – that is, call it from your current component – continue with

Component Usage Without Controller Access [page 59] ●

If you want to enable the current component to access the interface controller of the used component, continue with

Component Usage with Controller Access [page 62]

2.2.1

Component Usage without Controller Access

You can use an external component in two ways: If you only want to display the external component, but not change the data of its interface controller or use its functions, you can omit the explicit usage declaration of the external interface controller in the current controller. In this case, simply declare the usage of the external component in the currently edited controller (see figure).

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

May 2006

Controller of MYCOMPONENT Component Usage

Component

MYCOMPUSAGE

FOREIGN_COMPONENT

Controller

To do this, choose Sample Usageâ&#x2020;&#x2019;Foreign_Component. This merely enters the usage of the component in the table, and you can call the component for display purposes from the current component. The usage was added to the metadata again.

Instantiating the Used Component Regardless of whether you decided on a component usage with or without controller access, you now have to instantiate the used component in a method that you have selected:

Procedure ...

1. Select a method of your controller that you are currently processing. This may be the predefined method WDDOINIT, for example, which is called automatically each time the controller is called. If the jump to the external component should not be connected to an event, you can select an event handler method instead. 2. Double-click on the method selected in step 1 to open an ABAP Editor, where you can insert the necessary method. The Web Dynpro Code Wizard provides support: 3. Click on the Web Dynpro Code Wizard [externaly] in the Editorâ&#x20AC;&#x2122;s toolbar. A list of the frequently used Web Dynpro statement structures are listed in a separate window. 4. Select Instantiate Used Component. 5. Display the F4 help for the Comp. usage line. All of the component usages that are available in the table of the Properties tab for the controller are displayed. Select the usage you require and confirm the dialog. The required source code is automatically inserted into the current method. Once you save the method, the external component is available to your own component at runtime. Example: For a component, the usage of another component has been declared. This usage is called MY_COMP_USAGE. method MY_CONTROLLER_METHOD . data:

L_REF_CMP_USAGE L_REF_CMP_USAGE =

type ref to

IF_WD_COMPONENT_USAGE.

WD_THIS->WD_CPUSE_MY_COMP_USAGE( ).

L_REF_CMP_USAGE->HAS_ACTIVE_COMPONENT( ) is initial. L_REF_CMP_USAGE->CREATE_COMPONENT( ).

endif. endmethod.

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

May 2006

Method WD_CPUSE_<MY_COMPONENT_USAGE> This method contains the local interface of each controller as soon as you have declared the usage of an external component for (the entire component at first and then for) the current controller. The method returns a reference variable of type IF_WD_COMPONENT_USAGE. (See also Predefined Methods of the Local Controller Interface [page 22] in Part 1 of the programming manual). In the first step, method WD_CPUSE_<MY_COMP_USAGE was used to generate an object for the used component. In the second step, the object was instantiated provided that no instance existed. You can now access the used component, but you cannot use the methods of its interface controller, because you need to declare an additional usage for the respective controllers (see Component Usage with Controller Access [page 62]).

Calling the Used Component To display the external component, you can now embed an interface view of any window of this component in a window of your current component. This procedure corresponds exactly to embedding a view of oneâ&#x20AC;&#x2122;s own component. By setting up navigation from one outbound plug of a view of your current component to an inbound plug of the interface view of a window of the external component, you enable the external component to be displayed. Component A Window 1

2 Navigation Link Window Component B

Interface View

An example of how you set up a navigation is described in Part 5: Setting Up Navigation [externaly] of the Creating a Simple Flight Info Application [externaly] tutorial. Every interface view of a used component can be embedded exactly once into a window of an outer component. If you want to embed a particular interface view of a component more than once in an outer window, you must first declare the respective number of component usages. Usually you do not know this number during design time, because it depends on factors that are determined only at runtime. For more information, refer to Dynamically Creating a Component Usage [page 81] under Dynamic Programming [page 74] in this documentation. If you also want to access the content of the external controller context, or if you want to use methods of this controller, see Component Usage with Controller Access [page 62].

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

2.2.2

May 2006

Component Usage with Controller Access

If you want to enable access to the interface controller of the external component from the current component – that is, if you want to change this controller’s data or use its functions – you must choose on the Properties tab page of the selected controller Sample Usage → Foreign_component → Interface Controller. In this case, both the component and the interface controller are explicitly included into the table. Controller of MYCOMPONENT Component Usage

Component

MYCOMPUSAGE

FOREIGN_COMPONENT

MYCOMPUSAGE

FOREIGN_COMPONENT

Controller

InterfaceController

The usage was added to the metadata again. Instantiating the Used Component In accordance with the procedure described in the section above, the used component must be instantiated in an appropriate method of the component (see Component Usage without Controller Access [page 59]).

Implementing Access to Methods of the Controller of a Used Component If you now want to access the content of the used controller context or if you want to use methods of this controller, you have to expand the instantiation of the used component that is described above. To be able to do this, you must have entered the interface controller of the used component on the Properties tab page of the current controller (as described above). The usage declaration of the component is not enough in this case.

Procedure ...

1. Select another method on the Methods tab page. This can be – but does not have to be – the same method as in step 1. For example, you can instantiate the used component in a method of the component controller, so that you can then access its data or functions from different view controllers. However, you must ensure that the external component has been instantiated before the interface controller is accessed (see also The Phase Model [page 35] in Part 1 of the programming manual). 2. Open the ABAP Editor by double-clicking on the name of the selected method. 3. Click again on the Web Dynpro Code Wizard button. 4. Select Method Call in the Used Controller. 5. Use the F4 help to open the Component Name row. All available components and their controllers are listed in a separate window. 6. Select the controller you require and confirm the dialog. 7. In the next step, display the F4 help for the Methods row and select the required controller method on the subsequent dialog. 8. Confirm the Wizard dialog.

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

May 2006

The method of the controller for the used component that you selected was added to the coding of the method that you are currently editing. You can now use this function according to ABAP Objects programming.

Method WD_CPIFC_<MY_COMPONENT_USAGE> If in addition to the component usage the usage of the related interface controller has been entered, the list of the local controller methods is extended by the method WD_CPIFC_<MY_COMPONENT_USAGE>. This method returns a reference variable of type IWCI_<USED_COMPONENT>, that is of the type of the ABAP-global interface of the used component. Example: The entered component usage MY_COMP_USAGE includes the component MY_USABLE_COMPONENT into the current component. Method WD_CPIFC_MY_COMP_USAGE of the local controller interface enables you to access the methods of the interface controller of the used component MY_USABLE_COMPONENT. For example, you can then use its method WD_GET_API to access the methods of the runtime API (see above) of the used interface controllers. method MY_CONTROLLER_METHOD . data: L_REF_INTERFACECONTROLLER type ref to IWCI_MY_USABLE_COMPONENT, L_API_INTERFACECONTROLLER type ref to IF_WD_CONTROLLER. L_REF_INTERFACECONTROLLER = WD_THIS->WD_CPIFC_MY_COMP_USAGE( ). L_API_INTERFACECONTROLLER = L_REF_INTERFACECONTROLLER->WD_GET_API( ). endmethod.

2.2.3

Navigation Through Window Plugs

You can vary – at runtime – which link that was set up at design time you wish to follow. You can do this through navigation control [page 41] with the help of event handlers from window plugs [externaly]. In this manner you can control at runtime – within navigation in a window of an embedded component – which view of this embedded window is to be displayed first.

Including the Window Plugs into Navigation An additional step in navigation is necessary to include a parameter for navigation control. Instead of linking the outbound plug of a view in the window editor with the inbound plug of a subsequent view, the outbound plug of the view is linked with an inbound plug of the embedded window. Each window automatically has the inbound plug Default. However, you can create any number of your own inbound and outbound plugs for each window. The plugs of a window are displayed as its elements in the tree structure in the window editor and can be processed there as well. In addition, an outbound plug is created for the window for each required navigation option. The corresponding navigation link is set up in the window editor. In this way, all possible navigations are planned ahead of time.

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

May 2006

So that navigation can be controlled at runtime, the outbound plug of the starting view must pass a parameter to the inbound plug of the window. In the event handler method of the inbound plug of the window, the system controls which outbound plug of the window is called at runtime with the help of a suitable implementation â&#x20AC;&#x201C; depending on the value of the passed parameter. This means that the navigation path to be executed is controlled. Window main component

Window embedded component

main view_1 Out_1

Parameter P Default

InterfaceView

method HANDLEDEFAULT . . .

2.2.4

Out_2

Cross-Component Context Mapping

A third way of using the content of the interface controller of a used component is the crosscomponent context mapping. As soon as you have declared the usage of the interface controller and instantiated the external component as described in the procedure of the section above, the context of the external interface controller is available for mappings [page 16]. On the Context tab page of a controller for which a usage of the external interface controller has been declared, you see the context of this interface controller on the right side of the editor and you can define a mapping for a node of your current controller context to a node of the interface controller context.

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

Context Component Controller Node 1 Local Node

May 2006

Context Interface Controller Node 1 Node 2

Context View Controller Node 2 Local Node

Component A

2.2.4.1

Component B

External Context Mapping

Cross-Component Context Mapping [page 64] described the mechanism of a mapping across the borders of a Web Dynpro component. In the example, component A used a component B and for Node 1 of the component controller context of A a mapping was defined to the node of the same name of the interface controller context of component B. Both components are known at design time. For a better understanding, the figure below again shows the simple context mapping as explained in the section above:

Component Controller Component A Context Component Controller Node 1

Context Used Interface Controller

Node 1 Node 2

Local Node

Component B

The mapping definition at runtime provides component A with the value for its component controller context from the interface controller of component B â&#x20AC;&#x201C; with other words: The node of the interface controller context is the â&#x20AC;&#x153;sourceâ&#x20AC;? node in this mapping relationship. One example of this type of mapping is the use of a dark component [page 74]. Such a component does not have its own UI but is used solely for providing for a used component in which a layout is defined.

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

May 2006

In case of the external context mapping the flow of information is vice versa: The used component B defines in its interface controller context a node that is released for an external context mapping. In the controller editor, this is described with the attribute Input Element (Ext). when you create a node for the interface controller. This attribute is available explicitly only to context nodes of the component controller that are marked as interface nodes.

Context Interface Controller Node 1 released for ext. mapp.

Node 2

Component B

A node of the interface controller context marked in such a way can be linked with a context node of a used component and then receives the relevant values from the context node of the using component A only at runtime.

Controller Usage Component A

Context Used Interface Controller Node 1 released for ext. mapp.

Node 2

Context Component Controller

Node 1 Local Node

Component B

In this case, Node 1 of the component controller of component A is the â&#x20AC;&#x153;sourceâ&#x20AC;&#x153; node and at runtime determines the values also for the node with the same name of the interface controller context of component B.

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

May 2006

A simple context mapping is always defined in the context of the relevant controller. The relevant controller always belongs to the component you currently edit. The mapping path is always directed from the currently edited controller context to the controller node of the used interface controller. Contrarily, an external context mapping is always defined in the controller context of the respective component usage. You always define an external mapping for an appropriate node of an â&#x20AC;&#x153;externalâ&#x20AC;? interface controller you use. The mapping path in this case always points from the context of the used interface controller to a node in the currently edited controller context. An external context mapping to a context of a used component makes sense whenever the used component is intended to provide a frequently used UI schema for various other components. Usually, the node to be mapped externally is fully typed during creation. You already determine at design time which nodes and attributes the externally mappable node contains. This is of advantage because it allows you to program references to this node statically within the relevant controller. These references include linking a UI element to the node.

Example Within a large application a component is designed for address display. The context from which the address will be selected is completely open at design time, the content of a model belonging to the address display is unknown. However, since the address component is intended to display only addresses from one country, the view layout can be created. Thus you are able to construct a component for the display of country-specific addresses and bind the UI elements to externally mappable nodes. This component may now be used by all kinds of other components; by setting up an external mapping, the address display is supplied with the relevant data. You are not allowed to set up both a normal and an external mapping for the same controller usage. The resulting mapping would be cyclic and cause runtime errors.

Difference Between Normal and External Context Mapping The question of whether or not to use an external context mapping cannot always be answered uniquely. From the technical point of view, the desired result can frequently be reached via a normal mapping, provided that the application is redesigned accordingly. However, there is a fundamental difference: â&#x2014;?

As soon as you set up an external mapping for an externally mappable node, the runtime call of a supply function you may have explicitly coded is skipped. From this moment on the node is supplied with attribute values exclusively via the node of the using component.

Advanced Concepts When you create the node to be mapped externally, you can leave open the type. In this case, the node receives its complete typing from the context node for which a mapping is defined to external nodes. Against such a node, you can program only dynamically in the related controller, because its structure is unknown at design time (see Part 3: Dynamic Programming).

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

May 2006

If the node to be mapped externally of the used component requires a particular structure, this structure must be contained in the context node of the using component (A in our example). In addition, this node can contain other attributes, which are not known to the interface controller of component B at design time. In this case, the interface controller of component B can be coded â&#x2014;?

statically against the given structure, and additionally

â&#x2014;?

dynamically in view of attributes that may be added via a mapping.

A node, for which an external mapping has been defined, can no longer use the dispose method.

2.3

Working with Web Dynpro Component Interfaces

In every Web Dynpro component, the creation procedure implements an interface. This component interface contains exactly one interface controller and at least one interface view (for more information, see Interfaces of a [externaly] Web Dynpro Component [externaly] in the Architecture manual). The interface controller [page 56] contains a context, events and methods.

Window

Interface View

Interface Controller Interface of the Component Component

The interface views of the component interface have no direct connection to the interface controller; they are generated automatically for every window that is created within the component. The component interface is implemented exclusively in its related component; it cannot be implemented in other components. The programming environment of Web Dynpros now allows you to enhance this preimplemented interface by implementing additional interfaces, which have been defined independent of a component.

Component Interface Definitions Component interface definitions allow you to generically define a uniform interface structure and later use it in a variety of application components. The advantage of this procedure lies in the fact that in a distributed development the interfaces of all components that use the interface definition reliably contain a particular set of controller elements (methods, context elements, etc.) and interface views, which can be addressed by the developers of using

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

May 2006

components. The developer of a using component does not need to know which actual implementation of the interface is used – this can be determined dynamically at runtime. You use the Object Navigator to create [page 70] and edit component interface definitions analogous to components. The interface controller of a component interface definition and the interface controller of a component differ in two items: Interface Controller of a Component Interface Definition

Interface Controller of a Component

The controller can be edited

The controller can be displayed but not edited. To edit its elements, you must call the related component controller and mark the Interface checkbox for all elements intended for the interface controller (see The Different Controllers of a Web Dynpro Component [page 56])

Methods can be defined in the editor, but they cannot be programmed there.

The methods can be created in the editor of the related component controller (see above) and then be programmed in the ABAP editor.

The methods are programmed only after the implementation of the component interface definition in a Web Dynpro component.

In addition to the mandatory interface controller you can add any number of interface views to a component interface definition.

Implementing Component Interface Definitions These separately defined component interfaces can now be added to the implemented interface of a component. With the implementation of a component interface definition [page 71] in a component, the elements of the separately defined interface controller are added to the component controller of the implemented component. Within this implemented component, the methods of the interface controller that have only been defined so far can be programmed component-specifically. For large programming projects, this results in a higher reusability of the interface structures.

Component Interface Definition X Interface Controller • method X

Component Controller

Component Controller • method A

• method A • method X Component A

Component A

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

May 2006

Besides the interface controller a component interface definition can contain interface views.

Interface Controller Interface View X1 Interface View X2

Component Interface Definition X

When implementing a component interface definition, these interface views are added to the existing views in the interface folder of the implemented component. The related windows are generated and stored in the respective folder of the object list. They are empty and can now be laid out especially for the embedding component.

Component Interface Definition X Interface of Component A

Interface of Component A Interface Controller

Interface Controller

Interface View A1 Interface View A2

Interface View X1 Interface View X2

For a better understanding, the next section illustrates this concept by means of an application example.

2.3.1

Creating a Web Dynpro Component Interface Definition

Procedure 9. Start the Object Navigator and in the object list selection choose Web Dynpro Comp./Interf. 10. Enter a new name for your component interface definition and choose Display. 11. Confirm the Create Object dialog. 12. In the next dialog window enter a description of your component interface definition and in the list below mark the type Web Dynpro Component Interface. Confirm this dialog as well.

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

May 2006

13. Create an object catalog entry by assigning the new object to the desired package and by choosing Save. You can now create methods and interface views for this interface definition.

2.3.2

Implementing a Web Dynpro Interface Definition

To implement a Web Dynpro interface definition in a component, enter it into the Implemented Interfaces table of the component editor of the component: ...

1. Select the component that you want to process by double-clicking on it in the object list. You are now in the Component Editor and can switch to the Implemented Interfaces tab page. 2. Enter the name of the desired interface definition in the first column of the table and save it. 3. In the third column of the table, Implementation State, a traffic light symbol appears.. As long as this traffic light shows red, the interface definition is not or not completely implemented. Choose New Implementation to trigger the implementation; the traffic light switches to green. If changes are made to the interface definition after the implementation, then the traffic light in the table of the implementing component switches back to red; the changed interface definition must be re-implemented.

Result After the implementation, the implementing component now contains the elements of the interface definition. â&#x2014;?

The methods of the interface definition have been added to the component controller and can now be edited there. You can mark the Interface checkbox for each of them to make them visible as elements of the interface controller.

â&#x2014;?

The same applies for the context nodes of the interface definition.

â&#x2014;?

The interface views of the interface definition have been implemented in the component interface and are listed in the object list underneath the Component Interface node. In addition, all related Web Dynpro windows have been generated. They are also displayed in the object list and can now be edited.

2.3.3

Example for the Implementation of an Interface Definition

The example below illustrates the principle of the interface definition and implementation by means of an actual development situation. The static case described here is basically designed to demonstrate the principle; in the practice, it will be of limited use, because it requires all involved components of the using component to be known already at design time. And certainly, the implementation of interface definitions is most advantageous when this knowledge is missing at design time and the desired implementation of the interface is selected only at runtime. For more information on interface

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

May 2006

implementations, see the third part of this documentation: Dynamic Programming [page 74]. A central Web Dynpro component for travel expense management uses different components with related detail information, among them the components for flights, hotels and rented cars. In an interface definition IF_TRAVEL_COSTS a node is defined, which contains two attributes for open and paid costs. Component Hotels

Component Interface IF_TRAVEL_COSTS

Component Controller Context Hotel

Interface Controller Context total Costs

Arr_date Dep_date Price

open payed

total Costs open payed

Component Hotels Component Controller Context

Hotel Arr_date Dep_date Price

After the interface definition IF_TRAVEL_COSTS has been implemented in all three detail components, their component controllers now have a context node Costs. Each of these components can include this node into its own controller implementation and fill it individually. Component Hotels Component Controller Context Hotel

Component Flights Component Controller Context Flight

Name Arr_date Dep_date Costs open payed

Flight_date Carr_ID Conn_ID Costs open payed

Component Car_Rental Component Controller Context Car rented from rented to Price Costs open payed

After all detail components of our example now have a separate interface, you can declare a usage of exactly this interface for the superior Travel Costs component.

Web Dynpro ABAP: Development in Detail

Cross-Component Programming

May 2006

Component Travel_Expense Component Usages Comp. Usage Usage_Hotels

Component

Describtion

IF_TRAVEL_COSTS IF_TRAVEL_COSTS

Demo

Usage_Flights Usage_Car_Rental

IF_TRAVEL_COSTS

Demo Demo

As with a normal component usage [page 58] an instantiation of the involved components is programmed in an appropriate method of this component (for example, the method WDDOINIT of the component controller after a usage has been declared for this controller as well). method WDDOINIT. data: L_REF_CMP_USAGE type ref to IF_WD_COMPONENT_USAGE. L_REF_CMP_USAGE = WD_THIS->WD_CPUSE_USAGE_HOTELS( ). if L_REF_CMP_USAGE->HAS_ACTIVE_COMPONENT( ) is initial. L_REF_CMP_USAGE->CREATE_COMPONENT( COMPONENT_NAME = 'HOTELS' ). endif. data: L_REF_CMP_USAGE2 type ref to IF_WD_COMPONENT_USAGE. L_REF_CMP_USAGE2 = WD_THIS->WD_CPUSE_ USAGE_FLIGHTS( ). if L_REF_CMP_USAGE->HAS_ACTIVE_COMPONENT( ) is initial. L_REF_CMP_USAGE2->CREATE_COMPONENT( COMPONENT_NAME = 'FLIGHTS' ). endif. data: L_REF_CMP_USAGE3 type ref to IF_WD_COMPONENT_USAGE. L_REF_CMP_USAGE3 = WD_THIS->WD_CPUSE_ USAGE_CAR_RENTAL( ). if L_REF_CMP_USAGE->HAS_ACTIVE_COMPONENT( ) is initial. L_REF_CMP_USAGE3->CREATE_COMPONENT( COMPONENT_NAME = 'CAR_RENTAL' ). endif. endmethod.

For each of these three instances, the content of the interface implementation is now available to the using component. Example Context Mapping: For the context of the component controller this means that a mapping can be defined to each of the three different implementations of the interface context node Costs. In the context of the component controller an appropriate node must be created for each mapping.

Web Dynpro ABAP: Development in Detail

Dynamic Programming

May 2006

Component TRAVEL_COSTS Component Controller Context

Usage_Car_Rental Usage_Flights

Costs_Hotel

Usage_Hotels

open payed

Costs open payed

2.4

Working With Faceless Components

Features of Faceless Components Faceless components are Web Dynpro components without graphical elements â&#x20AC;&#x201C; that is, without windows or views. They only include a component controller; optionally, custom controllers can be added. You use faceless components to separate the data used in the framework of a large-scale programming project. They are designed exclusively for receiving and structuring data. By declaring a component usage [page 58] you embed them into other components; they then supply the embedding component with the required data. To create a faceless component, you create a new Web Dynpro component and delete the two visible elements â&#x20AC;&#x201C; that is, the view and the window â&#x20AC;&#x201C; from the object list.

Using Faceless Components Correctly Whether or not to use a faceless component to separate the required data depends on the structure and size of the planned application. A faceless component is only useful if several other components access the same set of data. It does not make sense to create a faceless component for every application, because in less complicated cases the performance is better if you store the required data in the component controller of a central application component. The usage of a faceless component and the subsequent mapping to its context node by the contexts of the using components also has logical consequences. Not only every change to the values of the context attributes is automatically propagated to all contexts involved in the mapping, but also properties such as the lead selection.

Dynamic Programming

Web Dynpro offers the frame for you to lay out the user interface structures of your business application as declarative as possible. Nevertheless, with increasing complexity of the application, it may become necessary to make certain decisions only at runtime.

Web Dynpro ABAP: Development in Detail

Dynamic Programming

May 2006

The dynamic embedding of an interface view [page 83] into a window in the context of a dynamically created component usage is an example for dynamic programming within a Web Dynpro application. In addition, you may influence, for example, the structure of a context [page 79] at runtime; you may add elements to a context at runtime. Besides, you can change the layout of a view [page 75] at runtime, which means that you can dynamically add UI elements.

3.1

Dynamic Layout Manipulation

Under certain conditions, it may be useful to change the layout of a view at runtime. In this context, you can add as well as remove UI elements. You can also change the dynamic properties of a UI element, bind an event to an action or manipulate the parameter mapping of event parameters [page 77]. Basically, you should use the dynamic manipulation of the layout – just like the dynamic manipulation of the context – only if it is not possible to construct a component by declarative means. This may be the case if parts of the component are not yet knows at design time. To make changes to the structure of a view layout, you must use the method WDDOMODIFYVIEW (or a method called within it). For a complete list of all UI element classes [externaly] and their methods, refer to the reference part of this documentation.

Containers and UI Elements To use the dynamic layout manipulation correctly, you must understand the structure of a view: In a view, a number of UI elements is laid out in relation to one another. This is done in so-called containers. To describe it, a layout is selected for every container: FlowLayout, MatrixLayout, or RowLayout exist (see reference documentation, chapter Layout [externaly]). Every UI element has layout data, in accordance with the embedding container. This layout data contains the description, at which position in the layout of the container an embedded UI element has its place. The layout of the container and the layout data of the embedded UI element must always match. Example: If the container is of type FlowLayout, then the layout data of the embedded UI elements must be of type FlowData. When a view is created, it already contains an empty container, the ROOTUIELEMENTCONTAINER. Within this container, the entire view layout is structured.

Adding a UI Element to a Container To add a new UI element to a UI element container, proceed as follows: ●

You must determine what kind of a UI element it is.

●

For the container element to which to add the new UI element you must create a reference (method view->GET_ELEMENT).

Web Dynpro ABAP: Development in Detail

Dynamic Programming

●

May 2006

You must determine the position in the container layout, where to fit in the new element. For this purpose, you must create the layout data for the newly created UI element.

The code fragment below shows the steps required to add a UI element of type Button: method WDDOMODIFYVIEW . data: LR_CONTAINER LR_BUTTON LR_FLOW_DATA LR_BUTTON LR_FLOW_DATA

type ref to CL_WD_UIELEMENT_CONTAINER, type ref to CL_WD_BUTTON, type ref to CL_WD_FLOW_DATA. = =

CL_WD_BUTTON=>NEW_BUTTON( ). CL_WD_FLOW_DATA=>NEW_FLOW_DATA( element = LR_BUTTON ).

LR_CONTAINER ?= view->GET_ELEMENT( ‘ROOTUIELEMENTCONTAINER’ ). LR_CONTAINER->ADD_CHILD( LR_BUTTON ). . . endmethod.

Properties of the Newly Added UI Element If you want to set a property of the UI element during the dynamic creation, pass the values when you create the element. To enhance the above example with a text on the button to be created (the text has been created before in the Online Text Repository [externaly]): data:

MY_TEXT

type string.

MY_TEXT

CL_WD_UTILITIES=>GET_OTR_TEXT_BY_ALIAS( ‘MY_TEXT_ALIAS’ ).

LR_BUTTON

CL_WD_BUTTON=>NEW_BUTTON( text = MY_TEXT ).

A property like the text of the button can also be used later. For this purpose, the class CL_WD_BUTTON, and all other basis classes of UI elements, contains the appropriate method – for the example above, this is the method SET_TEXT. In the same manner, you can set or change all other properties of a UI element. For example, you can assign an action [page 10] (which you created independently) to the button or change the assignment dynamically. LR_BUTTON

CL_WD_BUTTON=>NEW_BUTTON(

text = MY_TEXT On_action = MY_ACTION ).

Besides, you can bind properties of UI elements to context nodes. To do this, the class CL_WD_[UI element type] contains a set of methods BIND_[property type]: LR_BUTTON->BIND_TEXT( ‘NODE_NAME.ATTRIBUTE_NAME’ ).

Removing a UI Element from a Container To remove a UI element from a container, the class CL_WD_UIELEMENT_CONTAINER contains the method REMOVE_CHILD.

Web Dynpro ABAP: Development in Detail

Dynamic Programming

3.1.1

May 2006

Working Dynamically with Parameter Mappings

The term parameter mapping is used for the bind of an event parameter to a parameter of an action handler method.

Background A number of UI elements is able to trigger events. Each of these events has predefined parameters; for example, every event has the parameter ID. Depending on the type of the related UI element, other parameters may additionally be predefined. However, these event parameters are not represented individually in the development environment; for a complete list of all events and their related parameters for every UI element, see the reference part [externaly] of this documentation. In the handler method of the action related to the event, you can now use this event parameter by creating a parameter with the same name for the method. The mapping between these two parameters always occurs via similarity of names (see also Parameter Mapping [page 11] in the fundamental part of this documentation). Example: Every event has a parameter ID, to which the name of the respective UI element is assigned as value. If you create a parameter named ID in the handler method of the related action, the value of the event parameter with the same name is automatically passed to it.

Dynamically Creating Additional Event Parameters You can create and use other parameters besides the event parameters predefined by the meta model. However, this procedure is applicable only within the frame of dynamic programming. Adding additional event parameters must always be implemented in the method WDOMODIFYVIEW. Example A view contains several UI elements of type LinkToAction. The link the user activates controls the subsequent display within the view. Depending on the selected link, an attribute (for example, with the name ”CLICKED_AT”) of the view context must receive a specific value. The handler method of the only action (for example, with the name ”ON_CLICK”) of this view copies this value from the respective event parameter, which has been created for each of these UI elements and has been added dynamically to the respective event. For this procedure, you must perform the following three steps: ●

Create the additional parameter

●

Set its value which depends on the UI element

●

Assign the parameter to the respective event.

The coding below shows these three steps for the example above: METHOD wddomodifyview.

Web Dynpro ABAP: Development in Detail

Dynamic Programming

DATA: lt_parameters parameter lr_link1 lr_link2

May 2006

LIKE LIKE TYPE TYPE

if_wd_event=>parameters, LINE OF lt_parameters, REF TO cl_wd_link_to_action, REF TO cl_wd_link_to_action.

First, for method WDOMODIFYVIEW two variables are declared: one for the event parameters to be newly created and one for the local table that administers them. In addition, you need a variable of corresponding type for each of the UI elements. . . CHECK first_time = abap_true.

. .

lr_link1 ?= view->get_element( 'LINK1' ). lr_link2 ?= view->get_element( 'LINK2' ).

The parameter view is automatically known in each method WDOMODIFYVIEW. The two local variables are assigned by means of the related interface IF_WD_VIEW and the ID (Link1/Link2) of the respective UI element. . .

. .

parameter-name = 'MYID'. parameter-value = 1. parameter-type = 'g'. INSERT parameter INTO TABLE lt_parameters. lr_link1->map_on_action( lt_parameters ).

Then the new parameter receives a name, value and type and is added to the local table. If you want to add several parameters to the event of this UI element, repeat the last three steps as often as required and also add the additional parameters to the local table. Use the command lr_link1->map_on_action( lt_parameters ) to link the local table to the event. . .

CLEAR lt_parameters[]. parameter-name = 'MYID'. parameter-value = 2. parameter-type = 'g'. INSERT parameter INTO TABLE lt_parameters. lr_link2->map_on_action( lt_parameters ).

ENDMETHOD.

After resetting the local table, the steps are repeated for the second and all other events. As the result of this procedure, the events of the two UI elements Link1 and Link2 each contains a parameter named MYID, however with different values. When the respective event is triggered, the runtime automatically passes the new parameter to the action handler method, by which it is evaluated appropriately. A simple variant of the action handler method ONACTIONON_CLICK could look like this: Parameter

Declaration type

Web Dynpro ABAP: Development in Detail

Reference type

Dynamic Programming

May 2006

Importing Importing

WDEVENT MYID

CL_WD_CUSTOM_EVENT STRING

METHOD onactionon_click. wd_context->set_attribute( name = 'CLICKED_AT' value = myid ). ENDMETHOD.

The value of the event parameter MYID is passed to the context attribute CLICKED_AT and can now be used for further control.

3.2

Dynamic Context Manipulation

You can manipulate the context of a controller in different ways at runtime. To support the dynamic programming of contexts and view layouts, the Web Dynpro framework offers a number of methods in the service class CL_WD_DYNAMIC_TOOL. This class contains the frequently used methods in a predefined form. However, you can also implement yourself all the methods for dynamic context manipulation implemented in this class within the Web Dynpro framework. However, note that not all technically possible options are available in this class. In many cases, you will carry out your programming via the relevant framework interfaces to be able to use advanced functions.

To get an overview of how this class is used, have a look at the example component DEMODYNAMIC in the SWDP_DEMO package, which was delivered together with your system.

Adding Context Nodes Adding a node to a context at runtime may be necessary for a variety of reasons. In highly generically programmed components, the number of required nodes may not be known at design time. Even if the number is known, the structure of the node may become known only at runtime. In such a case, the node is also created and typed dynamically. For this purpose, the interface IF_WD_CONTEXT_NODE_INFO [externaly] contains the method ADD_NEW_CHILD_NODE, which has a number of parameters, such as the name of the new node or the assigned supply method. Alternatively, the service class CL_WD_DYNAMIC_TOOL [externaly] contains the method CREATE_NODEINFO_FROM_STRUCT, but with limited functionality.

Web Dynpro ABAP: Development in Detail

Dynamic Programming

May 2006

If you delete the node info, then all instances of the related node are automatically deleted as well. In contrast to statically created context nodes, the length of the name of a dynamically created node is not limited.

The Attribute Structure of the Node The method CREATE_NODEINFO_FROM_STRUCT expects a known structure to be passed, which means that the node created in such a way automatically has a fixed set of attributes in accordance with the selected structure. However, you can always add individual attributes to this structure (see below). Basically, you could also dynamically create an empty node and fill it with attributes afterwards. However, the service class CL_WD_DYNAMIC_TOOL does not provide a prepared method for this.

Binding a UI Element to a Dynamically Created Context Node The dynamic bind of a UI element to a context node is programmed at the UI element (see chapter Dynamic Layout Manipulation [page 75]).

Adding Context Attributes It can make sense to add or remove parameters to or from a context node, depending on the parameters evaluated at runtime. If you created a context node with a DDIC structure at design time, you can create additional attributes only dynamically. In generic applications it may happen that the type of an attribute is not yet known at design time; in this case, you will also create and type this attribute dynamically. For this purpose, the interface IF_WD_CONTEXT_NODE_INFO [externaly] contains the method ADD_ATTRIBUTE.

Fixed Values of Attributes A UI element can be bound to a dynamically created context node. The UI element may access fixed values of context attributes. In this case, it is necessary to determine fixed values for the attributes. For more information, see Fixed Values of Attributes [page 98].

3.3

Working Dynamically with Component Usages

The chapter on cross-component programming [page 55] explained the principles of how to use components and interfaces. In that case, the involved components have been known at design time and all navigations or method usages could be determined statically. In practice, however, in many cases this information is not available at design time so that the usage must be created dynamically [page 81] and can be generated only at runtime, after the name of the desired component has been passed. Consequently, all subsequent steps (such as Embedding an Interface View [page 83] or Registration onto an Event of a Used Component [page 86] etc.) must be programmed dynamically to be generated at runtime. The documents below give an overview on frequently used substeps within a dynamic component usage.

Web Dynpro ABAP: Development in Detail

Dynamic Programming

May 2006

Your system contains an example application in which you can, among others, repeat the steps described here. The application WDR_TEST_DYNAMIC is designed to visualize the interface views of different components as tab strips. All used components implement the component interface WDR_TEST_DYNAMIC_CI. At the interface controller of this component interface, the method MY_METHOD and the event DATA_SELECTED are defined. The component interface also contains the interface view W0.

3.3.1

Dynamically Creating Component Usages

Multiple Use of a Component The chapter on Component Usage Without Controller Access [page 59] already mentioned that, depending on the purpose of the application, it may be useful to display a particular interface view of a component more than once within a using component. If the number of embeddings is constant and known at design time, the structure of the embedding window can be constructed statically. However, if the application developer of the using component does not yet know at design time how many usages are needed at runtime, the generation of the component usages can be programmed dynamically. The code fragment below shows a section that might be implemented in a method of the component controller of the using component: method MY_CONTROLLER_METHOD . data: L_COMPONENT_USAGE L_MY_INITIAL_USAGE

type ref to IF_WD_COMPONENT_USAGE, type ref to IF_WD_COMPONENT_USAGE.

L_MY_INITIAL_USAGE = WD_THIS->WD_CPUSE_MY_INITAL_USAGE( ). L_COMPONENT_USAGE = L_MY_INITIAL_USAGE->CREATE_COMP_USAGE_OF_SAME_TYPE( <NAME_OF_THE_SECOND_USAGE> ). . . endmethod.

First, a first usage must be created statically, before at runtime other usages of the same component (....USAGE_OF_SAME_TYPE) can be generated dynamically out of it. The above example shows the creation of a second component usage. If the number of the usages needed later is not yet know at design time, this step must be programmed in an appropriate loop. The created component usages can be managed in an internal table, an attribute of the controller. This attribute must be created explicitly for that purpose. To do this, the Web Dynpro runtime offers the type WDAPI_COMPONENT_USAGE; however, you can also create a data type of your own.

Using Different Components In many applications, it may be necessary to dynamically create the usage of different components. For example, in an international application the usage of the respective countryspecific component may be created only after the user entered the country code. In this case, the component to be used is not known at runtime. Instead of the usage of a different component, you can now declare the usage of a separate component interface [page 68]. The programming is done as shown in the above example. All components to be embedded into

Web Dynpro ABAP: Development in Detail

Dynamic Programming

May 2006

the using component must implement the respective component interface at design time. At runtime, now any number of usages of the interface can be created. The assignment of the actual implementation to each of the usages is done only when the respective component is instanciated (see section Instanciating Used Components in Component Usage Without Controller Access [page 59]). In this case, the name of the component to be instanciated is programmed as a variable and passed at runtime. If you want to embed an interface view of a component included dynamically in the way described above you must program this embedding dynamically as well. For more information see Dynamically Embedding an Interface View [page 83].

Component Usage Groups Instead of managing dynamically created component usages in an internal table at the component controller, you can also use component usage groups. The concept of the component usage groups integrates the management of the dynamically created usages into the Web Dynpro runtime. A component usage group is always created in the using component, preferably at the component controller. The code fragment below shows how a component usage group is created dynamically. method MY_CONTROLLER_METHOD . data: L_CMP_API L_CMP_USAGE_GROUP

type ref to IF_WD_COMPONENT, type ref to IF_WD_COMPONENT_USAGE_GROUP.

L_CMP_API = WD_THIS->WD_GET_API( ). if L_CMP_API->HAS_CMP_USAGE_GROUP( ‘TESTGROUP’ ) is initial.

. .

WD_THIS->CMP_USAGE_GROUP = L_CMP_API->CREATE_CMP_USAGE_GROUP( NAME = ‘TESTGROUP’ USED_COMPONENT = ‘<name used component>’). endif.

Into this dynamically created usage group you can now add component usages: WD_THIS->CMP_USAGE_GROUP->ADD_COMPONENT_USAGE( NAME =’USAGE1’ EMBEDDING_POSITION = ‘<Name View>/<Name Container>’ USED_COMPONENT = ‘<Name used component>’ ). WD_THIS->CMP_USAGE_GROUP->ADD_COMPONENT_USAGE( NAME =’USAGE2’ EMBEDDING_POSITION = ‘<Name View>/<Name Container>’ USED_COMPONENT = ‘<Name used component>’ ). . .

For the values of parameter EMBEDDING_POSITION there is a convention: If the selected container itself also contains a view, the further specification is separated with a period from the specification of the outer view/outer container: EMBEDDING_POSITION Container2>*’

= ‘<Name View>/<Name Container>.<Name Sub-view>/<Name

You can repeat this nesting several times.

Web Dynpro ABAP: Development in Detail

Dynamic Programming

3.3.2

May 2006

Dynamically Embedding an Interface View

An interface view of a dynamically embedded component must be included dynamically into the navigation of a window. You can implement this, for example, in a method of the controller of the view that launches the navigation. The code fragment below shows the instanciation of the dynamically embedded component. data: L_VIEW_CONTROLLER_API type ref to IF_WD_VIEW_CONTROLLER, L_COMPONENT_USAGE type ref to IF_WD_COMPONENT_USAGE, COMPONENT_NAME type STRING. if L_COMPONENT_USAGE->HAS_ACTIVE_COMPONENT( ) is initial. L_COMPONENT_USAGE->CREATE_COMPONENT( COMPONENT_NAME ). endif.

Then the method PREPARE_DYNAMIC_NAVIGATION of the runtime API of the view controller is called. All attributes of the own – that is, the using – component are known and can be implemented statically (source attributes). All attributes of the used component are unknown at design time and are passed as variables (target attributes, values are displayed as placeholders in pointed brackets). L_VIEW_CONTROLLER_API = WD_THIS->WD_GET_API( ). L_VIEW_CONTROLLER_API->PREPARE_DYNAMIC_NAVIGATION( source_window_name = 'W0' source_vusage_name = 'MAIN_USAGE_1' source_plug_name = 'TO_V1' target_component_name = <component_name> target_component_usage = <component_usage_name> target_view_name = <interface_view_name> target_plug_name = <inbound_plug_name> target_embedding_position = <embedding_position> ).

The method PREPARE_DYNAMIC_NAVIGATION of the API of the view controller embeds the interface view <interface_view_name> of component <component_name> at the respective embedding position <embedding_position> (see below). In addition, a navigation link is created from the outbound plug TO_V1 of the view MAIN to the inbound plug <inbound_plug_name> of the interface view <interface_view_name>. The component specified in <component_name> must implement the component interface to which the component usage <component_usage_name> points. In the last step of this fragment, the outbound plug is called. WD_THIS->FIRE_TO_V1_PLG( ). . .

Web Dynpro ABAP: Development in Detail

Dynamic Programming

May 2006

In the example application WDR_TEST_DYNAMIC the component interface WDR_TEST_DYNAMIC_CI is implemented by the components WDR_TEST_DYNAMIC_1, WDR_TEST_DYNAMIC_2 and WDR_TEST_DYNAMIC_3.

Note that the method PREPARE_DYNAMIC_NAVIGATION must be called in the phase model up to and including the phase DO_BEFORE_NAVIGATION, ideally in an action handler, because otherwise no navigation will take place.

Embedding Position of the Interface View When embedding the interface view, different cases may be of relevance: 4. To embed the interface view directly into a window of the using component, no further steps are required. By specifying the value for the attribute <embedding_position>, the display of the interface view within the selected window is triggered automatically. emb. Interface-View link

View

5. However, if you want to display the interface view in a view within the window of the using component, the interface view is considered in the rendering process only if it has been positioned in a view container element within the embedding view: View

link

emb. Interface-View

ViewContainerelement

This view container element can exist in the embedding view if it has been declared statically. In this case, the embedded interface view will also be displayed automatically and together with the embedding view after specifying the view container element as the value for the embedding position in method PREPARE_DYNAMIC_NAVIGATION. 6. However, it may also occur that the view container must be created dynamically at runtime. The code fragment below shows an example for creating such an additional container, which must always be programmed in the method WDDOMODIFYVIEW of the respective view:

Web Dynpro ABAP: Development in Detail

Dynamic Programming

data: L_ROOT_CNT

May 2006

type ref to CL_WD_UIELEMENT_CONTAINER,

L_VIEW_CNT

type ref to CL_WD_VIEW_CONTAINER_UIELEMENT,

L_MATRIX_HEAD_DATA

type ref to CL_WD_MATRIX_HEAD_DATA.

if first time = abap_true. L_ROOT_CNT ?= VIEW->GET_ELEMENT( ’ROOTUIELEMENTCONTAINER’ ). L_VIEW_CNT = CL_WD_VIEW_CONTAINER_UIELEMENT=>NEW_VIEW_CONTAINER_UIELEMENT( ID = ‘CNT1’ ). L_ROOT_CNT->ADD_CHILD( L_VIEW_CNT ). L_MATRIX_HEAD_DATA = CL_WD_MATRIX_HEAD_DATA=>NEW_MATRIX_HEAD_DATA( ELEMENT = L_VIEW_CNT ). endif.

The name of the dynamically created view container element is passed to method PREPARE_DYNAMIC_NAVIGATION (see above) even though the element will be created only at a later point in time in the phase model.

3.3.3

Method Call in a Dynamically Created Component Usage

If a used component of the using component wants to provide a method to be called, this method must be defined in the interface controller of the used component. In practice, the method to be called is generally declared in the interface controller of an interface definition and programmed in the component controller of an implemented component. The code fragment below shows a section of a method of a view controller of the using component: method MY_CONTROLLER_METHOD . data: L_INTF_CONTROLLER L_COMPONENT_USAGE

type ref to IWCI_<NAME_INTERFACE_DEFINITION>, type ref to IF_WD_COMPONENT_USAGE.

L_INTF_CONTROLLER ?= L_COMPONENT_USAGE->GET_INTERFACE_CONTROLLER( ). L_INTF_CONTROLLER-><NAME_METHOD>( ). . . endmethod. L_COMPONENT_USAGE is a reference to the dynamically created component usage [page 81]. L_INTF_CONTROLLER is a reference to the interface controller of the used

component/component interface.

Web Dynpro ABAP: Development in Detail

Advanced Concepts

3.3.4

May 2006

Dynamically Registering an Event Handler to an Event

Components you use within another component can have events. An event of an interface definition is triggered in the component in which the interface definition is implemented. An event handler of the using component can register onto such an event. If the usage of a component has been created dynamically, then also the registration of the using component onto an event of the used component or the implemented interface must be created dynamically. The code fragment below shows an example of how to implement a dynamic registration. method MY_CONTROLLER_METHOD . data: L_COMPONENT_API L_COMPONENT_USAGE

type ref to IF_WD_COMPONENT, type ref to IF_WD_COMPONENT_USAGE.

L_COMPONENT_API = WD_COMP_CONTROLLER->WD_GET_API( ). L_COMPONENT_USAGE->ADD_EVENT_HANDLER( listener handler_name controller_name event_name

. . endmethod.

= = = =

L_COMPONENT_API <event_handler_name> ‘INTERFACECONTROLLER’ <event_name> ).

The method ADD_EVENT_HANDLER ( ) is called at the object of the component usage L_COMPONENT_USAGE. The attribute controller_name describes the controller in which the event is defined: If, as described here, the event is defined in a used component, then it can only be the interface controller of this component. The method you want to implement in the registration must be called in the phase model [page 35] of the Web Dynpro framework at a point in time before the call of the method that triggers the event.

Advanced Concepts

In the following structure, you will find – irrespective of the structure of the first three sections – a series of self-contained topics that play a role within the framework of Web Dynpro for ABAP. These topics usually become relevant only when your application has reached a certain degree of complexity.

Web Dynpro ABAP: Development in Detail

Advanced Concepts

4.1

May 2006

Working with the Assistance Class

For each Web Dynpro component, you can create a uniquely assigned assistance class. This class should inherit from the abstract class CL_WD_COMPONENT_ASSISTANCE. The assistance class of a component provides the following advantages: ●

You can store coding there that is required within the component, but is not linked directly with the layout or with the function of a controller. This could be, for example, a call of the application layer or UI-based editing of the data. Method calls of the assistance class are much better from a performance point of view than calls of methods of a Web Dynpro controller.

●

The second important function of the assistance class is the management of dynamic texts. Texts that are combined at runtime only and/or contain variables can be stored in the text pool of the assistance class as text symbols.

The assistance class is automatically instantiated when a component is called. The instance is available to each controller of the component through the attribute WD_ASSIST.

Working with Text Symbols in Web Dynpro ABAP The class CL_WD_COMPONENT_ASSISTANCE provides central functions through which a Web Dynpro component can access text symbols of the assistance class. Using the instance attribute WD_ASSIST as well as the method _WD_COMPONENT_ASSISTANCE~GET_TEXT( ), you can access text symbols of the assistance class from within each controller of your component. When the method is called, the three-digit ID of the text symbol is passed to the KEY parameter. method MY_CONTROLLER_METHOD . data: my_text type string. my_text = WD_ASSIST->IF_WD_COMPONENT_ASSISTANCE~GET_TEXT( KEY = ‘001’ ). . . endmethod.

Accessing text symbols from a Web Dynpro component is different from the same procedure in ABAP objects (Text Symbols in General ABAP Programming [externaly]). Maintaining text symbols in the assistance class is possible from each controller. For this purpose, choose the entry Goto->Text Symbols in the menu.

As a rule, every ABAP class can serve as an assistance class; however, the services integrated in the Web Dynpro framework are available only if the assistance class is derived from the class CL_WD_COMPONENT_ASSISTANCE.

Web Dynpro ABAP: Development in Detail

Advanced Concepts

4.2

May 2006

Service Calls in a Web Dynpro Application

Use With the help of the service call function it is possible to call an existing function module from within a Web Dynpro component.

Prerequisites If you wish to use the service call to include an existing function module into your Web Dynpro application, you can access available function modules in the current system.

Features To simplify the creation process, you have an extensive wizard at your disposal. With the help of this wizard, all the required context elements are automatically generated in a controller you have selected. Also, the wizard automatically creates a method in this controller that calls the function modules and ensures parameter transfer. For more information, refer to the chapter Creating Service Calls [page 88]. For information on using service calls, refer to the chapter Using Service Calls [page 89].

4.2.1

Creating a Service Call

To create a service call, you have an easy-to-use wizard at your disposal within the Web Dynpro tools in the ABAP Workbench.

Starting the Wizard To start the wizard, position the cursor on the Web Dynpro component to be edited in the object list at the left margin of the workbench window. Open its context menu by clicking with the right mouse key. From the context menu, choose the entry Create->Service Call. The wizard is started and leads you to the creation process.

Choice of Controller On the second dialog window of the wizard, you can choose whether the service call is to be embedded in an existing controller or whether a new controller is to be created for this purpose. Service calls can only always be embedded in global controllers â&#x20AC;&#x201C; that is, in the component controller or in additionally created custom controllers. It is not possible, on the other hand, to embed service calls in view controllers. If, at this point, you decide on creating a new controller, you enter it in the object node Custom Controllers after you have saved the data. Then the new controller can be used by other controllers of the component [page 58] later on, just like the component controller.

The Required Methods and Context Elements On the two subsequent dialog windows, default values are listed for giving names to the context nodes and attributes required by the service call as well as to the required methods.

Web Dynpro ABAP: Development in Detail

Advanced Concepts

May 2006

The proposed names are based on the names of the embedded service, but you can change them as required. However, heed the respective notes in the corresponding dialog box.

Completing the Choice When you have confirmed the last dialog box, the generation is triggered. Afterwards you now have the required methods and contexts at your disposal for using them within your Web Dynpro component. For more information, refer to the chapter Using Service Calls [page 89].

4.2.2

Using a Service Call

Prerequisites A service call has been created in accordance with the procedure laid out in the previous chapter.

Procedure The use of a service call is in no way different from the use of a manually created method of the controller. The procedure for automatic creation by the wizard creates â&#x20AC;&#x201C; in addition to the required context nodes and attributes â&#x20AC;&#x201C; solely a method in a cross-view controller. This method takes on the job of calling the service. This will be demonstrated here using a simple example:

A Simple Example You wish to read data from a database table and display it in a view with the help of an existing function module. For this purpose, you have created a service call for the function module in your Web Dynpro component. The global controller that you have chosen or created during the creation procedure now contains the required context nodes and attributes as well as a method for calling the function module. global Controller

global Controller Context

Methods

FUNCMODULE1 Attribute_1

Context

Methods

EXECUTE_FUNCMODULE1 WDDO.... WDDO....

Attribute_2

The method EXECUTE_FUNCMODULE1 was already programmed automatically. The function module is now available to the component. Now it is possible to choose a view in order to display the elements of the database table in the browser. Provided the global controller is not the component controller, a use [externaly] of the global controller must be entered for the controller of the selected view. Afterwards, mapping [externaly] of the node FUNCMODUL1 onto the node with the same name in a view controller context is generated.

Web Dynpro ABAP: Development in Detail

Advanced Concepts

May 2006

Controller myFirstView Context

global Controller Context

FUNCMODULE1

Methods

FUNCMODULE1

Attribute_1

Attribute_2

Now, to fill the context node FUNCMODUL1 of the view controller context with the data of the database table, the method EXECUTE_FUNCMODULE1 of the global controller is called it its supply function. For this purpose you must create such a supply function by calling the method EXECUTE_FUNCMODULE1 . (Refer also to the chapter Web Dynpro Code Wizard [externaly], Calling Methods in the Used Controller). Controller of myFirstView: Supply Function of Node FUNCMODULE1 …

call_method EXECUTE_FUNCMODULE1 …

global Controller: Method EXECUTE_FUNCMODULE1 …

call_function ‘FUNCMODULE1‘ …

4.3

Working with Dialog Boxes

Dialog boxes are used to display concrete information or possible settings on a Web Dynpro view. After the dialog has been exited, either the view underneath becomes active again or you can navigate to another screen. There are two different types of dialog boxes:

●

Modal A modal dialog box opens in the current browser window. Each modal dialog box has its own phase model instance [page 35].

●

External An external dialog box is opened in a separate browser window and can be moved around the screen independently of the original window. External dialog boxes are generally modeless.

Web Dynpro ABAP: Development in Detail

Advanced Concepts

May 2006

Calling a Dialog Box ●

Dialog boxes are implemented within a Web Dynpro application via an additional window and are generally called by the event handler of an action (if necessary however, all other methods of the phase model can be used). The component controller contains the interface IF_WD_WINDOW_MANAGER, with which a new window for the content of the dialog box can be created and opened. (During the creation process, a usage of the corresponding component controller is automatically set up for every view controller.) In most cases, you will use a modal dialog box in your application. In your system you will find the detailed example component WDR_TEST_POPUPS_RT_00. It is located in package SWDP_TEST.

The parameter MODAL is no longer used. It is contained in the parameter list for compatibility reasons.

4.3.1

Calling Dialog Boxes of the Same Component

●

If the dialog box that you want to display is connected to the current component by content and was created specifically for this purpose, you should also create the corresponding window in this component.

●

The method CREATE_WINDOW of the interface IF_WD_WINDOW_MANAGER allows you to create a dialog box in an event handler method from a displayed window at runtime. The name of the window to be opened is passed to the CREATE_WINDOW method as a parameter.

method onactionpopup1_1 . data: l_cmp_api l_window_manager

type ref to if_wd_component, type ref to if_wd_window_manager.

l_cmp_api = wd_comp_controller->wd_get_api( ). l_window_manager = l_cmp_api->get_window_manager( ). if wd_this->m_popup1_1 is initial. wd_this->m_popup1_1 = l_window_manager->create_window( window_name = 'POPUP1_1' button_kind = if_wd_window=>co_buttons_yesnocancel message_type = if_wd_window=>co_msg_type_question ). endif. wd_this->m_popup1_1->open( ). endmethod. ●

Note that the CREATE_WINDOW method only creates the new dialog box, it does not open it. To open the dialog box you also need the OPEN method.

The Buttons of the Dialog Box ●

Using the parameter BUTTON_KIND, you specify which buttons should appear in the dialog box. In the example above, the constant CO_BUTTONS_YESNOCANCEL is

Web Dynpro ABAP: Development in Detail

Advanced Concepts

May 2006

set. This constant is of the ABAP Dictionary type WDR_POPUP_BUTTON_KIND, the domain of which has a set of fixed values. The fixed values represent all the meaningful combination possibilities for dialog box buttons, such as OK, OK/Cancel, or Yes/No/Cancel. The default of the constant, an attribute of the interface IF_WD_WINDOW, is the value 5. That means, the combination contains the constants CO_BUTTON_YES, CO_BUTTON_NO, CO_BUTTON_CANCEL, and three buttons will be created in the dialog box, one each for Yes, No, and Cancel.

The Window of the Dialog Box â&#x2014;?

In the hook method WDDOINIT of the view of the dialog box, the button constants are linked to appropriate actions. For this purpose, the interface IF_WD_WINDOW contains the method SUBSCRIBE_TO_BUTTON_EVENT. The actions must be created directly in the dialog box and the automatically created event handler methods must be programmed accordingly.

method wddoinit . data: l_api type ref to if_wd_view_controller, l_window_ctlr type ref to if_wd_window_controller, l_popup type ref to if_wd_window. l_api = wd_this->wd_get_api( ). l_window_ctlr = l_api->get_embedding_window_ctlr( ). if l_window_ctlr is bound. l_popup = l_window_ctlr->get_window( ). if l_popup is bound. l_popup->subscribe_to_button_event( button = if_wd_window=>co_button_yes button_text = 'Yes' "#EC * action_name = 'YES' action_view = l_api is_default_button = abap_true ). l_popup->subscribe_to_button_event( button = if_wd_window=>co_button_no button_text = 'No' "#EC * action_name = 'NO' action_view = l_api is_default_button = abap_true ). l_popup->subscribe_to_button_event( button = if_wd_window=>co_button_cancel button_text = 'Cancel' "#EC * action_name = 'CANCEL' action_view = l_api is_default_button = abap_true ). endif. endif. endmethod. â&#x2014;?

The phase model instance of the dialog box is attached to the same component as the instance of the calling window. For this reason, when the dialog box is opened not only are all the hook methods [page 21] of the view called that are displayed in the dialog box, all the hook methods of the view that are imbedded in the calling window are called as well.

Web Dynpro ABAP: Development in Detail

Advanced Concepts

May 2006

The WDDOONOPEN and WDDOONCLOSE Methods Every window controller has the hook methods WDDOONOPEN and WDDOONCLOSE. These two methods are only processed when a window is opened, or closed, as a dialog box. Since the opening of a dialog box does not involve any navigation, no inbound plug is called and therefore no event handler method is processed. The method WDDOONOPEN can therefore be used to implement initializations.

4.3.2 ●

Calling Dialog Boxes of a Used Component

If the dialog box that you want to display is of a generic nature and can be used in many different components, you create the corresponding window in a separate component, which is then used by the current component. In this case, you create the dialog box at runtime in the current component using the method CREATE_WINDOW_FOR_CMP_USAGE and pass the names of the interface view and the component usage. There must be a component-usage [page 58] entry in the attribute table of the current component for the component to which the dialog box belongs.

● method ONACTIONPOPUP2_1 . data: l_cmp_api l_window_manager

type ref to if_wd_component, type ref to if_wd_window_manager.

l_cmp_api = wd_comp_controller->wd_get_api( ). l_window_manager = l_cmp_api->get_window_manager( ). if wd_this->m_popup2_1 is initial. wd_this->m_popup2_1 = l_window_manager->CREATE_WINDOW_FOR_CMP_USAGE( interface_view_name = 'MAIN' component_usage_name = 'USAGE_POPUP2_1' ). endif. wd_this->m_popup2_1->open( ). endmethod. ●

Setting the Buttons of a Dialog Box of a Used Component Unlike with dialog boxes of the separate component, the buttons of the dialog box that is to be opened cannot be created in one of the methods on the view controller of the calling view as buttons can only be set by the separate component. Dieser Schritt wird bei Dialogfenstern von Components, die zur Verwendung durch andere Components erstellt wurden, in der Hook-Methode WDDOONOPEN an dessen Window-Controller implementiert (see document Calling Dialog Boxes of the Same Component [page 91]). ●

The following source code shows the method WDDOOPEN on the controller of the dialog box:

method wddoonopen . if window_descr->is_popup = abap_true. window_descr->window->set_button_kind( if_wd_window=>co_buttons_yesnocancel ). window_descr->window->set_message_type( if_wd_window=>co_msg_type_question ). endif.

Web Dynpro ABAP: Development in Detail

Advanced Concepts

May 2006

endmethod. ●

If the dialog box is not part of the separate component, but was created in a used component, the phase model instances of the two windows are not attached to the same component either. If the dialog box is open, only the hook methods of the views that are embedded in the dialog box will be processed.

4.3.3

Calling a Confirmation Dialog Box

●

To quickly create dialog boxes of a standardized layout (for example, for the confirmation of changes to current data) you can call the CREATE_POPUP_TO_CONFIRM method of the IF_WD_WINDOW_MANAGER. You do not need to create a separate window for this. The dialog box is created automatically by the runtime.

●

The CREATE_POPUP_TO_CONFIRM method creates an object of the type IF_WD_WINDOW; the dialog box can be created using its parameters.

method onactionpopup4_1 . data: l_cmp_api l_window_manager l_popup l_text l_api

type type type type type

ref to if_wd_component, ref to if_wd_window_manager, ref to if_wd_window, string_table, ref to if_wd_view_controller.

l_cmp_api = wd_comp_controller->wd_get_api( ). l_window_manager = l_cmp_api->get_window_manager( ). insert `Data where changed` into table l_text. "#EC * insert `Do you want to save?` into table l_text.

"#EC *

l_popup = l_window_manager->create_popup_to_confirm( text = l_text button_kind = if_wd_window=>co_buttons_yesnocancel message_type = if_wd_window=>co_msg_type_question window_title = 'Test: Popup to confirm' window_position = if_wd_window=>co_center )."#EC * l_api = wd_this->wd_get_api( ). l_popup->subscribe_to_button_event( button = if_wd_window=>co_button_yes action_name = 'YES' action_view = l_api is_default_button = abap_true ). l_popup->subscribe_to_button_event( button = if_wd_window=>co_button_no action_name = 'NO' action_view = l_api is_default_button = abap_false ). l_popup->subscribe_to_button_event( button = if_wd_window=>co_button_cancel action_name = 'CANCEL' action_view = l_api is_default_button = abap_false ).

Web Dynpro ABAP: Development in Detail

Advanced Concepts

May 2006

l_popup->open( ). endmethod.

The SUBSCRIBE_TO_BUTTON_EVENT method of IF_WD_WINDOW assigns the actions to the appropriate buttons. If you have created a window for the dialog box yourself, the assignment of individual actions to the buttons takes place in the hook method WDDOINIT (see document Calling Dialog Boxes of the Same Component [page 91]). ●

As no explicitly created window exists in this case, the corresponding actions are created in the same view in which the dialog box is called. Assignment using the method SUBSCRIBE_TO_BUTTON_EVENT takes place immediately after the creation of the dialog box in same method.

4.4

Data Binding Concepts

In the basics section of this documentation, the binding of UI element properties to context attributes [page 8] has already been discussed. For a simple application, basically the property value is bound to an attribute to display a value from the context on the screen or to pass a user input to the context. Most of the other properties of a UI element can also be determined statically in the table by specifying a value, and can therefore be manipulated at design time without being bound to a context attribute. One example for this is the enabled property of a button. At design time, you can determine a button to be active all the time by setting the respective tick in the properties table of the button. However, in a larger application it may make sense to vary the state of a number of properties depending on particular conditions. In such a case, you can no longer determine the value of the respective property at design time. The property is then bound to a context attribute that can accept different values at runtime. A button can then be active or inactive, depending on the program conditions. Another example is the visible property. A table can be visible in a particular context while it shall not be displayed in a different context. To support this data binding concept, the Web Dynpro runtime offers a set of special data types.

4.4.1

Data Binding of User Interface Element Properties

The cooperation of UI elements and context elements is made possible by a mutual data binding. The view that contains the UI elements is bound against the context of the controller assigned to it. 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 they 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.

Web Dynpro ABAP: Development in Detail

Advanced Concepts

May 2006

The Web Dynpro Explorer 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: ●

Data binding with identical or convertible data types The type of the context attribute must be compatible to 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.

●

Data binding of UI elements with dynamic or static character, respectively For certain UI element properties it does not make sense to be bound to a related context - for example, properties that have a static character. 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.

●

Data binding of UI elements with a non-scalar character Many properties of UI elements are not of a scalar character but resemble a collection of values. 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.

●

Data binding to a context node There are also properties that refer to an entire 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.

Web Dynpro ABAP: Development in Detail

Advanced Concepts

May 2006

DDIC Binding of UI Element Properties As well as being able to be bound to a context attribute (context binding), some properties of certain UI elements can also be bound to a DDIC data type. For example, the length property of the UI element Inputfield can be bound to either of the following: ●

An attribute of the context of the view

●

A DDIC data type independent of the context attributes

It is thus possible to adapt the length of the input field to the length of the used context attribute or vary it with the length of a DDIC data type. Depending on the individual UI element, DDIC binding is possible for properties connected with field labels and the character length of fields. In the case of the above example of the UI element Inputfield, the properties length and tooltip can be bound to a DDIC data type. You normally choose from the options Short Text, Medium Text, Long Text, and so on.

4.4.2

Data Binding Using Index and Key

For Dropdown listboxes and RadioButtonGroups there are different ways of data binding: data binding using an index (index binding) and data binding using a key (key binding). The names of the UI elements indicate the respective data binding variant. ●

●

Index Binding ○

DropDownByIndex [externaly]

○

RadioButtonGroupByIndex [externaly]

Key Binding ○

DropDownByKey [externaly]

○

RadioButtonGroupByKey [externaly]

Index Binding Index binding is based on multiple nodes. The texts property is bound to an attribute within a context node, which contains several elements (cardinality = 0..n). The number of elements defines the possible entries in the list, and the lead selection defines the selected element; for example, with a RadioButtonGroupByIndex one radio button is displayed for each element. The selected radio button is specified by the lead selection of the context node. If the user selects a different element, the lead selection changes accordingly. It is possible to bind this element in a table. Each instance can then contain a different selected set.

When you toggle the selection, the lead selection is changed. If a singleton node is contained in the selection, it will be invalidated.

Web Dynpro ABAP: Development in Detail

Advanced Concepts

May 2006

For examples, refer to the system in the Web Dynpro component WDR_TEST_EVENTS in the views DropDownByIdx and RadiobtngrpByIdx.

Key Binding With this kind of binding, the values are determined using attribute information in the node information. If the attribute type is a type from the ABAP Dictionary, then the texts are automatically retrieved from the Dictionary, which means that the respective domain values are retrieved from the Dictionary for the display. This is the default. However, it is also possible to determine the value set yourself and to build the list dynamically (see also Fixed Values of Attributes [page 98]): IF_WD_CONTEXT_NODE_INFO=>SET_ATTRIBUTE_VALUE_SET If the data type already has a value set, all you can do is restrict this set. The value of the attribute is the key from the attribute info. The related text (value) is displayed. The value of the attribute changes by selection. Keys and texts (values) are specified for the value set so that the displayed value does not have to correspond to the value in the context (important for translatability). The structure of the value set thus is predefined as a collection of key-value pairs. In contrast to index binding, the UI elements bind against a context attribute and not against an attribute of a multiple node.

Example for data binding where the property of a UI element, which is to display the content, is bound against the attribute. With a RadioButtonGroupByKey the property selectedKey is bound to a context attribute that has a value set, for example, domain values from the ABAP Dictionary. With a RadioButtonGroupByKey one radio button is displayed for every single key. If a radio button is selected, then the related value is returned to the context attribute. For examples, refer to the system in the Web Dynpro component WDR_TEST_EVENTS in the views DropDownByKey and RadiobtngrpByKey. In contrast to index binding, where always different texts are listed in a table column, with this kind of data binding also identical texts can appear in the column.

4.4.3

Fixed Values of Attributes

The limited set of all values allowed for an input field is called fixed values. Some UI elements that accept user input must be supplied with such fixed values depending on the related context. This implies that the attribute, to which the UI element is bound, is assigned to a set of fixed values from which the user selects one as input. The fixed values for these possible input values offered by the context attribute are bound to the UI element property SelectedKey. See also Data Binding Using Index and Key [page 97]. Fixed Values of attributes are needed for the two UI controls ●

DropDownByKey and

●

RadiobuttonGroupByKey.

For the UI element ●

Inputfield

Web Dynpro ABAP: Development in Detail

Advanced Concepts

May 2006

the context attribute to which the element is bound can also be preset with a set of fixed values. These fixed values are then proposed to the user as input by the F4 input help. In addition, the input check then refers to the set of existing fixed values.

Attribute with DDIC Type with Fixed Values If a context attribute is of a DDIC [externaly] type whose Domäne [externaly]already offers Festwerte [externaly], these are automatically stored in the related node info (see below).

Attribute Without DDIC Type with Fixed Values However, if the attribute is not of a DDIC type with fixed values, then you must provide the fixed values in a different way and store them in the node info.

Interface IF_WD_CONTEXT_NODE_INFO The interface IF_WD_CONTEXT_NODE has already been explained in Reference Variable WD_CONTEXT [page 19]. This interface has a method GET_NODE_INFO, which returns meta information on the respective node. This information is of type IF_WD_CONTEXT_NODE_INFO. method WDDOINIT . data:

INFO_NODE type ref to IF_WD_CONTEXT_NODE_INFO.

NODE_INFO = WD_CONTEXT->GET_NODE_INFO( ). NODE_INFO = NODE_INFO->GET_CHILD_NODE( ‘NODE1’ ).

To be able to store the fixed values for the attribute in the node info, two additional variables are necessary: data: LT_VALUESET type WDR_CONTEXT_ATTR_VALUE_LIST L_VALUE type WDR_CONTEXT_ATTR_VALUE.

WDR_CONTEXT_ATTR_VALUE is a data type defined in the DDIC. It contains two components KEY and VALUE, both of type STRING. WDR_CONTEXT_ATTR_VALUE_LIST is a table type stored in the DDIC, whose rows are of type WDR_CONTEXT_ATTR_VALUE. The two variables created in the source text example are used to accept the value pairs that will later be passed to the node info. L_VALUE-VALUE = ‘V1’. L_VALUE-TEXT = ‘yesterday’. INSERT L_VALUE into table LT_VALUESET. L_VALUE-VALUE = ‘V2’. L_VALUE-TEXT = ‘today’. INSERT L_VALUE into table LT_VALUESET. L_VALUE-VALUE = ‘V3’. L_VALUE-TEXT = ‘tomorrow’. INSERT L_VALUE into table LT_VALUESET.

In such an application, the value should be programmed languagedependent.

Web Dynpro ABAP: Development in Detail

Advanced Concepts

May 2006

NODE_INFO->SET_ATTRIBUTE_VALUE_SET ( NAME = ‘ATTRIBUTE1’ VALUE_SET = LT_VALUESET ). endmethod.

Setting these fields applies for all nodes bound to this node info. Also in existing nodes the value set is reset when setting the node info attributes. A manipulation of the node info must not be implemented in a supply function, because the point in time at which the method is called, is not known explicitly. For this reason, always edit the node info using method WDDOINIT. If an attribute is attached to DDIC fixed values, the value list can be changed using the node info. An example would be the additional restriction of the value list.

4.4.4

Context Change Log (Recording User Entries)

In many applications, it is important to mark user entries as such. If, for example, many bound UI elements are displayed in a view, but only one single value changes through a user entry, this can have an unnecessary negative effect on performance – when all the context contents are again processed by the business logic. It is more appropriate to mark the changes that the user has made within the view and to edit them separately. The changes which the user can make include changing the value of an attribute and converting the selection or the lead selection. First of all, each context node provides the option of storing the relevant information for itself. However, so that not all existing context nodes of a controller have to be checked, the Web Dynpro Framework provides the context change log function. Within a controller, all the information on user-based changes to context elements are stored in a single internal table only. The Web Dynrpo runtime has access to this table and can adapt the flow of business logic to the table entries. The table records solely changes made by the user; changes to context elements that were made in the programs (for example, dynamic programming) are not listed. The function of the context change log is switched off in the controller default settings. You may activate it as required. You do this through the IF_WD_CONTEXT interface of the respective controller.

The IF_WD_CONTEXT Interface The IF_WD_CONTEXT interface provides a reference to the controller context. In contrast to the IF_WD_CONTEXT_NODE interface, IF_WD_CONTEXT does not refer to the root node of the context but to the context as a whole. Use the following call to get a reference to IF_WD_CONTEXT: MY_CONTEXT = WD_CONTEXT->GET_CONTEXT( ).

Web Dynpro ABAP: Development in Detail

100

Advanced Concepts

May 2006

The following methods are available with the interface IF_WD_CONTEXT for using the change log function: ENABLE_CONTEXT_CHANGE_LOG( )

Switches on the recording of user entries for this controller.

DISABLE_CONTEXT_CHANGE_LOG( )

Switches the recording off again.

GET_CONTEXT_CHANGE_LOG( and_reset )

Supplies the current content of the change log table and automatically resets this (the latter feature is set as default, but can be switched off as well).

RESET_CONTEXT_CHANGE_LOG( )

Resets the change log table.

ADD_CONTEXT_ATTRIBUTE_CHANGE( )

Using this method, changes to a context attribute can be programmed into the change log table. This is particularly important during programming of input helps since the data selected from the help is not automatically entered into the change log table.

Table of User-Defined Context Changes The table in which the user-defined changes to context are listed is of the type WDR_CONTEXT_CHANGE_LIST. It contains nine columns which have the following meanings: NODE_NAME

Name of the node that contains the change

SEQUENCE

Current number of the entry

NODE

Reference to the node

NODE_PATH

Node path

CHANGE_KIND

Categorizes the type of change ; the constants are available for the values IF_WD_CONTEXT=>CHANGED_*

ELEMENT_INDEX

Index of the context element

ATTRIBUTE_NAME

Name of the attribute that was changed

OLD_VALUE

Reference to the current value

NEW_VALUE

Reference to the new value

With regard to the values in the columns OLD_VALUE und NEW_VALUE, a copy is first made of the old and the new attribute values. A reference to this copy is then stored in the table.

Web Dynpro ABAP: Development in Detail

101

Advanced Concepts

May 2006

Changes in the lead selection are also recorded as changes in the selection. In the case of OVS input help [page 104] or freely programmed input help [page 106], the new value is not entered automatically into the table but must be entered actively using the method ADD_CONTEXT_ATTRIBUTE_CHANGE of the interface IF_WD_CONTEXT â&#x20AC;&#x201C; provided an entry is desired. You will find an example application DEMO_CONTEXT_CHANGES in your system in the package SWDP_DEMO.

4.5

Input Help

In the context of an interactive business application, the input of data by the user is of great importance. In a large number of dialog variants, a valid input represents an element of a limited set of values. A simple example is the short name of an airline carrier, which is frequently used for demonstration purposes: To select an airline, the user enters the two letter ID of the airline into a search mask. The list of valid letter combinations is limited to the number of available airlines; there is a unique assignment. To facilitate the input, it makes sense to offer a list of the available IDs to the user, from which to select the desired one. You can do this by implementing an input help.

Input Help for Web Dynpro for ABAP As the result of such an implementation for the respective input field, the Web Dynpro framework will automatically generate and implement the correct icon for the user to choose at runtime to call the input help. In parallel, the keyboard key F4 is automatically assigned to the call of the input help. The subsequent section of this documentation introduces and explains two pre-implemented input helps that are available in the Web Dynpro for ABAP context. Input Help Based on the Search Help Function of the ABAP Dictionary [page 102] and Object Value Selection Input Help [page 104]. In addition, you can also program your own input help [page 106].

4.5.1

ABAP Dictionary Search Help

In Web Dynpro ABAP you can reuse existing search helps from the ABAP Dictionary. For more information on the classic ABAP search helps see Search Helps [externaly]. In your view you can create input help (F4 help) for fields, which makes it easier for users to input data. A symbol at the end of an input field means that search help is available for that field.

Web Dynpro ABAP: Development in Detail

102

Advanced Concepts

May 2006

The search help symbol is always the same regardless of whether the search help comes from the ABAP Dictionary, is an OVS search help, or a search help created by an application programmer or user.

Example input help of table SPFLI for the input field for an airline:

There are two types of search help: ●

Elementary Search Helps See also Structure of an Elementary Search Help [externaly]

●

Collective Search Help See also Structure of a Collective Search Help [externaly]

For information about the individual steps, input options, and actions see Using ABAP Dictionary Search Helps [externaly].

Integration ABAP Dictionary search helps are integrated using Input Help Mode of the context attributes in a Web Dynpro application. See also Creating and Maintaining Context Attributes [externaly].

Web Dynpro ABAP: Development in Detail

103

Advanced Concepts

May 2006

The context node must have been defined as a dictionary structure. This ensures that all components of the structure are available dynamically at runtime as attributes of the node. Only the options Automatic and Dictionary Search Help are relevant for ABAP Dictionary search help: ●

Automatic The search help assigned to the data type of the context attribute in the ABAP Dictionary is used. Example: the search help SCITAIRP is assigned to the SPFLIAIRPFROM field in the ABAP Dictionary. If the type of context attribute is SPFLIAIRPFROM, the SCITAIRP search help is used. The search help is displayed under Determined Search Help and cannot be changed. The search help displayed for the example here is SCITAIRP. If no search help can be determined for the attribute type, no search help symbol is displayed and no search help can be performed.

●

Dictionary Search Help One search help from the Dictionary can be assigned to the context attribute. Beneath the Input Help Mode field the Dictionary Search Help field appears, in which you can enter the search help you want. The search help must be defined in the ABAP Dictionary. If you do not enter a search help, at runtime the system attempts to determine a search help using the type of context attribute.

Be aware that import and export parameters for the search help are determined only within the same context node (see also Transport of Values for the Input Help [externaly]), and even then only if a Dictionary structure is assigned to the node.

Restrictions ●

The hot key for collective search helps is not supported.

●

Search help exits containing Dynpro-specific functions, for example, CALL SCREEN, are not supported.

Example You can find an example of ABAP Dictionary search help in the system under component WDR_TEST_DDIC_SHLP.

4.5.2

OVS Input Help

A further option for using the F4 input help consists of including OVS input help (OVS stands for Object Value Selection). The OVS input help is provided by a system-side Web Dynpro component that can be used by every application component (you will find more information on the subject Component-Uses [page 58] in the chapter Cross-Component Programming [page 55] in this documentation).

Web Dynpro ABAP: Development in Detail

104

Advanced Concepts

May 2006

After the OVS input help has been entered for a context attribute, it is automatically available for each input field that is bound to this context attribute. At runtime, the OVS component is then automatically instantiated whenever a user presses the F4 button for a selected input field or clicks the input help icon to the right of the input field in question. Also, the creation of the dialog box on the screen takes place automatically at this moment.

The System Component WDR_OVS The component WDR_OVS provides a view in which the search results can be displayed as a table. In addition, the component gets a selection view that can be implemented to restrict the search criteria. Both the input fields of the selection view as well as the structure and the contents of the table of the results view are defined by the application used. Therefore, the OVS component must call back, at a suitable time, into the using component.

Event OVS and Its Parameter OVS_CALLBACK_OBJECT The callback into the using component is implemented through the OVS event at the interface controller of the OVS component. This event is automatically triggered four times, one after the other, and it passes the parameter OVS_CALLBACK_OBJECT of the type IF_WD_OVS to the corresponding event handler in the application component. Through the instance attribute PHASE INDICATOR of the event parameter, the respective phase is transmitted: When this event is first triggered, the attribute has the value CO_PHASE_0; when it is triggered a second time, CO_PHASE_1, and so on. Below, the four target points are described in detail. PHASE_INDICATOR = IF_WD_OVS=>CO_PHASE_0 At this time, the OVS component can be configured. For example, the window title, the heading, or the column heading of the output table can be defined. In addition, you can set whether one or several rows from the event table should be selected. For this purpose, the event parameter OVS_CALLBACK_OBJECT provides the method SET_CONFIGURATION, which can be used solely at this point; calling this method at a later point triggers an error message. PHASE_INDICATOR = IF_WD_OVS=>CO_PHASE_1 If the optional selection view of the OVS component is to be used, the structure of the selection fields to be displayed must be defined in this phase and passed to the OVS component. At the same time, initial values can be passed for the selection fields. The method SET_INPUT_STRUCTURE is provided for this purpose. For this method, too, the following applies: If it is called at a later time, an error message is triggered. If the method is not called at all, the display of the selection view is not used and the event view is displayed immediately. PHASE_INDICATOR = IF_WD_OVS=>CO_PHASE_2 In this phase, the results set from the search must be determined by the component used. If values were entered on a selection view for the selection parameters, these are now available as instance attribute QUERY_PARAMETERS of the event parameter OVS_CALLBACK_OBJECT. In addition, the application component must pass the table with the values available for selection to the OVS component. This is done with the help of the method SET_OUTPUT_TABLE of the event parameter OVS_CALLBACK_OBJECT.

Web Dynpro ABAP: Development in Detail

105

Advanced Concepts

May 2006

Calling SET_OUTPUT_TABLE is mandatory and must take place in this phase. PHASE_INDICATOR = IF_WD_OVS=>CO_PHASE_3 The result of the search was displayed in the results view of the OVS component. The user now has the option of choosing one or several rows of the table. However, the latter is only possible if multiple selection for the results table has been configured in the first phase of the run using the method SET_CONFIGURATION. In the standard configuration of the OVS component, only one row of the results table can be chosen. The content of the chosen line is then available for reading in the instance attribute SELECTION of the result parameter OVS_CALLBACK_OBJECT.

Binding the Value Help to a Context Attribute To bind an OVS value help to a context attribute, the following steps are required: 7. First, you must enter a component use for the OVS component in your application component. 8. Then you must store this use on the tab page Properties in the corresponding view. 9. In the properties table of each single context attribute of the view, you now have the option of selecting the entry Object Value Selector in the row Input Help Mode. In a new table row, you will be requested to enter the component use intended for the input help. You can perform these settings already when you create the attribute. 10. In your application component, an event handler must be stored for the OVS event of the OVS component used.

Context Change Log for OVS Input Help When you work with OVS input help, you can still use the function Context Change Log [page 100]. However, you must observe the following: In the phase PHASE_INDICATOR = IF_WD_OVS=>CO_PHASE_3, the selected data must be entered explicitly in the change log table since this takes places automatically only for user inputs. You will find the necessary information for this in the chapter Context Change Log [page 100] of this documentation. In addition, the package SWDP_DEMO contains an example application in your system, which you can use for orientation when programming your application.

4.5.3

Freely Programmed Input Help

The Framework Web Dynpro for ABAP allows you to create and use your own input help components. A component meant to be an input help must implement the interface IWD_VALUE_HELP (see Working with Web Dynpro Component Interfaces [page 68] in the area Cross-Component Programming [page 55] in this documentation). After the freely programmed value help has been attached to a context attribute, the input help is automatically available for every input field linked with this attribute.

Web Dynpro ABAP: Development in Detail

106

Advanced Concepts

May 2006

Interface IWD_VALUE_HELP When programming with the help of interface IWD_VALUE_HELP, beware of the following: ●

The method SET_VALUE_HELP_LISTENER at the interface controller of IWD_VALUE_HELP may be called only by the Web Dynpro Framework. With the help of this method, the framework passes a callback interface to the input help component. The input help component can use this interface to tell the framework that is shall be closed, for example, if data has been selected, if 'Cancel' has been applied or if an error has occurred. In addition, this interface contains the two attributes F4_CONTEXT_ELEMENT and F4_ATTRIBUTE_INFO. They describe the context element for which the F4 help has been requested.

●

The events VH_WINDOW_CLOSED and VH_WINDOW_OPENED of the component interface may only be triggered by the framework. The events indicate the points in time when the input help window is closed or opened. When implementing the component interface IWD_VALUE_HELP, these events should be copied to the component interface of the input help component to make them available in the calling component and to allow its event handlers to register onto these events.

●

The component interface IWD_VALUE_HELP has the interface view WD_VALUE_HELP. The views to be displayed in the input help window must be embedded into the window WD_VALUE_HELP, which belongs to the interface view.

Attachment to a Context Attribute You attach a freely programmed input help in analogy to the attachment of an OVS input help [page 104] by following these steps: 11. Creating an input help component and implementing the component interface IWD_VALUE_HELP. 12. Creating a component usage for the input help component in your application component. 13. Attaching the component usage to the context attribute. In this case, for the input help mode choose free (either when creating the attribute or later in its properties table) and specify the respective component usage.

Context Change Log for Freely Programmed Input Help When you work with a freely programmed input help, you can still use the function Context Change Log [page 100]. Note, however, that the values selected by the user are not automatically written to the change table; you must program this explcitly (see OVS Input Help [page 104] and Context Change Log [page 100]).

4.6

Messages

In Web Dynpro ABAP you can create and display messages that contain important information for the end user of the Web Dynpro application. Messages are languagedependent texts that are displayed on the screen if, for example, an error occurs when an application is run, or the user has entered data in the wrong format.

Web Dynpro ABAP: Development in Detail

107

Advanced Concepts

May 2006

Example application (WDR_MESSAGE_AREA)

Example application for user input checks (WDR_TEST_INPUT)

For programming these user messages – such as information, error messages, and warnings – the Web Dynpro runtime of the application server ABAP provides a runtime service. The message component is part of every Web Dynpro application and be configured if required in the Settings for a Web Dynpro application. Three settings are possible for handling messages: ●

Show message component if required If messages exist, they are displayed. Example:

●

Always show message component Even if there are no messages, the message component is still displayed in the top view. Example:

Web Dynpro ABAP: Development in Detail

108

Advanced Concepts

●

May 2006

Display messages without the message component Hide message component. Messages are displayed in the earlier way. With this type of message handling only one message is displayed and there is no message log. This option is recommended for smaller test applications only.

User messages are displayed as links in the status bar. The user can then use the link to navigate to the user UI 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 a table. You can assign specific views and windows to messages so that messages that actually belong for instance to the main window are not displayed in a popup. To do this, you can use the optional parameter VIEW in the message manager methods to specify the name of the relevant view or window.

To improve how your application displays messages, check whether it would be useful to include a message in a view or window in certain places, rather than it being displayed in a popup. If you use read-only popups, it may also be useful to suppress the entire message display. The messages are defined at the level of a Web Dynpro component.

The ABAP development tools include a graphics tool for Message Maintenance [externaly].

Messages in Popups The message display in a popup works on demand in the standard configuration, regardless of what is set in the application. Popups can still be configured using an indicator so that they display: ●

All messages as up to now (standard setting)

●

Only those messages that belong to their window, as well as all non-window-specific messages

●

No messages at all.

Basic Functions ●

Display: ○

Current messages from the last user interaction.

○

Last message with the highest weighting at the start of the message log.

○

One counter for new messages and one counter for all messages

○

Symbol for the weighting of each message.

○

Time stamp for all messages.

Web Dynpro ABAP: Development in Detail

109

Advanced Concepts

●

To navigate to the message, the user clicks on the message link.

●

Messages are sorted in a tab strip by:

●

○

Weighting

○

Text

○

Time stamp

May 2006

Input of filter criteria for: ○

Weighting

○

Text

○

Time stamp

●

Reset the entire message log, that is delete the current message log.

●

Show and hide message log. ○

Hide Only the header of the last message and the message counter remains shown.

○

Mapping Table view of the current messages and the total number of messages.

Integration For application development the UI element MessageArea [externaly] is provided for positioning the message display on the screen. The procedure to integrate messages into the message log can be found in Integration [page 110].

Example You can find example applications in the system in components WDR_MESSAGE_AREA and WDR_TEST_INPUT.

4.6.1

Integration of Messages in the Message Log

Messages are integrated into the message log of a component using the Message Manager (interface IF_WD_MESSAGE_MANAGER) . The Message Manager is integrated into the Web Dynpro Code Wizard [externaly]. The following methods are provided for triggering messages: ●

CLEAR_MESSAGES Deletes all messages

●

IS_EMPTY Queries whether there are any messages

●

REPORT_ATTRIBUTE_ERROR_MESSAGE

Web Dynpro ABAP: Development in Detail

110

Advanced Concepts

May 2006

Reports a Web Dynpro exception to a context attribute ●

REPORT_ATTRIBUTE_EXCEPTION Reports a Web Dynpro exception to a context attribute

●

REPORT_ATTRIBUTE_T100_MESSAGE Reports a Web Dynpro exception to a context attribute

●

REPORT_ERROR_MESSAGE Reports a Web Dynpro message with optional parameters

●

REPORT_EXCEPTION Reports a Web Dynpro exception (it may come back)

●

REPORT_FATAL_ERROR_MESSAGE Reports a fatal Web Dynpro message with optional parameters

●

REPORT_FATAL_EXCEPTION Reports a fatal Web Dynpro exception

●

REPORT_SUCCESS Reports a success message

●

REPORT_T100_MESSAGE Reports a message using a T100 entry

●

REPORT_WARNING Reports a warning

Note the RAISE methods in the Message Manager are deprecated. For this reason you should not use it. For the relevant methods you can use the optional parameter VIEW to enter the name of the window or view in which you want to display the message. See also: IF_WD_MESSAGE_MANAGER [externaly]

Example Triggering a T100 Message * get message manager data: L_CURRENT_CONTROLLER type ref to IF_WD_CONTROLLER, L_MESSAGE_MANAGER type ref to IF_WD_MESSAGE_MANAGER. L_CURRENT_CONTROLLER ?= WD_THIS->WD_GET_API( ). call method L_CURRENT_CONTROLLER->GET_MESSAGE_MANAGER receiving MESSAGE_MANAGER = L_MESSAGE_MANAGER . * report message call method L_MESSAGE_MANAGER->REPORT_T100_MESSAGE

Web Dynpro ABAP: Development in Detail

111

Advanced Concepts

* * * * *

May 2006

exporting MSGID =’BC’ MSGNO =’005’ MSGTY =’E’ P1 = P2 = P3 = P4 = MSG_USER_DATA =

4.7

Handling Web Icons

When user interfaces are created for Web applications graphical elements of a fixed size for multiple use are needed, for example for using on buttons or as status icons on screens or in lists. These icons are used as the graphical image of an object or a function. SAP provides predefined Web icons for the standard objects and functions that are used most frequently. The standard symbols are addressed in Web Dynpro normally using symbolic names. The symbolic name always begins with WEBICON_*. You can use this name as the name for the source in the Image [externaly] UI element. Predefined Web Icons Symbolic Name

Visual Display

Description

WEBICON_ATTACHMENT

Attachment

WEBICON_LED_GREEN

Green LED display

WEBICON_LED_YELLOW

Yellow LED display

WEBICON_LED_RED

Red LED display

WEBICON_LED_INACTIVE

Inactive LED display

WEBICON_POSITIVE

Positive

WEBICON_NEGATIVE

Negative

WEBICON_CHECKED

Selected, OK

WEBICON_CRITICAL

Critical

WEBICON_FAILURE

Failed function

WEBICON_LOCKED

Locked

WEBICON_UNLOCKED

Unlocked

WEBICON_LOCKED_BY_ME

Locked by me

Web Dynpro ABAP: Development in Detail

112

Advanced Concepts

May 2006

WEBICON_CHECKED_OUT

Checked out

WEBICON_CHECKED_OUT_BY_ME

Checked out by me

WEBICON_ALERT

Caution

WEBICON_WARNING

Warning

WEBICON_HINT

Note

WEBICON_STATUS_OPEN

Open

WEBICON_STATUS_BOOKED

Booked

WEBICON_STATUS_PARTLY_BOOKED

Partly booked

WEBICON_STATUS_CANCELLED

Cancelled

WEBICON_TREND_CONSTANT

Constant trend

WEBICON_TREND_INCREASING

Trend increasing

WEBICON_TREND_DECREASING

Trend decreasing

WEBICON_TREND_UP

Trend strongly increasing

WEBICON_TREND_DOWN

Trend strongly decreasing

WEBICON_DUPLICATE

Duplicate entry

WEBICON_WRONG_REFERENCE

Incorrect reference

WEBICON_WAITING_FOR_APPROVAL

Waiting for approval

WEBICON_MISSING_GOODS_RECEIP T

Missing good receipt

WEBICON_MISSING_INFORMATION

Missing information

WEBICON_PRICE_VARIANCE

Price variance

WEBICON_QUANTITY_VARIANCE

Quantity variance

Note that except for /path (see table) no relative paths are supported, that is no input in form ./path or ../path. Supported URL Formats Format

Description

Ttranslation in

WEBICON_<NAME>

Format of the new predefined Web icons

Uppercase letters

Web Dynpro ABAP: Development in Detail

113

Advanced Concepts

May 2006

ICON_<NAME>

Format of older SAP icons See also NAME column of table ICON.

Uppercase letters

$NAME$ or $NAME$/path

$NAME$ refers to an entry in transaction SM59 for an HTTP connection (type G). If a path is specified, it is attached to the path prefix already defined. This is the only way absolute URLs can be used.

$NAME$ sequence in upper case letters, /path in lower case letters

/path

Relative path details from a server to a MIME Repository [externaly] entry. This entry begins with the root of the MIME repository. The URL is always loaded by the active server. If the path is a Web Dynpro path, its name is converted to an icon. Otherwise no checks to ensure the validity of the URL can be made.

Lowercase letters

image.ext or folder/image.ext

Loads an image from the MIME folder of the active component. This is the short form of the following format.

{/NAMESPACE/COMPONEN T}/image.ext or {/NAMESPACE/COMPONENT }/folder/image.ext

The image is specified relative to another component. This means that the image is stored in the MIME folder of the component in question. For components within the SAP namespace the /NAMESPACE/-sequence is not specified.

[WWWDATA]/objectName

Loads an image from the SAP Web repository of ITS.

4.8

Namespace and component in upper case, path in lower case.

File Export

Use You can export files in accordance with the FileDownload [externaly] functionality, thereby fulfilling the usual security requirements. This download functionality is available in every action handler, for example, when clicking a Button, a LinkToAction or (what you should not do) when switching a TabStrip or clicking a RadioButton. When the user clicks the respective UI element, a binary data stream is generated. For this data stream, the appropriate URL is generated and the result is displayed in a separate browser window.

Web Dynpro ABAP: Development in Detail

114

Advanced Concepts

May 2006

Features For both cases, whether to export a single file or several files, the same ways of displaying and storing the file(s) exist: ●

Display in the same window Example:

●

Save query in the same window Example:

●

Display in a separate window

●

Save query in a separate window

With the MS Internet Explorer, the Save query for several files does work only with the external window. Therefore, simultaneously downloading several files is always done via external windows.

Activities Use the method ATTACH_FILE_TO_RESPONSE of class CL_WD_RUNTIME_SERVICES for the file export.

Example For an example for the file export via a button, see the component WDR_TEST_EVENTS in the view Button. The area to the right contains the test example for all eight cases in the bottom group.

Web Dynpro ABAP: Development in Detail

115

Advanced Concepts

4.9

May 2006

Portal Integration

Web Dynpro ABAP applications can be integrated into the SAP Enterprise portal – that is, they can be bound into a portal navigation as an iView. For a description of the individual steps for integrating a Web Dynpro application, see the chapter Portal Binding: Prerequisites [page 117]. The description given in this programming manual for binding a Web Dynpro application into a portal is written for the developers of applications and is suitable for binding individual applications for test purposes. For more detailed information, refer to the appropriate sections in the Portal documentation [externaly]. In addition, it is possible to address portal functions from within a Web Dynpro application. For this purpose, you can access portal manager methods (interface IF_WD_PORTAL_INTEGRATION) as source code templates for the different functions by calling up the Web Dynpro Code Wizard [externaly]. These include: ●

Using Portal Events [page 120]

●

Navigation [page 123] between Web Dynpro applications within the portal or to any other portal content. The following navigation types are supported:

Objekt...

Object-Based Navigation [page 124] Absolute Navigation [page 126] Relative Navigation [page 129] ●

Using the WorkProtect [page 131] mode

Examples The following examples of Web Dynpro applications for portal integration are available in the package SWDP_TEST in the system: ●

WDR_TEST_PORTAL_EVENT_FIRE Trigger event

●

WDR_TEST_PORTAL_EVENT_FIRE2 Trigger free event

●

WDR_TEST_PORTAL_EVENT_REC Receive portal event

●

WDR_TEST_PORTAL_EVENT_REC2 Receive free portal event

●

WDR_TEST_PORTAL_NAV_OBN Object-based navigation

●

WDR_TEST_PORTAL_NAV_PAGE Page navigation

●

WDR_TEST_PORTAL_WORKPROTECT Security monitoring

Web Dynpro ABAP: Development in Detail

116

Advanced Concepts

4.9.1

May 2006

Binding to Portal: Prerequisites

To be able to integrate a Web Dynpro application, the following prerequisites must be fulfilled.

●

You yourself have a user in the portal to which a suitable role is assigned. The role Content Admin [externaly], for example, contains all the required authorizations and tools. This should always be the case; if not, contact your portal administrator.

●

The ABAP system in which the application is located must be known to the portal. This, too, should be the case already. Since a special authorization is required for entering the system data [externaly], contact your portal administrator to have the ABAP system entered, if necessary. (Documentation about registering the system is available under Editing SAP System Properties [externaly]). During the following steps, you will need the system alias [externaly] of the ABAP system that was assigned by the portal administrator in the portal concerned. For more information on the different roles [externaly] and the task areas involved, refer to the chapter Administration Guide for the Portal [externaly].

●

To test the application afterwards, you must – of course – also have a user in the ABAP system. Using user mappings [externaly], you can link your portal user with the ABAP system user in order to avoid a separate logon when calling the application.

As soon as these technical prerequisites are fulfilled, log on to the portal and choose the function Content Administration in the initial navigation screen [externaly]. For a description of the following steps, refer to the document Binding the Application into a Portal [page 117].

4.9.2

Integrating an Application in the Portal

In the navigation panel on the Portal homepage, goto Content Administration [externaly] and open the folder portal_content.

You can create your application in any folder or insert a separate folder for your application. 14. Right-click the portal_content folder and choose New → iView.

Web Dynpro ABAP: Development in Detail

117

Advanced Concepts

May 2006

15. The iView wizard opens. Select the source application type and choose Next. To integrate a Web Dynpro ABAP application, choose iView template.

16. From the list choose SAP Web Dynpro iView followed by Next.

17. Enter a name for your application and choose Next.

18. Specify the type, since you want to integrate an ABAP application.

Web Dynpro ABAP: Development in Detail

118

Advanced Concepts

May 2006

Enter the System Alias [externaly] and specify the namespace and name of the application. The namespace is sap. You can find the application name in the ABAP system.

19. Choose Next and then Finish. Now the application is ready to start.

Additional Settings You can also make further settings for your application.

Size Open the iView and choose Appearance â&#x2020;&#x2019; Size from the dropdown list box. The standard size of iViews is 80 pixels. This is not large enough for complex applications. Therefore, change the size to Automatic or Full Height, or increase the number of pixels.

Displaying the iView The iView has now been created, but you can only display it after setting up the access. Since all applications in the Portal are provided via Portal Pages [externaly], you will generally have to assign the new iView to a page first. This page is in turn assigned to a role and is called via the role. However, provided the application is to be called only for test purposes by developer himself, the iView can also be assigned to a corresponding test role. Carry out the following steps to assign the iView to a role. a. Open the role by right-clicking and select the folder in the role you want to assign the iView to. b. Find the iView in the portal content on the right-hand side.

Web Dynpro ABAP: Development in Detail

119

Advanced Concepts

May 2006

c. Right-click to add the iView to the role as a delta link. d. Now your iView will appear in the menu structure.

4.9.3

Portal Events

In the SAP Enterprise Portal, you can process different application types in special iViews on the same portal page. Here, iViews can be included using different technologies (such as Web Dynpro ABAP, Java, or BSP). The communication between these iViews takes place through an event function – portal eventing (or client-side eventing). A Web Dynpro ABAP application can be registered [page 122] for portal events. In this way, the Web Dynpro application can react to an event that was triggered in another iView in the portal. Therefore, it does not matter what technique you used to set up the application that is the basis for the other iView. The assignment as to which event handler is to be called when this event occurs is stored In the Web Dynpro application that has registered itself on the portal event. Similarly to registration, a Web Dynpro application can trigger [page 120] any portal event. In this case, the event is passed to the portal by the respective iView. The portal passes the event to all iViews that have registered for this event. The application that finally handles this event can, in turn, have been set up with a different technique than the Web Dynpro application triggering it.

Portal eventing functions only between iViews that are on the same browser window. Events between iViews in different browser windows cannot be transported. All participating iViews must also belong to the same domain. Otherwise portal eventing cannot work due to JavaScript restrictions.

4.9.3.1

Triggering a Portal Event

A portal event is an event that is triggered within an iView – in this case, within a Web Dynpro application – and is then passed by the portal to one or several other iViews. The portal passes the event to all iViews that have registered for this event. In this way, events can be transported between several iViews based on different development techniques. Portal eventing functions only between iViews that are on the same browser window. Events between iViews in different browser windows cannot be transported. All participating events must also belong to the same domain. Otherwise portal eventing cannot work due to JavaScript restrictions. In Web Dynpro ABAP, the Portal-Manager (interface IF_WD_PORTAL_INTEGRATION [externaly]) provides the FIRE method. Using the Web Dynpro Code Wizard [externaly], you can insert this method call as a template into your source code and fill it with values in accordance with the requirements of your application. method ONACTIONFIRE_PORTAL_EVENT .

Web Dynpro ABAP: Development in Detail

120

Advanced Concepts

May 2006

. . . data: L_API_COMPONENT type ref to IF_WD_COMPONENT, L_PORTAL_MANAGER type ref to IF_WD_PORTAL_INTEGRATION. L_API_COMPONENT = WD_COMP_CONTROLLER->WD_GET_API( ). L_PORTAL_MANAGER = L_API_COMPONENT->GET_PORTAL_MANAGER( ). L_PORTAL_MANAGER->FIRE( PORTAL_EVENT_NAMESPACE = 'my_namespace_for_Web_Dynpro_documentation' PORTAL_EVENT_NAME = 'showCustomer' PORTAL_EVENT_PARAMETER = CUSTOM_ID ). endmethod.

In addition to the mandatory parameters Namespace and Name, you can also pass on another parameter: Namespace in which the event is stored

’PORTAL_EVENT_NAMESPACE’

Name of the event

’PORTAL_EVENT_NAME’

Parameter

’PORTAL_EVENT_PARAMETER’

You can trigger such a portal event from anywhere in your Web Dynpro application. The event is sent with the next response to the client. You can even trigger several portal events in one request-response cycle. However, it is usual to trigger a portal event in an action handler of a Web Dynpro application. This could be the case, for example, with an action handler of a UI element (for example, a button). When a portal event is triggered, an internal application event is first passed from the iView to the portal and can e handled within one or several other iViews.

Syntax for Namespace and Names of Events The characters permitted for the namespace and event name are restricted to the namespaces of the SAP Enterprise Portal – Client Framework. You can only use the characters listed in the table below. Valid Characters Uppercase letters

"A" - "Z"

Lowercase letters

"a" - "z"

Numbers

"0" - "9"

Special character

"-" "_" "."

Also note that: ●

The namespace must begin with the character string urn:

●

Namespaces com.sapportals.portal.* and com.sapportals.* are reserved for SAP, and therefore you should not use them for your applications.

●

Note that the namespace and the name are case-sensitive.

Web Dynpro ABAP: Development in Detail

121

Advanced Concepts

May 2006

urn:com.sap.webdynpro.testApplications.testEvent

Example ●

You can find examples in the system under the Web Dynpro applications: WDR_TEST_PORTAL_EVENT_FIRE Trigger Event

●

WDR_TEST_PORTAL_EVENT_FIRE2 This application serves as a test application. You can enter the name of an event from your own application in order to test the event separately.

4.9.3.2

Registering and Handling an Event

Registration for a Portal Event To register your Web Dynpro application for a portal event, you have the method SUBSCRIE_EVENT available in the interface IF_WD_PORTAL_INTEGRATION [externaly]. To delete your registration for the portal event, use the method UNSUBSCRIBE_EVENT in the portal manager. Registration or deletion of registration must be performed individually for each view in the respective method WDDOINIT. Generate yourself a suitable template using the Web Dynpro Code Wizard [externaly]. You can then fill this with values. method WDDOINIT . data: L_API_COMPONENT type ref to IF_WD_COMPONENT, L_PORTAL_MANAGER type ref to IF_WD_PORTAL_INTEGRATION, VIEW type ref to IF_WD_VIEW_CONTROLLER. L_API_COMPONENT = WD_COMP_CONTROLLER->WD_GET_API( ). L_PORTAL_MANAGER = L_API_COMPONENT->GET_PORTAL_MANAGER( ). VIEW ?= WD_THIS->WD_GET_API( ). L_PORTAL_MANAGER->SUBSCRIBE_EVENT( PORTAL_EVENT_NAMESPACE = 'my_namespace_for_Web_Dynpro_documentation' PORTAL_EVENT_NAME = 'showCustomer' VIEW = VIEW ACTION = 'RECIEVE_CUSTOMER_ID' ). endmethod.

Enter the namespace and the name of the event. The combination of namespace and event name must be unique. In addition, enter the name of the action that is to be triggered if

Web Dynpro ABAP: Development in Detail

122

Advanced Concepts

May 2006

exactly this portal event is to be received. The corresponding action handler is then called automatically. The action, in this case RECEIVE_CUSTOMER_ID, is not created automatically. Therefore, create the action explicitly on the tab page Actions in the view.

Handling a Portal Event The parameters of a portal event are passed to the action parameter WDEVENT using its method GET_STRING. With the help of the optional parameter PORTAL_EVENT_PARAMETER, you can have application-dependent information passed to the handler method. In the following example, this is the ID of a particular customer whose value is passed to the SHOWCUSTOMER method of the component controller called afterwards. method ONACTIONRECIEVE_CUSTOMER_ID . data: EVT_NAME type STRING, CUST_ID type SCUSTOM-ID. EVT_NAME = WDEVENT->GET_STRING( NAME = 'PORTAL_EVENT_NAME' ). if EVT_NAME = 'showCustomer'. CUST_ID = WDEVENT->GET_STRING( NAME = 'PORTAL_EVENT_PARAMETER' ). WD_COMP_CONTROLLER->SHOWCUSTOMER( CUSTOMER_ID = CUST_ID ). endif. endmethod.

Example You can find examples in the Web Dynpro applications in the system: ●

WDR_TEST_PORTAL_EVENT_REC Receive portal event

●

WDR_TEST_PORTAL_EVENT_REC2 This application also serves as a test application. You can enter the name of an event from your own application in order to test the event separately.

4.9.4

Portal Navigation

The SAP Enterprise Portal supports navigation between various types of portal content. For example, a Web Dynpro application can navigate to the portal content as well as to another Web Dynpro application that is set up differently. Portal content can be, for example, a BSP or an ITS application. As well as being object-based [page 124], page navigation can be absolute [page 126] or relative [page 129].

Web Dynpro ABAP: Development in Detail

123

Advanced Concepts

4.9.4.1

May 2006

Object-Based Navigation (OBN)

The structure of SAP Enterprise Portal content is based on roles. You can browse through the user-specific navigation structures using the top-level navigation and the detailed navigation. Portal navigation allows you to navigate between different iViews or pages in any application running as a portal content (that is, any page or iView). In many cases it is sufficient to use either relative or absolute navigation to navigate to a specific iView or page. However, sometimes more flexibility is required. For this purpose, you have Object-Based Navigation [externaly], which allows you to define navigation steps at a higher semantic level. Instead of defining a concrete target URL, you call a particular operation of a particular business-object [externaly]. You configure in the portal which concrete iView (or which page) is to be used for executing this operation. This configuration can be role-specific or user-specific. The Web Dynpro application itself passes on solely the name of the business object and the operations linked to it. In Web Dynpro for ABAP, the integration of object-based navigation is very similar to the integration of portal eventing [page 120]. To trigger the navigation itself, the Web Dynpro Framework provides a service that can be called from the application. This service, like Portal Eventing, is part of the portal manager.

Triggering Object-Based Navigation You can activate object-based navigation of the portal in Web Dynpro ABAP by calling the method NAVIGATE_TO_OBJECT of the portal manager (interface IF_WD_PORTAL_INTEGRATION [externaly]). You can generate an appropriate template using the Web Dynpro Code Wizard [externaly], in which you then enter values. data LR_COMPONENTCONTROLLER type ref to IG_COMPONENTCONTROLLER . data L_API_COMPONENTCONTROLLER type ref to IF_WD_COMPONENT. data LR_PORT_MANAGER type ref to IF_WD_PORTAL_INTEGRATION. LR_COMPONENTCONTROLLER =

WD_THIS->GET_COMPONENTCONTROLLER_CTR( ).

L_API_COMPONENTCONTROLLER = LR_COMPONENTCONTROLLER->WD_GET_API( ). LR_PORT_MANAGER = L_API_COMPONENTCONTROLLER->GET_PORTAL_MANAGER( ). call method LR_PORT_MANAGER->NAVIGATE_TO_OBJECT exporting SYSTEM

= NAVIGATION_DATA-SYSTEM

OBJECT_TYPE

= NAVIGATION_DATA-OBJECT

OPERATION

= NAVIGATION_DATA-OPERATION

OBJECT_VALUE_NAME

= NAVIGATION_DATA-OBJECT_VALUE_NAME

OBJECT_VALUE

= NAVIGATION_DATA-OBJECT_VALUE

BUSINESS_PARAMETERS

= BUS_PARAMETER_LIST

FORWARD_OBN_METADATA

= NAVIGATION_DATA-FORWARD_OBN_METADATA.

Web Dynpro ABAP: Development in Detail

124

Advanced Concepts

May 2006

Only two parameters are required for the navigation: ●

SYSTEM Specify the system (or the system alias) the business object is assigned to.

●

OBJECT_TYPE Specify the business object you are using.

All other parameters are optional. ●

OBJECT_VALUE Usually there are many different instances of a business object – for example, for the business object Customer. You use this parameter to specify which specific customer (for instance, use the customer number) you want to use for the object-based navigation step.

●

OPERATION You use this parameter to specify which operation is to be used for the object-based navigation step.

●

OBEJCT_VALUE_NAME The specified object value is transferred as a URL parameter to the OBN step. The standard name of this parameter is ObjectValue. You can change this name if you want.

●

BUSINESS_PARAMETERS As well as specifying the object value you can define other parameters that are to be forwarded by the OBN step. An example of a parameter string you could define is: Mode=Edit&ShowHeader=false. These parameters can be used by the target of the OBN if the operation of the business object has been prepared accordingly (see below under the section Maintaining the Target Application in the Portal.

●

FORWARD_OBN_METADATA Sometimes it is useful for the OBN target to receive more details about the current navigation step. For instance, if you implement an application that serves for implementing different operations performed on a business object, the application must know which operation was triggered by the OBN step. Therefore, you can pass on the following parameters: ○

obn.system The system the business object is assigned to.

○

obn.bo_type The business object itself

○

obn.operation The respective operation If the default operation is used, the value is _default_.

Web Dynpro ABAP: Development in Detail

125

Advanced Concepts

May 2006

Maintaining the Target Application in the Portal The target application is maintained in the portal for the respective operation of the business object. This is usually done in by the portal administrator. To be able to transport the business parameters correctly from a Web Dynpro ABAP application to the target application, the following JavaScript must be stored at the target application under Object-Based Navigation: return 'DynamicParameter=' + objValue;

Example You can find an example in the system in the Web Dynpro application, WDR_TEST_PORTAL_NAV_OBN.

Role-Based Authorization Check Execution of the navigation is thus dependent on the customizing for the role settings in the portal. For example, the user of a role could have the authorization for displaying and editing the content of a page, while the users of another role might only be allowed to display the content. If a user triggers object-based navigation, but does not belong to a role that has authorization for the respective operation, an appropriate error message will appear. So as to make the user interface as user-friendly as possible, it is a good idea – from the very start – not to provide this operation for the user in question. For this purpose, however, the information for the authorization of the respective operation must be got by the portal. This can be done with the help of a Web service that is called from the Web Dynpro ABAP application using the class CL_WDR_PORTAL_OBNWEB_SERVICE [externaly].

4.9.4.2

Absolute Navigation

You can activate absolute path navigation for the portal in Web Dynpro ABAP using the portal manager (interface IF_WD_PORTAL_INTEGRATION [externaly], method NAVIGATE_ABSOLUTE). You can generate a template using the wizard, in which you then enter values. With the absolute navigation tool, you must know the name of the page to be displayed in order to pass it to the method. data LR_COMPONENTCONTROLLER type ref to IG_COMPONENTCONTROLLER . data L_API_COMPONENTCONTROLLER type ref to IF_WD_COMPONENT. data LR_PORT_MANAGER type ref to IF_WD_PORTAL_INTEGRATION. LR_COMPONENTCONTROLLER =

WD_THIS->GET_COMPONENTCONTROLLER_CTR( ).

L_API_COMPONENTCONTROLLER = LR_COMPONENTCONTROLLER->WD_GET_API( ). LR_PORT_MANAGER = L_API_COMPONENTCONTROLLER->GET_PORTAL_MANAGER( ). call method LR_PORT_MANAGER->NAVIGATE_ABSOLUTE

Web Dynpro ABAP: Development in Detail

126

Advanced Concepts

May 2006

exporting NAVIGATION_TARGET

= NAVIGATION_DATA-TARGET

NAVIGATION_MODE

= NAVIGATION_DATA-NAVIGATION_MODE

WINDOW_FEATURES

= NAVIGATION_DATA-WINDOW_FEATURES

WINDOW_NAME

= NAVIGATION_DATA-WINDOW_NAME

HISTORY_MODE

= NAVIGATION_DATA-HISTORY_MODE

TARGET_TITLE

= NAVIGATION_DATA-TARGET_TITLE

CONTEXT_URL

= NAVIGATION_DATA-CONTEXT_URL

POST_PARAMETERS

= ABAP_FALSE

USE_SAP_LAUNCHER

= ABAP_TRUE

BUSINESS_PARAMETERS

= BUS_PARAMETER_LIST

LAUNCHER_PARAMETERS

= LAUNCHER_PARAMETER_LIST.

The navigation target is the only parameter required here. It stands for an absolute address in the portal. The other parameters are used for controlling the navigation and are optional. You can set business parameters and parameters for the respective application launcher in the portal. To transport business parameters correctly to the target application, you have to set the parameter USE_SAP_LAUNCHER. If it is an SAP application (for example, BSP Web Dynpro, and so on), you have to set the switch to TRUE. Overview of Parameters Name

Opti onal

NAVIGATI ON_TARG ET

NAVIGATI ON_MODE

WINDOW_ FEATURE S

√

Possible values

Description

Address, for example ROLES://portal_content/

Absolute address, path f in the portal content dire

web_dynpro_abap/ web_dynpro_abap_tester/ portal_integration/ portalNavigation/ portal_navigation_target

This path is displayed in catalog – for instance, w page or an iView.

″INPLACE″

Displays the navigation target on the same page

Navigation mode

″EXTERNAL″

Displays the navigation target on a new page, but only as an iView, without the portal

″EXTERNAL_PORTAL″

Displays the navigation target on a new portal page.

″TOOLBAR″

Displays the standard toolbar

″LOCATION″

Displays the Web address

″DIRECTORIES″

Displays the directory buttons of the browser

Web Dynpro ABAP: Development in Detail

Additional JavaScript pa external window – for ex character set or size spe as width=300 or he

These parameters are se

127

Advanced Concepts

May 2006

″STATUS″

Displays the status bar

″MENUBAR″

Displays the menu bar of the browser

″SCROLLBARS″

Displays the scroll bar

″RESIZABLE″

Windows can be resized

″WIDTH″

Width of the window

″HEIGTH″

Height of the window

WINDOW_ NAME

√

String

HISTORY_ MODE

√

″ALLOW_DUPLICATIONS″

A navigation entry can be listed more than once in the history.

″NO_DUPLICATIONS″

A navigation entry can be listed only once in the history.

″NO_HISTORY″

No navigation entry in the history

commas. Spaces are no

Title of the target page in browser. The specified W loaded into a window of instance, MyWindowNam used to access the addre

Specifies whether the vis address should be listed navigation history.

TARGET_ TITLE

√

String

Title of the portal page

CONTEXT _URL

√

String

Determines the navigatio

POST_PA RAMETER S

√

″TRUE″

Transfer parameters as a POST request

“FALSE” (default value)

Transfer parameters as a GET request

USE_SAP _LAUNCH ER

BUSINESS _PARAME TERS

√

“TRUE” (default value)

Target is called using the SAP launcher – for example, BSP

″FALSE″

Target is not called using the SAP launcher

See structure WDR_NAME_VALUE_LIST with name and value pairs

Transfer options for para

SAP launcher is used

Transfer parameters for target application (Web D Web application), for exa customer number. These are transferred by URL.

See also URL Paramete

Keep in mind the transfe

Web Dynpro ABAP: Development in Detail

128

Advanced Concepts

May 2006

for example, a paramete larger than 1 KB. LAUNCHE R_PARAM ETERS

√

See structure WDR_NAME_VALUE_LIST with name and value pairs

Parameter list for the ap launcher, parameter list

WebDynproNamesp space

If you define BUSINESS_PARAMETERS as application parameters in your Web Dynpro application and the parameter names start with ″APP″, they will automatically be forwarded to the startup plugs of the Web Dynpro application – provided they are marked as startup parameters. In this case, keep in mind that the iView/page used as the navigation target must be assigned to the user role. If it is not, navigation cannot be triggered.

Example You can find an example in the system in the Web Dynpro application, WDR_TEST_PORTAL_NAV_PAGE.

4.9.4.3

Relative Navigation

The relative path navigation variant can be used, for example, for delivering content across several directories. To activate relative path navigation for the portal in Web Dynpro ABAP, use the portal manager (IF_WD_PORTAL_INTEGRATION [externaly], method NAVIGATE_RELATIVE). You can generate a template using the wizard [externaly], in which you then enter values. call method LR_PORT_MANAGER->NAVIGATE_RELATIVE exporting BASE_URL

= NAVIGATION_DATA-BASE_URL

LEVELS_UP

= LEVELS_UP

PATH

= PATHLIST

NAVIGATION_MODE

= NAVIGATION_DATA-NAVIGATION_MODE

WINDOW_FEATURES

= NAVIGATION_DATA-WINDOW_FEATURES

WINDOW_NAME

= NAVIGATION_DATA-WINDOW_NAME

HISTORY_MODE

= NAVIGATION_DATA-HISTORY_MODE

TARGET_TITLE

= NAVIGATION_DATA-TARGET_TITLE

CONTEXT_URL

= NAVIGATION_DATA-CONTEXT_URL

USE_SAP_LAUNCHER

= ABAP_TRUE

BUSINESS_PARAMETERS = BUS_PARAMETER_LIST

Web Dynpro ABAP: Development in Detail

129

Advanced Concepts

May 2006

LAUNCHER_PARAMETERS = LAUNCHER_PARAMETER_LIST. Relative navigation can be used from the defined starting point. Overview of Parameters Name

Optional

Possible values

Description

BASE_URL

â&#x2C6;&#x161;

Path name

Starting point for relative navigation

LEVELS_UP

Numeric value

Number of navigation steps upwards in the navigation structure

PATH

Path name

Relative path list for the target application

You use the remaining parameters in the same way as for Absolute Navigation [page 126]. BASE_URL :

pcd:role1/folder1/folder2/fodler3/workset1/page1 LEVELS_UP: 3 PATHLIST: folder4/workset2/page2 The target is:

pcd:role1/folder1/folder2/folder4/workset2/page2 The BASE_URL does not have to be specified. If it is not, the current URL is used. PATH is a list of the nearest nodes. In this case, these would be:

folder4 workset2 page2 Example You can find an example in the system in the Web Dynpro application WDR_TEST_PORTAL_NAV_PAGE.

4.9.4.4

Resume Plugs and Portal Navigation

For every interface view, you can flag exactly one inbound plug as a resume plug. When navigating in the portal, the existence of a resume plug results in the following behavior: If the Portal Navigation [page 123] recognizes such a plug in the running application, the latter is not exited when navigating away but is instead transferred to a suspend mode. The session ID and contents of the context are retained and a new application is started. If a user then goes back to the original application via the navigation menu of the portal, it can be processed in exactly the same state in which it was left. Note the following: If an application features a resume plug, the corresponding session is retained when navigating away in the portal. However, in many cases it may be

Web Dynpro ABAP: Development in Detail

130

Advanced Concepts

May 2006

sensible or even absolutely necessary to close the application completely. In such cases, you must not implement a resume plug for the interface view.

Method WDDOAPPLICATIONSTATECHANGE The method WDDOAPPLICATIONSTATECHANGE is a method of the component controller. It is processed whenever the status of an application changes – that is, precisely when the application is transferred from running to suspend mode and when it is subsequently restarted via the resume plug. This method thus replaces the WDDOEXIT method in the phase model. Application development can – but does not have to – add code to the method WDDOAPPLICATIONSTATECHANGE. However it can be useful, for example, to delete database locks in this method that are not be in place during the resume state. While your applications are running within a portal, the portal navigation takes care of the suspend step without you having to implement it at design time. The mere existence of a resume plug ensures that an application is only interrupted and not exited in the case of a portal navigation. However, this does not take place if the application is not running in the portal and can thus not make use of the portal navigation mechanism.

Resume and Suspend Plugs Outside the Portal If you want to interrupt an application and retain the session in the context of a pure Web Dynpro navigation, you must create a suspend plug for the interface view of the relevant window and fire it at an appropriate time. Every interface view can have several outbound plugs flagged as suspend plugs. Firing a suspend outbound plug also results in the method WDDOAPPLICATIONSTATECHANGE being called instead of WDDOEXIT. The URL of the suspended application is automatically passed to the subsequent application, so that it is possible to navigate back to the original application.

If an outbound plug is flagged as a suspend flag in a Web Dynpro ABAP application, this can lead to errors when the application is executed in the portal. If you are not completely sure that your application is executed solely outside a portal, you should avoid the use of suspend plugs.

4.9.5

Work Protect Mode

The work protect mode provides the infrastructure for handling unsaved data in SAP Enterprise Portal. An application is called “dirty” if the entered data has not yet been saved. Normally data is lost when the user navigates to another application without having first saved the data. To prevent this from happening, the client framework of the portal monitors the current status of all the applications in the portal.

Web Dynpro ABAP: Development in Detail

131

Advanced Concepts

May 2006

Example of dialog box showing the work protect mode:

The application must define a special status (dirty flag), which tells the portal when there is unsaved data. You can set and cancel this status (TRUE, FALSE) using method SET_APPLICATION_DIRTY_FLAG in interface IF_WD_PORTAL_INTEGRATION. If the dirty flag is set to TRUE, each navigation step is automatically executed in a new window. The unsaved data is retained in the original window. This means the user can switch to the original application and save the data afterwards. The following source text shows how to set the dirty status: data L_COMPONENTCONTROLLER type ref to IG_COMPONENTCONTROLLER . data L_API_COMPONENTCONTROLLER type ref to IF_WD_COMPONENT. data L_PORTAL_MANAGER type ref to IF_WD_PORTAL_INTEGRATION. L_COMPONENTCONTROLLER = WD_THIS->GET_COMPONENTCONTROLLER_CTR( ). L_API_COMPONENTCONTROLLER = L_COMPONENTCONTROLLER->WD_GET_API( ). L_PORTAL_MANAGER = L_API_COMPONENTCONTROLLER->GET_PORTAL_MANAGER( ). call method L_PORTAL_MANAGER->SET_APPLICATION_DIRTY_FLAG exporting DIRTY_FLAG = TRUE | FALSE . Web Dynpro supports the work protect mode in three different ways (method SET_WORK_PROTECT_MODE in the interface IF_WD_PORTAL_INTEGRATION): ●

NONE This value means that the work protect mode is not used by the Web Dynpro application. If you navigate to another application in the portal, unsaved data is lost, even if you set the dirty flag.

●

APPLICATION_ONLY This value means that the Web Dynpro application itself decides if there is still unsaved data – that is, whether the application is dirty. This is why the “dirty” status is only monitored by the server. With this value you cannot ensure that data that has not yet been transferred to the server will not be lost.

●

BOTH This value means the client also checks the “dirty” status. This ensures that no user input that has not yet been transferred to the server will be lost. This is done by setting the dirty status of the application in SAP Enterprise Portal as soon as the user has entered data.

The modes described above can be changed as often as required during runtime of a Web Dynpro application. For example, you can change the mode when a user navigates from one view to another. For one view, it may make sense to save data that is entered in an input

Web Dynpro ABAP: Development in Detail

132

Advanced Concepts

May 2006

field. In this case you define the value BOTH or APPLICATION_ONLY. For another view this protection mode may not be necessary. In this case you define the value NONE. The source text below shows how the work protect mode can be set: data L_COMPONENTCONTROLLER type ref to IG_COMPONENTCONTROLLER . data L_API_COMPONENTCONTROLLER type ref to IF_WD_COMPONENT. data L_PORTAL_MANAGER type ref to IF_WD_PORTAL_INTEGRATION. L_COMPONENTCONTROLLER = WD_THIS->GET_COMPONENTCONTROLLER_CTR( ). L_API_COMPONENTCONTROLLER = L_COMPONENTCONTROLLER->WD_GET_API( ). L_PORTAL_MANAGER = L_API_COMPONENTCONTROLLER->GET_PORTAL_MANAGER( ). call method L_PORTAL_MANAGER->SET_WORK_PROTECT_MODE exporting MODE = NONE | APPLICATION_ONLY | BOTH .

4.10 Example You can find an example in the system in the Web Dynpro application WDR_TEST_PORTAL_WORKPROTECT.

4.11 Integrating Forms For Web Dynpro user interfaces, forms can be created and used in the context of Interactive Forms Based on Adobe Software [externaly]. For an efficient and straightforward development of the user interface, you can integrate the Adobe LiveCycle Designer tool with editor and the Adobe UI elements into the development workbench. There are two ways of using the solution Interactive Forms based on Adobe Software: ●

Print, offline, and display scenario Unlike in the interactive scenario, only non-input-enabled PDF forms are used here.

●

Interactive scenario With this scenario, forms containing input-enabled elements are created and edited.

The procedure for creating or using the relevant forms is largely the same for all scenarios. However, one of the main differences is in the calling of the application: When an interactive form is first called, a CAB file, containing a plug-in for the locally installed Adobe Reader, is automatically loaded from the server. This Active Components Framework (ACF) allows you to process form contents on your local computer. However, the ACF is not required for displaying or printing a form.

The UI Element InteractiveForm For Adobe integration, the Adobe Library with the InteractiveForm [externaly] interface element is provided in the Web Dynpro View Designer.

Prerequisites ●

SAP NetWeaver AS System with Adobe Document Services (ADS)

Web Dynpro ABAP: Development in Detail

133

Advanced Concepts

May 2006

Details on installation on the SAP Service Marketplace under the quick link: /installNW2004s. Notes on importing licenses are available in the Configuration Guide [externaly].

â&#x2014;?

Adobe Reader (>= 7.0) installed on your local computer See also note 834573

Connection Test Execute program FP_PDF_TEST_00 to ensure that the ADS was configured correctly. If the configuration is correct, the out put of the test program will be the version number of the installed ADS. For information about potential errors see Adobe Document Services Problem Analysis Scenarios [externaly].

Creating Web Dynpro Application Using Forms The individual steps involved in creating or using a form are described in the following: Integrating a PDF Form in a Web Dynpro Application [page 134] Interactive Form Use [page 137]

4.11.1

Integrating a PDF Form in a Web Dynpro Application

The following describes the procedure for using a PDF form in a Web Dynpro application. Forms can be created and maintained independently of Web Dynpro applications using the Form Builder (transaction SFP). Information about the creation of forms and using the Form Builder is available under Designing Forms with the Form Builder [externaly]. You can integrate a form within every view of any component, but it can often be useful to create a separate view for the integration of a form.

Including an Existing PDF Form in a Web Dynpro View ...

1. In the Web Dynpro Explorer, create a view for your component or select a view into which to integrate the form. 2. In the layout of this view, drag the UI element InteractiveForm [externaly] from the Adobe Library [externaly] into the Layout Designer. 3. For the templateSource property, enter the name of the selected form (an input help is available). Based on the interface of the selected form, a context node with attributes is automatically created for the UI element InteractiveForm. The dataSource property of the UI element is automatically bound to this context node. 4. To define that your form is an interactive form, select the option for the enabled property in the properties table of the UI element InteractiveForm. By default, enabled is inactive â&#x20AC;&#x201C; that is, it is usually a non-interactive form. Note that you must only check this checkbox if your application is to be used interactively. Selecting the checkbox means that the Active Components

Web Dynpro ABAP: Development in Detail

134

Advanced Concepts

May 2006

Framework (ACF) is used for rendering in the client (generally the browser of the user) and must therefore be installed. The ACF is installed centrally from SAP NetWeaver AS, normally automatically when a relevant application is first called. However, it is possible that a user may not have sufficient authorization for the local installation of the ACF-CAB files. In this case, the user cannot display the form. If a form us used without checking the enabled checkbox – that is, noninteractively – the ACF is not required for rendering. 5. After filling the created context structure – for example using a suitable supply function – and including it in the navigation of the window, you can activate and test the application.

Creating a PDF Form Within a Web Dynpro View Since in many cases the required form is not available, the Web Dynpro Explorer also allows you to create a new from when designing the Web Dynpro view. However, there is a different procedure for this: 6. In the Web Dynpro Explorer, create a view for your component or select a view into which to integrate the form. 7. In the view context, create the node with attributes that is later to be bound to the form. 8. In the layout of this view, drag the UI element InteractiveForm [externaly] from the Adobe Library [externaly] into the Layout Designer. 9. Now enter a name for the new form in the line templateSource of the UI element properties table and double-click the name. 10. The subsequent dialog box informs you that you must specify an interface before you can create the new template. At this point, you can use an existing interface, but you can also create a new interface adapted to suit your Web Dynpro view. To create a new interface, enter a name and choose Context. Since the creation process is connected to the view you are processing, the context of this view is provided for the selection of a suitable node. 11. Choose the context node created in step 2 and close the dialog box. 12. In the next two dialog boxes, you save a new interface and a form that uses this interface, each as a separate transport object. Only on the third dialog box do you save the processed view and branch to the Form Builder to design the form layout [externaly]. Based on your selected Web Dynpro context, an XML schema is created for the new interface, which is available to the new form for data selection. If you switch back to view editing after completing the form design and select the UI element InteractiveForm [externaly] in the view layout, you will see that view context node was automatically connected with the form or relevant interface. You have now finished integrating the newly created form and can complete the inclusion of the view context in the application logic of the component.

Subsequent Changes to the Web Dynpro Context To provide new elements in the data view for the form, you must first enhance the respective Web Dynpro context accordingly. You do this, as usual, in the context editor of the Web Dynpro Explorer. The triggering of forwards navigation on the UI element InteractiveForm branches subsequently back to the Form Builder. The XML schema, and thus also the data view of the Form Builder, is automatically adjusted.

Web Dynpro ABAP: Development in Detail

135

Advanced Concepts

May 2006

If you used an existing templateSource for the form integration whose interface is not based on an XML schema, you cannot add any further data fields at a later stage. Note that other forms may have used your interface and check carefully before you change an interface.

Form Data in XML Format In the two procedures described above, only the two properties templateSource and dataSource of InteractiveForm were bound to the view context. The templateSource property contains information about the form template, while the context node, to which the dataSource property was bound, contains the values to be displayed in the form as individual Web Dynpro context attributes. You can store or process the values of the form, completed at runtime by user input, in XML format. To do so, you have to include an additional attribute of the type xstring in the view context. You then bind the pdfSource property of the UI element InteractiveForm to this context attribute. The XML representation of the PDF values can be read and processed here. Using a suitable template and this XML data, you can create a complete PDF again at a different point. The transfer of form data from an xstring attribute, whose contents originate from the back end, into separate attributes of a Web Dynpro context node is not supported.

4.11.2

Supported Elements of the Adobe Library

Special Adobe UI elements are available for form development in a Web Dynpro application. These can be selected on the Web Dynpro tab of the Form Builder element library (see documentation on PDF-Based Print Forms [externaly]). Two of these elements are currently supported by the Web Dynpro environment:

Send Button (SubmitToSAP) With the Web Dynpro form UI element SubmitToSAP, the input data of a PDF form is sent to an SAP backend system for storage. The UI element also provides an automatically generated event.

Disable the Adobe Toolbar â&#x2014;&#x2039;

Using the form UI element HideReaderToolbar, you can prevent the Adobe tool list from being displayed in the browser. The user then cannot store a PDF form locally or print it out. The display area of the form on the screen is increased automatically when the toolbar is disabled.

Web Dynpro ABAP: Development in Detail

136

Advanced Concepts

May 2006

Documentation about forms and the Form Builder is available under Form Design Using the Form Builder [externaly]. Note that for Web Dynpro ABAP the interface definition and activation mentioned there is not required. Documentation on the individual UI elements is available in the online help for the Form Builders: Choose Help and then expand the section Working with Objects.

4.11.3

Interactive Form Use

There are many reasons for including forms in a Web Dynpro application. Most embedded forms are used for printing and archiving and therefore do not have to be made available in interactive form. However, the Web Dynpro framework still allows you to use embedded PDF forms interactively. Using a PDF as an input template for a Web Dynpro application can be especially useful when a user is familiar with the appearance of a form and, for reasons of recognition, you would like to also make this form available in the system. An example of this is a tax return form. A further use case for interactive forms relates to legal considerations. It may be necessary to store not only the data content of a form, but retain the form and the data together as a unit for future reference.

Releasing the Interactivity of a Form In the default system settings, a UI element of the type InteractiveForm is non-interactive â&#x20AC;&#x201C; that is, the checkbox of the enabled property is not checked. If you wish to use a form interactively, you must check the enabled property checkbox. Note that you must only check this checkbox if your application is to be used interactively. Selecting the checkbox means that the Active Components Framework (ACF) is used for rendering in the client (generally the browser of the user) and must therefore be installed. The ACF is installed centrally from SAP NetWeaver AS, normally automatically when a relevant application is first called. However, it is possible that a user may not have sufficient authorization for the local installation of the ACF-CAB files. In this case, the user cannot display the form. If a form us used without checking the enabled checkbox â&#x20AC;&#x201C; that is, noninteractively â&#x20AC;&#x201C; the ACF is not required for rendering.

4.11.4

Forms with Function Module-Based Interface

Before the introduction of the XML-based interface, a function module-based interface was created for a form during integration of the same. Such an interface, however, was not easily linked to the context of a Web Dynpro component. All the forms created from within the Web Dynpro context are not automatically equipped with an XML-based interface. In certain situations, however, it can be necessary to integrate an old form with a function modulebased interface into a Web Dynpro application. The Web Dynpro runtime makes it possible, in principle, to display or print such a form within a Web Dynpro application. In special cases, it is even possible to integrate such a form in a limited, interactive mode.

Web Dynpro ABAP: Development in Detail

137

Advanced Concepts

May 2006

Setting Up Limited Input Enablement The UI element InteractiveForm can be used, in this case also, with limited input enablement. The values entered by the user are not, however, distributed to the respective attributes. The form is displayed in change mode and, after the user has completed his or her entries, it is stored as a whole in the context attribute – which is then mapped to the property pdfSource. This is particularly helpful whenever you want to print or archive entries in a form. Validation of the entries, in this case, is not provided by the framework. Once a form is set to input enabled, this property is retained. It cannot be reset to a pure display mode again. The interface of the UI element InteractiveForm contains the method SET_LEGACY_EDITING_MODE, which in turn contains a Boolean parameter. The form is then ready for input when ●

The parameter has the value X.

●

The property enabled in the UI element InteractiveForm is selected.

●

The property pdfSource is mapped to a context attribute of the type XSTRING.

The following code fragment shows how this input readiness can be set up: method WDDOMODIFYVIEW. data: LR_INTERACTIVE_FORM LR_METHOD_HANDLER

type ref to CL_WD_INTERACTIVE_FORM, type ref to IF_WD_IACTIVE_FORM_METHOD_HNDL.

check first_time = abap_true. LR_INTERACTIVE_FORM ?= VIEW->GET_ELEMENT(‘INTERACTIVE_FORM_1’). LR_METHOD_HANDLER ?= LR_INTERACTIVE_FORM->_METHOD_HANDLER. LR_METHOD_HANDLER->SET_LEGACY_EDITING_ENABLED( abap_true ). . . . endmethod.

4.12 Personalization and Configuration When business requirements are mapped onto an ERP system, many standard applications arise that can be implemented by different companies. This does not automatically mean that also the user interface of a business application is always the same. Depending on the very different factors (for example, the required function of an application, size, or business industry of a company), changes to the UI of an application can vary greatly. On the other hand, it is often necessary to give users of business applications the option of independently co-designing the UI through which they perform their work Applications that are created with the help of Web Dynpro ABAP can be adjusted in different ways and by different target groups. In this context, we distinguish between two areas:

Web Dynpro ABAP: Development in Detail

138

Advanced Concepts

May 2006

Configuration The configuration of business applications takes place in two subsequent steps: First, configuration data records are created for the individual Web Dynpro components (Component Configuration [page 139]). Such configuration data records are absolutely necessary when using generic components, such as the ALV [page 147] or Pattern component. Configuration data is created and edited mainly by developers. The following step is the application configuration [page 141]. Each of these used components is required in a particular configuration. The application configuration defines which component with which configuration is required for the application. This step, too, is carried out primarily by application developers. Application and component configuration data is created and maintained with the help of the configurator.

Personalization and Customization (Cross-Client Adjustments) In contrast to configuration, personalization [page 143] is a function that is also available to the user of an application and provides him or her with the option of adjusting the application to suit his or her own personal requirements or preferences. The framework for variation options within personalization is less far-reaching than that in configuration; personal settings in the UI must never limit the running ability of an application. Personalization of an application is performed directly by a user from within the current application. It is possible to maintain personalization settings in a uniform manner for larger user groups (adjustment â&#x20AC;&#x201C; also called customization). A system administrator can process personalization settings on the basis of his or her extended authorization [externaly], provided the respective application runs in so-called configuration mode. For more information, refer to the chapter Personalization [page 143]. Configuration of Web Dynpro applications of a Web Dynpro component takes place almost always at design time (only exception here is the configuration of a bound ALV Component [page 147]; see also Component Configuration). In contrast to this, personalization and customization are always executed at runtime of an application.

4.12.1

Component Configuration

Using Component Configuration, you can control the behavior of each individual component within a Web Dynpro application. For each component, several records of configuration data can be created. This kind of data record contains two different types of attributes.

Implicit Configuration Each UI element has a set of attributes defined by the framework. Their values are set when a view is designed. Therefore, almost every UI element has the attribute Visibility. In the View Editor of the ABAP Workbench, an application developer sets the value, for example, to yes. Within a special application of the component, precisely this UI element, however, should not be visible. The application developer then creates a configuration for the component in which the value for the attribute Visibility is set to no. When the respective application is called, it will also require the information as to which existing configuration data is to be used. The value of the attribute Visibility is an example of a possible implicit configuration style. The attribute is preset by the Web Dynpro Framework and the value set by the application developer is edited automatically. There is no additional programming effort required by the component developer for implicit configuration.

Web Dynpro ABAP: Development in Detail

139

Advanced Concepts

May 2006

Many (not all) f the attributes of UI elements can be overridden with the help of configuration data.

Explicit Configuration: The Configuration Controller Context In addition to the implicit configuration of predefined attributes of UI elements, it is also possible to influence the appearance and behavior of a Web Dynpro component. These influences can be implemented through additional attributes in the context of a special custom controller – the Configuration Controller. You can create any number of Custom Controllers [page 56] for a Web Dynpro component. Only one custom controller, maximum, can be specified as the configuration controller. To do so, select the relevant controller in the object list and open its context menu. Choose Set/Reset as Config.Controller. In the same way, you can set the controller back to a simple custom controller. Therefore, you can define attributes in the context of the configuration controller. These are used to control the appearance of a screen in a view. This explicit configuration becomes clear through an appropriate example. In your system, you will find the example component WDR_TEST_PERS_IMP_EXP in the package SWDP_TEST. The value to be set as of which the system should switch from one reference icon to the next can be configured by the application developer. For this purpose, the two attributes CONFIG_LOW and CONFIG_HIGH have been created in the configuration controller context of this component. These two attributes set the limit value as of which occupancy with the icon is low (green square) or high (red circle). If the occupancy level is between the values, a yellow triangle will appear in the table. In contrast to implicit configurability, such attributes must be created explicitly in the configuration controller context. Therefore, the processing of attributes must also be explicitly programmed by the application developer in a controller method of the component. In the example component WDR_TEST_PERS_IMP_EXP, the logic for evaluating the attributes is entered in the method WDDOINIT of the component controller. The storage of the attributes in the context of the configuration controller ensures that their values can be set or changed later on with the help of the component configurator.

When you are creating a node in the configuration controller context, Singleton nodes and recursion nodes are not allowed.

The Component Configurator You start the component configurator as follows: ●

In the object list of the workbench, choose a Web Dynpro component and select it.

●

From the context menu of the component, choose the entry Create/Change Configuration. The system automatically opens a browser with the dialog window of the configurator. The mode Component Configurator is active and you enter a name for your new component configuration.

From the list of available functions, choose the entry Create. On two tab pages, you can set the values of the implicit and explicit attributes for your configuration. Save the component configuration and close the browser.

Web Dynpro ABAP: Development in Detail

140

Advanced Concepts

May 2006

A new configuration will be saved only when it actually contains values. An empty configuration file that merely has a name is not stored. Since the configurator is not part of the ABAP Workbench, but runs separately in the browser, the hierarchy of the object list in the workbench must be updated actively after completion of the creation or change procedure in a configuration.

In this way, you can combine and store many different configurations for each component. In large projects, it will happen that the structuring and functions of the explicit configuration is implemented by other development groups as the actual content of the attributes through the help of the component configurator. Processing values of context attributes can, as described above, be done by an application developer at design time with the help of the component configurator. The application developer, however, can additionally provide for having values changed by a user (personalization) or an administrator (customization). In the case of properties of the implicit configuration, the Web Dynpro framework provides all the required tools. For all explicitly created modification options, the application developer must, however, program the required dialog himself/herself (for more information on this, refer to the chapter Personalization [page 143]).

4.12.2

Application Configuration

A Web Dynpro application usually belongs to a main component, which - in turn - uses a series of other components. Using the application configuration, it is now possible to assign the configuration required in the current application to all the components used.

My Application Configuration Component

Component-Configuration

main

my_main_config

used_1

my_used_1_config

used_2 used_3

my_used_3_config

The Application Configurator â&#x2014;?

To create an application configuration, select a Web Dynpro application from the object list in the ABAP workbench.

Web Dynpro ABAP: Development in Detail

141

Advanced Concepts

May 2006

●

Open the context menu and choose the entry Create/Change Configuration. A browser window opens and you have the option of entering a name for the new application configuration.

●

After you have chosen the Create function, all the components used in the application will be displayed to you in a table. You can now choose for each individual component – from all the corresponding component configurations – the one that is required for your application. However, a configuration must not necessarily be actually used for all components.

●

After you have saved and refreshed your tree display in the Workbench, you now have the configuration you created at your disposal.

Assignment of the Configuration to the Application Various configuration data records can be created and stored for an application. To start an application with a special configuration, there are different options available: 13. In the portal, you can define the assignment by specifying the configuration name as Application Parameter in the iView wizard. 14. In SE80, you can call up the application with the required configuration directly through the context menu entry Test in the selected application configuration. 15. The name of the configuration can be passed to the application or passed as a default value. For this reason, you can maintain the parameter WDCONFIGURATIONID for a Web Dynpro application. You enter it on the Parameter tab page of the Application Editor [externaly]. The parameter WDCONFIGURATIONID can be assigned once only for each application. After you have saved the data, you now have the configured Web Dynpro application at your disposal.

Possible Development Scenario A component developer is setting up a component in order to represent a basic business function. In addition, he or she is integrating – already at this point – explicit configuration options by creating a range of attributes in the configuration controller context and by implementing the respective functions in suitable methods of the different component controllers. An application developer wishes to use this component in a particular context. He or she first creates a component configuration for the component used, one that matches his or her requirements. For the application, he or she will use perhaps other components with special component configurations that either already exist or will have to be specially created for this purpose. Afterwards, he or she sets up a main component and creates for this a new application as well as an application configuration. This has a unique name and contains a list of all the used components with the required component configuration in each case. Non-configured, used components are not contained in this data record. Finally, the application developer enters the name of the created application configuration as a default value for the parameter WDCONFIGURATIONID in the appropriate tab page in the application editor.

Web Dynpro ABAP: Development in Detail

142

Advanced Concepts

May 2006

When you start the application, all the required components are now brought in with the selected configuration.

4.12.3

Personalization

The concepts described so far for the component and application configuration referred to design processes that were implemented at design time and by application developers. Personalization and customization, on the other hand, take place at runtime and are executed by users or administrators.

Personalization The user of a Web Dynpro application can influence, to a certain degree, the appearance of a screen in the view displayed in the browser. The Web Dynpro Framework proved for each single UI element the option of changing part of the properties of the implicit configuration (see the chapter on Component Configuration). At the moment, this modification option is limited to the property Visibility. Without any additional effort for an application developer, therefore, the user of an application can hide or display individual UI elements on the view currently displayed. To open the respective dialog, the user positions the cursor on the UI element in question and presses Ctrl + right mouse-click. Sometimes, however, it can be appropriate to personalize such properties that were created with the help of explicit configuration in the context of the configuration controller. In this case, the dialog for access on behalf of the user to values of the configuration controller context must be created and programmed in a separate view explicitly by the application developer. In addition, the jump from the personalizing view to the personalization dialog must be created and implemented actively. In the demo application WDR_TEST_PERS_IMP_EXP, which is contained in your system in the package SWDP_TEST, you will find a special personalization view PERS_VIEW.

Embedding Implicit Configuration Options into the Personalization Dialog If a personalization dialog is created explicitly by the application developers, it can be appropriate to also embed the personalization of the implicit configuration option â&#x20AC;&#x201C; for example, on an additional tab page. In this case, the user would have the advantage of uniform handling. Embedding takes place with the help of a component interface already provided, whereby further programming of this implicit section of the personalization dialog is no longer required. The prepared Web Dynpro component interface to be used is called IWD_PERSONALIZATION and provides an interface view that, in turn, must be embedded in the window of the component used. This interface has a method called INIT_PERSONALIZATION, which is called in a method of the main component (for example, WDDOINIT of the component controller). The reference to the view controller for the view element to be personalized as well as the ID of this view element must be passed to the method INIT_ PERSONALIZATION.

Web Dynpro ABAP: Development in Detail

143

Advanced Concepts

May 2006

Cross-Client Customization While a single user – during a personalization process – can manipulate his or her own settings an administrator has the option of executing customizing settings for a larger range of users. Technically, this procedure is not different from personalization; both take place at runtime of an application. The difference lies in the range of the settings. In addition, an application for group settings must run in a special administration session. This is always automatically the case if an application was started in the portal in the preview session. Independently of the portal, you can start an application in the following manner from within the workbench in administration mode: ●

Double-click the name of the application in the object list.

●

In the menu Web Dynpro Applications in the upper, left-hand corner of the Workbench window, choose the entry Test -> Execute in Admin.Mode

The configuration mode is then passed to an application as URL parameter [externaly] sapconfig-mode=X. All the adjustments made by the administrator in the admin mode are stored as client-specific. At the moment, there is no option available for structuring smaller user groups on an administrative basis. Since cross-client adjustment takes effect for the respective configuration variant, structuring of smaller groups can be implemented currently through the maintenance of different configuration variants. For personalizing an individual user, a context menu opens when the relevant element is right-clicked while pressing the control key. However, when an administrator with URL parameter sap-config-mode=X right-clicks while pressing the control key, a separate dialog box opens.

4.12.4

Delta Handling in Customization and Personalization

The process of adapting a Web Dynpro application to suit the needs of individual users is generally divided into different steps. Example: ●

An administrator preconfigures the settings for a defined group of users (customization)

●

An individual user then adjusts some settings of the application to suit his or her own specific needs (personalization)

When the application configuration is saved at the end of this process, certain information is lost – for example, you can no longer see which changes were made by the administrator and which by the user. Therefore, it is generally necessary to store customization and personalization data in a way that allows the merged data to be managed appropriately. This gives rise to the following requirements:

○

Changes in the customizing of an application must be visible to the user for all contained pages, unless the user has overwritten the specific property with his or her own value.

○

Administrators must be able to flag the value of a property as “final”. This must then be valid for all users involved, even if the property was already changed by a single user and saved as a personalization. Once an administrator has flagged

Web Dynpro ABAP: Development in Detail

144

Advanced Concepts

May 2006

a property as â&#x20AC;&#x153;finalâ&#x20AC;?, any changes to the value as a personalization of a single user must no longer be permitted. â&#x2014;&#x2039;

Users and administrators must be able to reverse a change.

To enable administrators and end users to use customization and personalization appropriately, this must be taken into account when developing the relevant components.

Primary Attribute If you have created a custom controller and flagged it as a configuration controller, you can add the following specific information in its context: In every node of this context, you can flag exactly one attribute as the primary attribute of the node. At runtime, this attribute is used as the key for assembling the configuration data. The concept of the primary attribute corresponds to that of the key field in a database table. In the following example, the ID attribute was marked as the primary attribute.

Configured Data Elements Index

Value

1MB

blue

2MB

green

3MB

red

Customized Data Elements

myNode ID Value Result Data Elements Index

Value

1MB

blue

Index

Value

2MB

yellow

2MB

yellow

3MB

red

4MB

grey

4MB

grey

After the customizing, the framework recognizes a new value for the element with the ID 2MB, even though it has different index in the element set of the customizing data than in the set of the configuration data. The result of the overlay then contains all unchanged, configured values as well as all values overwritten or added in the customizing. The two separate element sets are known to the framework and can thus be read at any time. Therefore, if the customizing of the element with the ID 2MB is deleted, the value from the set of configuration data is used automatically. The primary attribute is defined by the developer of the component at design time. For the above example, the adjustment process is then as follows:

Web Dynpro ABAP: Development in Detail

145

Advanced Concepts

Framework loads Configuration data

Administrator adds Customizing data on top without seeing his own personalization data or that of other users Users may personalize some data as long as it is not set to “final” by configuration or customization

Result for a personalized data node

May 2006

Index

1MB

blue (final)

2MB

green

3MB

red

Index

Value

2MB

yellow

4MB

grey (final)

Index

Value

3MB

magenta

Value

Index

Value

1MB

blue (final)

2MB

yellow

3MB

magenta

4MB

grey (final)

Individual elements can be flagged as “final” both in the configuration and in the customizing. However, these can longer be changed in a subsequent adjustment step.

4.12.5

Notes on Working with Adjustment Data

There are a number of points to note to ensure the appropriate use of adjustment data.

Configuration Data The following rules apply for the configuration context created by the developer of the component: ●

Attributes must be of a simple type (no references or table structures)

●

The context structure should not be changed at runtime

●

The context must not contain any recursive nodes

●

The context should not contain any singleton nodes

●

The context should specify a primary attribute for every multiple node

If the value of an attribute is a text that is to be translated into different languages, you can use the element WDY_CONF_TRANSL_TEXT. Alternatively, you can create your own element that uses the domain WDY_CONF_TRANSL_TEXT.

Web Dynpro ABAP: Development in Detail

146

Advanced Concepts

May 2006

A data element that was created for the configuration cannot be deleted by customizing. If you want to implement an option for hiding individual elements when devising the configuration at design time, you must add an additional attribute to the context with the semantics “visible”, for example. In the customizing process, you can then control the visibility of individual elements via this attribute.

Changing Values of the Configuration Context There are different ways of changing the value of an element of the configuration context at runtime. ●

If the element is bound directly to a UI element that can be edited by the user (for example, an input field), the personalization framework recognizes the value change automatically.

●

However, if the value of the element is changed programmatically – for example, in a method call – the personalization framework only recognizes the change if it was implemented using the interface IF_WD_PERSONALIZATION. This interface is provided by the Web Dynpro code wizard. Changes made directly to the context node cannot be recognized.

4.12.6

Configuration of an Included ALV Component

An application developer has the option of setting up the ALV component so that it matches the including application. For this purpose, the ALV component provides predefined interface methods. From the viewpoint of the application developer, the ALV component is therefore a component application whose configuration is performed by the application developer himself/herself using interface methods released by the ALV. A configuration of the ALV component in the configuration editor does not make any sense since the data structures used are not known at design time. Therefore, configuration is possible for embedded ALV components at runtime.

Storage Options for Personalization Settings Just like other components, an embedded ALV component always provides a dialog for personalization data. Here, implicit and explicit configuration options are offered. You can call up this dialog at runtime via the Settings link and make the required settings. If you start, in administration mode, the application that embeds the ALV component, you have the option of storing this setting as a customized setting for all clients. If you have developer authorization for the embedding component, you will also be offered the option of additionally saving the setting data as configuration data. In this case, the data – just like all other component configurations – is stored as separated development objects and supplied with a TADIR entry.

●

Customizing and personalization of the ALV component can be set as the default view by selecting the Initial View flag in the Save dialog or in the ALV component settings.

●

If a configuration is to be set as the default, you must select the previously saved configuration of the ALV component for the relevant ALV component usage in the application configuration. You can either change an existing application configuration or create a new configuration for the application.

Web Dynpro ABAP: Development in Detail

147

Advanced Concepts

●

May 2006

For the application configuration to become effective, you must either set it as the default configuration in the application itself or it must always be passed as a URL parameter. This can be set in the Portal iView, for example.

4.13 Modification-Free Enhancements In many cases, it will be necessary to change or enhance applications delivered by SAP or ones that already exist. Unstructured changes to the source code or layout of an application are called modifications. Modifications can cause conflicts when a new release of the application programs is to be imported. To avoid such conflicts, you can create enhancement implementations [externaly] for existing applications that were implemented using Web Dynpro for ABAP. These enhancement implementations are independent development objects that are managed separately from the respective original object. They are part of the enhancement concept [externaly] that was integrated into the ABAP Workbench in the Web Application Server for Release 7.0. The original objects they are based on are not changed by such an enhancement and can therefore be updated without any problems whenever there is a release change.

Enhancement Implementations for Web Dynpro for ABAP ABAP source texts in a Web Dynpro application can be enhanced using BAdIs [externaly]. For this purpose, explicit anchor points (called enhancement options [externaly]) are implemented in the source code at suitable points during the development of the application. Using these options, you can insert a separately developed BAdI later on into the flow of the program. Each BAdI is therefore an explicit enhancement [externaly]. An implicit enhancement [externaly], on the other hand, does not need any advance implementation through the application development department. In addition to the source code enhancements described above, you can also perform enhancements to individual sections of a Web Dynpro component. For example, you can insert UI elements into a view or suppress them, or you can insert new nodes in a controller context.

Creating an Enhancement Implementation To create an enhancement implementation, first open the required component in the object list in SE80. With double-click, you open the view or the controller in which you wish to perform the enhancement in the editor.

In the icon toolbar of the Web Dynpro Explorer, you will find the icon for the function “Create/Change Enhancement Implementation”. The function „Create/Change an Enhancement Implementation“ will only be available to you if the original component is available in display mode. If you switch from display mode to change mode, the original component itself will be ready for change, so therefore no enhancement implementation can be created or changed; the icon is grayed out. By clicking the icon, you open either a creation dialog for a new enhancement implementation or you get a list of all the enhancement implementations that exist for this component.

Web Dynpro ABAP: Development in Detail

148

Advanced Concepts

May 2006

It is appropriate to start the names of objects that you have created within an enhancement implementation with a prefix that uniquely identifies the assignment to this implementation. This helps to prevent name conflicts with objects of the original component. Example: If you create a pushbutton in the enhancement myEnhancement_1, you could call it myEnhancement_1/button_1. As soon as you complete the dialog, you can then execute the enhancement or enhancement changes you have created. Enhancements in a View [page 149] Enhancements in a Controller [page 150] Enhancements in a Window [page 151]

As a rule, several enhancement implementations, all independent of one another, can be created for a component. The individual changes can be edited only in the implementation in which they were created.

4.13.1

Implementing Enhancements in a View

If you have chosen a view of the Web Dynpro component as the starting point of your enhancement implementation, you can now branch to the tab page Layout. If you select, in the layout, UI elements of the original component that already exist, you will see that you cannot change these. All fields that are otherwise ready for input or change are grayed out.

Creating New UI Elements To enhance the layout of the view, you can create new UI elements. This procedure is no different â&#x20AC;&#x201C; from a technical viewpoint â&#x20AC;&#x201C; from creating UI elements [externaly] in components themselves. All UI elements created within the enhancement implementation can then be processed as usual.

Suppressing Existing UI Elements UI elements that exist in the original component cannot be deleted. If you do not wish to display certain UI elements that exist in the layout, you can suppress such elements in your enhancement. Simply select the respective UI element and then choose its context menu entry Remove Element. In contrast to processing an original component, the UI element does not disappear from the hierarchy or the layout preview. Instead, the properties table of the element gets an additional line with the following information:

Property

Value

Binding

Enhancement

myEnhancment

This line records that the respective UI element has been suppressed/hidden in the enhancement implementation myEnhancement. In the context menu of the UI element, you will now find the entry for undoing the hidden status. You can use it to return the element to its original status.

Web Dynpro ABAP: Development in Detail

149

Advanced Concepts

May 2006

Hiding a UI element means that this element is skipped when the page is generated. It is not rendered completely "hidden" â&#x20AC;&#x201C; like, for example, a UI element that exists but is not visible. This needs to be taken into consideration in particular whenever such a UI element was programmed dynamically in the original component â&#x20AC;&#x201C; that is, a UI element that is then not available at runtime.

Actions, Inbound and Outbound Plugs For each view you can create additional plugs and actions in an enhancement implementation. The enhancement implementation in question is noted in the respective management table.

4.13.2

Implementing Enhancements in the Controller

All parts of a Web Dynpro controller can be enhanced. Here, too, the following applies: Controller parts created in the original component cannot be changed or deleted in an enhancement implementation.

Context Nodes and Context Attributes For each existing context, additional nodes and attributes can be created within an enhancement. However, if you wish to add an attribute to an existing node, there are two different situations: Within a node without a dictionary structure, this is possible without restriction. Within a node with a dictionary structure, one or several attributes from the used structure can be added through the context menu entry Create Through Wizard->Attributes from Components of a Structure. If you select an attribute added in this manner, you will see the name of the implementation for which it was created displayed in its properties table in the last row Enhancement Implementation. You may only change or delete a context note or context attribute that was created for enhancement purposes in exactly that enhancement implementation in which it was created.

Methods, Pre-Exits, and Post Exits In accordance with all the steps performed so far, it is possible to create and implement new methods for a controller in an enhancement. However, to be able to intervene in existing methods, a so-called pre-exit and post-exit are provided in an enhancement for each method. These two self-contained, additional methods are run directly before or directly after the corresponding original method is called. Pre-Exits: The pre-exit method automatically provides all the importing and changing parameters of the corresponding original method. Post-Exits: The post-exit method automatically reads the importing parameter of the original method. All the other parameters of the original method (exporting, changing, and returning parameters) are provided as changing parameters.

Web Dynpro ABAP: Development in Detail

150

Advanced Concepts

May 2006

Attributes Additional attributes can be created within an enhancement implementation.

4.13.3

Implementing Enhancements in a Window

In the navigation structure, too, it is possible to create enhancements within a Web Dynpro window. Changing navigation structures using enhancement implementations can cause inconsistencies. Steps that are technically required for the business logic can be suppressed in the navigation sequence, which could mean that data required later is not set.

Navigation Links ●

You can create new navigation links.

●

Existing navigation links, similar to UI elements in a view, can be suppressed. They are not deleted then by any means, but remain as part of the original component. Whenever you edit either the enhancement implementation or the original component, you will see displayed in the properties table – for example, of a navigation link – to which development object the enhancing element is assigned.

●

A new navigation target can be defined for an existing navigation link. When you select this step, the existing link is first suppressed, as described above.

4.14 Integration of Web Dynpro ABAP Applications in GUI Applications Use With the function module WDY_EXECUTE_IN_PLACE and within the framework of the classic Dynpro [externaly] interface development, you can integrate Web Dynpro ABAP applications into your GUI application. You can display the Web Dynpro ABAP application either in a specific area on your “in-place” screen or on a separate screen. The “in-place” is displayed in the SAP HTML viewer. The function module enables the relevant parameters to be transferred with both variants. You can also generate the URL belonging to the Web Dynpro ABAP application (OUT_URL) and then use it, for instance, to start a Web Dynpro ABAP application from the PFCG. Import Parameters Parameter

Optional

Description

Possible Values

PROTOCOL

Protocol to start the application

HTTP (default value) or HTTPS

INTERNALMODE

Internal display mode.

X or no specification (blank)

Web Dynpro ABAP: Development in Detail

151

Advanced Concepts

May 2006

If X is set, the application is started with the SAP HTML viewer. If no value is specified, a browser window is opened in which the application runs. APPLICATION

Name of the Web Dynpro ABAP Application [page 44]

Application name

CONTAINER_NAME

Name of the embedded container If no value is the ,specified here application is started in a new screen and the SAP HTML viewer takes up the whole screen In contrast, if the Web Dynpro application is to be displayed on the same screen, you can create a custom control and enter its name in this parameter.

Name of the custom control or else empty See example program DEMO_START_WD_IN_PLACE2

PARAMETERS

Internal table containing the names and values of the parameters that are to be forwarded in the application.

Table name

SUPPRESS_OUTPUT

If X is set, the generated URL is output, and the application is not started.

X or no specification (blank)

Export Parameters Parameter

Description

OUT_URL

Generated URL. It is always output, regardless of whether

Web Dynpro ABAP: Development in Detail

152

Advanced Concepts

May 2006

SUPPRESS_OUTPUT has been set or not.

Changing parameters Parameter

Optional

Description

CONTAINER

Reference to an instance of class CL_GUI_CUSTOM_CONTAINER. For the first function call you can put a non-assigned reference in this field The function initialized the object and returns the reference. See example program DEMO_START_WD_IN_PLACE2

VIEWER

Reference to an instance of class CL_GUI_HTML_VIEWER. For the first function call you can put a non-assigned reference in this field The function initialized the object and returns the reference. See example program DEMO_START_WD_IN_PLACE2

Example The following programs are provided as examples of how WDY_EXECUTE_IN_PLACE is used in the SAP system: ●

DEMO_START_WD_IN_PLACE1 Program for a simple call of the function module.

●

DEMO_START_WD_IN_PLACE2 Program that shows how the example Web Dynpro applications, WDR_INPLACE_DEMO1 and WDR_INPLACE_DEMO2, can be called either in the same screen or in a separate screen, and how the values of SAP GUI fields can be transferred into Web-Dynpro ABAP applications.

4.15 Accessibility of a Web Dynpro Application To make a business application available to those users who are dependent on technical support of various kinds due to disability, the Web Dynpro framework provides them with the option of setting up accessible applications.

For more information, refer to the chapter Accessibility [externaly]. You will find more information on the screen read program supported by SAP in the chapter Using the Screen Reader JAWS with SAP Software [externaly]

Web Dynpro ABAP: Development in Detail

153

Advanced Concepts

May 2006

Accessible User Interfaces Tooltip An important prerequisite for providing this accessibility is the availability of a tooltip for each UI element since tooltips are evaluated with the help of screen reader programs and can therefore be made accessible for visually impaired users. Each UI element provides such a tooltip. A tooltip must be maintained for a UI element to ensure accessibility whenever •

The UI element does not have a heading.

•

No label is assigned to the UI element.

•

Elements with a text property have neither set nor bound it (with the exception of the caption, for which no tooltip is checked) For example, there is no text on a button or link.

A tooltip must be maintained for some more complex UI elements. Examples of these are the UI elements Tree [externaly] or ProgressIndicator [externaly]. When you activate your component, you are made aware of the missing content of the tooltip property through an appropriate message – provided this property would have been necessary for the accessibility of the application. You have the option, however, of dynamically defining the value for the tooltip property. This option is not covered by the syntax check. In addition, the tooltip property must always be set, for example, to relate further semantic information on the UI element.

AccessibilityDescription Almost all UI elements additionally provide the property accessibilityDescription. This can be used to include a title, as an alternative, whenever the UI element should not or cannot carry a visible title (header). In contrast to the case with the tooltip, which should contain a semantic description of the purpose of the UI element, only a short, title-like expression is entered in the accessibilityDescription

More information on the individual UI elements is available in the reference section of this documentation under User Interface Elements [externaly].

Checks During Design Time During design time, accessibility checks are carried out automatically as part of the syntax checks. For every component, there is a flag Accessibility Checks Active on the Properties tab. If you deactivate this option, the development environment does not carry out any design time accessibility checks for the relevant component and its views. In principle, no semantic checks can be carried as the system cannot determine whether or not, for example, the content of a tooltip is useful within a given context. Instead, the system checks whether a specific property is set and filled. If this is not the case, the system checks whether any related properties are set.

Note that the accessibility checks are not carried out for Web Dynpro ABAP test applications (temporary objects in the package $TMP). The following is a list of the checks that are carried out for the specified UI elements.

Web Dynpro ABAP: Development in Detail

154

Advanced Concepts

May 2006

UI Element Checks UI Element

Type of Check

Button [externaly]

If the text property was not set, the system checks for the tooltip property.

LinkToAction [externaly] LinkToURL [externaly] ToggleButton [externaly]

An error message is displayed if, for example, a button or link with an icon has neither the text nor the tooltip property.

ToggleLink [externaly] ToolBarButton [externaly] ToolBarButtonChoice [externaly] ToolBarLinkToAction [externaly] ToolBarLinkToURL [externaly] ToolBarToggleButton [externaly] CheckBox [externaly] RadioButton [externaly] FileDownload [externaly] Group [externaly] Tray [externaly]

If the properties text and label were not set, the system checks for the tooltip property. An error message is displayed if, for example, a CheckBox has neither the text, label, or tooltip property. If the caption property was not set, the system checks for the accessibilityDescription property. An error message is displayed if, for example, a group has neither the caption nor the accessibilityDescription property.

Image [externaly]

If the properties label and isDecorative were not set, the system checks for the tooltip property. An error message is displayed if a tab-enabled image has an empty tooltip.

InputField [externaly] DropDownByIndex [externaly] DropDownByKey [externaly] ItemListBox [externaly] TextEdit [externaly] ToolBarDropDownByIndex [externaly] ToolBarDropDownByKey [externaly] ToolBarInputField [externaly]

The system checks whether the label property was specified. If no label has been set, and no descriptive text has been specified for the appropriate bound context element in the ABAP Dictionary, a check is made for the tooltip property. An error message is displayed if, for example, a TextEdit does not have a corresponding label or if a DropDownByKey does not have an assigned label and no description was entered in the ABAP Dictionary.

FileUpload [externaly]

Web Dynpro ABAP: Development in Detail

155

Advanced Concepts

Table [externaly]

May 2006

If the caption property was not set, the system checks for the accessibilityDescription property. Furthermore, the system checks whether the aggregation header is set for columns or whether the aggregation header is visible. The property tooltip is not checked. An error message is displayed if a table has neither a caption nor an accessibilityDescription or if a column does not have a (visible) header.

CheckBoxGroup [externaly] RadioButtonGroupByIndex [externaly] RadioButtonGroupByKey [externaly] RoadMap [externaly] DateNavigator [externaly]

If the tooltip property was not set, the system checks for the accessibilityDescription property. An error message is displayed if, for example, a CheckBoxGroup has neither the tooltip nor the accessibilityDescription property.

PhaseIndicator [externaly] TabStrip [externaly] TransparentContainer [externaly]

If the layoutContainer property was not set, the system checks for the accessibilityDescription property. An error message is displayed if a TransparentContainer has the property layoutContainer=false and does not have an accessibilityDescription.

4.16 Internationalization and Translation Static Texts Use In your Web applications views you can work with text literals and texts from the Online Text Repository [externaly]. If you use OTR texts only, you have the advantage that your Web application will be language-independent. All the texts defined in the OTR are displayed at runtime in the logon language. If the texts are not yet available in the logon language, they are displayed in the system language. The OTR texts that you create are automatically translated, or are forwarded to the translation transaction (SE63) and are entered in the translatorâ&#x20AC;&#x2122;s worklist. If necessary, you can change any OTR texts that you create later.

Web Dynpro ABAP: Development in Detail

156

Advanced Concepts

May 2006

Features OTR aliases are included in the View Designer for all properties of translatable text type. (WDY_MD_TRANSLATABLE_TEXT). You can find out what these types by choosing the F4 help symbol. â&#x2014;?

The OTR aliases displayed for selection are always those from the current package.

â&#x2014;?

You can create new OTR aliases.

Moving a component with OTR aliases from a local package to a transportable package can cause problems.

Activities ...

1. In your view call the View Designer in change mode and navigate to the UI element that you want to create or use an OTR alias for. 2. Click the

symbol in the Value field, for example, for the Text or Tooltip attribute.

The window Text Selection appears. You will see all the OTR aliases contained in the packet that your component is also assigned to. a. If you want to use an existing alias, select the alias you want from the Alias Name column and choose Enter. b. If you want to use a new alias, enter the character string $OTR:Aliasname in the Value field, and choose Enter. If the alias does not exist, you will be asked if you want to create it. Confirm with Yes and enter a name of your choice in the next dialog box. The text length can be a maximum of 255 characters. c. If you have defined for the property an alias that is in a separate package and is assigned to the corresponding development object (in this case View = WDYV), you can change this alias by double-clicking on the property. The Edit window will then appear as it does when you create an alias. 3. Save your changes.

Dynamic Texts If your texts are not compiled until runtime or if they contain variables, you can use text symbols from the assistance class. For more information see Working with the Assistance Class [page 87].

Long Texts The UI element FormattedTextView [externaly] is used for displaying long texts. Pay particular attention to the section Converting SAPscript Texts into Formatted Texts in the documentation for this UI element. You can find an example in the system in the Web Dynpro application WDR_TEST_MISC.

If you want to use SE61 texts to display long texts, note that not all SAPscript properties can be implemented in Web Dynpro ABAP. We do not recommend or support the use OTR long texts, nor their display in text view.

Web Dynpro ABAP: Development in Detail

157

Advanced Concepts

May 2006

4.17 SAP List Viewer in Web Dynpro for ABAP SAP List Viewer (ALV) is a flexible tool used to display lists and tabular structures. The tool provides common list operations as standard functions and can be enhanced by self-defined options. This allows you to use the ALV in a large range of application programs. For the end user, the standard output consists of a toolbar, a header, and the output table. The user can change and make settings for the column display, more complex sorting options, aggregations, and so on by using the additional dialog box. As the developer of the application, you have various options to define the appearance, function, and run-time behavior of this ALV output. You can also use the ALV component. You include this component in the component of your application (as with all other predefined components). You have all the means, therefore, to provide the user of your application with a powerful tool for displaying lists.

Features The ALV component is partly based on the Web Dynpro table [externaly] UI element. This means that many of the properties of the table element are supported. This includes the use of different cell editors, background colors, and size specifications. The following options are also available: ●

You determine which columns are contained in the user's column set, and which of these are visible when calling the ALV output.

●

You can sort and filter the values of the ALV output, and perform calculations.

●

You decide whether and to what extent the ALV output can be edited.

●

You determine which UI elements in the cells display the values of the columns.

●

You provide the UI elements in the toolbar with which the user can perform applicationspecific functions.

●

You determine whether and how user interactions in the ALV output are handled.

●

The user can save settings in different views.

●

You can configure special areas above and below the ALV output.

●

And much more…

4.17.1

Integration of the ALV in Your Application

Purpose If you want to use an ALV output in your application, you have to perform various steps, depending on what you want to achieve. The following variants show only the most important ways in which you can call the ALV: ●

Simple call without ALV configuration model You only display an ALV output. You do not want to make any changes.

Web Dynpro ABAP: Development in Detail

158

Advanced Concepts

●

May 2006

Simple call with ALV configuration model You want to change the standard output using your application. To do this you require the ALV configuration model.

●

ALV output in external view without ALV configuration model ALV output is just one element of many in a view. You do not want to change the ALV output. You do not need the ALV configuration model.

●

ALV output in external view with ALV configuration model ALV output is just one element of many in a view. You want to change the standard output using your application. To do this you require the ALV configuration model.

You will recognize the majority of the steps listed below from your work with the Web Dynpro components. Some of them, however, are tailored specifically for use with the ALV.

Prerequisites You must perform the following (ALV-independent) steps for all the above listed scenarios: ●

You generate a Web Dynpro component [page 2] for your application and save it as active.

●

You generate a context node [externaly] with the cardinality 0..n. The structure of the attributes in this context node (name and data type) and the structure of the internal data table that you connect to this context node in the next step match.

●

You connect your internal data table to the context node (for example, using the supply method). In doing so, you use the method BIND_TABLE from the interface IF_WD_CONTEXT_NODE [externaly].

●

You provide the DATA context node in the ALV interface controller with your application data using external context mapping [page 65].

Process Flow When the prerequisites listed above are satisfied, the procedure continues as follows (depending on the objective):

Simple call without ALV configuration model ...

Simple call with ALV configuration model ...

1. You define a component usage [page 58] for the ALV component SALV_WD_TABLE in your application component. In doing so, you specify a name for the component usage (for example, MY_ALV). You also define this component usage in your component controller. Since you need the ALV configuration model for your modifications, choose the with controller access [page 62] variant (component interface). 2. You embed the TABLE view of the ALV component SALV_WD_TABLE into a window of your component [externaly].

Web Dynpro ABAP: Development in Detail

159

Advanced Concepts

May 2006

3. To configure the ALV output, two more steps are necessary: ○

You instantiate [page 59] the used ALV component in a method of the component controller (for example, WDDOINIT).

○

You get the ALV configuration model [externaly] and with it the object model, as well as all field objects and column objects.

The description of all the classes and methods of the ALV configuration model can be found in the system in the package SALV_WD_CONFIG.

ALV output in external view without ALV configuration model ... ...

1. You decide whether you require the context node in the component controller or in the context of your application view. If necessary, you generate an appropriate context node in your view and map the context node from the component controller to it. 2. You define a component usage [page 58] for the ALV component SALV_WD_TABLE in your application component. In doing so, you specify a name for the component usage (for example, MY_ALV). You also define the usage of this component in the properties for your view. Since you do not need the ALV configuration model, choose the without controller access [page 59] variant (no component interface). 3. You generate the UI element ViewContainerUIElement [externaly] in the layout of your view [page 5] at the required position. 4. You have already embedded your view in the window of your application. Underneath this, you can see the name of the UI element ViewContainerUIElement that you have prepared in the previous step for the ALV output. You then embed the TABLE view for the SALV_WD_TABLE ALV component under this entry.

ALV output in external view with ALV configuration model ... ...

1. You decide whether you require the context node in the component controller or in the context of your application view. If necessary, you generate an appropriate context node in your view and map the context node from the component controller to it. 2. You define a component usage [page 58] for the ALV component SALV_WD_TABLE in your application component. In doing so, you specify a name for the component usage (for example, MY_ALV). You also define the usage of this component in the properties for your view. Since you need the object model for your modifications, choose the with controller access [page 62] variant (component interface). 3. You generate the UI element ViewContainerUIElement [externaly] in the layout of your view [page 5] at the required position. 4. You have already embedded your view in the window of your application. Underneath this, you can see the name of the UI element ViewContainerUIElement that you have prepared in the previous step for the ALV output. You then embed the TABLE view for the SALV_WD_TABLE ALV component under this entry. 5. To configure the ALV output, two more steps are necessary: ○

You instantiate [page 59] the used ALV component in a method of your view (for example, WDDOINIT).

○

You get the ALV configuration model [externaly] and with it the object model, as well as all field objects and column objects.

Web Dynpro ABAP: Development in Detail

160

Advanced Concepts

May 2006

The description of all the classes and methods of the ALV configuration model can be found in the system in the package SALV_WD_CONFIG.

4.17.1.1

Defining the Component Usage

To use an ALV output in your application, use the component SALV_WD_TABLE. You can integrate this ALV component as an external component into your Web Dynpro component. To do this, you define the component usage [page 58].

If you want to display multiple different ALV outputs, distinguish between these outputs by using unique names for the respective usage variants of the component. How you define the component usage depends upon how you want to use the ALV component. ●

If the ALV output is the only element on the screen, you define the component usage of the ALV component only in the component of your application (the top node in the hierarchy of the component, as it is displayed in the Component Editor [externaly]). This is the simplest case. You cannot configure the ALV output before it is displayed.

●

If the ALV output is the only element on the screen (as above), but you want to make changes to the appearance, function, or run-time behavior, specify the usage of the component in the properties of the component controller for your application. Choose the variant with controller access [page 62].

●

If, however, you want to insert the ALV output into a complex layout in a view of your application, define the component usage in the properties of the view (and not the component controller) in which the ALV output is to be displayed. Depending on whether you want to use the standard display of the ALV output, or whether you want to change it, choose either the without controller access [page 59] or the with controller access [page 62] version respectively.

4.17.1.2

Providing the Data

To provide the data you want to display in the ALV output, perform the following three steps: ●

Internal data table You provide an internal data table.

●

Context node You provide a suitable context node and attributes in the context of your application.

●

Transfer data to the ALV component You provide this context node for the ALV component.

Internal Data Table The data from the internal data table must be available in flat structures. This is the only prerequisite. The easiest way to do this is to use an existing DDIC structure.

Web Dynpro ABAP: Development in Detail

161

Advanced Concepts

May 2006

Context Node The ALV component requires a context node that can contain the data for the internal data table. This context node has the following properties: ●

It has the cardinality 0..n.

●

It only contains attributes and no subnodes. You generate an attribute for every column of your internal data table (with the same name and data type).

If the internal data table is based on a DDIC structure, the easiest way to generate the attributes of the context node is to use a DDIC structure. To transfer the data of the internal data table into the application context node, connect the data table to this node. To do this, use the method BIND_TABLE, for example, in the SUPPLY method of your controller.

Transferring Data to the ALV Component In the previous step, you created the entire structure of the ALV output in the context node. Now you must transfer this to the ALV component. You can do this in the following ways: ●

By means of external context mapping [page 65]

●

Using the method SET_DATA

As you may have defined a particular component usage for several different components (or different ALV components), you must specify the exact ALV component usage that the data for your context node contains for context mapping.

External Context Mapping The ALV component contains a separate context node known as DATA that must contain the structure and data of the ALV output to be able to display the required output. The easiest way to transfer the data to the DATA context node is to use external context mapping [page 65].

SET_DATA Method You can transfer the data of your context node to the ALV component as well by using the SET_DATA method (reference type IF_WD_CONTEXT_NODE). You can do this, for example, in the WDDOINIT method. For more information, see SET_DATA [page 225]. You specify the correct context node of your application as a parameter.

You also use the method SET_DATA if you want to specify another structure for your ALV output at a later date or time. In this case, however, you cannot use the method in the WDDOINIT method or another standard method. If the ALV output has already been displayed once, you can only define the data for the ALV component in an event handler.

The method SET_DATA always deletes any ALV configuration model that may exist. If you want to configure the ALV output, you must retrieve the ALV configuration model [page 164] again once the SET_DATA method has been run.

Web Dynpro ABAP: Development in Detail

162

Advanced Concepts

4.17.1.3

May 2006

Using the ALV Views

The ALV component contains the following views, which you can use as required: ●

TABLE This is the central ALV view. To display the ALV output, you require this view. The TABLE view is the container in which the ALV output is displayed. It is a fundamental part of the ALV component. You cannot, therefore, change the layout.

●

SERVICE This view contains the Settings dialog box with which the user can make changes to the settings for column display, sorting, filtering, and so on. By default, the view is displayed above the ALV output when the user chooses the Settings hyperlink in the toolbar. You use this view when you want to display the dialog box elsewhere on the screen.

Inserting a TABLE View You require the TABLE view if you want to display an ALV output in your application. You can insert the TABLE view in various ways: ●

You insert it directly into a window of your application. In this case, you cannot display any another element on the screen except for the ALV output.

●

You insert it into a cell of a view set [externaly] in your application.

●

You generate a UI element of the type ViewContainerUIElement [externaly] in the position you want in one of the views. You then insert the TABLE ALV view into this UI element.

4.17.1.4

Objects of the ALV Configuration Model

The following main areas are available for configuring your ALV output: ●

Table settings The data for the Table UI element includes the structure of the application data as well as the technical fields that determine the appearance or function of the ALV output. You can define, for example, whether the ALV output is to be displayed with a simple, two-dimensional table or as a hierarchy with a leading hierarchy column.

●

Field settings The fields describe the data that is used in the ALV output. The name of a field corresponds to the name of an attribute in the context node: All field objects are automatically generated from the specifications that you made in the context node. As a result, every attribute in the context node has a representative with the same name in the ALV configuration model.

Web Dynpro ABAP: Development in Detail

163

Advanced Concepts

May 2006

By connecting the internal data table to the context node you fulfill all the prerequisites to start your application with ALV. You can sort the data with statements from your application, filter it, or perform applications. All these functions (ALV services) are essentially field object methods. You cannot, however, display the data yet. To do this, you need columns. ●

Column settings The column objects are visible elements that define the ALV output. The columns have the same names as the corresponding field objects and attributes in the context node. The column object contains settings as to whether and how the data for the field of the same name is displayed in the ALV output. If you do not want to display the values of the field, you can delete the corresponding column object. You use the column settings to manage a list of all the column objects (the columns for the Table UI elements).

●

Standard function settings ALV provides a number of functions. The following list shows the most important of these standard ALV functions: ○

ALV services: Sorting, filtering, aggregating (calculations), as well as the option to make all the necessary settings for these services.

○

Settings you can provide for editable ALV output, such as inserting and deleting rows.

○

Exporting the ALV output to Microsoft Excel or generating a print version in PDF format.

All these standard functions are accessible using the relevant UI elements. You can hide or show these UI elements by using the standard function settings. ●

Application-specific function settings You can define as many functions as you want in your application and provide suitable UI elements to the user with which he or she can then run these functions.

As an application developer, you can configure all these areas. You can use a complete object model for object-oriented ABAP programming to do this. You can use it to change the ALV output, if necessary. There is an interface class for each of the areas listed here. They are implemented by the central class CL_SALV_WD_CONFIG_TABLE (see Class Diagram [page 165]).

All the classes that are required for the configuration of the ALV output can be found in the system in the package SALV_WD_CONFIG.

4.17.1.5

Getting the ALV Configuration Model

To be able to use the ALV configuration model, use a method from the class IWCI_SALV_WD_TABLE in, for example, WDDOINIT. You choose one of the following methods: ...

●

GET_MODEL The system returns a complete ALV configuration model with all the column objects and field objects.

Web Dynpro ABAP: Development in Detail

164

Advanced Concepts

May 2006

This is the default variant. The method does not have any parameters. ●

GET_MODEL_EXTENDED The system returns all the field objects (as above) but it only supplies the column objects as and when needed. If, for example, you want to manage a large number of field objects but you only want to display a few columns, create the field objects first and then generate the column objects you require to display the contents later. The parameter S_PARAM from the method GET_MODEL_EXTENDED (type IF_SALV_WD_TABLE=>S_TYPE_PARAM_GET_MODEL) consists of the following fields: ○

DEFAULT_COLUMNS Here you can determine whether the column objects are to be generated or not.

○

DEFAULT_FIELDS This parameter is not currently used.

You now have all the objects [page 165] needed to configure the ALV output as required.

You can specify a new internal data table for the ALV output [page 161] at any point in the future. To do this, use the method SET_DATA. However, by using this method you also automatically delete the entire ALV configuration model with all the fields and column objects. To make the configuration model available to the new data table again, use one of the methods GET_MODEL or GET_MODEL_EXTENDED again.

4.17.1.6

Class Diagram

The object model for the ALV configuration model consists of the following classes and interfaces:

Web Dynpro ABAP: Development in Detail

165

Advanced Concepts

May 2006

CL_SALV_WD_ CONFIG_TABLE

IF_SALV_WD_ TABLE_SETTINGS

IF_SALV_WD_ COLUMN_SETTINGS

IF_SALV_WD_ STD_FUNCTIONS

CL_SALV_WD_ COLUMN

IF_SALV_WD_ FIELD_SETTINGS

IF_SALV_WD_ FUNCTION_SETTINGS

CL_SALV_WD_ FIELD

CL_SALV_WD_ FUNCTION

CL_SALV_WD_ CV_STANDARD

IF_SALV_WD_ FILTER

CL_SALV_WD_ FILTER_RULE

CL_SALV_WD_ COLUMN_HEADER

IF_SALV_WD_ SORT

CL_SALV_WD_ SORT_RULE

IF_SALV_WD_ AGGR

CL_SALV_WD_ AGGR_RULE

CL_SALV_WD_ HEADER

CL_SALV_WD_ A_HEADER IF_SALV_WD_ TABLE_CELL_EDITOR

CL_SALV_WD_ FE

IF_SALV_WD_ COLUMN_REF

CL_SALV_WD_ UIE_BUTTON

CL_SALV_WD_ FE_BUTTON

IF_SALV_WD_ COLUMN_SERVICE_REF

CL_SALV_WD_ UIE_INPUT_FIELD

CL_SALV_WD_ FE_INPUT_FIELD

IF_SALV_WD_ COLUMN_HIERARCHY

…

… Class Interface

This class diagram has been simplified. Some superclasses have been left out. The exact structures can be found in the system in the package SALV_WD_CONFIG.

4.17.2

Managing ALV Output Areas

The ALV output consists of the following different areas which, to a certain extent, you can generate, change, and remove independently of each other. ●

Header area (see Header and Footer Areas [page 176])

●

ALV output header [page 167]

●

Fields [page 168] and columns [page 169]

Web Dynpro ABAP: Development in Detail

166

Advanced Concepts

May 2006

●

Column headers [page 171]

●

Footer and paginators [page 174]

●

Footer area (see Header and Footer Areas [page 176])

This section describes how you can use the different areas in your application.

4.17.2.1

ALV Output Header

By default, the ALV output has no header. You can generate a header and display it above the ALV output. The header can have the following parts: ●

Text

●

Graphic

●

Tooltip

You can make the following settings for the header of the ALV output: ●

Generate, get, and delete a header object

●

Set wording for header

●

Set graphic path for header

●

Set position of graphic for header

●

Set wording for tooltip

Generating, Getting, and Deleting a Header Object The header of the ALV output is an instance of the class CL_SALV_WD_HEADER. To generate or delete the object, use the methods of the interface class IF_SALV_WD_TABLE_SETTINGS (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Creating, Getting, and Deleting Header Objects Function

Method

Generate header object

CREATE_HEADER

Get header object

GET_HEADER

Delete header object

DELETE_HEADER

Setting Wording for Headers The header of the ALV output has the type STRING. To define the header, use methods of the class CL_SALV_WD_HEADER. Methods for Wording of Headers Function

Method

Set wording for header

SET_TEXT

Get wording for header

GET_TEXT

Web Dynpro ABAP: Development in Detail

167

Advanced Concepts

May 2006

Setting Graphic Paths for Headers You can display any graphic in the header of your ALV output as long as it is suitable for the Web Dynpro environment (see Handling Web Icons [page 112]). To define the path or ID of the graphic file, use the methods of the class CL_SALV_WD_HEADER. Methods for Graphic File Paths Function

Method

Set path or ID for graphic

SET_IMAGE_SOURCE

Get path or ID for graphic

GET_IMAGE_SOURCE

Setting Position of Graphics for Headers You can choose whether the graphic displayed in the header is placed before or after the header text. To do this, use the methods of the class CL_SALV_WD_HEADER. Methods for Placing Graphics in Headers Function

Method

Set position within header

SET_IMAGE_FIRST

Get position within header

GET_IMAGE_FIRST

Setting Wording for Tooltip The tooltip of the header becomes visible when the user places the cursor over the header of an ALV output. To specify the wording of the tooltip, use the methods of the class CL_SALV_WD_HEADER. Methods for Header Tooltip Function

Method

Set wording for tooltip

SET_TOOLTIP

Get wording for tooltip

GET_TOOLTIP

4.17.2.2

Field

You mainly use field objects in two situations: ●

You want to apply standard ALV functions (ALV services) to the ALV output before displaying it (see Predefining Standard ALV Functions [page 190]).

●

You want to assign properties to the cells of a field that are defined for another field (see Assigning Properties to Columns and Rows [page 183]).

In addition to these standard ALV functions, you can also make settings for field objects: ●

Get field object

●

Get field name

●

Create and delete field object

Web Dynpro ABAP: Development in Detail

168

Advanced Concepts

May 2006

Getting a Field Object In order to make the required settings for a field, you first have to get the instance of the field. You can decide whether you address a specific field object by its name or get all field objects at once in order to handle them one after another. In both cases you use the methods of the interface class IF_SALV_WD_FIELD_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Getting Field Objects Function

Method

Get single field object

GET_FIELD

Get all field objects

GET_FIELDS

Getting Field Names Use the class CL_SALV_WD_FIELD to get the name of the current field instance. Method for Getting Field Names Function

Method

Get field name

GET_FIELDNAME

Creating and Deleting Field Objects When you call the ALV, appropriate field objects are created automatically from the specifications for the attributes of your context node (see Getting the ALV Configuration Model [page 164]). However, in exceptional cases you may need to create or delete field objects.

When creating a field object you enter its technical name. This name must match the name of an attribute in the context node of your application. You use the methods of the interface class IF_SALV_WD_FIELD_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Creating and Deleting Field Objects Function

Method

Create field object

CREATE_FIELD

Deleted field object

DELETE_FIELD

4.17.2.3

Columns

Depending on how you got the ALV configuration model, there is either just one, identically named column object for each attribute of your context node, or there is no column object at all (see Getting the ALV Configuration Model [page 164]). In the latter case, you must generate the column objects required for the desired display of the ALV output separately. You can make the following settings for column objects: â&#x2014;?

Get column object

Web Dynpro ABAP: Development in Detail

169

Advanced Concepts

May 2006

●

Get technical name for a column

●

Create and delete a column object

●

Set up a column header (see Column Headers [page 171])

●

Change the position of a column (see Position of Columns [page 173])

Further Information ●

For information on designing the appearance of a column, see the sections below Appearance of ALV Output [page 182].

●

For information on filtering, sorting, and aggregating columns, see Predefining Standard ALV Functions [page 190].

Getting a Column Object In order to make the required settings for a column, you first have to get the instance of the column. You can decide whether you address a specific column object by its name or get all column objects at once in order to handle them one after another. In both cases you use the methods of the interface class IF_SALV_WD_COLUMN_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Getting Column Objects Function

Method

Get individual column object

GET_COLUMN

Get all column objects

GET_COLUMNS

Getting the Technical Name for a Column Use the class CL_SALV_WD_COLUMN to get the name of the current column instance. Method for Getting the Technical Name of a Column Function

Method

Get technical name

GET_ID

Creating and Deleting Column Objects If, when getting the ALV configuration model, you defined that the system should not generate column objects, you need to generate the column objects required for displaying the ALV data yourself in your application. The user's column set contains all columns for which a column object exists. If you do not want a column to appear in the user’s column set, you have to delete the corresponding column object.

When creating a column object, you enter its technical name. This name must match the name of an attribute in the context node of your application. To generate or delete a column object, use the methods of the interface class IF_SALV_WD_COLUMN_SETTINGS (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Generating and Deleting Column Objects

Web Dynpro ABAP: Development in Detail

170

Advanced Concepts

May 2006

Function

Method

Create column object

CREATE_COLUMN

Delete column object

DELETE_COLUMN

4.17.2.3.1

Column Headers

By default, each column in the ALV output has a column header. You do not have to generate the objects in question first. You can change a column header. To do this, you can set up the following component parts: ●

Text

●

Graphic

●

Tooltip

You are able to make the following settings for a column header: ●

Generate, get, and delete object for column header

●

Set wording of column header

●

Specify path to graphic in column header

●

Set position of graphic in column header

●

Set wording for tooltip

Information on Standard Column Headers Standard column headers only contain text. The wording depends on the context node attribute: ●

If the attribute has no DDIC reference: By default, the system uses the technical name of the attribute for the column header.

●

If the attribute has a DDIC reference: The system assigns column headers as follows: ○

If field labels have been defined for the DDIC data element, the system uses the short text of the DDIC data element as the column header.

○

If no field labels have been defined, the system uses the technical name of the DDIC data element.

Generating, Getting, and Deleting Objects for Column Headers The column header of a column in your ALV output is an instance of the class CL_SALV_WD_COLUMN_HEADER. A column header object can exist for every column object. To get, generate, or delete a column header object, use the methods of the class CL_SALV_WD_COLUMN. Methods for Getting, Generating, and Deleting Column Headers

Web Dynpro ABAP: Development in Detail

171

Advanced Concepts

May 2006

Function

Method

Get column header object

GET_HEADER

Generate column header object

CREATE_HEADER

Delete column header object

DELETE_HEADER

Defining the Wording of Column Headers You can define the text to be displayed as a column header. You have the following options: ●

You can enter free text.

●

You can enter a separate DDIC data element whose short field label is to be used as the column header.

●

You can enter a separate DDIC element and define which of the field labels of the DDIC data element is to be used as the column header.

To specify the wording of the column header, use the methods of the class CL_SALV_WD_COLUMN_HEADER. Methods for the Wording of Column Headers Function

Method

Define free text as column header

SET_TEXT

Get wording for column header

GET_TEXT

Specify DDIC data element whose field label is to be used as the column header

SET_BINDING_ELEMENT

Get name of the DDIC data element

GET_BINDING_ELEMENT

Specify type of field label to be used as column header

SET_BINDING_FIELD

Get type of field label to be used as column header

GET_BINDING_FIELD

Setting Path of Graphic in Column Headers You can display any graphic in a column header as long as it is suitable for the Web Dynpro environment (see Handling Web Icons [page 112]). To define the path or ID of the graphic file, use the methods of the class CL_SALV_WD_COLUMN_HEADER. Methods for Defining Paths of Graphic Files Function

Method

Set path or ID for graphic

SET_IMAGE_SOURCE

Get path or ID for graphic

GET_IMAGE_SOURCE

Setting Positions of Graphics in Column Headers You can choose whether graphics displayed in column headers are placed before or after the text. To do this, use the methods of the class CL_SALV_WD_COLUMN_HEADER. Methods for Placing Graphics in Headers Function

Method

Set position within header

SET_IMAGE_FIRST

Web Dynpro ABAP: Development in Detail

172

Advanced Concepts

May 2006

Get position within header

GET_IMAGE_FIRST

Setting Wording for Tooltips The tooltip of a column header becomes visible when the user places the cursor over the header of a column. To specify the wording of tooltips, use the methods of the class CL_SALV_WD_COLUMN_HEADER. Methods for Column Header Tooltips Function

Method

Set wording for tooltip

SET_TOOLTIP

Get wording for tooltip

GET_TOOLTIP

4.17.2.3.2

Position of Columns

By default, all columns are arranged in the same order as the attributes in the context node of your application. You can change the sequence of the columns. You can do this in the following ways: â&#x2014;?

Change the position number

â&#x2014;?

Fix the column

For information on the sequence of hierarchy columns, see Table as Hierarchy [page 189].

Changing the Position Number Every column is automatically assigned the position number 0 initially. You can change the position of a column by changing this position number. The position number does not have to be unique.

Columns with the position number 0 are always left-justified. This means that if you want to align a column to the left, you must give all other columns a higher position number the column in question. You can also use negative numbers for position numbers. This means that you can give a single column an appropriate position number without changing the 0 of all the other columns. To change the position number of a column, use the methods of the class CL_SALV_WD_COLUMN. Methods for Changing the Position Number Function

Method

Set position number

SET_POSITION

Get position number

GET_POSITION

Fixing a Column You can fix columns. This has the following effects:

Web Dynpro ABAP: Development in Detail

173

Advanced Concepts

May 2006

●

You move the column in question to the edge of the ALV output.

●

The column can then no longer be moved when scrolling sideways with the horizontal paginators.

When fixing a column, you specify whether the column is to be fixed to the left-hand side or the right-hand side. This allows you to generate up to three blocks of columns: The leftjustified columns, the unfixed columns, and the right-justified columns. You can also change the position number of a column to fix its position (see above). This allows you to arrange all columns in a block according to their position numbers. To fix columns, use the methods of the class CL_SALV_WD_COLUMN. Methods for Fixing Columns Function

Method

Fix column

SET_FIXED_POSITION

Check whether a column is fixed and where it is fixed

GET_FIXED_POSITION

4.17.2.4

Footer and Paginators

The ALV output has its own footer that always contains the vertical paginators and optionally contains the horizontal paginators too. You can make the following settings for the footer and paginators: ●

Show or hide the footer

●

Show horizontal paginators

●

Scroll horizontally and vertically

Further Information ●

For information on defining the number of visible rows and columns, see Size of ALV Output, Columns, and Cells [page 184].

●

For information on the difference between scrollable and fixed columns, see Position of Columns [page 173].

Showing/Hiding the Footer The ALV output normally has too many entries to display at once. The user cannot use the scroll bars to view the invisible entries - instead, he or she must use the paginators in the footer to navigate to the required location. If your ALV output contains a lot of data records, you must make sure that you provide paginators for the user: You show the footer containing the paginators. You can define whether the footer containing the paginators is visible, and when it is visible: ●

Never Even if entries are hidden in the invisible area, the footer is not shown.

●

Always

Web Dynpro ABAP: Development in Detail

174

Advanced Concepts

May 2006

Even when all entries are visible at any time, the footer is shown. In this case, the paginators are deactivated. â&#x2014;?

Only when required The footer is only visible if there are more rows and columns than can be displayed in the ALV output.

To show or hide the footer, use the methods of the interface class IF_SALV_WD_TABLE_SETTINGS (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Showing the Footer Function

Method

Show footer

SET_FOOTER_VISIBLE

Check whether the footer is shown

GET_FOOTER_VISIBLE

Showing Horizontal Paginators By default, all columns marked as visible are displayed. The user may have to navigate to the required location using the horizontal scroll bar of the browser window. The horizontal paginators are hidden. You can define how many scrollable columns are visible at once, thereby determining the width of the ALV output. The user requires the paginators in order to move the invisible columns into the visible area. This is because he or she cannot use the scroll bar for this.

The vertical paginators are always visible, regardless of the number of visible rows you choose. However, the horizontal paginators are only visible if you define the number of scrollable columns. If you set this number high enough for all columns to be visible, the paginators are deactivated. To define the number of visible columns and thereby determine whether to show or hide the paginators, use the methods of the interface class IF_SALV_WD_TABLE_SETTINGS (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Showing Horizontal Paginators Function

Method

Define number of scrollable columns

SET_SCROLLABLE_COL_COUNT

Get number of scrollable columns

GET_SCROLLABLE_COL_COUNT

Scrolling Horizontally and Vertically The user requires the pushbuttons of the paginators in order to move invisible columns or rows into the visible area of the ALV output. He or she can also use the input fields of the paginators to enter the row or column to be displayed as the first visible row or column in the ALV output. You can use the ALV configuration model to define which row or column is displayed first regardless of whether the footer is shown.

Web Dynpro ABAP: Development in Detail

175

Advanced Concepts

May 2006

To specify the first row, use the index of the row. To specify the first column, use the technical name of the column. To scroll to the required column or row in the ALV output, use the methods of the interface class IF_SALV_WD_TABLE_SETTINGS (implementing class CL_SALV_WD_CONFIG_CLASS). Methods for Horizontal and Vertical Scrolling Function

Method

Specify row to be displayed as the first row

SET_FIRST_VISIBLE_ROW

Get row to be displayed as the first row

GET_FIRST_VISIBLE_ROW

Specify column to be displayed as the first column

SET_FIRST_VISIBLE_SCROLL_COL

Get column to be displayed as the first column

GET_FIRST_VISIBLE_SCROLL_COL

4.17.2.5

Header and Footer Areas

You are able to design the areas above and below the ALV output using various elements. To do this, you use design objects. You can use as many elements of different element types as you want in order to form a design object. Then you display it at your desired position.

All classes and methods for the design object are found in the system in the package SALV_FORM_ELEM.

Element Types and Layout Forms You use elements of the following element types for your design object: ●

Header element (header info)

●

Text element with or without label (text label)

●

Action information

The elements only differ in appearance. No functions are linked with the various element types. These elements can be arranged within your design object. To do this, choose between two forms of layout: ●

Single element You generate an element and display it in the required position.

●

Row-type layout You arrange as many elements as you want in a row, one after the other.

●

Table-type layout

Web Dynpro ABAP: Development in Detail

176

Advanced Concepts

May 2006

You arrange as many elements as you want in rows and columns.

You are able to combine the two layout forms with one another as you wish, that is, you can insert rows into a table and vice versa.

Context Nodes TOP_OF_LIST and END_OF_LIST The ALV component provides the two context nodes TOP_OF_LIST and END_OF_LIST. Each contains an attribute CONTENT. These context nodes hold the data of your design objects for the header and footer areas of the ALV output. You define context mapping to a node with the same name in the context of your application and set the attribute CONTEXT of your context node to your design object.

Setting Up a Design Object Proceed as follows to set up a design object for the header and footer areas: ●

Map the context nodes TOP_OF_LIST and END_OF_LIST of the ALV component to the context of your application (see Context Mapping [page 16]).

●

Generate a design object. To do this, use either the row-type or the table-type layout. You insert the required elements into this layout (see Creating Design Objects and Elements [page 178]).

●

Where required, you make various settings for the elements (see Design Object Settings [page 179]).

●

Set the design object as a value of the attribute CONTENT in the context node.

Showing and Hiding Design Objects By default, the design object for the header area and the design object for the footer header are both shown. You can hide and show these two design objects separately. You use the methods of the interface class IF_SALV_WD_TABLE_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Showing/Hiding Design Objects Function

Method

Show or hide the design object for the header area

SET_TOP_OF_LIST_VISIBLE

Check whether the design object for the header area is shown or hidden

GET_TOP_OF_LIST_VISIBLE

Show or hide the design object for the footer area

SET_END_OF_LIST_VISIBLE

Check whether the design object for the footer area is shown or hidden

GET_END_OF_LIST_VISIBLE

Web Dynpro ABAP: Development in Detail

177

Advanced Concepts

4.17.2.5.1

May 2006

Creating Design Objects and Elements

Creating a Design Object Firstly, you define the basic layout for your design object. You decide whether to display a single element, a sequence of elements in a row, or elements arranged in multiple rows and columns. You use one of the following classes for this purpose: Classes for the Layout of Design Objects Layout

Class

Single element

See Elements Types and Their Classes (except for the element type Label)

Row-type layout

CL_SALV_FORM_LAYOUT_FLOW

Table-type layout

CL_SALV_FORM_LAYOUT_GRID

When creating an element of the element type Label, you must always specify the corresponding text element. This means that you cannot use this element as a single element in a design object.

Creating an Element After you have created a layout for a design object (see above), you can use methods to create elements with the various element types: These methods can be found in the classes CL_SALV_FORM_LAYOUT_FLOW and CL_SALV_FORM_LAYOUT_GRID. Methods for Creating Elements for a Design Object Function

Method

Create row-type layout (for nested layouts)

CREATE_FLOW

Create table-type layout (for nested layouts)

CREATE_GRID

Create text element

CREATE_TEXT

Create a label for a specific text element

CREATE_LABEL

Create a header element

CREATE_HEADER_INFORMATION

Create action information

CREATE_ACTION_INFORMATION

You use the elements to create objects of the following classes: Element Types and Their Classes Element Type

Class

Row-type layout (for nested layouts)

CL_SALV_FORM_LAYOUT_FLOW

Table-type layout (for nested layouts)

CL_SALV_FORM_LAYOUT_GRID

Text element

CL_SALV_FORM_TEXT

Label element

CL_SALV_FORM_LABEL

Header element

CL_SALV_FORM_HEADER_INFO

Action information

CL_SALV_FORM_ACTION_INFO

Web Dynpro ABAP: Development in Detail

178

Advanced Concepts

May 2006

No parameters are required for the row-type layout. However, for the table-type layout you specify the parameters ROW and COLUMN. Exception: When creating an element of the element type Label, you must always specify the corresponding text element (R_LABEL_FOR) too, regardless of the layout type.

4.17.2.5.2

Design Object Settings

You can make settings for a design object, each contained element, and, in the case of a table-type layout, for the individual columns.

Design Object Settings You can make the following settings for a design object and for design object elements: Settings for Row-Type Layout (CL_SALV_FORM_LAYOUT_FLOW) Function

Method

Move element within the layout

SET_ELEMENT

Get number of elements in row-type layout

GET_ELEMENT_COUNT

Set tooltip for design object

SET_TOOLTIP

Get tooltip for design object

GET_TOOLTIP

Settings for Table-Type Layout (CL_SALV_FORM_LAYOUT_GRID) Function

Method

Move element within the layout

SET_ELEMENT

Append empty row (FLOW object)

ADD_ROW

Get number of rows

GET_ROW_COUNT

Show lines between columns and rows

SET_GRID_LINES

Set tooltip for design object

SET_TOOLTIP

Get tooltip for design object

GET_TOOLTIP

Settings for Elements You have quite similar functions available for the different element types: Settings for Element Types Function

Method

Class

Set wording for element

SET_TEXT

CL_SALV_FORM_TEXT

Get wording for element

GET_TEXT

CL_SALV_FORM_LABEL

Set tooltip for element

SET_TOOLTIP

CL_SALV_FORM_HEADER_INFO

Get tooltip for element

GET_TOOLTIP

CL_SALV_FORM_ACTION_INFO

Web Dynpro ABAP: Development in Detail

179

Advanced Concepts

May 2006

Set corresponding text element

SET_LABEL_FOR

Get corresponding text element

GET_LABEL_FOR

CL_SALV_FORM_LABEL

Width and Alignment in a Column A column in the table-type layout of your design object is an object of the class CL_SALV_FORM_GRID_COLUMN. Whenever you create an element in your layout and enter a column that does not yet exist (for example, COLUMN = 2), one or more objects of this class are generated as appropriate. You can use the class CL_SALV_FORM_LAYOUT_GRID to create several column objects in one go. Methods for a Column in a Table-Type Layout Function

Method

Get column

GET_COLUMN

Create columns in table layout

SET_COLUMN_COUNT

Get number of columns in table layout

GET_COLUMN_COUNT

You can use the column object to define the width of the column and the alignment of elements in the column. Methods for Width and Alignment Function

Method

Set width of column

SET_WIDTH

Get width of column

GET_WIDTH

Set horizontal alignment of elements

SET_H_ALIGN

Get horizontal alignment of elements

GET_H_ALIGN

Width and Alignment of a Single Element You can define the width and alignment of elements individually. For technical reasons, you must determine whether the element is in a row-type or table-type layout: ●

For a row-type layout, use the class CL_SALV_FORM_LAYOUT_DATA_FLOW

●

For a table-type layout, use the class CL_SALV_FORM_LAYOUT_DATA_GRID

To change the layout data, first cast the element to one of these classes. Methods for Layout Data of an Element Function

Method

Get layout data on the alignment and width of the element

GET_LAYOUT_DATA

To define the width and alignment of the element, now use the methods of the casted classes: Methods for the Width and Alignment of an Element Function

Method

Set width

SET_WIDTH

Web Dynpro ABAP: Development in Detail

180

Advanced Concepts

May 2006

Get width

GET_WIDTH

Set horizontal alignment

SET_H_ALIGN

Get horizontal alignment

GET_H_ALIGN

4.17.2.5.3

Examples of Design Objects

Table-Type Layout at the Beginning of the ALV Output The following example shows how you insert a design object with a table-type layout at the beginning of the ALV output: ... *... TOP_OF_LIST data: lr_node type ref to if_wd_context_node, lr_grid type ref to cl_salv_form_layout_grid, lr_text type ref to cl_salv_form_text, lr_label type ref to cl_salv_form_label. create object lr_grid. lr_text = lr_grid->create_text( text

= '1.2 TEXT'

row

= 1

column = 2 ). lr_label = lr_grid->create_label( text

= '1.1 LABEL'

row

= 1

column = 1 r_label_for = lr_text ). lr_text = lr_grid->create_text( text

= '2.2 TEXT'

row

= 2

column = 2 ). lr_label = lr_grid->create_label( text

= '2.1 LABEL'

row

= 2

column = 1 r_label_for = lr_text ). lr_node = wd_context->get_child_node( name = 'TOP_OF_LIST' ).

Web Dynpro ABAP: Development in Detail

181

Advanced Concepts

May 2006

call method lr_node->set_attribute exporting value = lr_grid name

= 'CONTENT'.

...

Row-Type Layout at End of ALV Output The following example shows how you display an element of type Text at the end of the ALV output: ... *... END_OF_LIST data: lr_node type ref to if_wd_context_node, lr_flow type ref to cl_salv_form_layout_flow, lr_text type ref to cl_salv_form_text. create object lr_flow. lr_text = lr_flow->create_text( text = 'MyText'). lr_node = wd_context->get_child_node( name = 'END_OF_LIST' ). call method lr_node->set_attribute exporting value = lr_flow name

= 'CONTENT'.

...

4.17.3

Appearance of ALV Output

There are different ways of changing the appearance of the ALV output. You can define the following: ●

Size of ALV output, columns, and cells [page 184]

●

Visibility of individual areas [page 185]

●

Color of ALV output, columns, and cells [page 186]

●

Text properties [page 187]

●

Lines between columns and rows [page 188]

●

Table as a hierarchy [page 189]

Web Dynpro ABAP: Development in Detail

182

Advanced Concepts

4.17.3.1

May 2006

Assigning Properties to Columns and Cells

You can assign most of the properties that affect the appearance of columns in the ALV output in the following two ways: ●

You assign the property to the entire column. Each cell in the column then receives this property.

●

In another field in each cell, you define information on how the cell in question is to appear in the current column. You then assign this field to the current column. This allows you to assign the required properties to cells individually.

You can assign the following properties like this: ●

Background color of a column ((SET_CELL_DESIGN or SET_CELL_DESIGN_FIELDNAME)

●

Cell variant (SET_SELECTED_CELL_VARIANT or SET_SEL_CELL_VARIANT_FIELDNAME)

Cell Editor Properties Some properties for the appearance of a cell are connected to the cell editor used in the cell. This means that the properties of the cell editor define how a column is displayed. The following is also true for these properties: They can be valid for all instances of the editor, or they can be overridden by information in another field.

In a column, you use the cell editor BUTTON. This causes each cell to be displayed as a button. You want to hide some of the cells in this column. Because visibility is a property of the button, and not of the column, you have to use a workaround to hide the cell: ●

You generate an object of the class CL_SALV_WD_UIE_BUTTON (for example, lr_button).

●

A different field (for example, BUTTON_VIS) contains information on the visibility of each cell You assign this field to the button lr_button:

lr_button->set_visible_fieldname( ‘BUTTON_VIS’ ). ●

You then assign the button to the column (for example, lr_column) as a cell editor:

lr_column->set_cell_editor( lr_button ). This means that the field BUTTON_VIS determines the cells of the column lr_column in which the button is visible. Below are additional examples of properties that you assign using the cell editor: ●

Font type used in TEXT_VIEW (SET_DESIGN or SET_DESIGN_FIELDNAME)

●

Graphic for a selected toggle button (SET_CHECKED_IMAGE_SOURCE or SET_CHECKED_IMG_SRC_FIELDNAME)

●

Size of the progress bar in the ProgressIndicator (SET_PERCENT_VALUE or SET_PERCENT_VALUE_FIELDNAME)

●

And much more…

Web Dynpro ABAP: Development in Detail

183

Advanced Concepts

May 2006

The possibilities for this procedure are highly dependent on which UI element the cell editor is handling.

4.17.3.2

Size of ALV Output, Columns, and Cells

By default, the size of the ALV output, columns, and rows depends on their content. In other words: ●

A column is at least as wide as its widest cell.

●

The ALV output is at least as wide as all its columns together.

●

A row is at least as high as its highest cell.

You can easily increase the width of the ALV output and columns by specifying the required width. However, to reduce the size, you firstly have to fix the layout of the ALV output. This assigns the same width to all columns. You can then specify the required column width. You can make the following settings for the size of the individual areas: ●

Change width

●

Fix table layout

You can only control the height of the rows by content (for example, by using a particular graphic size or several lines of text).

Changing the Width To change the width of an area, use the methods of the classes of the respective areas. Methods for Changing the Width Function

Class

Method

Set width of ALV output

IF_SALV_WD_TABLE_SETTINGS

SET_WIDTH

Set width of column

CL_SALV_WD_COLUMN

Set width of cell Only with the following cell editors: Button

CL_SALV_WD_UIE_BUTTON

Dropdown list box

CL_SALV_WD_UIE_DROPDOWN_

SET_WIDTH or SET_WIDTH_FIELDNAME

BY_KEY Image

CL_SALV_WD_UIE_IMAGE

InputField

CL_SALV_WD_UIE_INPUT_FIELD

ProgressIndicator

CL_SALV_WD_UIE_PROGR_ INDICATOR

Toggle Button

CL_SALV_WD_UIE_TOGGLE_ BUTTON

Get width of ALV output

IF_SALV_WD_TABLE_SETTINGS

Web Dynpro ABAP: Development in Detail

GET_WIDTH

184

Advanced Concepts

Get width of the column

May 2006

CL_SALV_WD_COLUMN

Get width of cell (only with cell editors listed above)

GET_WIDTH or GET_WIDTH_FIELDNAME

Fixing the Table Layout Fixing the layout of the ALV output can be used to make columns narrower than their content dictates. You use the methods of the interface class IF_SALV_WD_TABLE_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Fixing the Table Layout Function

Method

Fix table layout

SET_FIXED_TABLE_LAYOUT

Check whether the table layout is fixed

GET_FIXED_TABLE_LAYOUT

4.17.3.3

Visibility of Individual Areas

You can show or hide the different areas of the ALV output.

If an area is contained in an invisible area, the contained area is also invisible. You can show and hide the following areas separately: ●

Entire ALV output

●

Individual columns

●

Every UI element used as a cell editor or cell variant

●

Entire toolbar with all functions

●

Individual UI elements of standard ALV functions in the toolbar

●

Footer with paginators

●

Design object for the header area of the ALV output

●

Design object for the footer area of the ALV output

To hide another object, such as the header of the ALV output or a column header, you have to delete the object in question. Classes and Methods for Hiding Areas Area

Class

Method

Entire ALV output

IF_SALV_WD_ TABLE_SETTINGS

SET_VISIBLE

Individual column

CL_SALV_WD_

Web Dynpro ABAP: Development in Detail

GET_VISIBLE

185

Advanced Concepts

May 2006

COLUMN Every UI element used as a cell editor or cell variant

CL_SALV_WD_UIE (base class of all UI elements)

Entire toolbar with all functions

IF_SALV_WD_ FUNCTION_SETTINGS

Footer with paginators

IF_SALV_WD_ TABLE_SETTINGS

Design object for the header area of the ALV output

IF_SALV_WD_ TABLE_SETTINGS

Design object for the footer area of the ALV output

IF_SALV_WD_ TABLE_SETTINGS

Individual UI elements of standard ALV functions in the toolbar

IF_SALV_WD_ STD_FUNCTIONS

SET_<standard function>_ ALLOWED IS_<standard function>_ ALLOWED

4.17.3.4

Color of ALV Output, Columns, and Cells

You can influence the color design of various areas of the ALV output. The following options are available: ●

ALV output You can choose between two variants: ○

Standard colors All rows and columns have the same color

○

Alternate The rows of the ALV output are alternate between light and dark

You only have these options if write-protection has been activated (see WriteProtection and Activation [page 215]). ●

Column You can change the background color of a column. You can use pre-configured semantic colors for this (see TableColumn Properties [externaly]).

You only have these options if write-protection has been activated (see WriteProtection and Activation [page 215]). ●

Cell variants You can specify a background color for a cell variant. You can use pre-configured semantic colors for this (see TableColumn Properties [externaly]).

Web Dynpro ABAP: Development in Detail

186

Advanced Concepts

May 2006

You only have these options if write-protection has been activated (see WriteProtection and Activation [page 215]). ●

Cell The only UI element whose color you can change is the cell editor TEXT_VIEW. Here, you can choose the combination of background and text color that you want to use (see SemanticColor in TextView Properties [externaly]).

You also have this option in the editable ALV. Methods for Changing the Colors Area

Class

Method

ALV output

IF_SALV_WD_ TABLE_SETTINGS

SET_DESIGN

CL_SALV_WD_ COLUMN

SET_CELL_DESIGN

CL_SALV_WD_ CV_STANDARD

SET_CELL_DESIGN or SET_CELL_DESIGN_FIELDNAME

Column Cell variant

GET_DESIGN GET_CELL_DESIGN

GET_CELL_DESIGN or GET_CELL_DESIGN_FIELDNAME Cell

CL_SALV_WD_ UIE_TEXT_VIEW

SET_SEMANTIC_COLOR or SET_SEMANTIC_COLOR_FIELDNAME GET_SEMANTIC_COLOR or GET_ SEMANTIC_COLOR_FIELDNAME

4.17.3.5

Text Properties

You can affect how text is displayed in individual areas of the ALV output as follows: ●

Horizontal alignment within a column

●

Horizontal alignment within a cell variant

●

Font size and style in a cell This function is only available in the cell editor TEXT_VIEW. Here, you can choose the pre-configured formatting that you want to use (see Design in TextView Properties [externaly]). You can also set the reading direction here.

●

Line break for a cell This function is only available in the cell editors TEXT_VIEW, LINK_TO_ACTION, and LINK_TO_URL. If the text contains characters that permit a line break (for example, spaces and hyphens), the text can be distributed across more than one line.

●

Font color in a cell (see Color of ALV Output, Columns, and Cells [page 186])

Web Dynpro ABAP: Development in Detail

187

Advanced Concepts

●

May 2006

Alignment, font size, and font style in a design object for the header or footer area (see Design Object Settings [page 179])

Methods for Text Properties Function

Class

Method

Horizontal alignment within a column

CL_SALV_WD_ COLUMN

SET_H_ALIGN

Horizontal alignment within a cell variant

CL_SALV_WD_ CV_STANDARD

SET_H_ALIGN

Font size and style in a cell

CL_SALV_WD_ UIE_TEXT_VIEW

SET_DESIGN or SET_DESIGN_FIELDNAME

GET_H_ALIGN GET_H_ALIGN

GET_DESIGN or GET_DESIGN_FIELDNAME Line break for a cell

CL_SALV_WD_ UIE_TEXT_VIEW

SET_WRAPPING or SET_WRAPPING_FIELDNAME

CL_SALV_WD_ UIE_LINK_TO_ACTION

GET_WRAPPING or GET_WRAPPING_FIELDNAME

CL_SALV_WD_ UIE_LINK_TO_URL

4.17.3.6

Lines Between Columns and Rows

You can define whether lines between columns and rows are to be shown or hidden in the ALV output. You can choose between the following variants: ●

Only show lines between columns

●

Only show lines between rows

●

Show lines between columns and rows

●

No lines

You use the methods of the interface class IF_SALV_WD_TABLE_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Showing Grid Net Lines Function

Method

Show or hide lines

SET_GRID_MODE

Check which lines are shown

GET_GRID_MODE

Web Dynpro ABAP: Development in Detail

188

Advanced Concepts

4.17.3.7

May 2006

Table as Hierarchy

You can display the ALV output as a hierarchy. You carry out two steps to do this: ●

Specify the hierarchy column You specify one or more columns as hierarchy columns.

●

Define display type You define the ALV output as a hierarchy.

Hierarchy Displaying the ALV output as a hierarchy has the following effects on the columns: ●

The ALV table is automatically sorted according to all hierarchy columns.

●

By default, the sort sequence (and therefore the sequence of the hierarchy levels) is determined by the sequence of the column objects. You have the following options for changing the sequence of the hierarchy levels: ○

Change the position of the (hierarchy) columns

○

Change the sequence used for sorting the fields of the hierarchy columns

●

The columns that you have defined as hierarchy columns are not displayed in the usual form. Instead, all values of all hierarchy columns are displayed together in the first column. The value is indented according to the hierarchy level to which it belongs.

●

The values in the first column of a hierarchy have a small arrow symbol. The user can use this arrow to show or hide all subordinate data records.

●

The first column of a hierarchy is not an object instance of the class CL_SALV_WD_COLUMN.

●

The first column of a hierarchy does not have a column header.

●

Hierarchy columns (that is, their values, since the columns themselves are not displayed) cannot be hidden.

The Settings dialog box displays hierarchy columns in green on the Column Selection tab page. The user cannot transfer them to the list of hidden columns.

Specifying Hierarchy Columns To define a column as a hierarchy column, use the methods of the interface class IF_SALV_WD_COLUMN_HIERARCHY (implementing class CL_SALV_WD_COLUMN). Methods for Defining Hierarchy Columns Function

Method

Specify hierarchy column

SET_HIERARCHY_COLUMN

Check whether a column is a hierarchy column

IS_HIERARCHIY_COLUMN

Web Dynpro ABAP: Development in Detail

189

Advanced Concepts

May 2006

Defining the Display Type To define your ALV output as a hierarchy, thereby defining the type of the display, use the methods of the interface class IF_SALV_WD_TABLE_SETTINGS (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Defining the Display Type Function

Method

Define display type

SET_DISPLAY_TYPE

Get display type

GET_DISPLAY_TYPE

4.17.4

Predefining Standard ALV Functions

You can use your application to predefine how the ALV output is displayed on the screen when the user calls the application up. This relates to the data itself, as well as to design aspects, so you can affect the manner in which the data is arranged in the table. The functions are: ●

Sorting data (see Sorting [page 190])

●

Filtering data (see Filters [page 193])

●

Calculations (see Calculation (Aggregation) [page 195])

●

Views (see Managing Views [page 200])

●

Exporting as external data formats (see Export [page 200])

For information on the design possibilities available to you in the ALV output, see Appearance of ALV Output [page 182].

4.17.4.1

Sorting

You can change the sequence of data records according to specific rules by sorting the ALV output. You specify which fields contain the values that are to be sorted alphabetically or numerically, thereby determining the sequence of all rows. You are able to make the following settings for sorting: ●

Create, get, and delete sort settings (sort conditions)

●

Setting sort direction and sort sequence

●

Grouping same values

●

Forbidding sorting for a field

●

Enabling sorting by clicking on a column header

●

Sorting a field according to the values of another field

●

Hide and show tab for sorting (see Providing Standard ALV Functions [page 206])

Web Dynpro ABAP: Development in Detail

190

Advanced Concepts

May 2006

You are able to make calculations using the values of numeric columns (see Calculation (Aggregation) [page 195]). By default all values of a column are used for this. If you need intermediate results in addition to the overall result of the calculation, the rows that contain the subvalues of an intermediate result need to be next to each other, so you sort the ALV output. If you display intermediate results, these are generated for all sorted columns by default (see Intermediate Results [page 197]).

Creating, Getting, or Deleting Sort Conditions for a Field Sorting is a property of a field in the ALV output (see Fields [page 168]). To create, get, or delete the sort condition of a field, use the methods of the interface class IF_SALV_WD_SORT (implementing class CL_SALV_WD_FIELD). Methods for Creating, Getting, and Deleting the Sort Condition Function

Method

Get sort condition

GET_SORT_RULE

Create sort condition

CREATE_SORT_RULE

Delete sort condition

DELETE_SORT_RULE

The sort condition of a field is represented by an object of the class CL_SALV_WD_SORT_RULE.

If you assign a new data table with a new structure to your ALV output, all sort conditions for all fields are deleted automatically.

Setting Sort Direction and Sort Sequence For each individual sort condition, you are able to define whether you want to sort the values of the field ascending (for example, a, b, c) or descending (for example, c, b, a): You do this by setting the sort direction. If you sort the ALV output by multiple fields, the result changes depending on the sequence of fields that is used to sort. By default, the fields are sorted in the sequence in which you generated your sort conditions. You are able to change this sequence. To do this, assign a position number in the sort sequence to the field (or its sort condition). To change the sort direction or sort sequence of a sort condition, use the methods of the class CL_SALV_WD_SORT_RULE. Methods for the Sort Direction and Sort Sequence Function

Method

Set sort direction

SET_SORT_ORDER

Get sort direction

GET_SORT_ORDER

Set position of field within sort sequence

SET_SORT_POSITION

Get position of field within sort sequence

GET_SORT_POSITION

Web Dynpro ABAP: Development in Detail

191

Advanced Concepts

May 2006

Grouping Same Values By default, values that are the same are combined in a sorted ALV output in a sorted field. The values are grouped. You can choose that a value appear in each row, even if this value does not change. You use the methods of the interface class IF_SALV_WD_SORT for this (implementing class CL_SALV_WD_FIELD). Methods for Grouping Sorted Values Function

Method

Group values/remove grouping

SET_GROUPING_ALLOWED

Check whether values are grouped

IS_GROUPING_ALLOWED

Forbidding Sorting for a Field You can explicitly forbid sorting for a field. This has the following effects: ●

The field in question is no longer available on the Sorting tab of the Settings dialog box.

●

If you permit the sorting of columns by clicking on column headers (see below), the function is not available for a column for which you have forbidden sorting, and the arrows are hidden.

●

If you defined a sort condition for this field in your application, the sorting in the ALV output has no effect.

To forbid sorting for a field, use the methods of the interface class IF_SALV_WD_SORT (implementing class CL_SALV_WD_FIELD). Methods for Forbidding Sorting Function

Method

Forbid sorting

SET_SORT_ALLOWED

Check whether sorting is allowed

IS_SORT_ALLOWED

Enabling Sorting by Clicking on a Column Header You can display small arrows in the column headers of the ALV output. The user can use these arrows to sort the columns in ascending or descending order. To display these arrows, use the methods of the interface class IF_SALV_WD_STD_FUNCTIONS (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Sorting by Clicking on a Column Header Function

Method

Show arrows in column headers

SET_SORT_HEADERCLICK_ALLOWED

Check whether arrows are shown in column headers

IS_SORT_HEADERCLICK_ALLOWED

Sorting a Field According to the Values of Another Field You can specify a field according to which the current field is to be sorted if the field itself fails to deliver the required result. You use the methods of the interface class IF_SALV_WD_COLUMN_SERVICE_REF for this (implementing class CL_SALV_WD_COLUMN).

Web Dynpro ABAP: Development in Detail

192

Advanced Concepts

May 2006

Methods for Sorting According to the Values of Another Field Function

Method

Set field name of other field

SET_SORT_FIELDNAME

Get field name of other field

GET_SORT_FIELDNAME

4.17.4.2

Filters

With filters you restrict the display of data records in the ALV output. To do this, you specify conditions that a record in a specific field has to fulfill in order to be displayed or filtered out. You are able to make the following settings for filter objects: ●

Create, get, or delete filter conditions for a field

●

Make settings for a filter condition

●

Forbid filters for a column

●

Filter according to the values of another field

●

Hide or show tab for filtering or pushbutton Filter in the toolbar (see Providing Standard ALV Functions [page 206])

Creating, Getting, or Deleting Filter Conditions for a Field Unlike a sort condition, you can create as many filter conditions for each field as you want.

You are only able to create a filter condition for fields for which you have not expressly forbid this (see below Filtering is a property of a field in the ALV output (see Field [page 168]). To create, get, or delete the filter condition of a field, use the methods of the interface class IF_SALV_WD_FILTER (implementing class CL_SALV_WD_FIELD). Methods for Creating, Getting, and Deleting Filter Conditions Function

Method

Get a specific filter condition

GET_FILTER_RULE

Get all filter conditions of a field

GET_FILTER_RULES

Create filter condition

CREATE_FILTER_RULE

Delete a specific filter condition

DELETE_FILTER_RULE

The filter condition of a field is represented by an object of the class CL_SALV_WD_FILTER_RULE.

If you assign a new data table with a new structure to your ALV output, all filter conditions for all fields are deleted automatically.

Web Dynpro ABAP: Development in Detail

193

Advanced Concepts

May 2006

Making Settings for a Filter Condition A filter condition consists of the following specifications: ●

Comparison value with which the rows are tested This can be an individual value or a range for the given value. You always enter the lower value (LOW_VALUE) and for a range, you enter an upper value too (HIGH_VALUE).

●

Operator for comparing the field value and the comparison value This specification (OPERATOR) defines the relationship between the cell value and the comparison value (for example, greater than, less than or equal to)

●

Inclusion or exclusion This specification defines whether rows that match the condition are displayed or not displayed.

To change settings for a filter condition, use the methods of the class CL_SALV_WD_FILTER_RULE. Methods for Settings for a Filter Condition Function

Method

Define comparison value (lower value)

SET_LOW_VALUE

Get comparison value (lower value)

GET_LOW_VALUE

Define upper value of comparison range

SET_HIGH_VALUE

Get upper value of comparison range

GET_HIGH_VALUE

Define operator

SET_OPERATOR

Get operator

GET_OPERATOR

Define inclusion or exclusion

SET_INCLUDED

Get inclusion or exclusion

GET_INCLUDED

Forbidding Filters for a Column You can explicitly forbid filters for a field. This has the following effects: ●

When an ALV output is filtered, a filter row showing the current filter for each column is displayed. The user can use this filter row to quickly enter a filter. If you forbid filtering for a field, the corresponding cell in the filter row is empty and cannot be filled.

●

The field in question is no longer available on the Filters tab of the Settings dialog box.

●

If you defined a filter condition for this field in your application, the filter in the ALV output has no effect.

To forbid filtering for a field, use the methods of the interface class IF_SALV_WD_FILTER (implementing class CL_SALV_WD_FIELD). Methods for Forbidding Filtering Function

Method

Forbid filtering for a field

SET_FILTER_ALLOWED

Web Dynpro ABAP: Development in Detail

194

Advanced Concepts

Check whether filtering is allowed

May 2006

IS_FILTER_ALLOWED

Filtering According to the Values of Another Field You can specify a field according to which the current field is to be filtered if the field itself fails to deliver the required result or requires overly complicated input. You use the methods of the interface class IF_SALV_WD_COLUMN_SERVICE_REF for this (implementing class CL_SALV_WD_COLUMN). Methods for Sorting According to the Values of Another Field Function

Method

Define field name of other field

SET_FILTER_FIELDNAME

Get field name of other field

GET_FILTER_FIELDNAME

4.17.4.3

Calculation (Aggregation)

You are able to make calculations in field with a numeric data type: You generate an aggregation condition. The result of the calculation is then displayed in a separate results row.

Intermediate Results Usually all values in a field are used in a calculation during aggregation. You are also able to obtain intermediate results. To do this you have to sort the ALV output and group the rows that you want to use for the intermediate result (see Sorting [page 190]). You are able to make the following settings for aggregations: ●

Creating, getting, and deleting an aggregation rule

●

Making settings for aggregation (see Settings for Aggregation [page 196])

●

Generating intermediate results (see Intermediate Results [page 197])

●

Hiding and showing interface elements for calculations or intermediate results (see Providing Standard ALV Functions [page 206])

Creating, Getting, and Deleting an Aggregation Rule You are able to create a maximum of one aggregation rule for a field. Aggregation is a property of a field in the ALV output. To create, get, or delete the aggregation rule of a field, use the methods of the interface class IF_SALV_WD_AGGR (implementing class CL_SALV_WD_FIELD). Methods for Creating, Getting, and Deleting the Aggregation Rule Function

Method

Get aggregation rule

GET_AGGR_RULE

Create aggregation rule

CREATE_AGGR_RULE

Delete aggregation rule

DELETE_AGGR_RULE

Web Dynpro ABAP: Development in Detail

195

Advanced Concepts

May 2006

The aggregation rule of a field is represented by an object of the class CL_SALV_WD_AGGR_RULE.

If you assign a new data table with a new structure to your ALV output, all aggregation rules for all fields are deleted automatically.

4.17.4.3.1

Settings for Aggregation

You are able to make the following settings for the calculation of field values: ●

Set aggregation type

●

Set the position of the result row

●

Forbid aggregation for a field

Setting the Aggregation Type The following calculation (aggregation) types are available: ●

Total Adds together all values of the field

●

Minimum Determines the smallest value of the field

●

Maximum Determines the largest value of the field

●

Average value Determines the geometric average of all values of the field

To define the calculation type, use methods of the class CL_SALV_WD_AGGR_RULE. Methods for Changing the Calculation Type Function

Method

Set calculation type

SET_AGGREGATION_TYPE

Get calculation type

GET_AGGREGATION_TYPE

In addition to the calculation types listed above, you can also determine the total number of data records. The result is displayed in the result row in the first available column. Because this setting affects the entire ALV output, you use methods of the interface class IF_SALV_WD_FIELD_SETTINGS (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Displaying the Data Records of a Result Function

Method

Display the number of data records

SET_COUNT_RECORDS_ENABLED

Check whether the number of data records is displayed

IS_COUNT_RECORDS_ENABLED

Web Dynpro ABAP: Development in Detail

196

Advanced Concepts

May 2006

Setting the Position of the Result Row You are able to define whether you wish to display the result row for the calculations in an ALV output above or below the rows that are included in the calculation. You use the methods of the interface class IF_SALV_WD_FIELD_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods Relating to the Position of the Result Row Function

Method

Place result row before data records

SET_AGGR_BEFORE_ITEMS

Check whether the result row is placed before the data records

IS_AGGR_BEFORE_ITEMS

Forbidding Aggregation for a Field By default, all fields with a numeric data type can be aggregated. You can forbid the aggregation of a field, if required. This has the following effects: ●

The column in question is no longer available on the Calculation tab of the Settings dialog box.

●

If you have defined an aggregation rule for this field in your application, the calculation is not carried out.

To forbid the aggregation of a field, use the methods of the interface class IF_SALV_WD_AGGR (implementing class CL_SALV_WD_FIELD). Methods for Forbidding Aggregation Function

Method

Forbid aggregation

SET_AGGREGATION_ALLOWED

Check whether aggregation is allowed

IS_AGGREGATION_ALLOWED

4.17.4.3.2

Intermediate Results

By default, all values in a field are used in the calculation during aggregation. However, you are also able to generate intermediate results. You group the data records that contain the values for an intermediate result and display each intermediate result in its own result row. To generate intermediate results, you have to provide certain information: ●

To specify in which field the values from which the intermediate results are calculated are located, generate an aggregation condition for the desired field. The overall result is displayed in the result row.

●

To specify which data records are contained in an intermediate result, group the data records: You sort the ALV output by the field that includes the criterion for the intermediate result.

●

To then generate the intermediate results, calculate the intermediate results using the field with the criterion.

●

To then display the intermediate results, switch on the display of intermediate results.

Web Dynpro ABAP: Development in Detail

197

Advanced Concepts

May 2006

The most common way of generating intermediate results is to use subtotals. That is way you often find this term in place of intermediate results for all aggregation types. Nevertheless you can of course generate intermediate results (or “subtotals”) for all other aggregation types. You are able to make the following settings for intermediate results: ●

Generate intermediate results

●

Display intermediate results

●

Setting levels for drilling down intermediate results

●

Set the position of the result rows (see Settings for Aggregation [page 196])

●

Forbid the generation of intermediate results

Prerequisites ●

You have generated an aggregation object for at least one aggregatable field.

●

The field with the criterion for intermediate results is not an aggregatable field, and therefore has an alphanumeric data type.

Generate Intermediate Results To generate intermediate results in a field that already has an aggregation condition, generate a sort condition for the field of a column (another column) (see Sorting [page 190]). In this sort condition, define whether intermediate results are to be generated. To do this, use the methods of the class CL_SALV_WD_SORT_RULE. Methods for Generating Intermediate Results Function

Method

Generate intermediate results

SET_GROUP_AGGREGATION

Check whether intermediate results are displayed

GET_GROUP_AGGREGATION

Display Intermediate Results Once you have made all settings, to generate intermediate results you have to switch on the display of these intermediate results. You use the methods of the interface class IF_SALV_WD_FIELD_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Displaying Intermediate Results Function

Method

Display intermediate results

SET_GROUP_AGGR_DISPLAYED

Check whether intermediate results are displayed

GET_GROUP_AGGR_DISPLAYED

Web Dynpro ABAP: Development in Detail

198

Advanced Concepts

May 2006

Setting Levels for Drilling Down Intermediate Results If you have defined intermediate results for several alphanumeric fields, there are multiple levels of subtotals: The intermediate results are subdivided hierarchically and are marked with a different number of points according to their level. The user can use these points to show and hide the entries for the individual intermediate results. You can use your application to show or hide the entries of one or more complete subtotal levels. You can also aggregate intermediate results: You hide all data records and any existing lower subtotal levels. Only the results rows of the highest subtotal level and the results row with the overall result remains visible. You use the methods of the interface class IF_SALV_WD_FIELD_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Steps for Expanding Subtotals Function

Method

Set highest subtotal level to be displayed

SET_EXPAND_LEVEL

Get current subtotal level being displayed

GET_EXPAND_LEVEL

Aggregate intemediate result

SET_GROUP_AGGR_COLLAPSED

Check whether intermediate results are aggregated

GET_GROUP_AGGR_COLLAPSED

Forbid the Generation of Intermediate Results By default, intermediate results are automatically displayed in the ALV output as soon as a calculation is performed in at least one field: all sorted fields with alphanumeric data types are interpreted as a possible criterion for intermediate results and are thus given intermediate results. You can forbid the generation of intermediate results for individual fields. This has the following effects: â&#x2014;?

If you generate intermediate results for this field in your application, these settings have no effect in the ALV output.

Afterwards, the user can determine for which columns he or she wants intermediate results. If you forbid the generation of intermediate results for a field, the particular column is not offered the to user. To forbid the generation of intermediate results for a field, use the methods of the interface class IF_SALV_WD_SORT (implementing class CL_SALV_WD_FIELD). Methods for Forbidding Intermediate Results Function

Method

Forbid the generation of intermediate results

SET_GROUP_AGGREGATION_ALLOWED

Check whether generating intermediate results is permitted

IS_GROUP_AGGREGATION_ALLOWED

Web Dynpro ABAP: Development in Detail

199

Advanced Concepts

4.17.4.4

May 2006

Managing Views

In a view, users are able to save information on column structure, sorting criteria, filter conditions, various display options, and so on. In this way, they are able to display their ALV outputs with the same properties every time. You are able to use your application to affect the options that users have for working with views.

You are not able to use the ALV object model to either create or delete views.

Views and Data Structure of ALV Configuration Model All settings that the user saves in a view for an ALV output relate to the fields of a specific data structure of the ALV configuration model. If, for example, you load another structure, the settings for the view may not work (see SET_DATA [page 225]). You must therefore make sure that a view is clearly assigned to both the current application and the data structure that is currently loaded. To do this, you give the data structure a unique key. All views that the user saves from now on are given this identifying key (see Configuration Key [page 222]). You can get all settings for a view using the method GET_CONFIG_DATA in the interface controller of the ALV component (see GET_CONFIG_DATA [page 220]). For information on showing and hiding UI elements for views, see Providing Standard ALV Functions [page 206].

User-Specific View/Non-User-Specific View Views can be available to only one user or for all users of your application. Consequently, views are either user-specific or non-user-specific. A user of your application normally generates a user-specific view. To save a non-userspecific view, the user must have authorizations for personalization and configuration functions (see Personalization and Configuration [page 138]).

4.17.4.5

Export

The user can export the ALV output that is currently being displayed in two different file formats: ●

Microsoft Excel (see Microsoft Excel [page 200])

●

Adobe Acrobat (see Adobe Acrobat [page 201])

4.17.4.5.1

Microsoft Excel

To generate an Excel list from the ALV output, the user simply chooses the corresponding pushbutton from the toolbar. The user cannot affect the result in advance. However, in your application, you can define whether information other than the ALV output is also copied to the Excel file when the user triggers the export. This applies to: ●

Design objects for header and footer areas

●

Result rows for calculations

Web Dynpro ABAP: Development in Detail

200

Advanced Concepts

May 2006

Copying Design Objects to the Excel File If you have defined a design object for a header or footer for the ALV output, you can define whether the content of this design object should also be copied into the Excel file. You use the methods of the interface class IF_SALV_WD_EXPORT_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Copying Design Objects into the Excel File Function

Method

Copy design object for the Excel header

SET_EXPORT_NO_TOL

Check whether the design object is to be copied for the Excel header

GET_EXPORT_NO_TOL

Copy design object for the Excel footer

SET_EXPORT_NO_EOL

Check whether the design object is to be copied for the Excel footer

GET_EXPORT_NO_EOL

Copy Result Rows for Calculations into the Excel File You can define whether result rows containing the results or interim results of aggregations should be copied to Microsoft Excel when the export takes place. You use the methods of the interface class IF_SALV_WD_EXPORT_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Copying Result Rows into the Excel File Function

Method

Copy result rows to Excel

SET_EXPORT_NO_SUMS

Check whether result rows are copied to Excel

GET_EXPORT_NO_SUMS

4.17.4.5.2

Adobe Acrobat

The user can print out the ALV output that is currently displayed. To do this, the user chooses the pushbutton Print Version from the toolbar. ALV then generates a standard PDF file from the ALV output data, starts Adobe Acrobat, and displays the generated PDF file. The user can use the Settings dialog box to make many settings related to the display of the PDF file. The same options are available in your application. Define the presettings for the PDF document as follows: ●

Define the paper format and alignment

●

Define the size of the printable area

●

Scale columns and rows

●

Send the output directly to the printer

●

Set up the header and footer

●

Copy design objects to the PDF file

You can also define whether a design object that you defined for the header or footer should also appear in the PDF file.

Web Dynpro ABAP: Development in Detail

201

Advanced Concepts

May 2006

Defining the Paper Format and Orientation You can specify the paper format for the PDF document. You can choose between the following paper formats: ●

DIN A4

●

Letter

You can also define whether the PDF document is to be generated in Portrait or Landscape format. You use the methods of the interface class IF_SALV_WD_PDF_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Paper Format and Orientation Function

Method

Define paper format

SET_PAGE_SIZE

Get paper format

GET_PAGE_SIZE

Set paper orientation

SET_ORIENTATION

Get paper orientation

GET_ORIENTATION

Defining the Size of the Printable Area You can define the size of the printable area on pages of your PDF document by specifying the width of the margins. You also specify the unit of measurement for your settings. You use the methods of the interface class IF_SALV_WD_PDF_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods Relating to the Printable Area of a Page Function

Method

Define unit of measurement for margins

SET_MARGINS_UNIT

Get unit of measurement for margins

GET_MARGINS_UNIT

Define width of bottom, top, right, and left margins

SET_MARGIN_BOTTOM SET_MARGIN_TOP SET_MARGIN_RIGHT SET_MARGIN_LEFT

Get width of bottom, top, right, and left margins

GET_MARGIN_BOTTOM GET_MARGIN_TOP GET_MARGIN_RIGHT GET_MARGIN_LEFT

Scaling Columns and Rows By default, the columns are displayed in the PDF document with the same width as in the ALV output. However, if there is not enough room on one page for all the columns, the table is split onto two or more pages. The rows are also distributed over the number of pages necessary to display them. There are different options for modifying the size of the columns and rows in line with the page size of your PDF document:

Web Dynpro ABAP: Development in Detail

202

Advanced Concepts

●

May 2006

Reduce the width of columns so that they fit onto one page. The height of the table remains unchanged.

●

Reduce the width and the height of the table so that the entire table fits onto one page.

●

Leave both width and height unchanged.

If the columns are distributed over several pages, you can define whether certain information should appear only on the first page or should be repeated on subsequent pages too. You can choose between the following variants: ●

If the column width is unchanged (wallpaper): The column titles are displayed on all pages.

●

If the column width is changed: The column titles are also repeated on subsequent pages.

●

Regardless of scaling: Fixed columns are repeated on all subsequent pages.

You use the methods of the interface class IF_SALV_WD_PDF_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Scaling Columns and Rows Function

Method

Define table scaling in PDF document

SET_PAGE_LAYOUT

Get table scaling in PDF document

GET_PAGE_LAYOUT

Repeat column titles if page width is adjusted

SET_REPEAT_HEADERS_FIT_H

Check whether column titles are repeated if page width is adjusted

GET_REPEAT_HEADERS_FIT_H

Repeat column titles for adjacent pages

SET_REPEAT_HEADERS_WALLPAPER

Check whether column titles are repeated for adjacent pages

GET_REPEAT_HEADERS_WALLPAPER

Repeat fixed columns on every page

SET_REPEAT_KEY_COLUMNS

Check whether fixed columns are repeated on every page

GET_REPEAT_KEY_COLUMNS

Sending the Output Directly to the Printer You can choose for the print version to be created as a PostScript file instead of a PDF document. The PostScript file is then sent directly to a printer of your choice.

If you do not specify an output device here, a PDF file is generated and displayed on the screen. You use the methods of the interface class IF_SALV_WD_PDF_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Printing Directly Function

Method

Set ALV output to be printed immediately

SET_PRINT_IMMEDIATE

Web Dynpro ABAP: Development in Detail

203

Advanced Concepts

May 2006

Check whether the ALV output is to be printed immediately

GET_PRINT_IMMEDIATE

Set printer

SET_PRINTER

Get printer

GET_PRINTER

Setting Up the Header and Footer You can use text modules to create a header and/or footer for your PDF document. The header or footer will appear on every page. When doing this, you have to specify the position of the text module (centered, left-justified, or right-justified). You can place one of the following text modules at the required position: ●

No text The current position is not occupied.

●

Free text The free text that you defined for the position is inserted at the current position.

●

Current date Current date and time

●

Current page

●

Page 1 of ? The number of the current page and the total number of pages are inserted at this position.

You use the methods of the interface class IF_SALV_WD_PDF_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Placing Text Modules in Headers and Footers Function

Method

Set free text for the different positions

SET_FOOTER_CENTER_FREETEXT SET_FOOTER_LEFT_FREETEXT SET_FOOTER_RIGHT_FREETEXT SET_HEADER_CENTER_FREETEXT SET_HEADER_LEFT_FREETEXT SET_HEADER_RIGHT_FREETEXT

Get free text for the different positions

GET_FOOTER_CENTER_FREETEXT GET_FOOTER_LEFT_FREETEXT GET_FOOTER_RIGHT_FREETEXT GET_HEADER_CENTER_FREETEXT GET_HEADER_LEFT_FREETEXT GET_HEADER_RIGHT_FREETEXT

Set text module for the different positions

SET_FOOTER_CENTER SET_FOOTER_LEFT SET_FOOTER_RIGHT

Web Dynpro ABAP: Development in Detail

204

Advanced Concepts

May 2006

SET_HEADER_CENTER SET_HEADER_LEFT SET_HEADER_RIGHT Get text module for the different positions

GET_FOOTER_CENTER GET_FOOTER_LEFT GET_FOOTER_RIGHT GET_HEADER_CENTER GET_HEADER_LEFT GET_HEADER_RIGHT

Copying Design Objects to the PDF File If you have defined a design object for a header or footer for the ALV output, you can define whether the content of this design object should also be copied into the PDF file. You use the methods of the interface class IF_SALV_WD_PDF_SETTINGS for this (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Copying Design Objects into the PDF File Function

Method

Copy design object for the PDF header

SET_EXPORT_NO_TOL

Check whether the design object is to be copied for the PDF header

GET_EXPORT_NO_TOL

Copy design object for the PDF footer

SET_EXPORT_NO_EOL

Check whether the design object is to be copied for the PDF footer

GET_EXPORT_NO_EOL

4.17.5

Functions, Interactions, and Events

As well as using ALV outputs to depict table-type data structures clearly for users, you can also allow users to interact with the ALV output in various ways. You can provide the following options: ●

Standard ALV functions [page 206] In the Settings dialog box or toolbar, you can show or hide the different UI elements with which the user can access the ALV output services.

ALV supports the selection of standard functions: If, for example, your ALV output does not contain any columns with values that can be calculated, the UI elements for calculation are not displayed in the columns. ●

Self-defined, application-specific functions [page 208] You generate UI elements in the toolbar with which the user can run the functions you programmed yourself, and thus use your application effectively.

●

Interactive UI elements within the ALV output table

Web Dynpro ABAP: Development in Detail

205

Advanced Concepts

May 2006

You can use interactive UI elements in the ALV output table (for example, as cell editors in the columns and rows of your ALV output). There are two types of interaction: ○

Interaction without changing data (see Handling Interaction with no Data Changes [page 213])

○

Interaction with data changes (see Handling Interaction in Editable ALV [page 215])

Various events are available to handle the user’s actions regarding these UI elements.

4.17.5.1

Providing Standard ALV Functions

You are able to provide functions to help users working with the ALV output. The functions that the system provides for ALV are called standard ALV functions. Standard ALV functions include, for example, sorting, filtering, and performing calculations. A number of UI elements can be found in the toolbar. The majority of the UI elements, however, are located in the Settings dialog box, a separate area that the user can show or hide as required. You cannot change the positioning of the UI elements for the standard ALV functions.

You can show, hide, or deactivate the entire toolbar [page 211].

Settings Dialog Box This dialog box is hidden as standard. The user can show it by choosing the Settings button in the toolbar.

The settings that the user makes in the dialog box can be applied to the ALV output in two ways: ●

Using the Copy pushbutton

The settings are applied to the ALV output. The dialog box remains open and the user can make further settings. ●

Using the OK pushbutton

The settings are applied to the ALV output. The dialog box closes. If the user chooses the Cancel pushbutton, the dialog box closes without changing the ALV output.

Providing Standard ALV Functions You determine which standard ALV functions are available to the user by showing or hiding the UI elements for the relevant standard functions.

By default, all UI elements are shown with the exception of those elements that are required for calculations (including intermediate results) and for the editable ALV.

Web Dynpro ABAP: Development in Detail

206

Advanced Concepts

May 2006

You can find the methods you require for this in the interface class IF_SALV_WD_STD_FUNCTIONS (implementing class CL_SALV_WD_CONFIG_TABLE). All of these methods contain the parameter VALUE of the type ABAP_BOOL: Methods for Standard ALV Functions Function

UI Element

Comments

Method

Show and hide columns Column Selection tab page

SET_COLUMN_SELECTION_ALLOWED

Sorting tab page

SET_SORT_COMPLEX_ALLOWED

Sorting

Sorting with single click on column header

Arrow icon in column header

SET_SORT_HEADERCLICK_ALLOWED

Filter Filter tab page

SET_FILTER_COMPLEX_ALLOWED

Filter pushbutton in toolbar

SET_FILTER_FILTERLINE_ALLOWED

Calculations Calculations tab page

SET_AGGREGATION_ALLOWED

All elements for intermediate results

SET_GROUP_AGGREGATION_ALLOWED

Count table entries

SET_COUNT_RECORDS_ALLOWED

Display tab page

SET_DISPLAY_SETTINGS_ALLOWED

Views dropdown list box

SET_VIEW_LIST_ALLOWED

Display

Views

Editable ALV Pushbutton Insert Row Pushbutton Append Row Pushbutton Delete Row

Can only be shown if writeprotection has been deactivated

SET_EDIT_INSERT_ROW_ALLOWED SET_EDIT_APPEND_ROW_ALLOWED SET_EDIT_DELETE_ROW_ALLOWED

Pushbutton Check

SET_EDIT_CHECK_AVAILABLE

Pushbutton Undo

SET_EDIT_UNDO_ALLOWED

Export

Web Dynpro ABAP: Development in Detail

207

Advanced Concepts

May 2006

Pushbutton Excel

SET_EXPORT_ALLOWED

Pushbutton and tab page Print Version

SET_PDF_ALLOWED

The names of the relevant get methods do not begin with GET_<METHOD NAME>, but with IS_<METHOD NAME>.

Standard ALV Function Events Two events have been provided to handle standard ALV functions: ●

ON_STD_FUNCTION_BEFO [page 230]

●

ON_STD_FUNCTION_AFTE [page 229]

4.17.5.2

Providing Application-Specific Functions

You are able to provide functions that are specially tailored to the business scenario for your application. To enable the user to use these functions, specify an appropriate UI element for each one. You can make the following settings for functions: ●

Generating and deleting a function [page 208]

●

Getting a function object [page 209]

●

Defining user interface elements [page 210]

●

Defining the position within the toolbar [page 211]

●

Controlling visibility and activation status [page 211]

●

Event for handling self-defined functions [page 213]

4.17.5.2.1

Preparing the Context

Some of the functions that you can insert into the toolbar cause a data change when the user triggers them. You therefore link these functions to a context node of your application. To do this, you have to define external context mapping to the context node FUNCTION_ELEMENTS of the ALV interface controller. You generate a separate attribute or subnodes for each function beneath this context node.

4.17.5.2.2

Generating and Deleting a Function

Every function is represented by a function object from the class CL_SALV_WD_FUNCTION. You can generate as many function objects as you want and arrange them in the toolbar. In contrast to the standard ALV functions, you can arrange self-defined, application-specific functions as you want within the toolbar. You must first decide whether the UI element is to be aligned to the left or the right margin of the ALV output (left-justified or right-justified). This dictates which methods you use to generate and delete the function object.

Web Dynpro ABAP: Development in Detail

208

Advanced Concepts

May 2006

You cannot change this setting once it has been made. To generate or delete a function object, use the methods of the interface class IF_SALV_WD_FUNCTION_SETTINGS (implementing class CL_SALV_WD_CONFIG_TABLE).

Generating a Function When you generate a function, you specify a unique ID (STRING type). This ID is later used to address this function. Methods for Generating Function Objects Function

Method

Generate function (left-justified)

CREATE_FUNCTION

Generate function (right-justified)

CREATE_FUNCTION_RIGHT

Deleting a Function To delete a function, specify its ID. Methods for Deleting Function Objects Function

Method

Delete function (left-justified)

DELETE_FUNCTION

Delete function (right-justified)

DELETE_FUNCTION_RIGHT

4.17.5.2.3

Getting a Function Object

To make settings for a function object, you must first call a suitable GET method. Before you can do this, you need to know if this function concerns a right-justified or left-justified function [page 208]. Various methods exist for this purpose in the IF_SALV_WD_FUNCTION_SETTINGS interface class (implementing class CL_SALV_WD_CONFIG_TABLE): Get Methods for Functions Function

Method

Get all left-justified functions

GET_FUNCTIONS

Get a particular left-justified function

GET_FUNCTION

Get all right-justified functions

GET_FUNCTIONS_RIGHT

Get a particular right-justified function

GET_FUNCTION_RIGHT

Web Dynpro ABAP: Development in Detail

209

Advanced Concepts

May 2006

To get the ID of a function, use the GET_ID method of the class CL_SALV_WD_FUNCTION.

4.17.5.2.4

Defining User Interface Elements

You can use the following UI elements for self-defined functions: ●

Button (CL_SALV_WD_FE_BUTTON)

●

DropDownByIndex (CL_SALV_WD_FE_DROPDOWN_BY_IDX)

●

DropDownByKey (CL_SALV_WD_FE_DROPDOWN_BY_KEY)

●

InputField (CL_SALV_WD_FE_INPUT_FIELD)

●

LinkToAction (CL_SALV_WD_FE_LINK_TO_ACTION)

●

LinkToURL (CL_SALV_WD_FE_LINK_TO_URL)

●

ToggleButton (CL_SALV_WD_FE_TOGGLE_BUTTON) For optical separation between the individual UI elements:

●

Separator (CL_SALV_WD_FE_SEPARATOR)

The classes in parentheses can be found in the system in the package SALV_WD_CONFIG. To determine the UI element for a self-defined function, perform the following steps: ●

Generate a right or left justified function object [page 208].

●

Generate one of the toolbar elements listed above.

●

Determine the properties of the toolbar element (as required).

●

Assign the toolbar element to the function.

To assign a suitable UI element to a function object, use the methods of the class CL_SALV_WD_FUNCTION. Methods for Assigning a UI Element Function

Method

Set UI element

SET_EDITOR

Get UI element

GET_EDITOR

Further Information For more information on the Web Dynpro elements of the toolbar, see the Toolbar section in the documentation on Web Dynpro for ABAP [externaly].

Web Dynpro ABAP: Development in Detail

210

Advanced Concepts

4.17.5.2.5

May 2006

Defining the Position Within the Toolbar

When you generated the function, you defined whether the UI element for the function would be positioned in relation to the left margin or in relation to the right margin (that is, whether it would be left-justified or right-justified). You cannot change this setting at a later date or time. However, you can change the order of the functions on one side of the toolbar. ●

The standard ALV functions are always on the outside (if you have chosen to display them [page 206]). You cannot change their order.

●

Functions that exist under the self-defined functions without a position number assignment are left-justified.

●

To the right of these functions are the self-defined functions, arranged from left to right in the order you define.

You insert eight functions into your toolbar with the names Button 1 to Button 8. You generate the first four buttons (1 to 4) as left-justified functions, and the last four (5 to 8) as right-justified. You then assign position 1 to the buttons 1 and 5, and position 2 to the buttons 2 and 6. These assignments give the following display:

Standard functions (left)

Sicht

Ex c el

Self-defin ed functio ns (left) without positio n numb er

Druc k v ers ion

But ton 3

Self-defin ed functio ns (left) with positio n numb er

But ton 4

But ton 1

But ton 2

Self-defin ed functio ns (right) without Position n umber

But ton 7

But ton 8

Self-defin ed functio ns (right) with positio n numb er

But ton 5

But ton 6

The self-defined functions to which you do not assign any position numbers always have the position number 0. To determine the position number of a function object, use the methods of the class CL_SALV_WD_FUNCTION. Methods for Changing the Position of Function Objects Function

Method

Set position number

SET_POSITION

Get position number

GET_POSITION

4.17.5.2.6

Controlling Visibility and Activation Status

You can affect the way self-defined functions operate: ●

You can deactivate an individual UI element for a function

Web Dynpro ABAP: Development in Detail

211

Filter

Standard functions (right)

Eins tellungen

Advanced Concepts

May 2006

●

You can hide an individual UI element for a function

●

You can deactivate the entire toolbar

●

You can hide the entire toolbar

Activating and Deactivating Functions If you do not want to hide a UI element, but you want to prevent the user from performing this function, you can deactivate the UI element. To deactivate or activate a UI element for a function object, you use the methods belonging to the class of your UI element [page 210]. Methods Relating to the Activation Status of Function Objects Function

Method

Enable/disable function object

SET_ENABLED

Get activation status

GET_ENABLED

Showing and Hiding Functions You can hide the UI element for a function in two ways: ●

VISIBILITY-NONE The UI element is invisible. The elements in the toolbar that are placed next to the function simply move up and there are no gaps in the toolbar.

●

VISIBILITY-BLANK The UI element is invisible but the space it occupied remains empty. Elements in the toolbar that were next to the function keep their former positions.

To show or hide a UI element for a function object, use the methods of the class CL_SALV_WD_FUNCTION. Methods for Hiding/Showing Function Objects Function

Method

Show/hide function object

SET_VISIBILITY

Get visibility

GET_VISIBILITY

Hiding, Showing, and Deactivating the Toolbar To determine the activation status or visibility of the entire toolbar, you use the methods of the interface class IF_SALV_WD_FUNCTION_SETTINGS (implementing class CL_SALV_WD_CONFIG_TABLE). Methods Relating to the Activation Status and Visibility of the Toolbar Function

Method

Activate/deactivate toolbar

SET_ENABLED

Get activation status

GET_ENABLED

Show/hide toolbar

SET_VISIBILITY

Web Dynpro ABAP: Development in Detail

212

Advanced Concepts

Get visibility

May 2006

GET_VISIBILITY

4.17.5.2.7

Event for Handling Self-Defined Functions

With standard ALV functions, you can only handle events at two specific time points: When the user has performed a function [page 230] or when he or she has completed a function [page 229]. You do not receive any information about which standard ALV functions the user has chosen. With self-defined functions, however, you can determine which functions the user chose. The event ON_FUNCTION [page 228] has been provided to handle self-defined functions.

4.17.5.3

Handling Interaction with no Data Changes

Not all actions carried out by the user in the ALV output lead to a change in the data. Examples of actions which do not cause changes to the data are: ●

Changing row selections (see Selecting Rows [page 213])

●

Choosing hyperlinks, buttons, and toggle buttons (see Using Hyperlinks, Buttons, and Toggle Buttons [page 214])

You can make various settings to control or handle this kind of interaction.

4.17.5.3.1

Selecting Rows

You can use the selection type to affect whether the user can select rows and how many he or she can select at once. This also defines whether a lead selection exists (see Lead Selection in Context Node: Properties [externaly]).

The user can also change the selection of rows in a write-protected ALV output as long as the selection type allows this. However, if you deactivate the ALV output, the user cannot select any rows, regardless of the selection type (see Write-Protection and Activation [page 215]).

Setting the Selection Type You can use the following selection types: ●

Automatic The settings are adopted from the context mode.

●

No selection possible (NONE) No pushbuttons for selecting rows are displayed at the start of the rows.

●

Single row (SINGLE)

Web Dynpro ABAP: Development in Detail

213

Advanced Concepts

May 2006

Pushbuttons are displayed at the start of rows. The user can only select a single row. This row is displayed as the lead selection. If a user selects another row, the lead selection is changed too. ●

Single rows without lead selection (SINGLE_NO_LEAD) Pushbuttons are displayed at the start of rows. The user can only select a single row. If a user selects another row, the selection is changed too. The ALV output has no lead selection.

●

Multiple rows (MULTI) Pushbuttons are displayed at the start of rows. The user can use the CTRL key to select multiple rows. The first selected row is the lead selection.

●

Multiple rows without lead selection (MULTI_NO_LEAD) Pushbuttons are displayed at the start of rows. The user can use the CTRL key to select multiple rows. The ALV output has no lead selection.

You use the property SELECTION of your context node to specify the number of data records that can be selected. Example: If you choose the value 1..1 for the SELECTION, one entry only must always be selected. The value 0..n means that it is possible to select no entries at all, but also to select as many as required. You can never use the selection type to allow the selection of more entries than the number defined in the context node. If you try to do this, you receive a runtime error and the application terminates. Example: If you made the SELECTION 1..1 in the context node, you may not use the selection types MULTI and MULTI_NO_LEAD. To define the selection type, use the methods of the interface class IF_SALV_WD_TABLE_SETTINGS (implementing class CL_SALV_WD_CONFIG_TABLE). Selection Type Methods Function

Method

Set selection type

SET_SELECTION_MODE

Get selection type

GET_SELECTION_MODE

Event Handling In the case of the selection types that allow the user to change the lead selection, the event ON_LEAD_SELECT can be used (see ON_LEAD_SELECT [page 229]).

4.17.5.3.2

Using Hyperlinks, Buttons, and Toggle Buttons

You can use UI elements in the cells of the ALV output that allow the user to trigger certain actions. The following UI elements do not automatically lead to data changes: ●

Hyperlink LINK_TO_ACTION (see LinkToAction [externaly])

●

Hyperlink LINK_TO_URL (see LinkToURL [externaly])

●

Button (see Button [externaly])

Web Dynpro ABAP: Development in Detail

214

Advanced Concepts

●

May 2006

Toggle button (see Toggle Button [externaly])

The cross-references listed above refer to generally usable Web Dynpro objects. Instead of the class names specified there, you use the class names listed below for the ALV configuration model: Classes for Interactive UI Elements UI Element

Class

Hyperlink LINK_TO_ACTION

CL_SALV_WD_UIE_LINK_TO_ACTION

Hyperlink LINK_TO_URL

CL_SALV_WD_UIE_LINK_TO_URL

Button

CL_SALV_WD_UIE_BUTTON

Toggle Button

CL_SALV_WD_UIE_TOGGLE_BUTTON

These classes can be found in the system in the package SALV_WD_CONFIG. For information on displaying one of the UI elements in a cell, see Assigning Properties to Columns and Cells [page 183]

The user can also use the UI elements listed here in a write-protected ALV output. However, if you deactivate the ALV output, the UI elements are also deactivated (see Write-Protection and Activation [page 215]).

Event Handling You can use the event ON_CLICK to handle user actions for the following UI elements: ●

Hyperlink LINK_TO_ACTION

●

Button

●

Toggle Button

(See ON_CLICK [page 226].) However, the UI element LINK_TO_URL is only for displaying a URL in an Internet browser. You cannot catch any events.

4.17.5.4

Handling Interaction in Editable ALV

You can use the columns of the ALV output to display UI elements that the user can use to change the data displayed there (see Changing Cell Content [page 217]). The user can also insert rows at certain positions, append them to the end of the ALV output, and delete them (see Adding and Deleting Rows [page 216]). The write-protection for the ALV output must be deactivated before these actions can be carried out (see Write-Protection and Activation [page 215]). You must also define the time at which the system checks whether changed data is correct (see Defining the Checking Time [page 218]).

4.17.5.4.1

Write-Protection and Activation

You can depict the data in the ALV output using UI elements that allow the data to be changed. However, you can then use various methods to prevent the user from changing data in these UI elements. You can make the following settings:

Web Dynpro ABAP: Development in Detail

215

Advanced Concepts

May 2006

●

Control write-protection for the ALV output

●

Activate and deactivate the ALV output

●

Deactivate individual UI elements (see Assigning Properties to Columns and Cells [page 183]).

Controlling Write-Protection for the ALV Output The ALV output is write-protected. You have to remove the write-protection in order to allow the user to change data. Write-protection has the following effects: ●

UI elements (in the cells, not in the toolbar) that allow data changes are not operable.

●

ALV standard functions in the toolbar for inserting, appending, and deleting rows and for checking data changes are hidden. You cannot show them if the ALV output is write-protected.

To switch write-protection on or off, use the methods of the interface class IF_SALV_WD_TABLE_SETTINGS (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for the Write-Protection of the ALV Output Function

Method

Switch write-protection on/off

SET_READ_ONLY

Check whether write-protection is switched on/off

GET_READ_ONLY

Activating and Deactivating the ALV Output The ALV output is activated by default. All interactive UI elements of the ALV output, both in the toolbar and in the table section, are operable if the ALV output is activated and writeprotection is switched off (see above). To activate or deactivate the ALV output, use the methods of the interface class IF_SALV_WD_TABLE_SETTINGS (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Activating the ALV Output Function

Method

Activate or deactivate ALV output

SET_ENABLED

Check whether ALV output is activated

GET_ENABLED

4.17.5.4.2

Adding and Deleting Rows

You can provide the user with pushbuttons in the toolbar for adding or deleting data records in various places in the ALV output. You can provide the following functions: ●

Insert row If the user has not selected a row, the new row is created as the first row. Otherwise, it is created before the selected row or rows.

●

Append row

Web Dynpro ABAP: Development in Detail

216

Advanced Concepts

May 2006

A new row is appended to the end of the ALV output, regardless of which row is selected. ●

Delete row The selected rows are deleted.

The number of rows that the user can insert or delete depends on how many rows he or she has selected. You use the selection type to define how many rows the user can select at once (see Selecting Rows [page 213]). See Editable ALV in Providing Standard ALV Functions [page 206] for information on which methods to use to show pushbuttons for inserting, appending, and deleting rows.

These pushbuttons are only visible if you have removed write-protection for the ALV output (see Write-Protection and Activation [page 215]). If the selection type No Selection Possible was defined, the user cannot select any rows. In this case, the pushbuttons for inserting and deleting rows are invisible.

Event Handling The event ON_DATA_CHECK contains parameters for getting the indexes of inserted or deleted rows (see ON_DATA_CHECK [page 227]).

4.17.5.4.3

Changing Cell Content

The user can use the following UI elements to change data directly in the ALV output: ●

InputField (see InputField [externaly])

●

CheckBox (see CheckBox [externaly])

●

DropDown list box BY_KEY (see DropDownByKey [externaly])

Class

InputField

CL_SALV_WD_UIE_INPUT_FIELD

CheckBox

CL_SALV_WD_UIE_CHECKBOX

Dropdown list box

CL_SALV_WD_UIE_DROPDOWN_BY_KEY

These classes can be found in the system in the package SALV_WD_CONFIG. For information on displaying one of the UI elements in a cell, see Assigning Properties to Columns and Cells [page 183].

Web Dynpro ABAP: Development in Detail

217

Advanced Concepts

May 2006

You have to switch off the write-protection in order for the user to be able to use the UI elements listed here. You must also make sure that the ALV output is activated (see Write-Protection and Activation [page 215]).

4.17.5.4.4

Defining the Checking Time

In the editable ALV the user can change data and add or delete rows. These changes are initially only stored in the context of the ALV component. At defined times, the system transfers the data of the ALV context into the context of your system and checks the data for the correct data type, and so on. This ensures that future actions are applied to the more current data.

When the user chooses the pushbutton Settings from the toolbar in order to use ALV services, the system automatically checks the data. You can define these additional times at which the current data status of the ALV output is to be synchronized with that of the application: ●

When the user chooses ENTER or triggers a system action Use this setting if you only anticipate a small number of data changes and will not greatly affect the performance of the system by frequent checks.

●

When the user chooses the pushbutton Check This pushbutton is shown by default as soon as you switch off write-protection for the ALV output. This setting is useful if the user is to process multiple data records one after the other without greatly affecting the performance of the system by frequent checks. You should also use this setting if you only want checks to be made if the user triggers the check himself or herself.

●

When you trigger the check in your system (see DATA_CHECK [page 219])

For information on showing or hiding the pushbutton Check, see Editable ALV in Providing Standard ALV Functions [page 206].

Defining the Time of the Check by the User To define which user action triggers the data check, use the methods of the interface class IF_SALV_WD_TABLE_SETTINGS (implementing class CL_SALV_WD_CONFIG_TABLE). Methods for Setting Checking Times Function

Method

Set time

SET_DATA_CHECK

Get time

GET_DATA_CHECK

Event Handling When the data is to be checked, the event ON_DATA_CHECK is triggered (see ON_DATA_CHECK [page 227]).

Web Dynpro ABAP: Development in Detail

218

Advanced Concepts

4.17.6

May 2006

Methods and Events of the Interface Controller

You can use the following methods in the interface controller of the ALV component: ●

DATA_CHECK [page 219]

●

GET_CONFIG_DATA [page 220]

●

GET_MODEL [page 223]

●

GET_MODEL_EXTENDED [page 224]

●

SET_DATA [page 225]

You can also use the following events of the interface controller of the ALV component: ●

ON_AFTER_CONFIG [page 226]

●

ON_CLICK [page 226]

●

ON_DATA_CHECK [page 227]

●

ON_FUNCTION [page 228]

●

ON_LEAD_SELECT [page 229]

●

ON_STD_FUNCTION_AFTE [page 229]

●

ON_STD_FUNCTION_BEFO [page 230]

4.17.6.1

DATA_CHECK

Use You use the DATA_CHECK method in the editable ALV. If the user has changed data in the ALV output, transfer the data from the context node of the ALV component to the context node of your application. In this way, you ensure that all the following functions can be performed on the correct datasets, regardless of whether the user has chosen the Check pushbutton or not.

We strongly recommend using the method before you bind new or changed data (for example, using the BIND_TABLE) to the context node of your application. The entries also undergo several checks to ensure, for example, that the data type and format are correct.

You can determine when the system calls the method automatically: ●

When the user chooses the pushbutton Check

●

When the user chooses RETURN or clicks in another cell

To do this, use the method IF_SALV_WD_TABLE_SETTINGS~SET_DATA_CHECK.

Web Dynpro ABAP: Development in Detail

219

Advanced Concepts

May 2006

Syntax Signature

METHODS DATA_CHECK

Parameter

(Importing) Return values

Exceptions

4.17.6.2

GET_CONFIG_DATA

Use The user can save settings in views for sorting, filtering, performing calculations and so on. The method GET_CONFIG_DATA returns information about the views that the user has saved for the current application: ●

Which views have been saved for the application? What are these views called?

●

Is a view available now (has it been loaded)? What is this view called? Which settings have been saved for this view?

●

Has the user defined any particular view as the initial view? What is this view called? Which settings have been saved for this view?

●

Which of the views belong to which structures? (This only applies when several structures with SET_DATA [page 225] are loaded in one ALV component.) You generate unique configuration keys and assign them to the individual structures. In the configuration key [page 222] example you can see how to generate and assign the configuration key.

Syntax Signature

METHODS GET_CONFIG_DATA IMPORTING S_PARAM_IN TYPE IF_SALV_WD_TABLE=>S_TYPE_PARAM_CONFIG_IN OPTIONAL RETURNING S_PARAM_OUT TYPE IF_SALV_WD_TABLE=>S_TYPE_PARAM_CONFIG_OUT

Web Dynpro ABAP: Development in Detail

220

Advanced Concepts

Parameter (Importing)

S_PARAM_IN

May 2006

Fields in the structure: ●

ACTION (type salv_wd_constant) ○

LIST Lists all the user’s saved views S_PARAM_OUT: T_VIEW_LIST

○

BYNAME Supplies information about the view <VIEW> S_PARAM_OUT: VIEW, R_MODEL

○

ACTUAL Supplies information about the view that is currently loaded S_PARAM_OUT: VIEW, R_MODEL

○

DEFAULT Supplies information about the initial view S_PARAM_OUT: VIEW, R_MODEL

○

LOAD Load the view <VIEW> as the current view

○

KEY Supplies information on the application that is running with which the application can generate a unique key for the current structure. S_PARAM_OUT: USAGE_PATH, ALV_COMPONENT_USAGE

○

SET Assigns the key to the present structure

●

VIEW (type wdr_pers_variant) Name of view for ACTION-BYNAME

●

IS_MODEL_REQUESTED (type wdy_boolean) Determines whether the configuration model is delivered to the view concerned in R_MODEL (S_PARAM_OUT) (performance aspect).

●

CONFIG_KEY (type wdy_config_key) For ACTION-SET: Defines the CONFIG_ID and CONFIG_TYPE (WDY_CONFIG_KEY)

The CONFIG_TYPE should be set to '08’ by default. ●

DEFAULT_MODEL (type s_type_param_get_model) For ACTION-SET:

Defines DEFAULT_COLUMNS and Web Dynpro ABAP: Development in Detail 221 DEFAULT_FIELDS (S_TYPE_PARAM_GET_MODEL) ●

LIST_TYPE (type salv_wd_constant)

Advanced Concepts

Return values

S_PARAM_OUT

May 2006

Fields in the structure: ●

T_VIEW_LIST (type wdr_pers_variants) List of all the saved views

●

VIEW (type wdr_pers_variant) Name (description) of the view

●

R_MODEL (type ref to cl_salv_wd_config_table) Configuration model in accordance with the settings for the view

●

USAGE_PATH (type string) Location of the current application

●

ALV_COMPONENT_USAGE (type string) Name of the component use in the current application

Exceptions

4.17.6.2.1

Configuration Key

The key that you assign to the structure must fulfill the following conditions: ●

It identifies the application in which the ALV output is displayed. You can use the field USAGE_PATH from S_PARAM_OUT for this purpose, for example.

●

It identifies the ALV output within the application. If multiple ALV outputs are displayed in the application, you must be able to distinguish them from one another. To do this, you can use the field ALV_COMPONENT_USAGE, for example, which returns the component usage for the individual ALV outputs.

●

It identifies the structure that is displayed in the ALV output with SET_DATA . To do this you can use any unique character string.

If you connect three components to one another, you generate a key that identifies a structure sufficiently. In this way, a view can be assigned uniquely. The following example shows the steps in a method SET_ALV_CONFIG_ID that are required for generating and assigning the configuration key. METHOD SET_ALV_CONFIG_ID. [ ... ] DATA: L_REF_IF_CONTROLLER TYPE REF TO IWCI_SALV_WD_TABLE, LR_NODE TYPE REF TO IF_WD_CONTEXT_NODE, OWN_KEY TYPE STRING. *... GET RELEVANT NODE OF THE APPLICATION CONTEXT LR_NODE = WD_THIS->APPL_GET_DATA_NODE( ).

Web Dynpro ABAP: Development in Detail

222

Advanced Concepts

May 2006

*... DETERMINE NAME FOR KEY DEPENDING ON THE APPLICATION CONTEXT OWN_KEY = ‘ALV1’. *... SET NODE OF THE APPLICATION CONTEXT L_REF_IF_CONTROLLER->SET_DATA( R_NODE_DATA = LR_NODE ). [ ... ] *... CREATE CONFIGURATION KEY CONSISTING OF * USAGE PATH, COMPONENT USAGE, OWN KEY DATA: LS_PARAM_OUT TYPE IF_SALV_WD_TABLE=>S_TYPE_PARAM_CONFIG_OUT, LS_PARAM_IN TYPE IF_SALV_WD_TABLE=>S_TYPE_PARAM_CONFIG_IN, L_KEY TYPE STRING, L_KEY_32 TYPE STRING. LS_PARAM_IN-ACTION = IF_SALV_WD_TABLE=>KEY. LS_PARAM_OUT = L_REF_IF_CONTROLLER->GET_CONFIG_DATA( LS_PARAM_IN ). CONCATENATE LS_PARAM_OUT-USAGE_PATH LS_PARAM_OUT-ALV_COMPONENT_USAGE OWN_KEY INTO L_KEY SEPARATED BY '&'. *... HASH CONFIGURATION KEY TO UNIQUE KEY OF 32 CHARS LENGTH TRY. L_KEY_32 = CL_RSMDS_HASH_UTILITIES=>TO_HASH_C32( L_KEY ). CATCH CX_RSMDS_INPUT_INVALID CX_RSMDS_INPUT_INVALID_TYPE. ENDTRY. [ ... ] *... SET NEW CONFIGURATION KEY LS_PARAM_IN-ACTION = IF_SALV_WD_TABLE=>SET. LS_PARAM_IN-CONFIG_KEY-CONFIG_TYPE = '08'. LS_PARAM_IN-CONFIG_KEY-CONFIG_ID = L_KEY_32. L_REF_IF_CONTROLLER ->GET_CONFIG_DATA( LS_PARAM_IN ).

4.17.6.3

GET_MODEL

Use The method GET_MODEL returns a standard execution of the ALV configuration model. You can, therefore, configure the ALV output to meet your own specific requirements. The standard execution of the ALV configuration model contains all the field and column objects in accordance with the attributes in the application’s context node.

You can use the GET_MODEL_EXTENDED [page 224] method to determine whether you require the field objects on their own, or the column objects as well.

Web Dynpro ABAP: Development in Detail

223

Advanced Concepts

May 2006

Information about ALV Output If you configure the ALV output using your application, or the user changes the ALV output, this has an effect on the ALV configuration model. â&#x2014;?

The object for the corresponding field is changed by configuring the filter, sorting, and aggregation conditions.

â&#x2014;?

The object for the corresponding column is changed as a result of hiding and showing a column, for example.

You can use the method GET_MODEL to call the current status of the ALV output with all the settings for services, functions, and so on. In this way, you can transfer all the properties of a particular ALV output into another component and continue processing there.

Prerequisites You have generated a context node with all the attributes and transferred it to the ALV component using external context mapping [page 65] or the method SET_DATA [page 225].

Syntax METHODS GET_MODEL

Signature

OPTIONAL RETURNING VALUE TYPE REF TO CL_SALV_WD_CONFIG_TABLE

Parameter

(Importing) Return values

VALUE

Exceptions

4.17.6.4

Standard execution of ALV configuration model

GET_MODEL_EXTENDED

Use The method GET_MODEL_EXTENDED returns the ALV configuration model. You can, therefore, configure the ALV output to meet your own specific requirements. In contrast to the standard execution of the ALV configuration model, which you retrieve using the GET_MODEL [page 223] method, with the GET_MODEL_EXTENDED method, you can decide whether you require the column objects in addition to the field objects.

Prerequisites You have generated a context node with all the attributes and transferred it to the ALV component using external context mapping [page 65] or the method SET_DATA [page 225].

Web Dynpro ABAP: Development in Detail

224

Advanced Concepts

May 2006

Syntax METHODS GET_MODEL_EXTENDED

Signature

IMPORTING S_PARAM TYPE IF_SALV_WD_TABLE=>S_TYPE_PARAM_GET_MODEL OPTIONAL RETURNING VALUE TYPE REF TO CL_SALV_WD_CONFIG_TABLE

Parameter

S_PARAM

(Importing)

Scope of ALV configuration model Constants: ●

default_columns TYPE ABAP_BOOL

Return values

VALUE

Exceptions

4.17.6.5

Standard execution of ALV configuration model

SET_DATA

Use You use the method SET_DATA for two reasons: ●

To transfer the context of your application to the ALV component instead of using external context mapping [page 65]

●

To display the data from dynamically generated context nodes in the ALV output

Prerequisites The context nodes that you transfer to the method SET_DATA as parameters must already exist. It does not matter, however, whether you generated the context node for design time in the Web Dynpro Explorer or added it using the program during runtime [page 79].

Web Dynpro ABAP: Development in Detail

225

Advanced Concepts

May 2006

Syntax METHODS SET_DATA

Signature

IMPORTING R_NODE_DATA

R_NODE_DATA

Parameter (Importing) Return values

Exceptions

4.17.6.6

TYPE REF TO IF_WD_CONTEXT_NODE

Name of context node that is to be transferred to ALV component

ON_AFTER_CONFIG

Use This event is currently not supported.

4.17.6.7

ON_CLICK

Use The event ON_CLICK is triggered when the user clicks on one of the following UI elements in a cell of the ALV output: ●

Button

●

LinkToAction

●

ToggleButton

Prerequisites You have registered for this event.

Syntax Signature

EVENTS ON_CLICK IMPORTING R_PARAM TYPE REF TO IF_SALV_WD_TABLE_CLICK

Web Dynpro ABAP: Development in Detail

226

Advanced Concepts

Parameter

May 2006

R_PARAM

(Importing)

Class Interface Attributes ●

ATTRIBUTE Attribute of context node for the column in which the cell with the UI element can be found.

●

COLUMN Technical name of the column in which the cell with the UI element can be found

●

INDEX Index of the line in which the cell with the UI element can be found.

●

VALUE Value of cell after click

Exceptions

4.17.6.8

ON_DATA_CHECK

Use The event ON_DATA_CHECK is triggered when data that has been changed is checked in an editable ALV output: ●

The user has inserted or appended one or more rows

●

The user has deleted one or more rows

●

The user has changed data in a cell

You can define when the data check is carried out. ●

When the user chooses the pushbutton Check from the toolbar

●

When the user chooses ENTER or triggers a system action

●

When you execute the method DATA_CHECK (see DATA_CHECK [page 219])

Prerequisites You have registered for this event.

Syntax Signature

EVENTS ON_DATA_CHECK IMPORTING R_PARAM TYPE REF TO IF_SALV_WD_TABLE_DATA_CHECK

Web Dynpro ABAP: Development in Detail

227

Advanced Concepts

Parameter

May 2006

R_PARAM

Class Interface Attributes

(Importing)

●

T_INSERTED_ROWS Indexes and contents of the rows inserted

●

T_DELETED_ROWS Indexes and contents of the rows deleted

●

T_MODIFIED_CELLS Position and values of cells after the change has been made

●

T_ERROR_CELLS Cells in which errors have occurred

Exceptions

4.17.6.9

ON_FUNCTION

Use The event ON_FUNCTION is triggered when the user chooses a UI element in the toolbar that you have created for a self-defined, application-specific function.

Prerequisites

Syntax Signature

EVENTS ON_FUNCTION IMPORTING R_PARAM TYPE REF TO IF_SALV_WD_TABLE_FUNCTION

Parameter

R_PARAM

(Importing)

Class Interface Attributes ●

ID Function key (as chosen by user)

Exceptions

Web Dynpro ABAP: Development in Detail

228

Advanced Concepts

4.17.6.10

May 2006

ON_LEAD_SELECT

Use The event ON_LEAD_SELECT is triggered when the user changes the lead selection in an ALV output.

Prerequisites You have defined a selection type for the ALV output that allows both the selection of rows and the modification of lead selection.

Syntax EVENTS ON_LEAD_SELECT

Signature

IMPORTING R_PARAM TYPE REF TO IF_SALV_WD_TABLE_FUNCTION

Parameter

R_PARAM

(Importing)

Class Interface Attributes ●

INDEX Lead selection index after the selection was changed

●

OLD_INDEX Lead selection index before the selection was changed

Exceptions

4.17.6.11

ON_STD_FUNCTION_AFTE

Use The event ON_STD_FUNCTION_AFTE is triggered when the user performs one of the following actions: ●

The user chooses one of the pushbuttons Copy or OK in the Settings dialog box.

●

The user chooses the Delete Filter pushbutton in the toolbar.

You cannot use this event to determine which of the standard ALV functions the user has executed.

Prerequisites You have registered for this event.

Web Dynpro ABAP: Development in Detail

229

Advanced Concepts

May 2006

Syntax EVENTS ON_STD_FUNCTION_AFTE

Signature

IMPORTING R_PARAM TYPE REF TO IF_SALV_WD_TABLE_STD_FUNCTION

Parameter

R_PARAM

(Importing)

●

Exceptions

4.17.6.12

Class Interface Attributes ID (currently not able to be used)

ON_STD_FUNCTION_BEFO

Use The event ON_STD_FUNCTION_BEFO is triggered when the user performs one of the following actions: ●

The user chooses the Settings pushbutton in the toolbar.

●

The user chooses the Filter pushbutton in the toolbar.

You cannot use this event to determine which of the standard ALV functions the user has chosen.

Prerequisites You have registered for this event.

Syntax Signature

EVENTS ON_STD_FUNCTION_BEFO IMPORTING R_PARAM TYPE REF TO IF_SALV_WD_TABLE_STD_FUNCTION

Parameter

R_PARAM

(Importing) Exceptions

Class Interface Attributes ●

ID (currently not able to be used)

Web Dynpro ABAP: Development in Detail

230

Advanced Concepts

May 2006

4.18 Screen Design Time Conversion Use When you want to create Web Dynpro user interfaces that correspond to classical screens of ABAP programs, you can use the functions of the Screen Design Time Conversion. Based on the source code of the ABAP screen, the Screen Design Time Conversion creates Web Dynpro UI elements together with their corresponding context metadata and includes them in an existing Web Dynpro view. This view, filled with the generated UI elements, provides a first approximation of the underlying screen. The layout of the generated Web Dynpro UI elements will only be an approximation of the underlying screens. Manual rework will be necessary to ●

correct the layout,

●

extract the UI logic from the ABAP code, and

●

call business logic from Web Dynpro.

Screen Design Time Conversion is a pure design time tool and does not provide any runtime support for the generated Web Dynpro for ABAP objects, in particular, converting flow logic of the screen program and calling ABAP modules is out of scope. The tool is implemented as a wizard within the Web Dynpro View Editor which provides a means to take a ABAP screen as a template for the layout of a part of a Web Dynpro view. The wizard will not change the ABAP code that was called by the screen program. As a result, all UI objects contained in the ABAP code, like GUI controls or ABAP lists, are not included in the conversion. These objects have to be rewritten using Web Dynpro for ABAP. For more information see Restrictions [page 232]. The used screens and ABAP program sources remain unchanged after the execution of the wizard.

Process Flow To execute the conversion, proceed as follows: ...

1. Open the View Editor of the Web Dynpro Exlorer, switch to tab Layout and select

2. In dialog window Template Gallery double-click on Standard → Screen. 3. In the next dialog box insert the name of the program, to which the screen belongs to, and the screen number that should be converted. 4. Choose Execute to start the conversion.

Result For each screen element, a corresponding Web Dynpro UI element is created. All UI elements are inserted into a transparent container element, which is added at the end of the currently selected container in the Web Dynpro view layout.

Web Dynpro ABAP: Development in Detail

231

Advanced Concepts

May 2006

Additionally, a context node containing all bindable attributes – that is, properties that are relevant to runtime modifications - is generated for each Web Dynpro UI element, with the exception of TabStrip. For more information see Dynpro Controls [page 233]. The ID of the element and its context node is usually identical to the name of the corresponding screen element. However, because the naming convention for Web Dynpro elements is more restrictive, the screen element names will be changed in some cases.

4.18.1

Restrictions

The design time conversion of screen programs includes the objects in the screen source the objects in the ABAP code remain untouched. Therefore, not all UI-related objects in the ABAP code are covered. In particular, the following objects cannot be converted automatically: ●

GUI controls [externaly]

●

SAP graphics

●

ABAP lists

●

Selection screens and selection options

●

Office and desktop integration

●

Dynamically created screens, for example. using EXPORT DYNPRO

Because no runtime support for the converted screens exists, all screen-based services will no longer be available for the converted Web Dynpro objects, for example: ●

Batch input

●

GuiXT

●

Transaction variants

●

SAPGUI scripting

Web Dynpro ABAP: Development in Detail

232

Advanced Concepts

4.18.2

May 2006

Transformation Rules

Purpose The main concept behind the transformation rules for screens programs to Web Dynpro objects is the exclusive use of standard Web Dynpro features. Therefore, the resulting Web Dynpro view will only be an approximation to the original screen, in particular in the case of layout management. The following chapters describe the rules for transforming the original objects into their Web Dynpro counterparts.

4.18.2.1

Layout Management

Features A standard Web Dynpro layout manager (for MatrixLayout) is used to arrange the UI elements on the Web Dynpro view.

Constraints Since the layout management used for screens is based on absolute (grid) positioning and Web Dynpro does not offer this possibility, the resulting layout can only be an approximation of the original one. Therefore, you must correct the position and size of the UI elements on converted screens.

4.18.2.2

Dynpro Controls

Purpose For each screen element, a corresponding Web Dynpro UI element is created. Additionally, a context node containing all bindable attributes â&#x20AC;&#x201C; that is, properties that are relevant to runtime modifications - is generated for each Web Dynpro UI element, with the exception of TabStrip. The ID of the element and its context node is usually identical to the name of the corresponding screen element. However, because the naming convention for Web Dynpro elements is more restrictive, the screen element names will be changed in some cases. The mapping description often refers to specific attributes of a screen element:

Web Dynpro ABAP: Development in Detail

233

Advanced Concepts

May 2006

Element Attributes in the Classic Screen Painter

●

Element attributes are entries found in section 1 of the above figure

●

Element dictionary attributes are entries found in section 2

●

Element program attributes are entries found in section 3

●

Element display attributes are entries found in section 4

●

Element runtime attributes are fields found in the SCREEN structure of the screen element

Web Dynpro ABAP: Development in Detail

234

Advanced Concepts

May 2006

The following section lists the screen elements are only mapped onto Web Dynpro UI elements.

4.18.2.2.1

Checkbox

Integration The Checkbox screen element is mapped onto the CheckBox Web Dynpro UI element. CheckBox Mapping Rules CheckBox Property

Bound to Context Attribute

Value

Checked

VALUE

State of the checkbox

Enabled

ENABLED

Complement of element program attribute Input

State

Same as InputField

Text

Element attribute Text

Tooltip

Element attribute Quick Info

Visible

VISIBLE

Element runtime attribute Active

CheckBox Event

Action Name

Description

OnToggle

TBD

FctType is the type of the function code and FctCode is the function code of the element. This action is only defined if the FctCode attribute is not empty.

4.18.2.2.2

Frame

Integration The Frame or Box screen element is mapped onto the Group Web Dynpro UI element with a caption. In contrast to the Frame screen element, the Group is hierarchical and contains all Web Dynpro UI elements as children. The recalculation of the parent-child relationship is carried out during the conversion.

Group Mapping Rules Group Property

Bound to Context Attribute

Layout

Web Dynpro ABAP: Development in Detail

Value Constant MatrixLayout

235

Advanced Concepts

May 2006

Design

Constant Primarycolor

Enabled

Constant True

HasContentPadding

Constant True

Height

INITIAL

ScrollingMode

Constant None

Tooltip

INITIAL

Visible

VISIBLE

Width

Element runtime attribute Active INITIAL

Caption Property

Bound to Context Attribute

Value

Enabled

Constant True

ImageFirst

Constant True

ImageSource

IMAGE_SOURCE (if screen field was a FRAME_TMPL)

Derived from element attribute Icon

Text

TEXT (if screen field was a FRAME_TMPL)

Element attribute Text

Tooltip

TOOLTIP (if screen field was a FRAME_TMPL)

Element attribute Quick Info

Visible

VISIBLE

Element runtime attribute Active

4.18.2.2.3

I/O Field

Integration An I/O Field or Template screen element is mapped onto one of the following: ●

An InputField - if the OUTPUTONLY flag is not set and the dropdown type is No dropdown box.

●

A TextView - if the OUTPUTONLY flag is set.

●

A Label - if the flag LABELLEFT (LABELRIGHT) and OUTPUTONLY is set and there is an I/O or Text Field to the right (left) of the element

●

A DropDownByKey - if the dropdown type is list box or list box with key

InputField Mapping Rules InputField Property

Bound to Context Attribute

Web Dynpro ABAP: Development in Detail

Value

236

Advanced Concepts

May 2006

Enabled

Constant True

Length

LENGTH

Element attribute Defined Length

Password

PASSWORD_FIELD

Element display attribute Invisible

ReadOnly

READ_ONLY

Complement of element program attribute Input

Size

Constant Standard

State

Constant Normal or Required depending on screen element

Tooltip

Element attribute Quick Info

Value

VALUE

Set at runtime

Visible

VISIBLE

Element runtime attribute Active

Bound to Context Attribute

Description

TextView Mapping Rules TextView Property Design

Constant Standard

Enabled

Constant True

Layout

Constant Native

Text

VALUE

Element attribute Text

Tooltip

TOOLTIP

Element attribute Quick Info

Visible

TEXT_VISIBLE

Element runtime attribute Active

Wrapping

INITIAL

Label Mapping Rules Label Property

Bound to Context Attribute

Description

Design

Constant Light if LABELRIGHT==X, constant Standard otherwise

Enabled

Constant True

LabelFor

ID of the corresponding DynproInput element. In general, this is the ID of the first element to the right of the text field.

Web Dynpro ABAP: Development in Detail

237

Advanced Concepts

May 2006

Text

Element attribute Text

Tooltip

Element attribute Quick Info

Visible

VISIBLE

Element runtime attribute Active

Width

INITIAL

Wrapping

INITIAL

DropDownByKey Mapping Rules DropDownByKey Property

Bound to Context Attribute

Description

Enabled

ENABLED

Complement of field program attribute Input

SelectedKey

ABAP_VALUE

Set at runtime

Size

Constant Standard

State

Constant Normal

Tooltip

Element attribute Quick Info

Visible

VISIBLE

Width

Element runtime attribute Active INITIAL

DropDownByKey Event

Action Name

Description

OnSelect

TBD

FctType is the type of the function code and FctCode is the function code of the element. This action is only defined if the FctCode attribute is not empty.

4.18.2.2.4

Pushbutton

Integration The Pushbutton screen element is mapped onto the Web Dynpro UI element Button.

Button Mapping Rules Button Property

Bound to Context Attribute

Design Enabled

Value Constant Standard

ENABLED

Web Dynpro ABAP: Development in Detail

Complement of element program attribute Input

238

Advanced Concepts

May 2006

ImageFirst

Constant True

ImageSource

IMAGE_SOURCE (if screen field was a PUSH_TMPL)

Size

Derived from element program attribute Icon Constant Standard

Text

TEXT (if screen field was a PUSH_TMPL)

Element attribute Text

Tooltip

TOOLTIP (if screen field was a PUSH_TMPL)

Element attribute Quick Info

Visible

VISIBLE

Element runtime attribute Active

Width

INITIAL

Button Event

Action Name

Description

OnAction

TBD

FctType is the type of the function code and FctCode is the function code of the element.

4.18.2.2.5

Radio Button

Integration The Radio Button screen element is mapped onto the Web Dynpro UI element RadioButton. The RadioButton group – that is, the (invisible) screen element that defines which RadioButtons belong together – is implemented by creating a context node that contains the group ID and all nodes for the RadioButtons in the group.

RadioButton Mapping Rules RadioButton Property

Bound to Context Attribute

Value

Enabled

ENABLED

Complement of element program attribute Input

KeyToSelect SelectedKey

Index of the RadioButton in the group RADIO_GROUP

Index of the RadioButtonGroup

State

Constant Normal

Text

Element attribute Text

Tooltip

Element attribute Quick Info

Web Dynpro ABAP: Development in Detail

239

Advanced Concepts

May 2006

Visible

VISIBLE

Element runtime attribute Active

RadioButton Event

Action Name

Description

OnSelect

TBD

FctType is the type of the function code and FctCode is the function code of the element. This action is only defined if the FctCode attribute is not empty.

4.18.2.2.6

Step Loop

Integration The Step Loop screen element is mapped onto the Web Dynpro UI element MultiPane.

MultiPane Mapping Rules MulitPane Property

Bound to Context

Value

AccessibilityDescription

INITIAL

ColumnCount

Constant 1

DataSource

Node with same ID than Multipane

A 0:n node that contains the data for the MultiPane element. The data for the UI elements in the MultiPane is contained in subnodes of this node.

EmptyText

INITIAL

Enabled

Constant True

FirstActualPane

Attribute TC_TOP_LINE

First visible line in the step loop.

FirstVisiblePane

Attribute TC_TOP_LINE

First visible line in the step loop.

Height PaneCount

Height (in em) of the step loop at design time. Attribute PANE_COUNT

Number of visible panes.

Tooltip

INITIAL

Visible

Constant True

Width

Width (in em) of the step loop at design-time.

Web Dynpro ABAP: Development in Detail

240

Advanced Concepts

May 2006

Context Structure

Context Structure of the MultiPane The context node for a MultiPane (marked with 1 in the figure above) contains the following elements: ●

A node with cardinality 0:n for the step loop data (2 in above figure), which is used as the data source for the MultiPane UI element.

●

This node contains one subnode (3 in above figure) for each UI element in a step loop line.

The attributes TC_TOP_LINE and PANE_COUNT belong to the multipane’s context node and not to the data node.

4.18.2.2.7

Subscreen

Integration The Subscreen screen element is only a placeholder that defines an area on the main screen in which an actual screen, identified by a program name and a screen number, is displayed at runtime. For this reason, the only design time information for a subscreen in Web Dynpro is a placeholder for a Web Dynpro view, the ViewContainerUIElement, with the following properties:

ViewContainerUIElement Mapping Rules ViewContainerUIElement Property

Bound to Context Attribute

Value

Enabled

Constant True

Tooltip

INITIAL

Visible

Constant Visible

Web Dynpro ABAP: Development in Detail

241

Advanced Concepts

4.18.2.2.8

May 2006

Table Control

Integration The Table Control screen element is mapped onto the Web Dynpro UI element Table, which contains a set of TableColumn elements. The TableColumn consists of a caption for the column header and a Web Dynpro UI element that was obtained by transforming a noncontainer screen element.

Table Control Mapping Rules Table Property

Bound to Context

AccessibilityDescription DataSource

Value INITIAL

Node TABLE_DATA

The data for the cells in the table control

Design

Constant Standard

Enabled

Constant True

FirstVisibleRow

Attribute TC_TOP_LINE (default 0)

First visible line in table control

FirstActualRow

Attribute TC_TOP_LINE (default 0)

First visible line in table control

FooterVisible

Attribute FOOTER_VISIBLE

If true, the table footer with the paging arrows is visible.

ReadOnly

Constant False

RowCount

Constant -1

SelectionMode

Constant None Note: The selection mode for the table control (Selectability attribute for rows) is mapped by inserting a special DynproTableColumn that contains checkboxes with ID MARK for the selection markers.

Tooltip

INITIAL

Visible

Attribute VISIBLE (default visible/2)

Element runtime attribute Active

VisibleRowCount

Attribute TC_LINES

Number of visible lines in the table control. Set at runtime using the LINES attribute of the table control structure.

Width

INITIAL

TableColumn Mapping Rules

Web Dynpro ABAP: Development in Detail

242

Advanced Concepts

TableColumn Property

May 2006

Bound to Context Attribute

Value

Design

Constant Standard

FilterValue

INITIAL

HAlign

Constant Auto

Resizable

Constant True

Selected

COLUMN_SELECTED

True, if the column for table control is selected. Set at runtime using the SELECTED attribute of the COLS table, which is part of the table control structure.

Visible

COLUMN_VISIBLE

True, if the column is to be visible. Set at runtime using the VISIBLE attribute of the COLS table, which is part of the table control structure.

Width

WIDTH

Width of the column (in character grids). Set at runtime using the SCREEN_LENGTH attribute of the COLS table, which is part of the table control structure.

Context Structure

Context Structure of the Table The context node for a table control (marked with 1 in the figure above) contains the following elements: â&#x2014;?

A node with cardinality 0:n for the table data (2 in above image), which is used as the data source for the Table UI element.

â&#x2014;?

The subnodes of the table data node (3 in above figure) contain the data for the table cells. The structure of these nodes is element-specific and corresponds to the context structure of the non-container screen elements. If a row selection attribute is set, a

Web Dynpro ABAP: Development in Detail

243

Advanced Concepts

May 2006

node with the name of the corresponding ABAP variable is created. It stores the data for the selection column. â&#x2014;?

Nodes for the table columns (4 in above figure). These nodes contain the context attributes used for binding TableColumn properties as described above.

4.18.2.2.9

TabStrip

Integration The TabStrip screen element is mapped to the Web Dynpro UI element TabStrip, which contains TabStripPage elements for the tabs. The TabStripPage contains a ViewContainerUIElement for the subscreen display and a caption for the tab title that represents the Pushbutton screen element used to define the tab.

TabStrip Mapping Rules TabStrip Property

Bound to Context Attribute

Value

Enabled

Constant True

Height

Height of the TabStrip in RasterLayout units

SelectedTab

VALUE

Tooltip Visible

ID of the currently active TabStrip page INITIAL

VISIBLE

Width

Element runtime attribute Active INITIAL

TabStrip Events

Action Name

Description

onSelect

DC_TABSTRIP_SELECT

Handles the changing of a tab in the TabStrip

TabStripPage Property

Bound to Context Attribute

Value

Enabled

ENABLED

HasContentPadding

Constant True

Visible

VISIBLE

Caption Property

Bound to Context Attribute

Value

Enabled

ENABLED

Complement of field program attribute Input

ImageFirst

Constant True

ImageSource

IMAGE_SOURCE (if screen field was a PUSH_TMPL)

Derived from Element attribute Icon

Text

TEXT

Element attribute Text

Web Dynpro ABAP: Development in Detail

244

Advanced Concepts

May 2006

(if screen field was a PUSH_TMPL) Tooltip

TOOLTIP (if screen field was a PUSH_TMPL)

Element attribute Quick Info

Visible

VISIBLE

Element runtime attribute Active

Context Structure

Context Structure of the TabStrip The context node for a TabStrip contains the following elements: ●

One context node for each tab in the TabStrip, which contains the following attributes:

TabStripPage Context Attribute Name

Description

VISIBLE

Element runtime attribute Active

ENABLED

Complement of element runtime attribute Input

●

Attributes for runtime support of the TabStrip:

TabStrip Context Attribute Name

Description

VISIBLE

Element runtime attribute Active

VALUE

Holds the ID of the currently active tab

4.18.2.2.10

Text Field

Integration A Text Field screen element is mapped onto one of the following: ●

A Label - if ○

An I/O field with the same name as the Text Field exists

Web Dynpro ABAP: Development in Detail

245

Advanced Concepts

○ ●

May 2006

The flag LABELLEFT (LABELRIGHT) is set and there is an I/O or Text Field to the right (left) of the element

A TextView - in all other cases

Label Mapping Rules Label Property

Bound to Context Attribute

Description

Design

Constant Light if LABELRIGHT==X, constant Standard otherwise

Enabled

Constant True

LabelFor

ID of the corresponding DynproInput element. In general, this is the ID of the first element to the right of the text field.

Text

Element attribute Text

Tooltip

Element attribute Quick Info

Visible

VISIBLE

Element runtime attribute Active

Width

INITIAL

Wrapping

INITIAL

TextView Mapping Rules TextView Property

Bound to Context Attribute

Description

Design

Constant Standard

Enabled

Constant True

Text

Element attribute Text

Tooltip

Element attribute Quick Info

Visible

VISIBLE

Wrapping

Web Dynpro ABAP: Development in Detail

Element runtime attribute Active INITIAL

246

Advanced Concepts

May 2006

4.19 Version Comparisons in Web Dynpro for ABAP Version managements is used to store different versions of ABAP development objects. It allows you to display older versions of an object, compare versions and reset them, if necessary, to reverse unintended modifications. A version comparison must also take into account that, in addition to classic code sections, a Web Dynpro application also contains a large amount of metadata. The ABAP Workbench provides you with a version comparison for the development of the individual entities of a Web Dynpro component. You can compare different versions of: â&#x2014;?

Views

â&#x2014;?

Windows

â&#x2014;?

Controllers

Versions of an Object The currently processed version of the object is always retained in the development database. Furthermore, for every development object released, a corresponding version is stored in the version database. You are also able to store a version of an object in the version database without releasing it. To do so, the object must be selected in the object list and displayed in the Editor area. Open the menu in the upper line of the Workbench and choose: Utilities -> Versions -> Generate Version

Starting a Version Comparison Open the menu in the upper line of the Workbench and choose: Utilities -> Versions -> Version Management All stored versions of the selected object are displayed in a list. In addition to the current version in the development database, you are also shown all previously released or all active versions (see above) stored in the version database. . Similarly to the Editor itself, the To start a comparison, select two entries and choose subsequent screen then provides a number of tabs with all implementation areas of the object. All areas containing differences between the two compared objects are indicated by a yellow triangle in the header line of the relevant tab. For example, if one of two versions of a view features an additional UI element, the Layout tab is flagged with the yellow triangle in the version comparison. For all implementation areas without a yellow triangle the compared object versions are identical. On each tab, the individual implementation details of the two versions are compared and contrasted in table form. Any differences are highlighted.

Web Dynpro ABAP: Development in Detail

247

Advanced Concepts

May 2006

4.20 Quality Assurance One of the most important objectives when developing Web applications is to ensure a consistent high quality of the finished product. These sections contain information about handling error cases. Different tracing techniques are introduced. Web Dynpro Trace Tool [page 248] ICM Tracing [page 250] HTTP Browser Tracing [page 252]

4.20.1

Web Dynpro Trace Tool

Use The Web Dynpro trace tool supports the analysis of problems and errors arising in Web Dynpro ABAP, by collecting and listing the data related to the Web Dynpro ABAP application.

Prerequisites For the additional function to display the trace file you need software that is able to read ZIP files.

Features The Web Dynpro trace tool can be activated for a specific user on an application server. All Web Dynpro applications started within 30 minutes can then be traced for this user. To attach additional information to the trace and to control the tracing, an additional frame is included in the dynpro frameset. The content of this frame is filled by the trace tool. Example: Tracing of WDR_TEST_EVENTS

Web Dynpro ABAP: Development in Detail

248

Advanced Concepts

May 2006

Activities ...

1. Activate tracing in the SAP GUI. In transaction WD_TRACE_TOOL choose the pushbutton Activate for this User. This sets the status of the trace to active for the user in question. 2. Start the Web Dynpro application you want to trace.

Web Dynpro ABAP: Development in Detail

249

Advanced Concepts

May 2006

A new area, Web Dynpro Trace Tool, appears in the window of the Web Dynpro application. It contains a text field in which where you can enter comments about the screen displayed. 3. Execute the application until you get to the problem spot. a. Describe the separate interaction steps to reproduce the problem, for instance, enter “choose Continue”. b. Describe what should have happened, for example, the table should have been filled. c. Describe what actually did happen, for example, the table remained empty. The text field is automatically sent off when you make your next interaction step. Alternatively, you can choose Add. If you want to explain the problem in more detail, you can add a file with additional information, such as a screenshot. To do this choose Browse to navigate to the file you want and attach it with Add File. 4. Download the trace file and exit the tracing by choosing Save Trace as ZIP & Exit. Attach the trace file to an appropriate SAPNet R/3 front end message and send the message to SAP.

All the UI-relevant data is saved in the trace, even data from fields whose status was switched to hidden. For this reason you should not send traces from applications that contain sensitive data.

4.20.2

ICM Tracing

Use When developing a Web application, you will want to test parts of your application and analyze the coding’s dynamic behavior. Occasionally this will result in errors that cannot be solved even with the help of the Debugger. So that you can analyze the cause further, you need to be able to record the datastreams to and from the SAP Web Application Server. The SAP Web Application Server enables you to do this in the form of tracing. The component that regulates HTTP data traffic is the Internet Communication Manager [externaly], (ICM). You can use Transaction SMICM to manage and trace this SAP kernel component.

For more information about the ICM, see Internet Communication Manager (ICM) [externaly]. The following information explains how you can use ICM tracing.

Prerequisites You have basic knowledge about creating Web applications and the Internet Communication Manager.

Web Dynpro ABAP: Development in Detail

250

Advanced Concepts

May 2006

Activities ...

1. Call Transaction SMICM. 2. Choose Goto → Trace file → Display File or Display Start. This displays the trace file. Here is an extract from a trace file: ICM Tracefile (dev_icm) trc file: "dev_icm", trc level: 1, release: "700" [Thr

1] Mon Oct 27 17:19:11 2003

[Thr

1] systemid:

324 (IBM RS/6000 with AIX)

[Thr

1] version:

7000

[Thr

1] patchlevel: 0

(server: 0)

[Thr

1] patchno:

(server: 0)

[Thr

1] intno

20034400

[Thr

1] make:

multithreaded, Unicode, 64 BIT

[Thr

1] pid:

720906

[Thr

1] Mon Oct 27 17:19:12 2003

[Thr this

1] *** WARNING => maximum number of sockets supported on

(server: 20034400)

host (1993) less than parameter icm/max_sockets (2048) [icxxman_mt.c 2349] [Thr

1] ICM running on: is0206.wdf.sap-ag.de

[Thr

1] MtxInit: -2 0 0

[Thr

1] IcmInit: listening to admin port: 65000

[Thr

1] DpSysAdmExtCreate: ABAP is active

[Thr

1] DpSysAdmExtCreate: JAVA is not active

[Thr

1] DpShMCreate: sizeof(wp_adm)##9240#(1320)

[Thr

1] DpShMCreate: sizeof(tm_adm)##3159720#(15720)

[Thr

1] DpShMCreate: sizeof(wp_ca_adm)##8000#(80)

[Thr

1] DpShMCreate: sizeof(appc_ca_adm)#8000#(80)

[Thr

1] DpShMCreate: sizeof(comm_adm)##126400#(632)

[Thr

1] DpShMCreate: sizeof(vmc_adm)##0#(592)

[Thr

1] DpShMCreate: sizeof(wall_adm)##(40056/36728/64/192)

[Thr 1] DpShMCreate: SHM_DP_ADM_KEY##(addr: 0x7000000000f0000, size: 3395432) [Thr

1] DpShMCreate: allocated sys_adm at 0x7000000000f0000

[Thr

1] DpShMCreate: allocated wp_adm at 0x7000000000f1bc8

Web Dynpro ABAP: Development in Detail

251

Advanced Concepts

May 2006

[Thr

1] DpShMCreate: allocated tm_adm_list at 0x7000000000f3fe0

[Thr

1] DpShMCreate: allocated tm_adm at 0x7000000000f4008

[Thr

1] DpShMCreate: allocated wp_ca_adm at 0x7000000003f76b0

There are several levels for a trace. The trace level is set to 1 by default. This setting creates a short log of only the most important system events and errors. This level is not usually sufficient to find out the precise cause of the error, however, which is why you can change the trace level interactively. 3. To increase the trace level, on the initial screen of Transaction SMICM choose Goto â&#x2020;&#x2019; Trace level â&#x2020;&#x2019; Increase. You have the option of setting the level directly, or increasing or reducing it by one level. 1 is the lowest level, 3 is the highest level with the greatest level of detail for the trace entries. All data traffic, amongst other things, is recorded in the highest level.

Since trace level 3 records all data traffic, you must make sure that you set this level to trace an error situation only and that you reset it to the default value 1 immediately after you have finished the trace. If you do not do this, very large data volumes will be written to the file system, which could cause your hard disk partition to overrun. For more information about managing the ICM process, see Monitoring the ICM with the ICM Monitor [externaly].

4.20.3

HTTP Browser Tracing

Use To analyze the dynamic behavior of your coding, you can use HTTP browser tracing as an alternative to ICM Tracing [page 250]. To do this, install an http proxy [page 256] tool locally on your computer, which you can then use to trace all HTTP traffic between the browser and the server.

There are different HTTP proxy tools. We do not recommend a specific HTTP proxy tool from any provider. You choose which tool you will use. Note the license conditions of the tool you select.

Prerequisites You have installed an HTTP proxy tool on your computer.

Example Since HTTP proxy tracing for the Web Dynpro for ABAP and the BSP program model have similar functions, an HTTP trace analysis is explained below using the example of a BSP application.

Web Dynpro ABAP: Development in Detail

252

Advanced Concepts

May 2006

Create a small test program, such as: <%@page language="ABAP"%> <html><body><form method="POST"> <input type=text name="test" value="<%=test%>"> <input type=submit> </form></body></html>

Start your test program in the browser, perform the user authentication and then enter a value in the input field. The roundtrip is started when you click on the button. This is how the HTTP trace looks (this is an extract and has been edited): Connection: 1 -- HTTP Request received from browser 365 bytes GET /sap/bc/bsp/sap/bcm00/helloworld.htm HTTP/1.1 Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */* Accept-Language: en-us,de;q=0.5 User-Agent: Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 5.0) Host: ld0020.wdf.sap.corp:50021

The browser was started and an HTTP request was sent to the server. The trace contains a lot of useful information. The first line of the HTTP request is always in the format HTTP verb (usually GET or POST), URL, and the HTTP protocol used (HTTP/1.0 or HTTP/1.1). For the GET verb, all parameters (form fields) are specified as part of the URL using the delimiters ? and &. The parameters are placed in the HTTP body for the POST verb. The URL is always an absolute URL. Even if relative URLs are used in the HTML document, the browser changes them into absolute URLs to retrieve them. The Accept header lists all types of responses that the browser can understand. This list is always completed by the wildcard */* (accept everything). The Accept-Language header is very important. This header mirrors the browserâ&#x20AC;&#x2122;s language settings. It lists the languages that the user specified as possible languages. SAP Web AS will use these languages to perform the logon in the required language. The User-Agent header identifies the browser. This header is often employed during the rendering to compensate for the small differences in HTML that the different browsers can understand. The Host header represents the host name that was used originally within the URL. The GET line only lists the absolute URL and does not represent the host name. This information is stored in the Host header.

Note that this host name does not absolutely have to be the correct host name, but is merely the name with which you addressed the server.

Note that in this small example, the entire HTTP communication runs over one connection. In complex browsers, the browser can open several connections, however, and can send several requests in parallel. The server notes which HTTP request comes from which connection, and sends the HTTP response over the correct connection. You should therefore always use the connection number so that HTTP requests can be mapped to responses in the trace. The server replies with an HTTP response. Connection: 1 -- HTTP Response from ld0020.wdf.sap.corp 1960 bytes HTTP/1.1 401 Unauthorized Content-Length: 1718 Content-Type: text/html; charset=iso-8859-1

Web Dynpro ABAP: Development in Detail

253

Advanced Concepts

May 2006

WWW-Authenticate: Basic realm="SAP Web Application Server [B20]" <html> <head><title>Logon Error Message</title></head> <body>....Error message: Logon failed....</body> </html>

The first line in the HTTP response is important. It contains the HTTP protocol that is used by the server, the HTTP return code and a string with a descriptive text. The server usually (but not always) answers with exactly the same protocol that the browser requested. The server can also â&#x20AC;&#x153;switch downâ&#x20AC;? the HTTP protocol that is used. The HTTP return code is very important. In this example it is 401, which means that the server rejected the request and requires authentication. Content-Length and Content-Type describe the utilization. The WWW-Authenticate header is used with HTTP 401 responses only. It informs the browser which string (server identification) should be displayed in the authentication popup that requests the user name and password. There then follows a blank line, and then the response body.

Note that the authentication response has an HTML body. The browser only represents this HTML if the authentication popup is cancelled. Once you have entered a user name and password, the browser submits the same request again. Connection: 1 -- HTTP Request received from browser 412 bytes GET /sap/bc/bsp/sap/bcm00/helloworld.htm HTTP/1.1 Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */* Accept-Language: en-us,de;q=0.5 User-Agent: Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 5.0) Host: ld0020.wdf.sap.corp:50021 Authorization: Basic T25lIFR3byBUaHJlZTpGb3VyIEZpdmUgU2l4

Connection: 1 -- HTTP Response from ld0020.wdf.sap.corp 899 bytes HTTP/1.1 302 Moved temporarily Location: /sap(bD1lbiZjPTAwMA==)/bc/bsp/sap/bcm00/helloworld.htm Set-Cookie: MYSAPSSO2=AjEx...tggN5w%3d%3d; path=/; domain=wdf.sap.corp Content-Length: 25 Content-Type: text/html

In this case, the additional authentication header is useful. You can see that basic authentication is used. Then follow the coded user name and password. This information is only coded, it is not encrypted. The HTTP response has return code 302, which means that the requested URL is not available. The new destination is specified in the Location header. You can recognize the BSP runtime URL mangling process here. URL mangling is carried out so that additional information can be coded in the URL. There is also a Set-Cookie header. SSO2 is configured and active on this server. The server implements an SSO2 cookie in the root path for the complete domain. This means that for each new HTTP request to any other URL on a different server in our domain, an SSO2 cookie is sent together with the request. If the new sever has a relationship of trust with the server that sent the SSO2 cookie, then it will accept the HTTP request without additional authentication queries. This costs a few hundred additional bytes per request. Once the browser has received a new location as the access target, it triggers a GET request to this location and receives the expected page.

Web Dynpro ABAP: Development in Detail

254

Advanced Concepts

May 2006

Connection: 1 -- HTTP Request received from browser 1033 bytes GET /sap(bD1lbiZjPTAwMA==)/bc/bsp/sap/bcm00/helloworld.htm HTTP/1.1 Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */* Accept-Language: en-us,de;q=0.5 User-Agent: Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 5.0) Host: ld0020.wdf.sap.corp:50021 Cookie: MYSAPSSO2=AjEx...tggN5w%3d%3d

Connection: 1 -- HTTP Response from ld0020.wdf.sap.corp 501 bytes HTTP/1.1 200 OK Set-Cookie: sap-appcontext=c2Fw...4tQVRU; path=/sap(bD1lbiZjPTAwMA==)/bc/bsp/sap/bcm00/ Content-Length: 123 Content-Type: text/html; charset=iso-8859-1 Expires: 0 Pragma: no-cache Cache-Control: no-cache <html><body><form method="POST"> <input type=text name="test" value=""> <input type=submit> </form></body></html>

You can see a Cookie header in the HTTP request. (This cookie is supplied to the browser by the Set-Cookie header and is returned by the browser with the Cookie header.) Note that with this cookie, the values for the previous path and the domains that were used when the cookie was set are not forwarded to the server. The browser used this information to find out that the cookie goes with the request, and then sent the cookie. The HTTP response is answered with return code 200 OK. This is a normal response that can be displayed. The BSP runtime similarly sets a cookie, although this is placed in a path that is intended for this BSP application. The BSP runtime also adds three new headers to the HTTP response to inform the browser and all HTTP proxies that they should not cache this HTTP response. You can see the HTML of the test page in the HTTP response’s capacity. This is displayed by the browser. In an additional HTTP request/response cycle, enter the value “abc” in the input field and press the button. Connection: 1 -- HTTP Request received from browser 1358 bytes POST /sap(bD1lbiZjPTAwMA==)/bc/bsp/sap/bcm00/helloworld.htm HTTP/1.1 Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */* Referer: http://ld0020.wdf.sap.corp:50021/sap(bD1lbiZjPTAwMA==)/bc/bsp/sap/bcm00/hell oworld.htm Accept-Language: en-us,de;q=0.5 Content-Type: application/x-www-form-urlencoded Content-Length: 8 User-Agent: Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 5.0) Host: ld0020.wdf.sap.corp:50021 Cookie: sap-appcontext=c2FwL…tQVRU; MYSAPSSO2=AjEx..tggN5w%3d%3d test=abc Connection: 1 -- HTTP Response from ld0020.wdf.sap.corp 312 bytes HTTP/1.1 200 OK

Web Dynpro ABAP: Development in Detail

255

Advanced Concepts

May 2006

Content-Length: 126 Content-Type: text/html; charset=iso-8859-1 Expires: 0 Pragma: no-cache Cache-Control: no-cache <html><body><form method="POST"> <input type=text name="test" value="abc"> <input type=submit> </form></body></html>

The HTTP request now uses the POST verb (as specified in the HTML <form> element). For the POST, the current form Field (the value of the input field) is written to the body of the request after a blank line. These values are always written as “name=value”. A new header, Referer, has been added. This header comes from the browser and identifies the server that triggered the HTTP request. The Referer is very useful for Web sites in order to find out from which other sites a Web site is accessed. This header is also very controversial, however. For example, you can use a search engine with a certain number of keywords and then click on a link. The Referer now becomes the search engine: Part of its URL contains the keywords that were used to find this link. Web sites can assess this Referer header to find out which type of keywords attracts the most users. This is why many firewall and proxy tools have techniques for deleting these headers from the HTTP request. The Cookie header now contains both cookies (in a Header field). No additional cookies are set in the HTTP response. The server found out that the browser already has all relevant cookies and will not set them again. Here you can recognize the asymmetrical behavior of cookies. They are sent to the browser with a Set Cookie header in the HTTP response only, including information about the path and domain. Afterwards, cookies are only sent from the browser to the server using the Cookie header in the HTTPrequest, but without any domain or path information. The body of the response now contains the newly rendered HTML coding. The input field contains the value “abc” that was just entered.

4.20.3.1

HTTP Proxy

The following graphic shows how data is transferred with HTTP: Browser

HTTP Request & Response

Server

HTTP is a request/response protocol. Only the browser can send requests, and only the server can respond with a suitable response. This is also known as the HTTP request/response cycle. Many HTTP requests may still be open in the browser and waiting for a response from the server. Each HTTP response is always correctly mapped to the HTTP request that started this cycle.

Web Dynpro ABAP: Development in Detail

256

Advanced Concepts

May 2006

The server is frequently outside a firewall, however, so that it is not possible to communicate directly with that server. This is why companies place HTTP proxy servers on the firewall, where one part is within the firewall, and the other part is outside it. The browser is configured so that it uses the proxy server as a representative for handling HTTP requests. This means that instead of calling the server for every request, the browser contacts the proxy server with the HTTP request and waits until the proxy server returns the HTTP response. Browser HTTP Request & Response

Proxy Server

HTTP Request & Response

Server

From this you can see that the browser is familiar with the concept of a mediating agent, which can be configured in such a way to handle all HTTP requests on its behalf. The browser contacts the proxy server and thatâ&#x20AC;&#x2122;s it for the browser. The browser now has to be configured so that it uses a different proxy, the proxy for HTTP tracing Browser

HTTP Request & Response

Trace Proxy

HTTP Request & Response

Proxy Server

HTTP Request & Response

Server

The browser will now pass the HTTP request to the proxy server as usual. The proxy logs the data traffic and passes the request directly to the proxy server that performs the actual work. On the way back, the data traffic is held again in a trace.

Web Dynpro ABAP: Development in Detail

257

Advanced Concepts

May 2006

4.21 System Logon Use When creating Web applications using Business Server Pages (BSP [externaly]) or Web Dynpro [externaly], you can define logon screens for end users to log onto your system. For the sake of simplicity you can use a logon screen which is similar to the classic logon screen, where you must enter the client, user name, password and language. Without much programming you can define which fields should be available, which additional help should be offered and how the logon screen should be designed for your Web applications. You activate and configure the system logon in the Internet Communication Framework (ICF [externaly]) using the respective service nodes for your application. In addition to these settings, you can also make User-Specific Changes [page 268] using a separately developed class.

An example (NW2004s) of a logon screen for a Web application with additional links, which has been configured with the system logon functionality: For further layout variants see Examples of the Logon Screen [page 280].

If problems occur during the logon process, the system outputs various error messages or warnings depending on the cause. In addition to errors that refer to the status of the user data and input errors during the logon, problems in the server or client configuration can also mean that the logon cannot be performed correctly. You can find these error messages and their long texts about solving the errors in the system in message class ICF_SYSTEM_LOGIN.

Web Dynpro ABAP: Development in Detail

258

Advanced Concepts

May 2006

Prerequisites You can find the steps that you must carry out in order to ensure that the logon functionality works smoothly in Prerequisites [page 261].

Features The following functions are supported within the logon application: ●

Logon and password change

●

Configuration of the layout and process using the ICF service

●

Log of the toggle to HTTPS to transfer the user data securely

●

Three implemented layouts and five selectable stylesheet categories

●

SSO2 support •

Changing Your Password with Basic Authentication [page 267]

●

Customization for the logon layout and process

●

Accessibility support

●

System message display

●

Check for existing user sessions during the logon

●

Logon with X.509 certificates

For more information about the various default settings, see Configuration Settings [page 262].

If you start the logon directly using HTTPS and client certificate, then no system messages are displayed and there is no check for multiple logons. See also: Scenarios for Changing Passwords [page 265]

Activities ...

1. Branch in Transaction SICF to the service node for your Web application. 2. Call the detail view of the service by double-clicking it or press F8. 3. Choose the Error pages tab page. 4. In change mode, select the System Logon radio button and the Configuration pushbutton.

Web Dynpro ABAP: Development in Detail

259

Advanced Concepts

May 2006

You branch to the configuration screen for the system logon. 5. Enter your configurations for the system logon. 6. Select

(Enter) for your configuration settings.

7. On the “Create/Change Service“ screen, first

(save) and then

(cancel).

You return to the node for your application. 8. Position the cursor on your application’s node and then choose Test service in the context menu. The logon screen you have configured is displayed in the browser.

Web Dynpro ABAP: Development in Detail

260

Advanced Concepts

4.21.1

May 2006

Prerequisites

Checklist for configuration in the system The following settings must be made in your AS-ABAP system:

Short instructions for configuring the security functionality (SSO2)

You only need these settings if you want to support SSO2. This means they are optional. Also note that the SAP Cryptographic Library is not needed. For SSO2 the SAP Security Library is sufficient. This is delivered in the standard AS-ABAP system. ...

1. The profile parameter login/accept_sso2_ticket is set to 1 and login/create_sso2_ticket set to 1 or 2. You can find details in configuring the system so that is displays logon tickets [externaly]. 2. The system is now restarted. 3. The AS-ABAP is configured for using SSL [externaly] (optional, but recommended): ...

a. A PSE was generated. You can find details in Creating SSL Server PSE [externaly]. b. A certificate requirement was created for the PSE. You can find details in Creating Certificate Requirements for the SSL Server PSEs [externaly]. c. The certificate requirement was sent to a certification authority (CA) You can find details in Sending Certificate Requirements to a CA [externaly]. d. The generated PSE was imported. You can find details in Importing Certificate Replies [externaly]. e. The certificate list of the PSE was entered. You can find details in Maintaining the SSL Server PSE Certificate List [externaly]

These settings are all explained in Security on the SAP Web Application Server [externaly]. See also Note 51007 “Setting Up SSL On the Web Application Server”.

Configuring the Internet Communication Manager (ICM) In the Internet Communication Manager (ICM) [externaly] you have configured the HTTPS service (in Goto → Services in Transaction SMICM), see also Displaying and Changing Services [externaly].

Browser End users have the option to have browser cookies activated in their browser’s security settings. When the user ID and password is sent, the activation of cookies in the browser is checked. If it is determined that the browser does not accept cookies, which is why SS02 is not supported

Web Dynpro ABAP: Development in Detail

261

Advanced Concepts

May 2006

and cannot be used, the user receives a confirmation with the option of performing the logon once again using Basic Authentication.

4.21.2

Configuration Settings

You can make various settings on the configuration screen for system logon. These are explained in more detail below.

Configuration screen Settings Selection Area

Web Dynpro ABAP: Development in Detail

262

Advanced Concepts

May 2006

You can decide whether you want to use the global settings to display the logon screen and for the logon process, or if you want to configure individual parameters especially for this service. To do this, choose the corresponding radio button. If you select the option for the global settings, the lower fields are not ready for input because the default settings are used. If you select the option for service-specific settings, you can make additional settings in the lower part of the screen. As an administrator you can also change the global settings yourself. To do this you need to have the S_ADMI_FCD authorization object in your user master record, with which the S_ADMI_FCD attribute is set to ICFA.

As an administrator you can make the global settings in any service node. Save the global settings by choosing Save as Global Settings. This pushbutton is only displayed if you have the relevant administration authorizations. System Logon Settings Area Select Display

System ID

The logon screen displays the threedigit SAP system ID of the system in which the application is started.

Client

The logon screen contains an input field for the client in which the application should be started. You can assign a default value to the content of the field. To do this, select the Client field in the Default area.

Language

A dropdown list box is displayed on the logon screen with the languages installed in the system. You can assign a default value to the content of the field. To do this, select the Language field in the Default area.

System messages

After logging on successfully, the user will see the current system messages (created using Transaction SM02).

Logon and system information

Displays logon and system information, which can be displayed on the logon screen. This is the same information that you see on the SAP GUI. This information is stored in the ZLOGIN_SCREEN_INFO document, General Text document class (created in Transaction SE61).

Web Dynpro ABAP: Development in Detail

263

Advanced Concepts

Actions During Logon

Check for Multiple Logons

No Toggle to HTTPS

May 2006

Following a successful logon, the system checks whether the user has already logged onto the system using HTTP/HTTPS using his or her user ID. In the case of multiple logons, the existing sessions are listed in a table and the user has three options to continue: ●

Continue with this logon and end all existing logons

●

Continue with this logon without ending all existing logons

●

Cancel this logon

The logon takes place using the HTTP protocol only. The user name and password are sent unencrypted.

The unencrypted transfer of name and password is a security risk. Do Not Display Warnings

Error messages are displayed during logon, but no warning messages.

Accessibility

A checkbox is placed on the logon screen, which the user can use to request (accessibility-specific) input help. The logon procedure itself is always accessible.

This indicator does not make a statement about the accessibility of the application itself. The developer of the respective application is responsible for its accessibility. Default

Client

The client specified here is used to assign a default value for the Client field on the logon screen. If no client is displayed on the logon screen, then the application is started on the client specified here. If this field remains empty and if no client input field is displayed on the logon screen, then the application is started on the client specified in the

Web Dynpro ABAP: Development in Detail

264

Advanced Concepts

User-specific Adjustment

4.21.3

May 2006

Language

The language specified here is displayed as the preselected logon language on the logon screen. If no language is displayed on the logon screen, then the application is started in the language specified here. If this field remains empty and if no language input field is displayed on the logon screen, then the application is started in the language according to logon language determination [externaly] in the ICF.

SAP Implementation

SAP provides three predefined layouts that you can use for the logon. For each of these layouts there are five stylesheet categories.

User-specific

You can adjust the layout and the logon process to your user-specific requirements. To do this you need a new class, which is a subclass of the CL_ICF_SYSTEM_LOGIN class and implements the respective changes (see User-specific Changes [page 268]).

Password Logon Scenarios

The system logon can be used with every ICF logon procedure. Three scenarios are supported for logging on with user and password: ●

Logon using the logon ticket

●

Logon using basic authentication.

●

Logon when application is started

Logon Using the Logon Ticket (SSO Logon) Once the user and password have been entered on the logon page, the MYSAPSSO2 cookie is created that serves as the logon ticket. Any applications started after this are authenticated using this ticket. The authentication remains active until the browser window is closed. See also: Password Changes in the SSO Environment [page 268]

Prerequisites ●

The logon procedures Fields Authentication and SSO Authentication must be permitted in transaction SICF for the ICF node of your application. In transaction SICF in your application, on the title element Logon Data select the logon sequence Standard as the Procedure.

Web Dynpro ABAP: Development in Detail

265

Advanced Concepts

●

SSO must be configured correctly

●

Cookies must be allowed in the Web Browser

May 2006

The URL must be fully qualified for starting the logon (FQDN [page 48])

Logon using basic authentication becomes active when the SSO logon has been explicitly switched off (no logon with procedure SSO Authentication), or the SSO logon cannot be started due to an error in the configuration.

Logon Using Basic Authentication. With basic authentication the authentication data is retrieved from the Web browser itself using a user dialog. For this reason on the system logon page these fields are inactive and are not activated until the user chooses the Logon pushbutton. The authentication remains valid until the browser window is closed. See also: Changing Your Password with Basic Authentication [page 267]

Prerequisites The logon procedure Basic Authentication must be permitted in transaction SICF for the ICF node of your application. In transaction SICF in your application, on the title element Logon Data choose the entry Standard as the Procedure, or make sure that the entry Basic Authentication is available in the list below if you are using Alternative Logon Sequence.

Logon When Application is Started (session-based) This procedure works only for applications that are stateful. The authentication is valid only for the application just started. Once the application is closed or if the user switches to a different application the user must log on again. The following applications work with the session-based logon procedure: ●

ITS applications

●

Web Dynpro applications

●

BSP applications that are stateful

Prerequisites ●

The logon procedure Fields Authentication must be permitted in transaction SICF for the ICF node. The logon procedures SSO Authentication and Basic Authentication must not be permitted. To do this, in your application in the SICF on the title element Logon Data choose Alternative Sequence as the Procedure and delete the entry SSO Authentication.

●

Cookies must be allowed in the Web Browser

The URL must be fully qualified for starting the logon (FQDN [page 48])

Web Dynpro ABAP: Development in Detail

266

Advanced Concepts

May 2006

If SSO is configured for the system, a logon ticket is nevertheless issued. This can lead to security problems. For this reason ensure that SSO is deactivated for the system.

4.21.3.1

Changing You Password with Basic Authentication

Use Instead of using SSO2 for your logon procedure, you can also log on using Basic Authentication. When using Basic Authentication, if you want to (or have to) change your password, the necessary procedure for doing this is described below.

Since there is no switch to HTTPS, sending the password is potentially unsafe.

Prerequisites â&#x2014;?

You have deactivated the cookies option in your browser.

â&#x2014;?

You have deactivated SSO2 (PSE management is not activated).

Procedure ...

1. In the Object Navigator, navigate to your application and choose F8 (Test/Execute). This takes you to the usual logon screen with the note that logon is only possible using Basic Authentication. 2. Choose the Change Password button. Note that you may change your password once a day only. 3. A popup is displayed in which you can enter your user name and password. 4. Choose the Change Password button. 5. On the next screen, enter your current (old) password, your new password and confirm your new password by entering it again. 6. Confirm your entries by choosing the Change button. You will receive a confirmation that you have successfully changed your password. 7. An additional popup is displayed in which you can enter your new password again.

Result You have successfully changed your password.

Web Dynpro ABAP: Development in Detail

267

Advanced Concepts

4.21.3.2

May 2006

Password Changes in the SSO Environment

When users log on with passwords the system checks whether the password needs to be changed. Possible reasons for changing the password are that it is set to initial or has expired. If the user logged on through user/password query or through basic authentication, the user has to change the password. If the logon was through, for example, an SSO certificate, rather than through user/password query, parameter login/password_change_for_SSO is used to determine how the system should behave. ●

login/password_change_for_SSO=0 The obligation to change the password is ignored. No password change dialog box is displayed.

●

login/password_change_for_SSO=1 (default setting) The password must be changed or deleted. The password change dialog box appears with an additional delete button.

●

login/password_change_for_SSO=2 The password change dialog box appears and the password must be changed (input: old and new password).

●

login/password_change_for_SSO=3 The password can only be deactivated. The password is automatically deactivated and no dialog box appears.

Note: Once the password has been deleted the user cannot log on with this password again. The system administrator must assign a new password.

4.21.4

User-specific Changes

Purpose To change the layout and the logon process according to your special requirements, you can make user-specific changes in addition to the settings that are possible on the configuration screen [page 262].

Process Flow ●

Create a new class that is a subclass of CL_ICF_SYSTEM_LOGIN.

●

You change the layout of the logon screen by overwriting the htm_login method in the new class.

Web Dynpro ABAP: Development in Detail

268

Advanced Concepts

â&#x2014;?

May 2006

To modify the screen for the password change, overwrite the htm_change_passwd method.

To ensure that the entries made are forwarded to the relevant screens and to trigger the corresponding events for the transfer of the results, it is necessary for you to use default constants and attributes for form names, input field names, event names and script functions. The constants and attributes that should be used depend on the logon functionality to be implemented.

Constants Below is a list of all constants used by the system, which are necessary for changes to the process and layout of logging on and changing passwords: Logon Constants

Description

CO_SAP_USER

Name and ID of the input field for the user name

CO_SAP_PASSWORD

Name and ID of the input field for the password

CO_SAP_CLIENT

Name and ID of the input field for the client

CO_SAP_LANGUAGE

Name and ID of the input field for the language

CO_FORM_LOGIN

Form name

CO_JS_SUBMIT_LOGIN

Name of the JavaScript function to be called when a pushbutton is pressed on the logon screen

CO_EVENT_LOGIN

Event to be triggered when the logon pushbutton is pressed

CO_EVENT_CHANGE_PASSWORD

Event to be triggered when the Change password pushbutton is pressed

CO_EVENT_BASIC_AUTHENTICATION

Event to be triggered when the Basic Authentication pushbutton is pressed

M_SAP_APPLICATION

Value of the action form attribute

Password change Constants

Description

CO_PASSWORD

Name and ID of the input field for the current password

Web Dynpro ABAP: Development in Detail

269

Advanced Concepts

May 2006

CO_PASSWORD_NEW

Name and ID of the input field for the new password

CO_PASSWORD_REPEAT

Name and ID of the input field for repeating the new password

CO_FORM_CHANGE_PASSWORD

Form name

CO_JS_SUBMIT_CHANGE_PASSWORD

Name of the JavaScript function to be called when a pushbutton is pressed on the change password screen

CO_EVENT_DO_CHANGE_PASSWORD

Event to be triggered when the Change pushbutton is pressed

CO_EVENT_CANCEL_PASSWORD

Event to be triggered when the Cancel pushbutton is pressed

CO_EVENT_CONTINUE_PASSWORD

Event to be triggered when the Continue pushbutton is pressed after successfully changing the password

M_SAP_APPLICATION

Value of the action form attribute

You can use the following classes as a reference to implementation additional functions: ●

CL_ICF_BASIC_LOGIN

●

CL_ICF_IDES_LOGIN

●

CL_ICF_NW04_LOGIN

Example You can find a sample implementation in the system in the CL_ICF_EXAMPLE01_LOGIN class and in the following simple example [page 270].

4.21.4.1

Example

Introduction This example shows which attributes you have to change and which methods you have to overwrite in order to implement your own logon screen that should have the following elements: ●

User name

●

Password

●

Logon pushbutton

Web Dynpro ABAP: Development in Detail

270

Advanced Concepts

May 2006

Prerequisites Your class is a subclass of CL_ICF_SYSTEM_LOGIN.

Attributes You need the following attributes in your class for your changes: Attributes Attribute

Description

CO_FORM_LOGIN

Form name

M_SAP_APPLICATION

Value of the action form attribute

CO_SAP_USER

Name and ID of the input field for the user name

CO_SAP_PASSWORD

Name and ID of the input field for the password

CO_JS_SUBMIT_LOGIN

Name of the JavaScript function to be called when a pushbutton is pressed on the logon screen

CO_EVENT_LOGIN

Event to be triggered when the logon pushbutton is pressed

Methods In addition to the attributes, you need the htm_login method, which you overwrite in your class. The interface of the htm_login method is used to transfer the JavaScript functions that are necessary and provided by the system and a series of form field value pairs of type HIDDEN, which are required to control the logon. The JavaScript functions are transferred as a string in the iv_javascript parameter; the form fields are transferred in the iv_hidden_fields parameter The HTTP body that is necessary for the HTTP response is summarized in the htm_login method and returned as a string to the caller.

4.21.5

URL Generation in an AS-ABAP - Web Dispatcher Configuration

This section describes a standard configuration for generating URLs. In a simple system landscape the AS-ABAP and the browsers are usually located in the same network. In this case the browser can access the AS-ABAP server directly using its configured name. Conversely, if the AS-ABAP has to generate an absolute URL for the browser, it can use its configured name to generate the URL. In more complex system landscapes a reverse proxy server, for instance, the SAP Web Dispatcher [externaly], is used in the network. This happens, for example, if the reverse proxy

Web Dynpro ABAP: Development in Detail

271

Advanced Concepts

May 2006

server is visible in the Internet and the AS-ABAP is located behind a firewall. In this case the browser uses the name of the reverse proxy server when it is communicating with the server. Conversely, it is not possible for the AS-ABAP to use its own configured name to generate absolute URLs. The URL must contain the name and port of the reverse proxy server (that is, the name and port of the unit with which the browser communicates). For more information, refer to: Host Header [page 272] Absolute URL Generation [page 273] Configuration Table HTTPURLLOC [page 273] Programming Interface [page 274] Scenario 2 [page 276] Scenario 3 [page 276] Scenario 3 [page 277] Scenario 4 [page 279] Special Case [page 279]

4.21.5.1

Host Header

Before we get to an overview of scenarios and the affects on the configuration table, first comes a description of how the browser sets the host header. When a request is fetched from the server, the full URL is written to the browser, including the protocol (HTTP), the host name, port, and path. The HTTP protocol, however, still sends a slightly different request. GET / HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Accept-Language: de,en-us;q=0.5 Host: intranet.sap.com User-Agent: Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 5.0) The request line contains the HTTP specification and the necessary path (in the example here this is GET /). A host header is also set containing the full name of the server that the browser sees as its communication partner. If the URL points to a non-standard port (HTTP uses by default port 80 and HTTPS Port 443), then the port will be included in the host header. So the host header reflects the name that the browser uses to reach the server. The browser assumes this name is valid. It does not have to be the actual name of the server.

When an application gateway, load balancer, or reverse proxy is used, it has to retain the host header, and it must not change it. Note that in particular with apache reverse proxies this feature is available only as of version 2 (configuration option ProxyPreserveHost).

Web Dynpro ABAP: Development in Detail

272

Advanced Concepts

4.21.5.2

May 2006

Absolute URL Generation

Sometimes it is important to create fully-specified URLs. For some of these cases you could use the host header and determine the port from the list of active ports configured on the server. This procedure often works well, but not always. First of all, the cases that need fullyspecified URLs are considered: ●

When a test URL is generated to start the application in the browser.

●

When the protocol is switched. This is usually a switch from HTTP to HTTPS to ensure the data transfer is secure. This case arises often.

●

When a Java applet is loaded sometimes a fully-specified URL is required in a complex frameset, because otherwise the applet is loaded from the server where the root document is located rather than from the frame owner where the applet is located.

●

Return URLs in typical catalog applications. Here a URL is required that is used to return data to the server and for the specific application. In this case a fully-specified URL is also necessary. The first example listed is a special case, as there are no incoming HTTP requests from which you could use the host header. So a completely new URL has to be generated, without any prior information of possible server names. In all the other examples an incoming HTTP request is available, from which the host header can be used for heuristic information for filtering relevant entries.

4.21.5.3

Configuration Table HTTPURLLOC

The configuration table HTTPURLLOC is provided to handle any URL generation problems. In this table you can configure how a URL is to be generated. Note that this table simply contains configuration information. The relevant Programming Interface [page 274] is described further below. The HTTPURLLOC table contains the following fields: HTTPURLLOC Field

Data Type and Length

Value Range

MANDT

CHAR 3

000 - 999

SORT_KEY

CHAR 4

0000 - 9999 (recommended)

PROTOCOL

CHAR 8

HTTP | HTTPS

APPLICATN

CHAR 128

FOR_DOMAIN

CHAR 128

HOST

CHAR 255

PORT

CHAR 6

The entries should be in upper case so that the string compare algorithm is as quick as possible. There is no tool to manage or update this table. So make your settings directly in transaction SE16. Fields and their meanings: ●

MANDT

Web Dynpro ABAP: Development in Detail

273

Advanced Concepts

May 2006

Client for which the configuration is to be performed. Different clients represent different identities, for which different configuration data is needed. For instance, the host name could be server.abc.com for client 100, whereas it could be www.xyz.de for client 200. ●

SORT_KEY Sort sequence of entries. Entries in this sequence are compared from top to bottom and the first matching entry is used.

●

PROTOCOL Protocol for which a fully specified URL must be generated. It can be HTTP or HTTPS.

●

APPLICATN This string can be used to filter the entry for special application types. If this is configured, this entry is used as the template to determine how the current application that would like to generate a fully specified URL is used. For BSP the string /BSP/<namespace>/<name> is always used. Leave this field empty if this configuration is used again and again. Examples of values: /BSP/SAP/IT00 assigns access rights only to BSP application IT00. /BSP/XYZ/* assigns access right to all BSP applications in the XYZ namespace (registered namespace of the organization). /BSP/* assigns access rights to BSP applications. An empty string assigns access rights for all applications.

●

FOR_DOMAIN Can be used by an application, an SMTP mail system for instance, to generate URLs in other domains. It is not used in the BSP environment. If a value is specified for this field, it is used to filter the request for which a new URL has to be generated. We recommend to always leave this field empty.

●

HOST Mandatory field for generating the new URL. If the host is requested from an API, this field is used as a filter for the host header of the inbound request to decide which configuration line is to be used. It is a special case when the exception table is not to be used for an entry. If the field for the host is empty and the other parameters tally, this field is used as an indicator to specify that the local host data is used for generating the URL, and not the exception table.

●

PORT Port number used in the new, fully-specified generated URL.

4.21.5.4

Programming Interface

A simple programming interface is provided to use configuration data from Table HTTPURLLOC [page 273]. Two functions have been added to interface IF_HTTP_SERVER [externaly] (implemented in class CL_HTTP_SERVER). GET_LOCATION_EXCEPTION Parameter

Type

Kind of Typing

Reference Type

PROTOCOL

Importing

Type

CSEQUENCE

APPLICATION

Importing

Type

CSEQUENCE

Web Dynpro ABAP: Development in Detail

274

Advanced Concepts

May 2006

FOR_DOMAIN

Importing

Type

CSEQUENCE

SERVER

Importing

Type Ref To

IF_HTTP_SERVER

HOST

Exporting

Type

STRING

PORT

Exporting

Type

STRING

OUT_PROTOCOL

Exporting

Type

STRING

Method GET_LOCATION is a wrapper function for GET_LOCATION_EXCEPTION. It first calls the exception coding. If no value is returned, it uses the standard AS-ABAP name and the standard port configuration for the requested data.

Parameters ●

PROTOCOL Protocol for which the data is needed. It can be HTTP (standard value) or HTTPS. This parameter is optional. If the parameter is not specified and if the server object is available, the query is performed on the protocol to be used.

●

APPLICATION Application name for which the URL is to be generated. This name is matched against the pattern in HTTPURLLOC-APPLICATN. This parameter is optional It is only needed if different host and port data have been configured depending on the application. For BSP runtime the string /BSP/<namespace>/<application> is always used.

●

FOR_DOMAIN This parameter is matched against the pattern in HTTPURLLOC-FOR_DOMAIN. This parameter is optional. We recommend you do not enter a value for this parameter.

●

SERVER Server is a reference to the server object that is available if the application is running in the context of an inbound HTTP request. This means that the matching algorithm can extract the host header from the request and use it as an extra criterion for matching against the HTTPURLLOC-HOST field. This parameter is optional. Nevertheless we recommend you always enter a value in this field.

●

HOST Host is the returned host name that is to be used for generating the fully-specified URL. When an input is matched, this enters the value of HTTPURLLOC-HOST, otherwise the parameter keeps its initial value.

●

PORT Port is like the value of HTTPURLLOC-PORT.

●

OUT_PROTOCOL This parameter matches the requested importing protocol field if this is specified. If however the fully-specified URL is not needed to switch the protocol, but it is needed to

Web Dynpro ABAP: Development in Detail

275

Advanced Concepts

May 2006

load specific resources, we recommend that you do not set the importing protocol parameter. Instead enter the server object. The server object is used to determine which protocol is currently being used and then this information is used elsewhere. The algorithm is also for cases when the browser is communicating via HTTPS with a reverse proxy server and when HTTP is being used for the AS-ABAP.

Note that these methods are integrated in a very deep layer. It cannot be guaranteed that they can be called every time and from all different frameworks. For BSP method CONSTRUCT_BSP_URL has been extended to implement this programming interface.

Scenario 1: Direct Browser - AS-ABAP Communication

Web Browser

4.21.5.5

AS-ABAP

In this case the host header already displays the correct host. Fully-specified URLs can be generated without input in Table HTTPURLLOC [page 273].

Scenario 2: Browser - AS-ABAP Communication Through a Reverse Proxy

Web Browser

4.21.5.6

Reverse Proxy

AS-ABAP

The browser communicates always with the AS-ABAP through a reverse proxy server. For this reason all generated URLs must contain the name and port of the reverse proxy server.

Example: Proxy:

www.sap.com (http:80, https:443)

Host: webas.sap.corp (http:1080, https:1443) HTTPURLLOC

Web Dynpro ABAP: Development in Detail

276

Advanced Concepts

May 2006

MANDT

SORT_KEY

PROTOCOL

APPL

HOST

PORT

100

010

HTTP

WWW.SAP.COM

100

011

HTTPS

WWW.SAP.COM

443

As there is no application filter, table http synchronizes all requests in order to generate new URLs. The protocol is the factor that decides which entry is used.

Reverse Proxy

Web Browser

Scenario 3: Direct Communication Through a Reverse Proxy

Web Browser

4.21.5.7

AS-ABAP

Some Web browsers always communicate with the AS-ABAP through a reverse proxy server (Internet scenario). Other browsers communicate directly with the AS_ABAP (for example, in an organizationâ&#x20AC;&#x2122;s intranet).

Example: Proxy:

www.sap.com (http:80, https:443)

Host: webas.sap.corp (http:1080, https:1443) HTTPURLLOC MANDT

SORT_KEY

PROTOCOL

APPL

HOST

PORT

100

020

HTTP

WEBAS.SAP. CORP

1080

100

021

HTTPS

WEBAS.SAP. CORP

1443

100

030

HTTP

WWW.SAP.C OM

100

031

HTTPS

WWW.SAP.C OM

443

All applications are synchronized in this table. If an inbound host header is available, it is used to filter the rows to be used. This is particularly important if the protocol has to be switched, for instance, from HTTP to HTTPS. In this case it is important to know whether you are working in the Internet or in the intranet. If no host header is available (for instance, if an application from the workbench is being tested), the first matching entry is used. In this case the sorting key is important and an intranet URL is created by default.

Web Dynpro ABAP: Development in Detail

277

Advanced Concepts

May 2006

In these scenarios it is important that the reverse proxy server does not change the host header. It must be forwarded fully transparently from the browser to the server. This is necessary to be able to differentiate between Internet requests and intranet requests. For an Apache reverse proxy (mod_proxy) the configuration option, ProxyPreserveHost, must be active.

Note that this feature is supported by Apache Version 2+ only. The point is, what happens when more than one application server is active and the request is in the intranet. With the above table definition, when testing from the workbench the first entry is synchronized (as no host header is available), whereby a URL is generated for the intranet name (webas.sap.corp). This could be the information for each application server or also for the message server that dispatches the HTTP request. However, debugging and testing Web applications does prove difficult with this procedure. Therefore a technique is needed to specify that the information is evaluated from the local application server when no host header is available. This can be achieved by adding two additional entries with empty host headers to the table. The empty host header is used as the exit criterion from the exception code. HTTPURLLOC MANDT

SORT_KEY

PROTOCOL

APPL

HOST

PORT

100

010

HTTP

100

011

HTTPS

100

020

HTTP

WEBAS1.SA P.CORP

1080

100

021

HTTPS

WEBAS1.SA P.CORP

1443

100

022

HTTP

WEBAS2.SA P.CORP

1080

100

023

HTTPS

WEBAS2.SA P.CORP

1443

100

030

HTTP

WWW.SAP.C OM

100

031

HTTPS

WWW.SAP.C OM

443

When no host header is available the first entry is synchronized. In this case the host header is empty there which means that the information about the local AS-ABAP is to be used. If a host header is available, there are two options: Either all the names must be listed in the table so that no entry matches, or there are no entries (020 to 029) available in the table. Then the information about the local AS-ABAP is used for the URL generation.

Web Dynpro ABAP: Development in Detail

278

Advanced Concepts

Web Browser

4.21.5.8

May 2006

Scenario 4: Communication with Protocol Switch Through Reverse Proxy

HTTPS

HTTP

Reverse Proxy

AS-ABAP

When HTTPS is used in the Internet, HTTP can be used from the reverse proxy to the server. In this special case, the generation of absolute URLs is very important, particularly for special resources such as return addresses that match the external protocol used in the Internet. When the programming interface is called without a specified protocol; instead only a server object is specified, the protocol currently in use determines which name and port to use. In such a case one entry only is usually sufficient. The protocol to be used is returned from the API call. HTTPURLLOC MANDT

SORT_KEY

PROTOCOL

APPL

HOST

PORT

100

010

HTTPS

WWW.SAP.COM

443

It is important that for the inbound request the reverse proxy uses the active protocol used in the Internet section of the request. The Web dispatcher transfers this information into a header field named ClientProtocol, when option wdisp/add_clientprotocol_header = 1 is set. With an Apache reverse proxy this can be done using the request header with client protocol HTTPS.

4.21.5.9

Special Case: Combination with the Logon Application

A URL configuration table often has to be used during the logon procedure. This is particularly important if a Web dispatcher is used that has configured various ports, and when the Logon Application [page 258] must switch to HTTPS to guarantee the secure transfer of passwords. The logon application runs in two different clients, one runs in client 000 as user SAPSYS until the logon has been successfully completed, and the other runs in the designated client with the logged on user. During the first part of the logon the logon application finds Table HTTPURLLOC [page 273] in client 000. Therefore, it is essential that all entries are duplicated in client 000 when the logon application is in use. Starting from the second scenario table HTTPURLLOC looks like: HTTPURLLOC MANDT

SORT_KEY

PROTOCOL

APPL

HOST

PORT

000

010

HTTP

WWW.SAP.C OM

000

011

HTTPS

WWW.SAP.C OM

443

100

010

HTTP

WWW.SAP.C

Web Dynpro ABAP: Development in Detail

279

Advanced Concepts

May 2006

OM 100

011

HTTPS

WWW.SAP.C OM

443

If more than one client is active on the same computer with different Web dispatchers, all entries of the various clients must still be duplicated in client 000. In this case the host header filters the entries to be used.

4.21.6

Examples of the Logon Screen

Below are examples (NW2004s) of a logon screen for a Web application that has been configured with the system logon functionality. The following fields are always selected: system ID, client, language, and system messages. Logon and system information, links, and various layout variants are sometimes selected.

Simple Template with SAP Motif SAP Tradeshow

Web Dynpro ABAP: Development in Detail

280

Advanced Concepts

May 2006

Simple Template with Image of SAP Motif SAP Streamline

NetWeaver Template with SAP Motif SAP Tradeshow Error! Objects cannot be created from editing field codes.

NetWeaver Template with SAP Motif High Contrast and error message because incorrect password was entered.

Web Dynpro ABAP: Development in Detail

281

Advanced Concepts

Web Dynpro ABAP: Development in Detail

May 2006

282