** TEAM FPM ** - Drag & Drop in FPM GUIBBs

[J_R]

Drag & Drop in FPM GUIBBs

Scope

This document describes the concept about how the drag & drop functionality of the GUIBBs List ATS, List, Tree, Form Repeater, Form@GL2.0, and Form (old) works as of NW 7.31 SP06 and how it can be used in FPM applications. In NW 7.31 SP05 the full drag & drop functionality is also available in the GUIBB runtime. However, the configuration editor for the GUIBBs does not yet support all the features.

Basic Concept

The FPM offers a drag & drop functionality in several of its GUIBBs. These are the GUIBBs List ATS, List, Tree, Form Repeater, Form@GL2.0, and Form (old). The List ATS, List, and Tree allow dragging and dropping entries whereas the Form Repeater, Form@GL2.0, and the old Form currently only support dropping entries. In order to use drag & drop in the GUIBBs the corresponding feeder classes have to define drag sources and/or drop targets. For this, the feeder interfaces IF_FPM_GUIBB_LIST, IF_FPM_GUIBB_TREE, IF_FPM_GUIBB_FORM_REPEATER, and IF_FPM_GUIBB_FORM offer a dedicated exporting parameter ET_DND_DEFINITION (of type FPMGB_T_DND_DEFINITION) in method GET_DEFINITION. Its line structure (of type FPMGB_S_DND_DEFINITION) will be explained in detail below. If not exceptionally configured the drag & drop definition entries will be evaluated and applied at runtime as provided by the feeder class. However, if the properties of these drag & drop definition entries do not exactly meet the application requirements they can be overwritten in the GUIBB configuration. For example, drag sources and/or drop targets can be enabled or disabled in the configuration or their tags can be changed. Depending on the use case, there are certain combinations of drag & drop definition entries that do not make much sense. The conditions for reasonable combinations will be mentioned in this document where applicable.

Line structure (type FPMGB_S_DND_DEFINITION) of the exporting parameter ET_DND_DEFINITION in feeder method GET_DEFINITION:

• TYPE

This field defines the type of the drag & drop definition entry, whether it is a drag source or a drop target and which kind of drop target. The type of a drag & drop definition entry that has been specified by the feeder can neither be overwritten in the GUIBB configuration nor modified at runtime.

The following types are supported by the FPM:

• Drag:

This is the type for a drag source and is available for the GUIBBs List ATS, List, and Tree. It allows dragging one or multiple entries from the drag table/ tree.

• Drop on Body:

This is a drop target type and is available for the GUIBBs List ATS, List, and Tree. It allows dropping a drag source between two entries in the drop table/ tree or into an empty drop table/ tree. However, it is not possible to drop the drag source on an entry in the drop table/ tree. Two different flavors of this drop target type have to be distinguished:

(a) Unspecific:

The drag source can be dropped between any two entries in the drop table/ tree. It is not possible to drop the drag source just between two specific entries in the drop table/ tree. This is the standard behavior for this drop target type.

(b) Specific:

The drag source can be dropped between any or just between two specific entries in the drop table/ tree. How to apply the latter feature will be explained in paragraph Using Body-Specific Dropping.

Important Remarks:

• The WD UI element ‘Table’ does not support this feature, but only the WD UI element ‘C-Table’. Therefore, this feature is only available for the GUIBB List ATS and for the new version of the GUIBB Tree.
• The old version of the GUIBB Tree is a special case. It is based on the WD UI Element ‘Table’. If row-specific dropping is used there, an entry that can be dropped on a specific tree node can always be dropped between the child entries of this node as well. In this way, there is also a kind of body-specific dropping in the old version of the GUIBB Tree.
• ‘Body-specific’ dropping means in WD ABAP/ UR terms dropping on the ‘row edge’ a table/ tree entry.

• Drop on Row:

This is a drop target type and is available for the GUIBBs List ATS, List, and Tree. It allows dropping a drag source on an entry in the drop table/ tree. However, it is not possible to drop the drag source between two entries or into an empty drop table/ tree. Two different flavors of this drop target type have to be distinguished:

(a) Unspecific:

The drag source can be dropped on any entry in the drop table/ tree. It is not possible to drop the drag source just on specific entries in the drop table/ tree. This is the standard behavior for this drop target type.

(b) Specific:

The drag source can be dropped on any or just on specific entries in the drop table/ tree. How to apply the latter feature will be explained in paragraph Using Row-Specific Dropping.

Important Remarks:

