Basic Concepts – Selection vs. LeadSelection
Anyone who starts developing an application using Web Dynpro ABAP comes across using the leadSelection or selection of a context node somewhere within the user interface, since many ui elements either utilize the leadSelection (e.g. DropDownByIndex) or the selection (e.g. CheckboxGroup) or both (e.g. the Table). This makes these two concepts (besides context binding) some of the most important ones regarding using ui elements. Therefore for a developer the question always arises sooner or later: What excatly is their purpose and how should I use them in my application? Let me give you quick overview:
- At context node level hence there is only a single one per node
- Denotes a single context element (e.g. table row, dropdown entry) as being special
- Used to navigate between detail data as ui elements binding to attributes of sub nodes of this element always follow the leadSelection
- At context element level hence many of them can be selected or not (while the minimum and maximum number of selected elements is determined by the selectionCardinality of the node)
- Denotes one or more items to be affected by a user action, e.g. buttons in a tables toolbar like delete, copy, etc
- Can not be used to navigate between detail data
Lets make a few examples.
DropDownByIndex Using the LeadSelection
This ui element allows a developer to choose an attribute of a context node and to display all of its values inside of a dropdown. Each entry corresponds to another context element of this node. There are as many entries as there are context elements.
Whenever a user selects an entry the leadSelection moves as well.
The context offers the possibility to either set the leadSelection by specifying the index of the affected context element or the context element itself.
my_node->set_lead_selection( my_context_element ). my_node->set_lead_selection_index( 1 ).
In contrast to Web Dynpro Java, the numbering starts with 1 not with 0 as this is common in ABAP and offers some performance benefits.
There are of course methods to retrieve the index of element that holds the leadSelection or the context element itself.
my_context_element = my_node->get_lead_selection( ). lead_selection_index = my_node->get_lead_selection_index( ).
As the leadSelection can be used to navigate between detail data, we will create a small example with two DropDownByIndex where the selected value of the first one determines the available entries in the second one.
It is a demo application that is part of the transport request, which can be downloaded at the end of this blog. It is called ZWDAA_BC_LEAD_SELECTION.
In order to achieve the desired result, create a 0..N node MAIN_VALUES with an attribute TEXT of type STRING. Then add a 0..N sub node SECONDARY_VALUES to MAIN_VALUES. Add an attribute TEXT of type STRING as well.
The next step is to specify a supply function to both nodes. Choose the S_MAIN_VALUES and S_SECONDARY_VALUES as their names and copy the coding below into them.
method s_main_values . data: lt_main_values type if_main=>elements_main_values, main_values like line of lt_main_values. do 5 times. main_values-text = sy-index. insert main_values into table lt_main_values. enddo. node->bind_table( new_items = lt_main_values ). endmethod. method s_secondary_values . data: lt_secondary_values type if_main=>elements_secondary_values, secondary_values like line of lt_secondary_values, parent_text type string. parent_element->get_attribute( exporting name = 'TEXT' importing value = parent_text ). do 5 times. secondary_values-text = sy-index. concatenate parent_text secondary_values-text into secondary_values-text. insert secondary_values into table lt_secondary_values. enddo. node->bind_table( new_items = lt_secondary_values ). endmethod.
The next step is to create the two DropDownByIndex. The first one is called MAIN_VALUES while the second one is called SECONDARY_VALUES. Now bind their texts attributes to the corresponding TEXT attribute in the context.
For accessibility reasons create a label pointing to the first drowndown. Mark the first dropdown as being a label for the second one by setting its labelFor attribute.
Please create an empty action and assign it to the onSelect event of the first dropdown. This will trigger a roundtrip whenever a user selects an entry. Otherwise you need to create an additional button for triggering a roundtrip.
The last step is to create an application and to make sure that the window embeds our newly created view. After starting the application you will see that after choosing a value of the first dropdown the available entries in the second dropdown change as well.
The demo application where you can see how it works is ZWDAA_BC_DEP_LEAD_SEL.
CheckboxGroup Using the Selection
This ui element works similar as a DropDownByIndex. The difference is that all elements of the corresponding context node are displayed as checkboxes. Since more than one can be selected at a time, the leadSelection cannot be used anymore. Instead, while selecting or deselecting a checkbox, the system toggles the selection of the corresponding context element.
Web Dynpro ABAP offers several methods to toggle the selection of a certain context element and to determine if a user selected a particular element.
my_node->set_selected( index = 1 flag = abap_true ). my_node->is_selected( index ). my_element->is_selected( ).
There is also the possibility to retrieve all currently selected context elements.
data: lt_selected_elements type WDR_CONTEXT_ELEMENT_SET lt_selected_elements = my_node->get_selected_elements( ).
The sample application is called ZWDAA_BC_SELECTION. By executing it you will see that the selected elements are not marked by the runtime, but that the runtime collects them in the order they were selected. As shown in the picture above, selecting 3, 4 and afterwards 1 returns an internal table of selected elements in that order. Removing 4 will lead to having 3,1 displayed. This means you cant depend on having the selected elements sorted by their index.
Table Using Selection and LeadSelection at the Same Time
The table ui element displays the elements of a context node as rows. In addition it also offers the possibility to make use of the two concepts of selection and leadSelection by providing a special button-like column at the left side that allows a user to mark a row. By clicking at this button, the user either toggles the selection of the current row and/or moves the leadSelection to it. The common CTRL and SHIFT logic can be applied as well to change the selection of multiple rows.
It is possible to specify if the leadSelection, selection or both should be changeable by setting the appropriate value of the selectionMode property. The property also allows a developer to switch off this special column completely. This should be done whenever neither the selection nor leadSelection are used to do something meaningful. This is common for display-only tables.
In addition it is highly advisable that a developer also switches off the usage of leadSelection in case there was no detail data. Employing the selection is the better concept as it offersthe possibility to mark multiple rows while each row will retain the same color. Having one of them in a different color without an obvious purpose confuses the user. Additionally, no roundtrip will happen, which reduces the time a user spends on a screen.
Switching off the special column if not needed or fine-tuning its usage shows that the developer has mastered the fine arts of applying these two concepts. :p
I created a sample application that demonstrates how these two concepts are applied to a table. It shows a small table and next to it a DropDownByIndex and a CheckboxGroup that both bind to the same context node as the table. In addition there is a DropDownByKey that allows the user to switch between the different selection modes of the table.
While playing around with the application you will see two things: Firstly, changing the selection or leadSelection inside of table affects the DropDownByIndex as well as the CheckboxGroup. The opposite direction works too. Secondly, the selectionMode property is merely a filter. It is still possible to change the selection and leadSelection of the context node, but the table wont display it nor allow you to change it.
The Web Dynpro component containing the example is ZWDAA_BC_LEAD_SEL_AND_SEL.
This weblog provides you with a first introduction to the two concepts of selection and leadSelection. The examples are also available as a transport request that you can import to your system. You can download it from here.
A more advanced topic concerning the leadSelection is the usage of singleton nodes and the selectionChangeBehaviour. Expect more details on it in another weblog. 🙂