Registration

Dear SAP Community Member,
In order to fully benefit from what the SAP Community has to offer, please register at:
http://scn.sap.com
Thank you,
The SAP Community team.
Skip to end of metadata
Go to start of metadata

Introduction

The Application Controller is the central controller of every FPM UI.
It is defined in the general settings of the Floorplan and Tabbed UIBB configuration.

The FPM SPI Integration (FSI) offers a generic Application Controller that handles for example all transactional tasks, controls the buttons of the Floorplan toolbar (CNR) and implements default logic for many FPM events.
The usage of this Application Controller is mandatory for every application that uses the FSI.
So within the Floorplan configuration the Web Dynpro component /PLMU/WDC_FRW_APPL_CNTRL needs to be set as Application Controller.

The logic of the generic application controller can be enhanced by implementing an application specific controller.

Handled FPM Events

The generic Application Controller of the FSI processes several events, which are listed below.
The application has the possibility to avoid the processing of those events by the Application Controller via either cancelling the event or setting the export parameter EV_SKIP_STANDARD of method PROCESS_EVENT of the application specific controller to ABAP_FALSE.

FPM Event ID

Behavior

FPM_CHECK

Raises a success message if no error message occurred during or before the event processing.

FPM_START

Sets the initial application mode (Display/Change/Insert – depending on application parameter 'FRW_MODE' or on configured FPM edit mode), controls the toolbar standard buttons accordingly and triggers the side-panel activation if no initial screen is used and a side-panel exists (i.e. raises FPM event FRW_ACTIVATE_SIDEPANEL)

FPM_LEAVE_INITIAL_SCREEN

triggers the side-panel activation if a side-panel exists (i.e. raises FPM event FRW_ACTIVATE_SIDEPANEL)

FPM_SAVE

Raises a confirmation popup if error or warning messages are present or a message if there is no unsaved data. Otherwise the Service Provider methods CHECK_BEFORE_SAVE and SAVE are triggered.

FPM_EDIT

Switches to application mode Change, controls the toolbar standard buttons accordingly and triggers a Service Provider CLEAN_UP call.

FPM_READ_ONLY

Raises a confirmation popup if unsaved data exists, sets the application mode to Display, controls the toolbar standard buttons accordingly, clears all previously raised messages (to avoid displaying e.g. obsolete error messages), sets all administered context nodes to read-only and triggers a Service Provider CLEAN_UP call.

FPM_CANCEL

same behavior as for FPM_READ_ONLY

FPM_REFRESH

Raises a confirmation popup if unsaved data exists, clears all previously raised messages (only when application is not in Display mode) and triggers a Service Provider CLEAN_UP call.

FPM_DELETE_CURRENT_OBJECT

Raises a confirmation popup and sets flag /PLMU/CL_FRW_APPL_CNTRL=>GV_ROOT_DELETE

FPM_OPEN_SIDE_PANEL

Refreshes the side-panel (/PLMU/CL_FRW_APPL_CNTRL=>REFRESH_SIDEPANEL)

FPM_NAVIGATE

Sets navigation parameters to the event data.

FPM_GOTO_START

Raises event FRW_AFTER_START_OVER.

FRW_AFTER_START_OVER

Resets the application mode to its initial value and controls the toolbar standard buttons accordingly.

FRW_ACTIVATE_SIDEPANEL

Adds the side-panel link to the UI.

FRW_SESSION_RESTART_CHANGE

Raises a confirmation popup if unsaved data exists and restarts the application in Change mode.

FRW_SESSION_RESTART_CREATE

Raises a confirmation popup if unsaved data exists and restarts the application in Insert mode.

FRW_SESSION_RESTART_DISPLAY

Raises a confirmation popup if unsaved data exists and restarts the application in Display mode.

FRW_LEAVE_TRANSACTION

Clears the complete Floorplan to end up on an empty screen (only supports OIF).

Constants for Event IDs

The constants for all 'FRW_*' event IDs can be found at /PLMU/IF_FRW_CONSTANTS=>GC_FPM_EVENT_ID and all 'FPM_*' event ID constants at class CL_FPM_EVENT

Behavior in Case of an Error