• The old version of the GUIBB Tree is a special case. If row-specific dropping is used there, an entry that can be dropped on a specific tree node can always be dropped between the child entries of this node as well. In this way, there is also a kind of body-specific dropping in the old version of the GUIBB Tree.

• Drop:

This is a drop target type and is available for the List ATS, List, and Tree as well as for the Form Repeater, Form@GL2.0, and the old Form.

In the case of a table or a tree, an entry of this drop target type is treated as if there were two drop target entries, one of type ‘Drop on Row’ and one of type ‘Drop on Body’. In this way, it’s like a mixture of these two drop target types.

In the case of a Form Repeater or a Form@GL2.0 this drop target type allows dropping a drag source on to the whole form, whereas in the case of an old Form, it allows dropping a drag source on single form groups.

• NAME

A name is required in order to distinguish multiple drop definition entries of the same type. This is currently only relevant if a body-specific and/ or a row-specific drop behavior is desired. The name of a drag & drop definition entry that has been specified by the feeder can neither be overwritten in the GUIBB configuration nor modified at runtime.

• SCOPE

The scope defines whether dropping is principally only possible on the drag source itself (scope ‘Local’, constant IF_FPM_GUIBB_CONSTANTS=>GC_DRAG_DROP_SCOPE-LOCAL) or on any other GUIBB that supports the drag & drop mechanism as well (scope ‘Global’, constant IF_FPM_GUIBB_CONSTANTS=>GC_DRAG_DROP_SCOPE-GLOBAL). Of course, in order to perform a real dropping operation, drop targets with appropriate tags have to exist in the target GUIBB. If not further specified, the default scope is ‘Global’. The scope can be overwritten in the configuration or later at runtime. For the latter, please refer to paragraph Modifying Drag Sources & Drop Targets at Runtime.

• ENABLED

This attribute defines whether a drag & drop definition entry is enabled or not. If a drag source is disabled dragging will be completely blocked. If a drop target is disabled dropping on this target will be completely blocked. The attribute value can be overwritten in the configuration and/or modified at runtime. For the latter, please refer to paragraph Modifying Drag Sources & Drop Targets at Runtime.

• TAGS

A drag source can only be dropped on a drop target if their tags match each other, i.e. at least one of the tags of the drag source must be part of the tag list of the corresponding drop target. Otherwise, dropping will not be possible. This field specifies the relevant tags of the drag & drop definition entry. Multiple tags can be separated by a space. Wildcards, such as ‘HUGO*’, are supported.

The tag list can be overwritten in the configuration and/or modified at runtime. For the latter, please refer to paragraph Modifying Drag Sources & Drop Targets at Runtime.

• OVERRIDE

This attribute defines whether the properties (e.g. the scope or the tag list) of the drag & drop definition entry can be modified at runtime or not. The attribute value can be overwritten in the configuration.

The feeder can in principle define multiple drag sources and multiple drop targets of the same type. However, in order to define meaningful drag & drop definition entries, some conditions have to be taken into account:

• There shouldn’t be more than one drag source entry since WD ABAP does not support more than one. The FPM will therefore consider only one drag source entry at runtime.
• There shouldn’t be multiple drop targets of the same type with the same name. Oherwise, only one entry per type and name will be considered by the FPM at runtime.
• If body-specific dropping is not required but body-unspecific dropping, only one entry of type ‘Drop on Body’ or ‘Drop’ is meaningful. Further entries will be neglected by the FPM at runtime. Please note that a drop target entry of type ‘Drop’ will result in two drop targets, one of type ‘Drop on Body’ and one of type ‘Drop on Row’.
• If row-specific dropping is not required but row-unspecific dropping, only one entry of type ‘Drop on Row’ or ‘Drop’ is meaningful. Further entries will be neglected by the FPM at runtime. Please note that a drop target entry of type ‘Drop’ will result in two drop targets, one of type ‘Drop on Body’ and one of type ‘Drop on Row’.
• If both, body-unspecific and row-unspecific dropping is required which have to be controlled completely independently of each other, one drop target entry of type ‘Drop on Body’ and one of type ‘Drop on Row’ is needed.

If body-unspecific and row-unspecific dropping is required which need not to be controlled independently of each other, one drop target entry of type ‘Drop’ is sufficient, since it will result in two drop targets, one of type ‘Drop on Body’ and one of type ‘Drop on Row’.

