How_to_use_BOL_Tree

SAP IS-U/CRM IntegrationBOL Tree (Generic Tree)How to use the generic Tree

12. January 2009

BOL Tree (Generic Tree)

Table of content:

1 Summary .........................................................................................................................3

2 Customizing ....................................................................................................................3

2.1 Define a tree profile ...............................................................................................................................32.1.1 Profiles ...............................................................................................................................................32.1.2 Define Columns ..................................................................................................................................32.1.3 Hierarchy ............................................................................................................................................42.1.4 One Click Actions (OCAs) ...................................................................................................................6

2.2 Define Node Presentation .....................................................................................................................72.2.1 Define Columns ..................................................................................................................................7

3 Implementation Tasks....................................................................................................8

3.1 Manditory Steps ....................................................................................................................................8

3.2 Tree properties ......................................................................................................................................9

3.3 Tree Event Handling............................................................................................................................12

4 Other considerations ...................................................................................................13

5 Conclusion....................................................................................................................13


1 SummaryThis document describes how to reuse the generic BOL-tree component IUBOTREE. At the beginning, therequired customizing steps are described followed by the descrition how to integrate the tree into a parentcomponent. The tree can be used in UIU and in IC WebClient scenarios.

2 CustomizingStart View Cluster CRM_IU_IC_BOLTREE in transaction SM34 or go to Customizing for the CRM systemunder Customer Relationship Management Industry-Specific Solutions Telecommunications MasterData Object Management Settings for Object Workbench Define Object Hierarchy and ObjectAttributes.

2.1 Define a tree profile

2.1.1 Profiles

For the definition of tree profiles the following data are required:

Profile Name: the technical name/key of this tree profile

Description: not relevant for the runtime UI Description of the profile

GenIL Component Set: this component set is loaded during runtime, the components of BOLobjects that are defined in the hierarchy should be part of this set

Rows per Page: when the number mentioned in this field is reached, google-like paging linksappear, if nothing is defined 16 is taken as default

Visible Rows in Scroll Area:

o default entry 0 means that there is no maximum height defined-> the tree will grow until“rows per page” is reached -> no vertical scrollbar will appear;

o an entry >0 defines the number of rows which will be visible -> the rest of the lines can bereached via the scroll bar)

2.1.2 Define Columns

For the definition of the BOL tree colums the following data are required:


Column ID: you can define up to 20 columns, the column ID is also used as sorting key

Title: this text appears as the title of the column

Width in %: The visible columns shouldn’t exceed 100%, if nothing is defined the system willcalculate the width proportionally

Hidden:

o If “Hidden” is marked the column will not appear during runtime, predefined hidden columnscan be defined by SAP and customers just have to activate them, or customers can hidenormally visible columns.

o This flag allows to reuse Node Presentations in multiple tree profiles. E.g. there are twodifferent tree profiles and in both one specific object is defined in the hierarchy. The NodePresentation of this object is the same except that in one profile one column is not needed.This column can be defined as hidden in the corresponding tree profile .This means that onlyone Node Presentation can be used.

2.1.3 Hierarchy

For the definition of the hierarchy of the BOL Tree the following data are required:

Node ID: the node key in the hierarchy

Parent Node ID: An existing Node ID in the hierarchy can be defined as parent, if no parent isdefined means this node is a root node. Multiple different root nodes can be defined. The ParentObject Name should display the External Object Name of the corresponding parent node.

Path for Target Nodes: a BOL relation path can be defined for non-root nodes as the relationbetween the parent node and the child node. (Alternatively, this relation can be defined via coding inthe “node class”, see Change Relation flag)

External Object Name: the BOL object type of this node, this BOL type is also the target object typeof the defined relation in Path for Target Nodes

Sequence No: On the same level multiple nodes can be defined (multiple nodes have the sameparent); this field defines the sequence of this nodes on one level.

Presentation ID: this field defines the Node Presentation for this node. A Node Presentation defineseach cell content of a node line. See Define Node Presentation

Hidden: This node is hidden, it is only used as a logical node, e.g to display the children directlybeneath the “grandparent”. For a hidden node, it is not necessary to define a Presentation ID.

Node is Folder: This node has a folder icon and it inherits the BOL object type from its parent. It isused to define e.g. semantic or systematic arranging of objects.

Is Recursive: Used to define a recursive hierarchy (of the same object type). E.g. Item -> SubItem ->SubItem…

Define user exit class (node class):


o Class Name: define an ABAP Objects class name which implements the interfaceIF_IU_IC_BOL_TREE. Because of possible future enhancements it is recommended to useCL_IU_IC_BOL_TREE as the superclass!

o Change relation: Instead of using the Path for Target Nodes the tree will call theIF_IU_IC_BOL_TREE~GET_CHILDREN method of the defined class to fill this node withobjects

