adding-dynamic-side-content-to-object-page-sections-8e01a46.md

Adding Dynamic Side Content to Object Page Sections

You can use extension points to add additional content to sections.

Sometimes it might be necessary to add additional information that is not available with annotations to object page sections or subsections.

Caution:

Use app extensions with caution and only if you cannot produce the required behavior by other means, such as manifest settings or annotations. To correctly integrate your app extension coding with SAP Fiori elements, use only the extensionAPI of SAP Fiori elements. For more information, see Using the ExtensionAPI.

After you've created an app extension, its display (for example, control placement and layout) and system behavior (for example, model and binding usage, busy handling) lies within the application's responsibility. SAP Fiori elements provides support only for the official extensionAPI functions. Don't access or manipulate controls, properties, models, or other internal objects created by the SAP Fiori elements framework.

You can add additional content in a flexible manner. When the side content is triggered, the main content is narrowed. The side content always comes from the right side of the app and provides the following features:

• Adding arbitrary sections with an xmlfragment definition

• Adding side content to sections as defined in the manifest for custom sections or facet-based sections

• API for toggling the display of the side content (show/hide)

Using the Side Content

You define the side content in the manifest as follows:

• For custom sections: add "sideContent" with the "template" property pointing towards the content xmlfragment definition

• For facet-based sections: add it in the same manner under subSections > sub-Section-key > sideContent, or under the section where there are no subsections as under Sections > section-key > sideContent

Sample Code:

manifest.json

{
   "sap.ui5": {
      "routing": {
         "targets": {
            "SalesOrderManageObjectPage": {
               "options": {
                  "settings": {
                     "content": {
                        "body": {
                           "sections": {
                              "<section-key>": {
                                 "sideContent": {
                                    "template": "SalesOrder.ext.CustomSideContent"
                                 }
                              },
                              "<section-key>": {
                                 "subSections": {
                                    "<subSection-key>": {
                                       "sideContent": {
                                          "template": "SalesOrder.ext.CustomSideContent",
                                          "equalSplit": true
                                       }
                                    }
                                 }
                              }
                           }
                        }
                     }
                  }
               }
            }
         }
      }
   }
}

Settings for Side Content

You can define your side content by implementing an xmlfragment and using the following properties:

Properties of Side Content

Property Name	Supported Values	Description
template	"<module_path_to_a_fragment>"	Defining the target fragment follows the syntax of defining a fragment through Fragment.load
equalSplit	true | false	Changes the visualization of the side content: instead of being split 1:3 / 1:2, according to responsiveness the side content is split 1:1. For information about the layout API, see the API Reference.

Bold formatting: default/fallback behavior

Toggling Side Content Through the showSideContent API

By default, the side content is not shown. SAP Fiori elements provides an API for the side content that enables you to toggle the side content display (show/hide): this.showSideContent("<SideContent-Key>").

The showSideContent API accepts two parameters:

• "SideContent-Key"

• an optional Boolean value to explicitly define whether to show or hide side content

If no value for the parameter is provided, the API toggles the display.

Sample Code:

manifest.json

{
   "sap.ui5": {
      "routing": {
         "targets": {
            "SalesOrderManageObjectPage": {
               "options": {
                  "settings": {
                     "content": {
                        "controlConfiguration": {
                           "_Item/@com.sap.vocabularies.UI.v1.LineItem": {
                              "actions": {
                                 "CustomActionToggleSideContent": {
                                 "press": "Namespace.ext.CustomSectionSideContent.toggleSideContent",
                                 "text": "Show/Hide Side Content",
                                 "enabled": true,
                                 "visible": true 
                              }
                           }
                        }
                     }
                  }
               }
            }
         }
      }
   }
}

For more information about defining an action, see Adding Custom Actions Using Extension Points.

Sample Code:

webapp/ext/customSectionSideContent.js

sap.ui.define([], function() {
   "use strict";

   return {
      toggleSideContent: function(oBindingContext) {
         this.showSideContent("<SideContent-key>");
      }
   };
});

To explicitly define that you want to display the side content, use this.showSideContent("customerInfo", true).

To explicitly define that you want to hide the side content, use this.showSideContent("customerInfo", false).

For information about the regular Extension API, see the API Reference.

Finding the Right Key for Sections, Subsections, and Side Content

The following table provides an overview of all possible combinations of facet nesting and how to find the right key in each scenario:

Finding the Right Key for Sections, Subsections, and Side Content

Scenario	Level 0	Level 1	Level 2	Section-Key	SubSection-Key	SideContent-Key	How Side Content is Displayed
One level of nesting
1	Reference Facet including form (RF)			RF @ Level 0 (for example: SalesOrderItems)	RF @ Level 0 (for example: SalesOrderItems)	RF @ Level 0 Key (for example: SalesOrderItems)
2	Reference Facet as Table (T)			RF @ Level 0	RF @ Level 0	RF @ Level 0 Key
3	Collection Facet (CF)			CF @ Level 0
3.1		RF			CF @ Level 0	CF @ Level 0 Key
4	CF			CF @ Level 0
4.1		T			CF @ Level 0	RF @ Level 1 Key
5	CF			CF @ Level 0
5.1/2		RF+RF			CF @ Level 0	CF @ Level 0 Key
5.3		T
Two levels of nesting
6	CF			CF @ Level 0
6.1		CF
6.1.1/2			RF+RF		CF @ Level 1	CF @ Level 1 Key
6.2		CF
6.2.1/2			RF+RF		CF @ Level 1	CF @ Level 1 Key
6.2.3			T
7	CF			CF @ Level 0
7.1		T			RF @ Level 1	RF @ Level 1 Key
7.2		CF
7.2.1			RF		CF @ Level 1	CF @ Level 1 Key
8	(CF - ignored)						- not displayed -
8.1		CF		CF @ Level 1
8.1.1			RF		CF @ Level 1	CF @ Level 1 Key

Tip:

Scenario 4.1 differs: while for all other scenarios the SubSection-Key and the SideContent-Key are similar, here they differ.

The Equal Split Functionality

The equalSplit property changes the visualization of the side content. It changes the aspect ratio of the section content in comparison to the side content. The following images show the UI without equal split mode and with equal split mode turned on:

Note:

For information about SAP Fiori elements for OData V2, see Adding Dynamic Side Content to Object Page Sections.