• If body-specific dropping is required it is mandatory to define multiple drop target entries of type ‘Drop on Body’ or ‘Drop’. Each drop target entry has to have a unique name. Please note that each drop target entry of type ‘Drop’ will result in two drop targets, one of type ‘Drop on Body’ and one of type ‘Drop on Row’.
• If row-specific dropping is required it is mandatory to define multiple drop target entries of type ‘Drop on Row’ or ‘Drop’. Each drop target entry has to have a unique name. Please note that each drop target entry of type ‘Drop’ will result in two drop targets, one of type ‘Drop on Body’ and one of type ‘Drop on Row’.
• If both, body-specific and row-specific dropping is required which have to be controlled completely independently of each other, there should be no drop target entries of type ‘Drop’, but only drop target entries of type ‘Drop on Body’ and ‘Drop on Row’. Each drop target entry has to have a unique name within the complete set of drop target entries.

If body-specific and row-specific dropping is required which need not to be controlled completely independently of each other, drop target entries of type ‘Drop’ are sufficient where dependence is desired since each of those drop target entries will result in two drop targets, one of type ‘Drop on Body’ and one of type ‘Drop on Row’. Where independent control is required separate drop target entries of type ‘Drop on Body’ and ‘Drop on Row’ are mandatory. Anyway, each drop target entry has to have a unique name within the complete set of drop target entries.

• If a mixture of body-unspecific and row-specific or body-specific and row-unspecific dropping is required the above-mentioned conditions are still valid.

Further information about body-specific and row-specific dropping can be found in the paragraphs Using Body-Specific Dropping and Using Row-Specific Dropping.

Using Body-Specific Dropping

This feature enables an application to control dropping of drag sources on the row edge level in the GUIBBs List ATS and Tree. It is possible in this way to enable dropping between two particular entries of the drop table/ tree but to forbid it between other entries. In the case of the GUIBB Tree this feature is in principle only supported in the new version of the GUIBB Tree that uses the C-table. However, in the old version of the GUIBB Tree there is automatically also a kind of body-specific dropping if the row-specific dropping feature is used since an entry that can be dropped on a specific tree node can always be dropped between the child entries of this node as well.

The technical mechanism behind the body-specific dropping feature is in principle based on different tag lists that are assigned to the single rows of the drop table. In order to provide such a pool of tag lists multiple drop targets are required because a drop target can always have just one tag list. The drop targets are then bound to the data table. For this, the data table has to have one explicit column that contains the name of the relevant drop target at runtime per row.

In order to use the feature the following has to be done:

• Depending on the number of different tag list that an application requires for controlling the drop behavior on the row edge level a corresponding number of drop target entries of type ‘Drop on Body’ or ‘Drop’ with unique names have to be defined by the GUIBB feeder class in method GET_DEFINITION. The conditions for meaningful drop target combinations have already been described in detail in paragraph Basic Concept. If required, the properties of the drop targets can be overwritten in the configuration.
• The name of a (technical) reference field of type string has to be specified with parameter DROP_ON_BODY_TRGT_NAME_REF in the exporting parameter ES_OPTIONS (which is of type FPMGB_S_LIST_OPTIONS in the case of the GUIBB List ATS and of type FPMGB_S_TREE_OPTIONS in the case of the GUIBB Tree) of the feeder method GET_DEFINITION. The reference field must of course be part of the GUIBB field catalog. At runtime the reference field has to contain the name of the relevant drop target for each data record in the data collection. As for any other feeder field, the field content can be provided in the feeder method GET_DATA.

Using Row-Specific Dropping

This feature enables an application to control dropping of drag sources on a row level in the GUIBBs List ATS, List, and Tree. It is possible in this way to enable dropping on particular entries drop table/ tree but to forbid it on other entries.

The technical mechanism behind the row-specific dropping feature is in principle based on different tag lists that are assigned to the single rows of the drop table. In order to provide such a pool of tag lists multiple drop targets are required because a drop target can always have just one tag list. The drop targets are then bound to the data table. For this, the data table has to have one explicit column that contains the name of the relevant drop target at runtime per row.

In order to use the feature the following has to be done:

• Depending on the number of different tag list that an application requires for controlling the drop behavior on the row level a corresponding number of drop targets of type ‘Drop on Row’ or ‘Drop’ with unique names have to be defined by the GUIBB feeder class in method GET_DEFINITION. The conditions for meaningful drop target combinations have already been described in detail in paragraph Basic Concept. If required, the properties of the drop targets can be overwritten in the configuration.
• The name of a (technical) reference field of type string has to be specified with parameter DROP_ON_ROW_TRGT_NAME_REF in the exporting parameter ES_OPTIONS (which is of type FPMGB_S_LIST_OPTIONS in the case of the GUIBB List ATS and of type FPMGB_S_TREE_OPTIONS in the case of the GUIBB Tree) of the feeder method GET_DEFINITION. The reference field must of course be part of the GUIBB field catalog. At runtime the reference field has to contain the name of the relevant drop target for each data record in the data collection. As for any other feeder field, the field content can be provided in the feeder method GET_DATA.