o Change Presentation: Normally, the content of a tree cell is defined in the NodePresentation (Presentation ID). This can be redefined in theIF_IU_IC_BOL_TREE~GET_ATTRIBUTE method. Within the method the cell content/valuecan be filled dynamically.

o Rerender Cell: Normally a cell content is rendered as text, icon, inputfield or link dependingon the definition of the Node Presentation. If this flag is marked the methodIF_IU_IC_BOL_TREE~RENDER_CELL will be called. Within this method the cell contentcan be rendered differently, e.g. in the form of a combination of multiple UI elements(multiple icons, icons + text, inputfield + icon, inputfield + text etc.)

Define initial expanding behaviour:

o Maximal Sibling Nodes: If there are more siblings than defined in this field, this node willnot be expanded The entry 0 means no maximum is defined and this node will be expanded,888 means the node stays collapsed.

o Maximal Child Nodes: If there are more children than defined in this field this node will notbe expanded. The entry 0 means no maximum is defined and this node will be expanded.888 means the node stays collapsed.

Hierarchy Overview


Hierarchy Node Details

2.1.4 One Click Actions (OCAs)

OCAs need a customizing and an implementation part.

Description of the customizing settings:

One Click Action ID: Key of the OCA, An event handler method of the parent UI Component iscalled when an OCA is selected, this key is passed to differentiate between the OCAs (seeImplementation Tasks).

Alternative Column ID: If nothing is defined in this field the OCA is rendered in the column with theColumn ID 1. Otherwise, it is displayed in the column with the ID defined in this field. If anothercontent cell is already defined, the OCA appear before the other cell content.

Sequence: defines the Sequence of the OCAs

Icon Name: You can either define a CRM icon (file name, e.g. delete.gif) or a SAP icon name(Transaction ICON, e.g ICON_LOCKED) as icon. Either Icon Name or Text or both should bedefined.

One Click Action Text: optionally a text can be defined, it will appear as a link. Either Icon Name orText or both should be defined.

One Click Action Tooltip: tooltip for the OCA icon and text


2.2 Define Node Presentation

For the definition of the node presentation the following data are required:

Presentation ID: The key of one node presentationYou can assign this ID to a node in the hierarchy definition (see Define a tree profile Hierarchy Presentation ID). It can be assigned to multiple nodes and multiple tree hierarchies.

Presentation Text: Just a description, not relevant for the UI

External Object Name: The BOL object type for this node presentationThe same object type that is defined in the corresponding hierarchynode

2.2.1 Define Columns

Like in the tree profile definition, multiple columns (up to 20) can be defined, too.One entry in this table defines the content of one tree cell:

Define Columns Detail

Column ID: The column ID is the key of this column.The content defined here will be displayed in the column with the same Column ID which is definedin the tree profile (see Define a tree profile Define Columns).

Icon: Optionally you can define an icon. It will appear before the content. You can either define aCRM icon (file name, e.g. delete.gif) or a SAP icon name (Transaction ICON, e.g ICON_LOCKED)as icon. This icon is not an OCA. It is recommended to use either icons or OCAs in one tree profile.

Value Path A:

o A BOL value path starting from the BOL object type defined in External Object Name can bedefined as value path.

o The syntax for the path is the following:“//<BOL_Atribute_Name>” or//<BOL_Relation_Name1>/<BOL_Relation_Name2>/.../<BOL_Atribute_Name>”. Thevalue of the attribute with the name “BOL_Atrribute_Name” will be displayed in the cell.The relations in the path can be used optionally to display attributes of objects which aredefined beneath the current object in the GenIL model.

o E.g. the current object is a Business Partner and we want to display the street of the billaddress in the same tree row, but in the model the address is an own object beneath the BP.The path would be: “//BillAdressRelation/STREET”


o It is also possible to define translatable OTR texts as the content of the cell. The syntax forthe OTR path is: “OTR/<otr_alias_name>”. E.g. “OTR/CRM_IC_APPL/PARTNER”. TheOTR texts can be found or created in the transaction SOTR_EDIT

Value path B, C: You can define up to 3 values in the paths A, B and C which will be concatenatedand separated by a blank and diplayed in the cell

Editable: Defines whether this cell can be edited. If the Edit Mode (see Implementation Tasks) isactive and the flag is marked the value defined in Edit Value Path is rendered as an input field. Thevalue paths A, B and C are not used in edit mode.

Edit Value Path: The value path for the edit mode. (see Value Path A for syntax, don’t use OTRtexts here)

Is Link: Defines whether the value should be rendered as a link within this cell.

Link Event ID: An event handler method of the parent UI Component is called when this link isclicked, this ID is passed to differentiate between the links. (see Implementation Tasks)

Define Columns Overview

3 Implementation TasksThis chapter describes the needed implementation tasks to use the generic tree component IUBOTREE.