In case an error occurred during this round-trip while an Application Model performed the automatic flush of context data changes, all events will get cancelled and navigation will be stopped.
There are only a few events which will never get cancelled by the Application Controller, since those events will either close the UI or trigger a complete CLEAN_UP of all data:

  • FPM_CLOSE
  • FPM_READ_ONLY
  • FPM_CANCEL
  • FPM_GOTO_ERROR_DISPLAY

Furthermore there are some events which will be validated by the Application Controller to decide if they need to be cancelled or not. Those events have in common that their execution might be needed to get rid of an existing error in the UI. However those events will also get cancelled if the validation comes to the conclusion that the event processing might lead to a situation where erroneous data might become inaccessible for the user, which might result in a deadlock:

  • FRW_DELETE
  • FRW_LEAD_SELECTION_CHANGED
  • FRW_SELECTION_CHANGED
  • FPM_GUIBB_LIST_ON_LEAD_SELECTI

Handling of the Main Toolbar (CNR)

Some standard buttons that are used by most applications are automatically controlled depending on the mode of the application.

Additional application specific toolbar buttons can easily be controlled either directly in the UI (using the respective FPM interface) or from within the Service Provider (SP).

Standard Buttons

When using the FPM edit mode which can be set within the Floorplan configuration (if supported by the Floorplan) the FPM controls of the default buttons like 'Save' and 'Edit'.

If the FPM edit mode is not used, the Application Controller handles the standard toolbar buttons depending on the value of /PLMU/CL_FRW_APPL_CNTRL=>GV_MODE.
The possible values are I for insert, C for change and D for display, which is also the default value.
The mode can be set at design-time via application parameter FRW_MODE or at runtime via method /PLMU/CL_FRW_APPL_CNTRL=>SET_MODE.

The buttons with the following FPM Event IDs will be controlled (if they exist in the Floorplan configuration):

FPM Event ID

Setting for Display Mode

Setting for Insert Mode

Setting for Change Mode

FPM_CHECK

Invisible

Enabled, default Button

Enabled, default Button

FPM_DELETE_CURRENT_OBJECT

Invisible

Invisible

Enabled

FPM_EDIT

Enabled

Invisible

Invisible

FPM_PRINT

Enabled

Invisible

Invisible

FPM_READ_ONLY

Invisible

Invisible

Enabled

FPM_REFRESH

Enabled

Invisible

Invisible

FPM_SAVE

Invisible

Enabled

Enabled

Application Specific Buttons