Modifying Drag Sources & Drop Targets at Runtime

It is possible to modify the properties of drag sources and drop targets at runtime. Currently, this mechanism is only supported by the GUIBBs List ATS, List, and Tree. As a prerequisite, the attribute OVERRIDE of the corresponding drag source or drop target must have the value ‘X’. The attribute value can either be set by the feeder itself when specifying the drag & drop definition entries in method GET_DEFINITION or by an administrator in the GUIBB configuration. At runtime the current settings of the drag sources and drop targets are passed to the feeder class via the changing parameter CT_DND_ATTRIBUTES of method GET_DATA. The feeder can modify these settings and pass them back via the same parameter. In order to notify the GUIBB runtime about the changes the exporting parameter EV_DND_ATTR_CHANGED of method GET_DATA has to be set to ‘X’ by the feeder as well. The GUIBB runtime will consider the changed settings of a drag source or a drop target if the modification is allowed for this entry, i.e. if OVERRIDE = ‘X’.

By using this feature it is possible, for example, to disable dragging for particular entries of a table/ tree. This can be done by modifying the property ‘Enabled’ of the drag source in GET_DATA based on the selected and dragged table/ tree entry. It is, however, not possible with this feature to add or remove drag sources or drop targets or to change their type or name.

Processing a Drag & Drop Operation

When a drag source is dropped on a drop target several steps are performed in the FPM GUIBBs. Basically, these steps can be summarized as follows:

1. The action handler on the drop target GUIBB raises an FPM event with the event ID FPM_DROP_COMPLETED (constant IF_FPM_CONSTANTS=>GC_EVENT-DROP_COMPLETED) and the drop target GUIBB key as event source. The drop event provides an FPM event parameter FPM_DROP_INFO (constant IF_FPM_CONSTANTS=>GC_GUIBB_DND-DROP_INFO; type FPMGB_S_DROP_INFO) which contains a table of the original Web Dynpro event parameters and, in case of the drop target GUIBBs List ATS, List, Tree, and Form Repeater, information about the drop position (drop index and offset).
2. During processing the drop event of step 1 each GUIBB that might be a valid drag source has to check whether it is the actual drag source. This is done in the GUIBB method FLUSH by evaluating the table of Web Dynpro event parameters that has been passed on the drop event as part of the FPM event parameter FPM_DROP_INFO. The relevant Web Dynpro event parameter in this table has the name DATA. The GUIBB is the drag source of the drag & drop operation if the value of the Web Dynpro event parameter DATA fits to the value of the property DATA of the drag source UI element of the GUIBB. The latter has been set by the GUIBB runtime during the creation of the UI elements of its view and normally has the GUIBB key as value.
3. If a GUIBB has identified itself as drag source it adds important drag source information to the drop event of step 1. This also happens in the GUIBB method FLUSH. The drag source information is provided with event parameter FPM_DRAG_SOURCE_DATA (constant IF_FPM_CONSTANTS=>GC_GUIBB_DND-DRAG_SOURCE; type FPMGB_S_DRAG_AND_DROP). It contains the GUIBB key of the drag source as string, the complete set of data records in the drag source GUIBB, the indices of the dragged entries in this set of data records, and the drop position.

The drop event will then be further processed as any other FPM event. This means that a GUIBB feeder class can react appropriately on the FPM drop event, in particular in the feeder methods PROCESS_EVENT and GET_DATA. In this way, a drag source GUIBB feeder can delete dragged entries and the corresponding drop target GUIBB feeder can insert them, for example.

If a free-style UIBB is used as drag source or drop target instead of an FPM GUIBB, similar steps as the ones described above have to be performed by the respective free-style UIBB. For this, the FPM provides a slim helper class CL_FPM_GUIBB_DRAG_AND_DROP. Method RAISE_DROP_EVENT of this class can be used for performing step 1 and method SET_FPM_DROP_DATA can be used for performing step 3. Step 2, however, is application-specific.

Related SAP notes

There are currently the following SAP notes available regarding the drag & drop functionality in GUIBBs: 1761101