3.1 Manditory Steps

First of all define in the parent component a usage of the IUBOTREE component:

The next step is to set the tree profile which should be used in the tree component. This can be donee.g in the method WD_USAGE_INITIALIZE of the parent component controller class:


data: lr_profile type ref to if_bol_bo_property_access, lr_node type ref to cl_bsp_wd_context_node.

lr_node = iv_usage->get_context_node( 'PROFILE' ).if lr_node is bound.

lr_profile = lr_node->collection_wrapper->get_current( ).if lr_profile is bound.

lr_profile->set_property( iv_attr_name = 'PROF_ID' iv_value = 'IPM_VITALI' ).

endif.endif.

Then depending on what object type(s) is defined as root object in the treeprofile the“ROOTOBJECTS” node should be filled with root objects. This can be done via bounding a node of theparent component to the “ROOTOBJECTS” node or via filling the “ROOTOBJECTS” node-collection withobjects manually.

If the tree is not used as an assignement block (in an overview page), one of the inbound plugsbeginning with “DEFAULT*” has to be triggered or the tree property “INITIAL_SELECT” has to be set(see tree properties).

The last mandatory step is to handle the outbound plugs of the generic tree component(NODE_CLICKED and NODE_SELECTED). Therefore, you have to create navigational links ordelegate them to outbound plugs of the parent component.

After these mandatory steps the tree will behave as follows (this behaviour can be influenced by furtheroptional steps):

the tree type is “Table Tree” (non-navigable; technical COLUMN). See UI Guidelines for SAP CRMChapter 10 (There are two types of hierarchies, the second type is Hierarchy Map -> navigatable)

there are no toolbar buttons

If the tree is an assignment block, it can be personalized, otherwise not

the tree can not be scrolled

tree rows are filled up until the number “Rows per Page” is reached

the tree is by default in edit mode -> cells defined as edit cells will be editable when object is locked

no row will be initially selected

the tree is in SINGLESELECT mode, deselection is not possible

3.2 Tree properties

The behaviour of the tree the can be influenced by setting the tree properties in the parent component. Thiscan be done in the same way as setting the tree profile in the WD_USAGE_INITIALIZE (see above):

data: lr_profile type ref to if_bol_bo_property_access, lr_node type ref to cl_bsp_wd_context_node, ls_tree_props type crm_isutree_tree_properties.

lr_node = iv_usage->get_context_node( ‘PROFILE’ ).if lr_node is bound.

lr_profile = lr_node->collection_wrapper->get_current( ).if lr_profile is bound.

*setting the profile lr_profile->set_property( iv_attr_name = ‘PROF_ID’ iv_value = ‘IPM_VITALI’ ).*setting the mode lr_profile->set_property( iv_attr_name = ‘MODE’ iv_value = ‘E’ ).*setting the tree properties ls_tree_props-type = ‘COLUMN’.


ls_tree_props-toolbar_foreign_use = ‘TRUE’. ls_tree_props-maxbuttonnumber = ‘8’. ls_tree_props-fill_up_empty_rows = ‘FALSE’. ls_tree_props-personalizable = ‘FALSE’. ls_tree_props-display_mode = ‘X’. ls_tree_props-initial_select= if_crm_iu_bol_tree_evt_service=>co_mode_select_first. ls_tree_props-expand_collapse_all = abap_true. ls_tree_props-find = abap_true. ls_tree_props-allow_unselect = abap_true. ls_tree_props-multiselect = abap_true.

lr_profile->set_property( iv_attr_name = ‘TREEPROPERTIES’ iv_value = ls_tree_props ).

endif.endif.

MODE: the value ‘E’ lets appearing the ‘environment’ toolbar buttons over the tree. These buttons

are: (from right to left:)

o Refresh: The tree is rebuilt (e.g. the agent assumes that some other objects could appear inthe tree).

o Display Superior Object: This button is active if a row is selected, it selects (sets the focusto) the superior row.

o Display Lower-Level Object: selects the lower row.

o Restrict Environment to Focus Object: Only active if a row is selected, the slected rowbecomes the root object (“zoom to the selected row”).

o Extend Evironment: only active if the zoom-button was clicked before(Restrict Environmentto Focus Object), it re-zooms, the root object becomes a child again.

o Display Entire Environment: only active if the zoom-button was clicked before (maybeseveral times), it re-zooms to the top root object which is defined in the tree profile (itexecutes several “Extend Environment” steps).

tree property TYPE:

o possible values: SIMPLE, COLUMN

o default value: COLUMN

o There are two types of hierarchies : See UI Guidelines for SAP CRM Chapter 10

tree property TOOLBAR_FOREIGN_USE

o possible values: TRUE, FALSE

o default value: FALSE

o If the the toolbar should be displayed within an assignment block header, set this property to

TRUE:

