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 |
|
OPERATION_TYPE |
/PLMB/SPI_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. |
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 |
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. |
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. |