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.

Registration

Service Provider Infrastructure (SPI) FPM SPI Integration Application Controller