tree property MAXBUTTONNUMBER

o possible values: integer numbers

o default value: 8

o A “more” button appears if there are more buttons available the defined in this property.

tree property FILL_UP_EMPTY_ROWS



o default value: TRUE

o if TRUE -> tree rows are filled up with empty rows util the number “Rows perPage”(Customizing) is reached

tree property PERSONALIZABLE


o default value:FALSE

o If TRUE-> personalizable icon appears

tree property DISPLAY MODE

o possible values: '' = edit mode; X = display mode

o default value: ‘’

tree property INITIAL_SELECT

o possible values: F=first; R=virtual root; S=current; N = ’’ = no selection


tree property EXPAND_COLLAPSE_ALL

o possible values: '' = no buttons visible; X = buttons visible

o default value:’’

o if TRUE: Expand All and Colapse All buttons appears in the toolbar:

o if no line is selected, everything is expanded/collapsed, if lines is are selected, only the areexpanded/collapsed

tree property FIND

o possible values: '' = no buttons visible; X = Position/Next Hit butt. visible


o if TRUE: Position/Next Hit buttons appears:

o With Position you can search for a string/pattern within the tree, the first found row will beselected. With Next Hit the next found row will be selected.

tree property SCROLLROWCOUNT

o possible values: integer numbers or initial

o default value: initial


o the maximal visible rows are defined here, if more rows are there a vertical scroll barappears:

tree property MULTISELECT

o possible values: '' = SINGLESELECT; X = MULTISELECT


tree property ALLOW_UNSELECT

o possible values: " = unselect a line not possible; X = unselect possible


3.3 Tree Event Handling

Since CRM 2007 it is possible to define 3 types of events in the tree:

Link Events (in each cell)

One Click Action Events (OCA Events)

Toolbar Button Events

To define a link event see 2.2.1 (cell attribute “Is Link” is marked and Link ID is defined)

To define a OCA event see 2.1.4 (OCA with OCA-ID is defined)

Toolbar buttons can not be defined via customizing, but via implementation (see below in this chapter)

To handle the events in the parent component the tree provides an event service. This event_service is apublic component node of the tree component. The event_service node implements the interfaceif_crm_iu_bol_tree_evt_service. To get an instance of the service the public static methodcl_iubotree_bspwdcomponen_cn08=>get_event_service( ir_parent_component = <parentcomponent instance> iv_tree_usage_name = <tree usage name> )should be used. This canbe done e.g. in the WD_USAGE_INITIALIZE of the parent component. Additionaly, to the event service youneed to implement one or more event handler. An event handler has to implement the interfaceIF_CRM_IU_BOL_TREE_EVT_HANDLER. E.g. the parent component itself could be the event handler.

So, if you have the service and an event handler you can register(subscribe) the handler to all events or onlyto an event type or even only to a specific event:

data tree_event_service type ref to if_crm_iu_bol_tree_evt_service.

tree_event_service = cl_iubotree_bspwdcomponen_cn08=>get_event_service( ir_parent_component = me iv_tree_usage_name = iv_usage->usage_name ).

if tree_event_service is bound.* subcsibe to all events: tree_event_service->subscribe( event_handler = me event_type = space event_id = space ).


* subcsibe to specific event type: tree_event_service->subscribe( event_handler = me event_type = 'LINK' event_id = space ).* subcsibe to specific event: tree_event_service->subscribe( event_handler = me event_type = 'LINK' event_id = '<LINK_ID>' ).endif.

Now whenever an event is triggered (link, OCA or button is clicked) the methodIF_CRM_IU_BOL_TREE_EVT_HANDLER~HANDLE_EVENT of your subscribed handler is called.

The method IF_CRM_IU_BOL_TREE_EVT_HANDLER~IS_EVENT_ACTIVE is called for links and for OCAsbefore they are displayed, so you can control whether the actions/ links which are defined in customizingshould be active.

In the method IF_CRM_IU_BOL_TREE_EVT_HANDLER~ADJUST_TOOLBAR_ACTIONS it is possible toadjust the toolbar buttons. It is possible to adjust (remove, sort, deactivate) the tree own buttons (likeposition, next, expand all, collapse all, see 3.2 Tree properties) and it’s possible to define your own buttons:

method if_crm_iu_bol_tree_evt_handler~adjust_toolbar_actions.data: ls_button type crmt_thtmlb_button.

ls_button-id = 'BUTTON_1'. ls_button-text = 'Button 1'. ls_button-tooltip = 'Click Button 1'. ls_button-on_click = 'BUTTON_1'. ls_button-on_client_click = ''. ls_button-enabled = abap_true.

append ls_button to ct_toolbar_actions.

endmethod.

4 Other considerations

5 Conclusion

How_to_use_BOL_Tree

Documents

Transcript of How_to_use_BOL_Tree