If a toolbar button belongs to a SP operation it should be controlled by the SP.
If the button is triggering an action that is only processed in the UI (so this button doesn't affect the backend) the button should be controlled within the UI directly by accessing the FPM CNR interface (see FPM documentation).

To control toolbar buttons from within the SP you need to set the operation properties, which are explicitly foreseen for operation control.
Then it is required to define a mapping in the UI that maps the toolbar buttons to the SP operations.

This mapping can be defined via the Application Controller method SET_CNR_OPERATIONS
This method receives a (sorted) table of type /PLMU/TS_FRW_CNR_OPR_MAP with mapping information. The structure of that table has the following components:

Component

Data Type

Description

ABBID

/PLMB/SPI_ABBID

Application Building Block ID (ABBID)

SP_NODE_NAME

/PLMB/SPI_NODE_NAME

Node name

OPERATION_TYPE

/PLMB/SPI_OPERATION_TYPE

Operation type

ACTION_NAME

/PLMB/SPI_OPERATION_NAME

Operation name (only required for operation type 'ACTION' or 'QUERY')

EVENT_ID

FPM_EVENT_ID

FPM Event ID of the toolbar button

ELEMENT_ID

FPM_ELEMENT_ID

Element ID of the toolbar button

The element ID of the button is mandatory if several toolbar buttons are using the same event ID, e.g. FPM_OPEN_DIALOG.
Whenever the FPM SPI Integration (FSI) receives operation properties from the Collector it will check the mapping table if the information is CNR relevant and then control those buttons automatically.

Control Application Specific Buttons via Metadata Node (Deprecated)

Limitations

This approach only supports freestyle UIBBs and is not recommended anymore. Instead the operation properties shall be used as described above.

In the first release of the FPM SPI Integration (FSI) there was no functionality to control the operation properties directly.
So if the application still wanted to control the operations – which are in the UI represented by buttons most of the time – on Service Provider level and not in the UI, the approach was to create a dummy node which had the only purpose of controlling the operations. A typical name which was used for this node was 'ACTIONS'.

The SP was then able to control the field properties of this node via the Collector.

Additionally a mapping on UI level is needed to assign the fields of this node to the respective toolbar button.
To define this mapping the Web Dynpro Component needs to implement the interface /PLMU/WDI_FRW_CNR.
By that the method GET_CNR_EVENTS is added to the component controller which needs to provide a table of:

  • Metadata node name
  • Attribute name (which is used for field control)
  • Event ID of the CNR button
  • Element ID of the CNR button

Reusing Context Menu Customizing to Create a CNR Button Choice

It is possible to create new or enhance an existing button choice item in the FPM CNR based on the context menu customizing. The action utilities interface provides a method /PLMU/IF_FRW_ACTION_UTIL->ADD_SERVICES_TO_CNR. You have to specify the item type(s) and the button choice element ID.
The item will be created or enhanced with context menu items based on the context menu customizing, which is explained in more detail in the navigation chapter.

Usually it is used for 'Additional Functions' button choice to provide customizing based navigation possibilities.

Application Specific Controller

Enhancement spot /PLMU/ES_FRW_CONSUMER_APPCC contains a BAdIs to create an application specific controller.
The BAdI interface provides several methods which then will be called at defined points in time.

Always Use BAdI Filter

For every BAdI implementation a filter needs to be defined. The filter parameters are the Web Dynpro application name and the application configuration name.

Use Case of BAdI

The use case of the BAdIs in enhancement spot /PLMU/ES_FRW_CONSUMER_APPCC is to handle the central logic of the application UI i.e. logic that goes beyond one single UIBB. The BAdI was not built to enhance existing applications, so this means when it is misused to enhance an existing application certain limitations might apply.

The available methods of every application specific controller are:

Name

Description

Example for Usage

AFTER_AFTER_FAILED_EVENT

After all failed event methods were executed this method runs.

Execute central logic that is needed after the application was set back to a previous state

AFTER_CLEANUP

Will be processed after a SPI CLEAN_UP call which is executed for example after a save or during a refresh.

Clear buffers that are owned by the application specific controller.

AFTER_FAILED_EVENT

Will get called when an event was cancelled.
Here the changes that might have been done during the event processing (i.e. during PROCESS_EVENT method) need to be undone.

Restore buffer values that were present before the event was processed

AFTER_FLUSH

Allows processing after the flush has been called on every GUIBB.

Perform validation after data changes were made.

AFTER_NEEDS_CONFIRMATION

Allows modifying the list of created confirmation requests.

When several UIBBs request different confirmations the application controller can combine, remove or replace those requests.

AFTER_PROCESS_BEFORE_OUTPUT

Will get called after all UIBBs retrieved their data

Check the results of the data retrieval or react on changes in the newly retrieved data

AFTER_PROCESS_EVENT

Gives the possibility to evaluate and change the result of the event after every UIBB processed it.

Process logic after all UIBBs successfully processed the event.

AFTER_SAVE

Is called after a successful SPI save call.

Trigger a workflow

FLUSH

Is called before the data of the GUIBBs is flushed to the SP via INSERT/UPDATE.

Perform validation before data changes are made.

INITIALIZATION

Initializes the application specific controller.

A UI or backend buffer is initialized.

NEEDS_CONFIRMATION

Allows raising a confirmation popup before a certain event gets processed.
When the popup is confirmed the event will be processed (PROCESS_EVENT is called by FPM), otherwise the event will fail (AFTER_FAILED_EVENT is called by FPM).

The user performs an action which is irreversible or has great impact and therefore the user should explicitly confirm the execution of this action.

OVERRIDE_CONFIG_TABBED

When a tabbed component uses Web Dynpro component /PLMU/WDC_FRW_TAB_APPCC as its application controller (optional) this method gets called for every event before its processing and grants access to the interface IF_FPM_TABBED.

The tabbed UIBB layout is adjusted e.g. an UIBB is added or deleted.

OVERRIDE_EVENT_XXX

Gets called for every event before its processing and grants access to the Floorplan interface (e.g. IF_FPM_OIF)

The Floorplan layout is adjusted e.g. an UIBB is added or deleted.

PROCESS_BEFORE_OUTPUT

Is called before all UIBBs retrieve their data.

Set up the necessary environment in the backend for retrieving the data.

PROCESS_EVENT

Processes an event with the possibility to cancel it, too.

Handle central tasks under consideration of the event ID before any other part of the UI has processed the event

Tutorial Available

A tutorial on how to create an application specific Application Controller can be found in the tutorials section.

Application Controller Service Class – /PLMU/CL_FRW_APPL_CNTRL

Class /PLMU/CL_FRW_APPL_CNTRL offers several attributes and methods that can be used by the application, which are especially useful for an application specific controller:

Attributes

Name

Description

Example for Usage

GV_APPLICATION_CONFIG_ID

Contains the name of the Web Dynpro configuration ID that is currently running.

Helps to identify the application at runtime.

GV_FPM_EVENTID

Contains the name of the FPM event that is currently being processed.

Get information about the current event ID where the event object is not available.

GV_MODE

Indicates the global mode the UI is currently in (I: Insert, C: Change, D: Display)

Set the title of the application UI depending on the UI mode.

GV_ROOT_DELETE

Indicates that the root object is currently being deleted.

Skip some logic in case the root object is about to be deleted.

GV_SKIP_MESSAGE_PROCESSING

Is set if the messages are not processed during the next POST_PROCESSING.

Allows evaluating if the publishing of a new message will be delayed.

GV_WDY_APPL_NAME

Contains the name of the Web Dynpro application that is currently running.

Helps to identify the application at runtime.

Methods

Name

Description

Example for Usage

CANCEL_NAVIGATION

Cancels the navigation that is about to be processed.

The FSI itself uses this method whenever an update error occurred during the data flush.

DISPLAY_ERROR_PAGE

Navigates to the error page.

Exit the application in case of a fatal error.

GET_COMPONENT_USAGE

Creates a component usage.

Reuse and communicate with a Web Dynpro component without the need of having an own Web Dynpro component (which is normally needed to create a component usage).

GET_FLOORPLAN_STATE

Provides the current Floorplan state

Evaluate the Floorplan state to process logic only when the main screen is visible but not on the initial screen.

GET_FPM

Provides an instance of the FPM access interface

Get access to various services the FPM offers.

GET_LEADING_ABBID

Provides the leading ABBID

If a UI consists of different ABBIDs one may be declared as leading ABBID.

REFRESH_SIDEPANEL

Refreshes the content of the side-panel.

New parameters are available that need to be considered by the side-panel.

RESET

Resets all error buffers of the FSI.

The whole UI needs to be reset.

SET_CNR_OPERATIONS

Defines CNR mapping information for operation control

Link a CNR button with a backend operation which will result in changes of the button properties (visible, enabled) whenever the SP controls an operation.

SET_LEADING_ABBID

Set the leading ABBID

If a UI consists of different ABBIDs one may be declared as leading ABBID.

SET_MODE

Sets the mode of the application to I (Insert), C (Change) or D (Display).

After an object status change the application is supposed to be switched to display mode.

Some of the service methods are applicable only for usage in combination with freestyle UIBBs:

Name

Description

Example for Usage

FLUSH

Triggers insert or update of changed data of freestyle UIBBs.

The FSI calls this method at the beginning of every round-trip of the main area of the Floorplan.

POST_PROCESSING

Triggers the final processing of the UI round-trip (e.g. processes all messages and properties that were not published yet)

Limitation of Usage

This method must never be called during an FPM event!

The FSI calls this method during the WDDOPOSTPROCESSING.

PROCESS_FIELD_PROPERTIES

Processes all field properties that have not been passed to Web Dynpro yet.

Limitation of Usage

This method must never be called during an FPM event!

This method is also called by service method POST_PROCESSING.

PROCESS_MESSAGES

Processes all messages that have not been published yet.

Limitation of Usage

This method must never be called during an FPM event!

This method is also called by service method POST_PROCESSING

SKIP_MESSAGE_PROCESSING

Skips the message processing during the next POST_PROCESSING.

Allows delaying the processing of unpublished messages to the next round-trip.

  • No labels