**TITLE**: Tables — configuration and annotation samples for SAP Fiori elements

**INTRODUCTION**: Practical, code-focused reference for configuring table behavior and appearance in SAP Fiori elements apps. Includes actionable steps and exact code snippets for: choosing table types, controlling column visibility (UI.Importance, UI.Hidden), context-menu behavior, copy-to-clipboard, freezing columns, column-width calculation, and tuning data loading (threshold, scrollThreshold) for OData V2 and V4.

**TAGS**: fiori-elements-framework, tables, manifest.json, annotations, UI.Importance, UI.Hidden, threshold, scrollThreshold, copy, frozenColumnCount, responsive-table, grid-table, analytical-table, tree-table, ODataV2, ODataV4

STEP: 1 — Determine default table type (OData V4)
DESCRIPTION: The table type in OData V4 is determined by manifest configuration or by inspecting entity characteristics. Use these rules to decide whether to explicitly set a table type in manifest.json or rely on defaults:
- If the entity set supports analytical usage (@Aggregation.ApplySupported with transformations including filter, identity, orderby, skip, top, groupby, aggregate, concat), default is AnalyticalTable.
- If both @Aggregation.RecursiveHierarchy and @Hierarchy.RecursiveHierarchy with a common RecursiveHierarchy qualifier exist, default is TreeTable.
- Otherwise default is ResponsiveTable.
LANGUAGE: plaintext
CODE:
```plaintext
Default precedence (OData V4):
1. AnalyticalTable if @Aggregation.ApplySupported + transformation functions
2. TreeTable if @Aggregation.RecursiveHierarchy and @Hierarchy.RecursiveHierarchy (same qualifier)
3. ResponsiveTable otherwise
```

STEP: 2 — Configure custom actions and context menu entries (manifest.json)
DESCRIPTION: To expose custom actions in the context menu, define actions under sap.ui.controllerExtensions -> sap.ui.generic.app -> <EntitySet>. Set requiresSelection to true and excludeFromContextMenu false or omitted. To exclude a custom action from the context menu set excludeFromContextMenu to true.
LANGUAGE: JSON
CODE:
```json
"sap.ui.controllerExtensions": {
    "sap.suite.ui.generic.template.ListReport.view.ListReport": {
        "controllerName": "STTA_MP.ext.controller.ListReportExtension",
        "sap.ui.generic.app": {
            "STTA_C_MP_Product": {
                "EntitySet": "STTA_C_MP_Product",
                "Actions": {
                    ...
                    "CopyWithNewSupplier": {
                        "id": "CopyWithNewSupplier",
                        "text": "Copy with new Supplier",
                        "press": "onCopyWithNewSupplier",
                        "excludeFromContextMenu": false,
                        "requiresSelection": true,
                    }
                    ...
                }
            }
        }
    }
}
```

STEP: 3 — Control column visibility by screen size using UI.Importance (XML annotation)
DESCRIPTION: Use UI.Importance to control which columns are visible, pop-in, or hidden when screen width is reduced. Set EnumMember to UI.ImportanceType/High, /Medium, or /Low. High stays visible (may pop-in), Low and Medium/None are hidden progressively.
LANGUAGE: XML
CODE:
```xml
<Annotations Target="STTA_PROD_MAN.STTA_C_MP_ProductSalesPriceType">
    <Annotation Term="UI.LineItem">
        <Collection>
            <Record Type="UI.DataField">
                <PropertyValue Property="Value" Path="PriceDay" />
                <Annotation Term="UI.Importance" EnumMember="UI.ImportanceType/High" />
            </Record>
            <Record Type="UI.DataField">
                <PropertyValue Property="Value" Path="TargetPrice" />
                <!-- This will be treated with default importance "None" which is the same as "Medium" -->
            </Record>
            <Record Type="UI.DataField">
                <PropertyValue Property="Value" Path="DiscountPriceTarget" />
                <Annotation Term="UI.Importance" EnumMember="UI.ImportanceType/Low" />
            </Record>
        </Collection>
    </Annotation>
</Annotations>
```

STEP: 4 — Hide entire columns or fields using UI.Hidden (XML, ABAP CDS, CAP CDS)
DESCRIPTION: - To hide an entire column statically, set UI.Hidden to Bool="true".
- To hide a specific field per row, set UI.Hidden with a Path; fields where the path evaluates to true are hidden. If the path-based UI.Hidden evaluates to true for all rows, only the fields are hidden, not the entire column. Avoid path-based UI.Hidden on groupable/sortable/filterable columns.
LANGUAGE: XML
CODE:
```
<Annotation Term="UI.LineItem">
    <Collection>
        <Record Type="UI.DataFieldForAnnotation">
            <PropertyValue Property="Target" AnnotationPath="@UI.FieldGroup#multipleActionFields" />
            <PropertyValue Property="Label" String="Sold-To Party" />
            <Annotation Term="UI.Hidden" Path="Delivered" />
        </Record>
    </Collection>
</Annotation>
```

LANGUAGE: ABAP CDS
CODE:
```
@UI.lineItem: [{
    type: #AS_FIELDGROUP,
    valueQualifier: 'multipleActionFields',
    label: 'Sold-To Party',
    hidden: #( 'Delivered' )
}]
TEST;
```

LANGUAGE: CAP CDS
CODE:
```
LineItem: {
    $value: [
        {
            $Type: 'UI.DataFieldForAnnotation',
            Target: '@UI.FieldGroup#multipleActionFields',
            Label: 'Sold-To Party',
            ![@UI.Hidden]: Delivered
        }
    ]
}
```

STEP: 5 — Show/hide Copy to Clipboard button (manifest.json, multiple targets)
DESCRIPTION: Configure the copy button visibility per table with tableSettings.copy in the List Report, Analytical List Page, or at section level in the Object Page. Table-level or section-level copy settings override broader settings; section-level has higher priority than object-page-level.
LANGUAGE: JSON
CODE:
```json
"sap.ui.generic.app": {
    "pages": {
        "ListReport|<EntitySetName>": {
            "entitySet": "<EntitySetName>",
            "component": {
                "name": "sap.suite.ui.generic.template.ListReport",
                "settings": {
                    "tableSettings": {
                        "copy": false
                    }
                }
            }
        }
    }
}
```

LANGUAGE: JSON
CODE:
```json
"sap.ui.generic.app": {
    "pages": {
        "ListReport|<EntitySetName>": {
            "entitySet": "<EntitySetName>",
            "component": {
                "name": "sap.suite.ui.generic.template.AnalyticalListPage",
                "settings": {
                    "tableSettings": {
                        "copy": true
                    }
                }
            }
        }
    }
}
```

LANGUAGE: JSON
CODE:
```json
"sap.ui.generic.app": {
    "pages": {
        "ListReport|<EntitySetName>": {
            ...
            ...
            "pages": {
                "ObjectPage|<EntitySetName>": {
                    "entitySet": "<EntitySetName>",
                    "component": {
                        "name": "sap.suite.ui.generic.template.ObjectPage",
                        "settings": {
                            "sections": {
                                "SalesOrderItemsID": {
                                    "navigationProperty": "<NavigationProperty>",
                                    "entitySet": "<NavigationEntitySetName>",
                                    "tableSettings": {
                                        "copy": true
                                    }
                                }
                            },
                            "tableSettings": {
                                "copy": false
                            }
                        }
                    }
                }
            }
        }
    }
}
```

STEP: 6 — Configure threshold (initial preload) — OData V2 (manifest.json, List Report / Object Page / Analytical List Page)
DESCRIPTION: Set tableSettings.threshold in the component settings to add N preloaded rows in addition to the visible rows. Example values override defaults. If threshold is 0, no preloading occurs and scrollThreshold is used instead.
LANGUAGE: JSON
CODE:
```
"component": {
    "name": "sap.suite.ui.generic.template.ListReport",
    "list": true,
    "settings": {
        "gridTable": true,
        "tableSettings": {
            "threshold": 400
        }
    }
}
```

LANGUAGE: JSON
CODE:
```
"component": {
    "name": "sap.suite.ui.generic.template.ObjectPage",
    "settings": {
        "showRelatedApps": true,
        "gridTable": true,
        "editableHeaderContent": true,

        "tableSettings": {
            "threshold": 400
        }
    }
}
```

LANGUAGE: JSON
CODE:
```
"component": {
    "name": "sap.suite.ui.generic.template.AnalyticalListPage",
    "list": true,
    "settings": {
        "tableSettings": {
            "type": "AnalyticalTable",
            "multiSelect": true,
            "selectAll": false,
            "selectionLimit": 10,
            "threshold": 400
        }
    }
}
```

STEP: 7 — Configure scrollThreshold (dynamic loading) — OData V2 (manifest.json)
DESCRIPTION: Configure tableSettings.scrollThreshold to control how many records are loaded when scrolling (default 300). For analytical and tree tables, ensure scrollThreshold > threshold to take effect.
LANGUAGE: JSON
CODE:
```
"component": {
    "name": "sap.suite.ui.generic.template.ListReport",
    "list": true,
    "settings": {
        "gridTable": true,
        "tableSettings": {
            "scrollThreshold": 600
        }
    }
}
```

LANGUAGE: JSON
CODE:
```
"component": {
    "name": "sap.suite.ui.generic.template.ObjectPage",
    "settings": {
        "showRelatedApps": true,
        "gridTable": true,
        "editableHeaderContent": true,

        "tableSettings": {
            "scrollThreshold": 600
        }
    }
}
```

LANGUAGE: JSON
CODE:
```
"component": {
    "name": "sap.suite.ui.generic.template.AnalyticalListPage",
    "list": true,
    "settings": {
        "tableSettings": {
            "type": "AnalyticalTable",
            "multiSelect": true,
            "selectAll": false,
            "selectionLimit": 10,
            "scrollThreshold": 600
        }
    }
}
```

STEP: 8 — Configure threshold and scrollThreshold — OData V4 (manifest.json examples)
DESCRIPTION: OData V4 uses manifest target/component options or controlConfiguration to set threshold/scrollThreshold. The sample below shows setting type and threshold for a target. Use controlConfiguration to scope to @com.sap.vocabularies.UI.v1.LineItem.
LANGUAGE: JSON
CODE:
```
"targets": {
                "SalesOrderManageList": {
                    "type": "Component",
                    "id": "SalesOrderManageList",
                    "name": "sap.fe.templates.ListReport",
                    "options": {
                        "settings": {
                            "contextPath": "/SalesOrderManage",
                            "controlConfiguration": {
                                "@com.sap.vocabularies.UI.v1.LineItem": {
                                    "tableSettings": {
                                        "type": "ResponsiveTable",
                                        "threshold": 100
                                    }
                                }
                            }
                        }
                    }
                }
            }
```

LANGUAGE: JSON
CODE:
```
"sap.ui5": {
    "routing": {
        "targets": {
            "SalesOrderManageList": {
                "options": {
                    "settings": {
                        "controlConfiguration": {
                            "@com.sap.vocabularies.UI.v1.LineItem": {
                                "tableSettings": {
                                    "type": "GridTable",
                                    "scrollThreshold": 200
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```

STEP: 9 — Freeze columns and disable freezing (manifest.json)
DESCRIPTION: Use frozenColumnCount to freeze a fixed number of first columns (not available for responsive tables). Use disableColumnFreeze to remove the *Column Settings* freezing option.
LANGUAGE: JSON
CODE:
```json
"_Item/@com.sap.vocabularies.UI.v1.LineItem": {
    "tableSettings": {
        "type": "GridTable",
        "frozenColumnCount": 3,
        …
    },
    …
}
```

LANGUAGE: JSON
CODE:
```json
"_Item/@com.sap.vocabularies.UI.v1.LineItem": {
     "tableSettings": {
          "type": "GridTable",
          "disableColumnFreeze": true,
          …
     },
     ...
}
```

STEP: 10 — Include column header when auto-calculating column width (manifest.json)
DESCRIPTION: Set widthIncludingColumnHeader at table level (controlConfiguration) or override at column level under columns definition. Column-level setting has higher priority.
LANGUAGE: JSON
CODE:
```json
"controlConfiguration": {
    "@com.sap.vocabularies.UI.v1.LineItem": {
        "tableSettings": {
            "widthIncludingColumnHeader": true
        },
        "columns": {
            "DataField::commonProperty": {
                "widthIncludingColumnHeader": false
            }
        }
    }
}
```

STEP: 11 — Disable copy-to-clipboard in OData V4 (manifest.json)
DESCRIPTION: Use disableCopyToClipboard under controlConfiguration -> @com.sap.vocabularies.UI.v1.LineItem -> tableSettings to hide the Copy to Clipboard button for responsive and grid tables in OData V4 apps.
LANGUAGE: JSON
CODE:
```
"sap.ui5": {
    "routing": {
        "targets": {
            "SalesOrderManageList": {
                "options": {
                    "settings": {
                        "controlConfiguration": {
                            "@com.sap.vocabularies.UI.v1.LineItem": {
                                "tableSettings": {
                                    "disableCopyToClipboard": true
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```

STEP: 12 — SearchRestrictions: define whether an entity is searchable (XML & CAP CDS)
DESCRIPTION: Use Capabilities.NavigationRestrictions on the parent entity to restrict Searchable for a navigation property (non-containment and containment scenarios). If not present at the parent, define SAP__capabilities.SearchRestrictions directly on the child entity set. For analytical or tree tables, search is enabled if the search transformation is present in @Aggregation.ApplySupported or if no Transformations are defined.
LANGUAGE: XML
CODE:
```xml
<Annotations Target="com.c_salesordermanage_sd.Container/SalesOrderManage">
    <Annotation Term="Capabilities.NavigationRestrictions">
        <Record>
            <PropertyValue Property="RestrictedProperties">
                <Collection>
                    <Record>
                        <PropertyValue Property="NavigationProperty" NavigationPropertyPath="_Items" />
                        <PropertyValue Property="SearchRestrictions">
                            <Record>
                                <PropertyValue Property="Searchable" Bool="false" />
                            </Record>
                        </PropertyValue>
                    </Record>
                </Collection>
            </PropertyValue>
        </Record>
    </Annotation>
</Annotations>
```

LANGUAGE: CAP CDS
CODE:
```
entity SalesOrderManage
    @(Capabilities: {
        NavigationRestrictions: {
            RestrictedProperties: [{
                NavigationProperty: '_Items',
                SearchRestrictions: {
                    Searchable: false
                }
            }]
        }
    })
```

LANGUAGE: XML
CODE:
```xml
<Annotations Target="com.c_salesordermanage_sd.Container/SalesOrderItem">
    <Annotation Term="SAP__capabilities.SearchRestrictions">
        <Record>
            <PropertyValue Property="Searchable" Bool="false" />
        </Record>
    </Annotation>
</Annotations>
```

LANGUAGE: CAP CDS
CODE:
```
entity SalesOrderItem
    @(Capabilities: {
        SearchRestrictions: {
            Searchable: false
        }
    })
```

LANGUAGE: XML
CODE:
```xml
<Annotation Term="SAP__aggregation.ApplySupported">
    <Record>
        <PropertyValue Property="Transformations">
            <Collection>
                <String>filter</String>
                <String>orderby</String>
                <String>search</String>
                <String>descendants</String>
            </Collection>
        </PropertyValue>
    </Record>
</Annotation>
```

STEP: 13 — Notes and usage tips (short actionable reminders)
DESCRIPTION: - Default row selection mode is single-selection; change selection mode via selection configuration (see related docs).
- Use extensionAPI.getSelectedContexts to get selected rows for context menu actions — call it only from synchronous code blocks.
- Responsive tables are for small item sets (<= 200). Use GridTable/Tree/Analytical for large sets.
- For responsive tables, UI.Importance controls pop-in/hide behavior. Columns with semantic keys and no importance are treated as High.
LANGUAGE: plaintext
CODE:
```plaintext
Key reminders:
- Default selection: single-selection; switch to multi-selection if needed.
- Use extensionAPI.getSelectedContexts only synchronously.
- Responsive table restriction: total items <= 200.
- Columns without importance but containing a semantic key are considered High importance.
```

fiori-elements-framework tables manifest.json annotations UI.Importance UI.Hidden threshold scrollThreshold copy frozenColumnCount responsive-table grid-table analytical-table tree-table ODataV2 ODataV4


**TITLE**: Chart Building Block — Instantiation, Personalization, and API Usage

**INTRODUCTION**: Practical, code-focused reference for instantiating and integrating the sap.fe.macros.Chart building block. Includes the required backend aggregation note, the sample XML macro, personalization configuration, linking with a FilterBar, handling selection events, and examples of using public APIs to get/set presentation and selection variants.

**TAGS**: fiori-elements-framework, chart, macros, UI5, personalization, aggregation, variant-management, filterbar, API

**STEP**: 1 — Ensure backend aggregation is enabled

**DESCRIPTION**: Charts require the referenced entity set to support aggregation on the backend. Confirm aggregation is enabled before instantiating the Chart building block. See the Configuring Charts subsection for backend configuration details.

- Reference: Enabling Aggregation in the Back End
- File path / anchor: configuring-charts-653ed0f.md#loio653ed0f4f0d743dbb33ace4f68886c4e__enabling_aggregation_subsection

**LANGUAGE**: Documentation

**CODE**:
```text
See: configuring-charts-653ed0f.md#loio653ed0f4f0d743dbb33ace4f68886c4e__enabling_aggregation_subsection
```

**STEP**: 2 — Instantiate the Chart macro (basic XML example)

**DESCRIPTION**: Use the macros:Chart XML macro to create a chart bound to an entity set or navigation property. The sample below demonstrates common properties: id, contextPath, metaPath, event handler for selections, personalization settings, and selectionMode.

- Note: contextPath is optional if metaPath is an absolute path. If metaPath is relative and contextPath is omitted, the parent binding path is used as contextPath.

**LANGUAGE**: XML

**CODE**:
```xml
<macros:Chart
    id="chartDefault"
    contextPath="/RootEntitySet"
    metaPath="@com.sap.vocabularies.UI.v1.Chart"
    dataPointsSelected=".onChartSelectionChanged"
    personalization="Sort,Type,Item"
    selectionMode="Multiple"
></macros:Chart>
```

**STEP**: 3 — Configure personalization and visible tabs

**DESCRIPTION**: Configure which personalization tabs appear using the personalization property. Example value: "Sort,Type,Item" shows only the Sort, Type and Item tabs. Enable chart personalization to use getSelectionVariant/setSelectionVariant (see Step 5). Variant management can be enabled via the page/manifest variant configuration and chart-specific personalization properties.

**LANGUAGE**: XML

**CODE**:
```xml
<!-- personalization controls which tabs are available in the chart personalization dialog -->
<macros:Chart
    id="chartDefault"
    personalization="Sort,Type,Item"
    selectionMode="Multiple"
    metaPath="@com.sap.vocabularies.UI.v1.Chart"
    contextPath="/RootEntitySet"
/>
```

**STEP**: 4 — Handle chart selection events (JavaScript controller)

**DESCRIPTION**: Attach a handler to the dataPointsSelected event in the macro (dataPointsSelected=".onChartSelectionChanged"). In the controller, implement onChartSelectionChanged to read selected data points from the event and act on them (e.g., update other controls, call oData operations, or synchronize with a FilterBar).

**LANGUAGE**: JavaScript

**CODE**:
```javascript
onChartSelectionChanged: function (oEvent) {
    // Example event parameters depend on the macro implementation; commonly include selected data points
    const aSelectedDataPoints = oEvent.getParameter("dataPoints") || [];
    // Process selected data points
    // Example: extract keys or dimensions for downstream filtering
    const aKeys = aSelectedDataPoints.map(dp => dp.key);
    // Use or pass selection to other components
    // e.g., update a FilterBar or set selection variant on a chart/table
    // this.byId("filterBar").setSelectionVariant(oSelectionVariant);
}
```

**STEP**: 5 — Link Chart with a FilterBar (example pattern)

**DESCRIPTION**: Typical integration is to read a SelectionVariant from the FilterBar and apply it to the Chart or vice versa. The chart exposes getSelectionVariant()/setSelectionVariant() for this purpose. Ensure chart personalization is enabled if you plan to use the selection-variant APIs (see Step 6 note).

**LANGUAGE**: JavaScript

**CODE**:
```javascript
// Example: apply the current FilterBar selection to the chart
const oFilterBar = this.byId("filterBar"); // your FilterBar control id
const oChart = this.byId("chartDefault");  // chart macro id

// Read selection variant from the FilterBar (implementation depends on your FilterBar API)
const oSelectionVariantFromFilterBar = oFilterBar && oFilterBar.getSelectionVariant
    ? oFilterBar.getSelectionVariant()
    : null;

if (oSelectionVariantFromFilterBar && oChart && oChart.setSelectionVariant) {
    oChart.setSelectionVariant(oSelectionVariantFromFilterBar);
}
```

**STEP**: 6 — Use Chart public APIs: get/set PresentationVariant and SelectionVariant

**DESCRIPTION**: The Chart building block exposes public APIs to read and apply PresentationVariant and SelectionVariant objects for programmatic control and integration with variant management. Use getPresentationVariant()/setPresentationVariant() and getSelectionVariant()/setSelectionVariant().

- Note: getSelectionVariant()/setSelectionVariant() consider only variants applied directly to the chart and exclude those applied to a bound model.
- Note: The get/set selection variant methods only work if chart personalization is enabled. See enabling-table-personalization-3e2b4d2.md for personalization prerequisites.

**LANGUAGE**: JavaScript

**CODE**:
```javascript
const oChart = this.byId("chartDefault");

// Get current presentation variant
if (oChart && oChart.getPresentationVariant) {
    const oPresentationVariant = oChart.getPresentationVariant();
    // inspect or store oPresentationVariant
}

// Set a presentation variant (object shape per OData presentation variant)
if (oChart && oChart.setPresentationVariant) {
    // oNewPresentationVariant must conform to the presentation variant structure
    oChart.setPresentationVariant(oNewPresentationVariant);
}

// Get current selection variant (only works when personalization is enabled)
if (oChart && oChart.getSelectionVariant) {
    const oSelectionVariant = oChart.getSelectionVariant();
    // use or store selection variant
}

// Apply a selection variant to the chart
if (oChart && oChart.setSelectionVariant) {
    // oNewSelectionVariant must conform to the selection variant structure
    oChart.setSelectionVariant(oNewSelectionVariant);
}
```

**STEP**: 7 — Get and set the currently visible variant ID (pattern)

**DESCRIPTION**: You can programmatically read or set the currently visible variant (variant management). The exact API names should be verified in the Chart API Reference linked below; use the chart control instance to call the appropriate get/set variant ID methods.

**LANGUAGE**: JavaScript

**CODE**:
```javascript
const oChart = this.byId("chartDefault");

// Example pattern (confirm exact method names in the API Reference)
if (oChart) {
    // Read current visible variant ID
    if (oChart.getVisibleVariantId) {
        const sCurrentVariantId = oChart.getVisibleVariantId();
    }

    // Set the visible variant by ID
    if (oChart.setVisibleVariantId) {
        oChart.setVisibleVariantId("myVariantId");
    }
}
```

**STEP**: 8 — Add custom actions and custom header configuration

**DESCRIPTION**: Add custom actions (toolbar buttons, contextual actions) using your app extensions. Use the chart macro’s extension points or the page/header aggregations to add buttons; attach event handlers in the controller to call chart APIs or perform actions based on current selection. Configure chart title and header visibility via macro properties or host page header configuration.

**LANGUAGE**: XML / JavaScript

**CODE**:
```xml
<!-- Example: set a title and hide the standard header (property names may vary; verify in API) -->
<macros:Chart
    id="chartDefault"
    title="Sales Chart"
    headerVisible="true"
    contextPath="/RootEntitySet"
    metaPath="@com.sap.vocabularies.UI.v1.Chart"
    personalization="Sort,Type,Item"
/>
```

```javascript
// Example: custom action handler attached to a custom button
onCustomChartAction: function () {
    const oChart = this.byId("chartDefault");
    const oPV = oChart && oChart.getPresentationVariant && oChart.getPresentationVariant();
    // perform custom behavior based on current presentation/selection
}
```

**STEP**: 9 — Live examples and API reference

**DESCRIPTION**: Check the SAP Fiori development portal and API Reference for live examples, control properties, event parameter shapes, and the exact method names for variant id manipulation.

**LANGUAGE**: Documentation / Links

**CODE**:
```text
Live examples:
- Building Blocks - Chart (explorer): https://ui5.sap.com/test-resources/sap/fe/core/fpmExplorer/index.html#/buildingBlocks/chart/chartDefault
- Building Blocks - Chart - Extensions - Chart APIs: https://ui5.sap.com/test-resources/sap/fe/core/fpmExplorer/index.html#/buildingBlocks/chart/chartPublicAPIs

API Reference:
- Chart API: https://ui5.sap.com/#/api/sap.fe.macros.Chart

Personalization prerequisite reference:
- Enabling Table Personalization: enabling-table-personalization-3e2b4d2.md
```

**STEP**: 10 — Important notes and behaviors

**DESCRIPTION**: Consolidated technical points to preserve:

- contextPath is optional when metaPath is absolute; if metaPath is relative and no contextPath is provided, the parent binding path is used as contextPath.
- Chart requires backend aggregation support for the referenced entity set.
- getSelectionVariant()/setSelectionVariant() only work if chart personalization is enabled and only consider variants applied directly to the chart (not bound models).
- Use the API Reference to confirm exact method names for getting/setting the visible variant ID and other control-specific methods.

**LANGUAGE**: Documentation

**CODE**:
```text
Notes:
- contextPath behavior: optional with absolute metaPath; fallback to parent binding path if metaPath is relative and contextPath is absent.
- Backend aggregation required: configuring-charts-653ed0f.md#loio653ed0f4f0d743dbb33ace4f68886c4e__enabling_aggregation_subsection
- Selection variant APIs require personalization: enabling-table-personalization-3e2b4d2.md
- API Reference for exact method signatures: https://ui5.sap.com/#/api/sap.fe.macros.Chart
```

fiori-elements-framework chart macros UI5 personalization aggregation variant-management filterbar API


**TITLE**: ConditionalSwitch Building Block — Use in Tables/Forms with a Factory Function

**INTRODUCTION**: Use sap.fe.macros.ConditionalSwitch to render different UI controls per row or context at runtime. Bind a set of watched properties in the XML macro and supply a lightweight factory function in the controller that returns a control (or oldControl) based on those property values and optional row context.

**TAGS**: fiori-elements, ui5, sap.fe.macros, ConditionalSwitch, table, form, factory, XML, JavaScript

**STEP**: 1 — Add ConditionalSwitch to a Table Column (XML)

**DESCRIPTION**: Insert the ConditionalSwitch building block in a table column. Provide ConditionalSwitchProperty elements for each property the factory should watch. Keep metaPath and column configuration as needed for your ListReport/ObjectPage scenario.

**LANGUAGE**: XML

**CODE**:
```xml

<macros:Table metaPath="/Products/@com.sap.vocabularies.UI.v1.LineItem">
    <macros:columns>
        <macros:Column key="My ComplexColumn" width="20rem">
            <macros:ConditionalSwitch factory=".myColumnFactory">
                <fe:ConditionalSwitchProperty key="travelID" value="{TravelID}" />
                <fe:ConditionalSwitchProperty key="price" value="{TotalPrice}" />
            </macros:ConditionalSwitch>
        </macros:Column>
    </macros:columns>
 </macros:Table>

```

**STEP**: 2 — Implement the Factory Function in the Controller (original sample)

**DESCRIPTION**: The factory receives three parameters: properties (the watched property values mapped by key), context (in table scenarios the binding context for the current row), and oldControl (the previously created control instance). Returning oldControl avoids recreating controls. This original example is preserved as-is.

**LANGUAGE**: JavaScript

**CODE**:
```javascript
 // In the controller
 myColumnFactory: function (properties, context, oldControl) {
    if (properties.travelID) {
        if (oProps.price > 1000) {
            return new ObjectStatus({ text: "Expensive!", state:"Warning" });
        }
		else {
            return new Button({ text: "Increase Price !" });
        }
    }
 }

```

**STEP**: 3 — Recommended: Lightweight, robust factory pattern (optimized example)

**DESCRIPTION**: Use a lightweight factory that:
- References properties by the provided keys (properties.price, properties.travelID).
- Uses context.getObject() or context.getProperty(...) to access additional row fields if required.
- Reuses oldControl when appropriate to avoid recreation.
- Minimizes logic and avoids expensive operations because this function runs frequently (scrolling in grids/trees triggers it).

Replace or adapt the names (e.g., TotalPrice, TravelID) to match your property keys.

**LANGUAGE**: JavaScript

**CODE**:
```javascript
// In the controller — recommended optimized implementation
myColumnFactory: function (properties, context, oldControl) {
    // Return old control when possible to avoid recreation
    if (oldControl) {
        // Optionally update existing control properties based on new values
        if (properties.price && oldControl.setText) {
            oldControl.setText(properties.price > 1000 ? "Expensive!" : "Increase Price !");
            if (oldControl.setState) {
                oldControl.setState(properties.price > 1000 ? "Warning" : "None");
            }
        }
        return oldControl;
    }

    // Create control based on watched properties
    if (properties && properties.travelID) {
        if (properties.price && properties.price > 1000) {
            return new sap.m.ObjectStatus({ text: "Expensive!", state: "Warning" });
        } else {
            return new sap.m.Button({ text: "Increase Price !" });
        }
    }

    // Fallback: return a lightweight placeholder or null
    return null;
}
```

**STEP**: 4 — Access row data from context (example)

**DESCRIPTION**: In table scenarios, use the context parameter to access additional fields beyond the watched properties. Use context.getObject() or context.getProperty("PropertyName").

**LANGUAGE**: JavaScript

**CODE**:
```javascript
// Example using context to read other fields in the row
myColumnFactory: function (properties, context, oldControl) {
    var rowData = context && context.getObject ? context.getObject() : null;
    var category = rowData ? rowData.Category : null;

    if (category === "Special") {
        return new sap.m.Label({ text: "Special Category" });
    }

    // Fallback logic...
    return null;
}
```

**STEP**: 5 — Performance tips and constraints

**DESCRIPTION**: Keep the factory function minimal:
- Avoid synchronous XHR, heavy computations, or DOM queries.
- Prefer updating and returning oldControl instead of creating new controls.
- Cache lightweight objects if necessary.
- Remember that for grid/tree/analytical tables the factory runs frequently during scrolling.

**LANGUAGE**: N/A

**CODE**:
```text
// Guidance summary (no code):
- Use properties.<key> for watched values.
- Use context.getObject()/getProperty() for row-specific data.
- Return oldControl to reuse UI elements.
- Keep logic simple and performant.
```

**STEP**: 6 — API reference

**DESCRIPTION**: Consult the official API for sap.fe.macros.ConditionalSwitch for full property and aggregation details.

**LANGUAGE**: N/A

**CODE**:
```text
https://ui5.sap.com/#/api/sap.fe.macros.ConditionalSwitch
```

fiori-elements ui5 sap.fe.macros ConditionalSwitch table form factory XML JavaScript


**TITLE**: Field Building Block — Instantiation, Configuration, and Examples

**INTRODUCTION**: Practical, code-focused guide for using the sap.fe.macros Field building block. Shows how to instantiate Fields in XML fragments and programmatically, configure behavior via manifest.json and formatOptions, and common examples (time, currency, radio buttons, JSON-binding). Use these snippets directly in fragments, controllers, or manifest files.

**TAGS**: fiori-elements-framework, Field, sap.fe.macros, manifest.json, formatOptions, XML, JavaScript, JSON, controlConfiguration, valueHelp

STEP: 1 — Basic instantiation in an XML fragment

DESCRIPTION: Use the Field building block in an XML fragment by referencing the building block namespace. This instantiates the control tree corresponding to the metadata property specified by metaPath.

LANGUAGE: XML

CODE:
```xml
<macros:Field xmlns:macro="sap.fe.macros" metaPath="MyProperty"/>
```

STEP: 2 — Create a Field programmatically inside a controller (runtime/dynamic creation)

DESCRIPTION: Instantiate Field at runtime, apply format options, add it to a Dialog, bind the dialog to an entity, and open. Use this pattern for dynamic UI creation or when needing programmatic control.

LANGUAGE: JavaScript

CODE:
```javascript
createField: function () {
    const maxLength = new FormatOptions({ textMaxLength: 10 });
    const field = new Field({ metaPath: "/Entities/singleLine", formatOptions: maxLength });

    const newDialog = new Dialog({
        title: "Dialog",
        content: [
            new Label({
                text: "My field",
                labelFor: field
            }),
            field,
        ],
        beginButton: new Button({
            text: "OK",
            press: function () {
                newDialog.close();
            }
        }),
        endButton: new Button({
            text: "Cancel",
            press: function () {
                newDialog.close();
            }
        })
    });
    newDialog.addStyleClass("sapUiContentPadding");
    newDialog.bindElement("/Entities(1)");
    this.getExtensionAPI().addDependent(newDialog);
    newDialog.open();
}
```

STEP: 3 — Configure Field via manifest.json (controlConfiguration, readOnly, semanticObject, formatOptions)

DESCRIPTION: Configure Field defaults and options per FieldGroup qualifier using controlConfiguration in the route target options. Supported settings: readOnly, semanticObject, and formatOptions parameters (textLinesEdit, textMaxLines, textMaxCharactersDisplay, textExpandBehaviorDisplay, textMaxLength). Restriction: readOnly and semanticObject apply only when the Field is used inside a field group in a standard UI, or inside a Form with an assigned field group for custom sections/pages.

LANGUAGE: JSON

CODE:
```json
"sap.ui5": {
    "routing": {
        "targets": {
            "SalesOrderManageObjectPage": {
                "options": {
                    "settings": {
                        "controlConfiguration": {
                            "@com.sap.vocabularies.UI.v1.FieldGroup#myQualifier": {
                                "fields": {
                                    "DataField::myFormTextField": {
                                        "readOnly": true
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```

STEP: 4 — Time data element: Field in custom section fragment (renders time picker in edit mode)

DESCRIPTION: Use Field for a Time-typed data element. Place Field in a fragment; it automatically renders an input with time picker in edit mode.

LANGUAGE: XML

CODE:
```xml
<core:FragmentDefinition
	xmlns="sap.m"
	xmlns:core="sap.ui.core"
	xmlns:macro="sap.fe.macros"
>
	<VBox width="30vw">
		<Text text="Time Data Field: " />
		<macro:Field metaPath="timeData" id="timeDataField" />
	</VBox>
</core:FragmentDefinition>
```

STEP: 5 — Numeric field with Currency: basic fragment (renders value and currency input controls)

DESCRIPTION: Use Field for a numeric value with currency (CDS Currency type). Field auto-generates numeric input and currency selection in edit mode.

LANGUAGE: XML

CODE:
```xml
<core:FragmentDefinition
	xmlns="sap.m"
	xmlns:core="sap.ui.core"
	xmlns:macro="sap.fe.macros"
>
	<VBox width="30vw">
		<Text text="Numeric Field with Currency: " />
		<macro:Field metaPath="numberWithCurrency" id="numberWithCurrencyField" />
	</VBox>
</core:FragmentDefinition>
```

STEP: 6 — Currency field: use formatOptions.measureDisplayMode to change currency input behavior

DESCRIPTION: Use formatOptions with measureDisplayMode to set the currency input to editable, read-only, or hidden. Place formatOptions as a child of Field in the fragment.

LANGUAGE: XML

CODE:
```xml
<core:FragmentDefinition
	xmlns="sap.m"
	xmlns:core="sap.ui.core"
	xmlns:macro="sap.fe.macros"
>
	<VBox width="30vw">
		<Text text="Numeric Field with Currency - no format Option: " />
		<macro:Field metaPath="numberWithCurrency" id="numberWithCurrencyField" />
		<Text text="Numeric Field with Currency - measureDisplayMode=ReadOnly: " />
		<macro:Field metaPath="numberWithCurrency" id="numberWithCurrencyFieldCurrencyReadOnly">
			<formatOptions measureDisplayMode="ReadOnly" />
		</macro:Field>
		<Text text="Numeric Field with Currency - measureDisplayMode=Hidden: " />
		<macro:Field metaPath="numberWithCurrency" id="numberWithCurrencyFieldCurrencyHidden">
			<formatOptions measureDisplayMode="Hidden" />
		</macro:Field>
	</VBox>
</core:FragmentDefinition>
```

STEP: 7 — Currency display modes: displayMode affects Value/Description presentation

DESCRIPTION: Use formatOptions.displayMode to control whether the currency field displays value and description as "ValueDescription" or "DescriptionValue".

LANGUAGE: XML

CODE:
```xml
<core:FragmentDefinition
	xmlns="sap.m"
	xmlns:core="sap.ui.core"
	xmlns:macro="sap.fe.macros"
>
	<VBox width="30vw">
		<Text text="Currency Field - displayMode=ValueDescription: " />
		<macro:Field metaPath="currencyField_code" id="currencyFieldValueDescription">
			<formatOptions displayMode="ValueDescription" />
		</macro:Field>
		<Text text="Currency Field - displayMode=DescriptionValue: " />
		<macro:Field metaPath="currencyField_code" id="currencyFieldDescriptionValue">
			<formatOptions displayMode="DescriptionValue" />
		</macro:Field>
	</VBox>
</core:FragmentDefinition>
```

STEP: 8 — Render Field as radio button group for fixed value lists (useRadioButtons + horizontal layout)

DESCRIPTION: For value lists with fixed values, set formatOptions useRadioButtons="true" to render a radio button group. By default layout is vertical. To render horizontally, set radioButtonsHorizontalLayout="true" (can be applied in the Field formatOptions or configured via manifest setting where supported).

LANGUAGE: XML

CODE:
```xml
<Text text="Field with fixed value list as radio buttons: " />
<macros:Field metaPath="FieldWithFixedValueList " id="FieldWithFixedValueListRadioButtonsHorizontal">
		<formatOptions useRadioButtons="true"
		radioButtonsHorizontalLayout="true" />
</macros:Field>
```

STEP: 9 — Bind Field to a JSON model value (and optional description)

DESCRIPTION: Use value to bind Field to any model (e.g., JSON model). Use description together with value to bind the description shown by value help. Supported for text, date/time picker, value help, and object status. Not supported for editing rating indicator fields.

LANGUAGE: XML

CODE:
```xml
<macros:Field
    id="myCustomField"
    metaPath="/RootEntity/name"
    value="{myJSONModel>/customModelBindingPath}"
/>
```

STEP: 10 — Bind Field to JSON model value + description

DESCRIPTION: Bind both value and description properties to a JSON model to show associated description with the selected value.

LANGUAGE: XML

CODE:
```xml
<macros:Field
    id="myCustomField"
    metaPath="/RootEntity/name"
    value="{myJSONModel>/customModelBindingPath}"
    description="{myJSONModel>/customModelDescriptionBindingPath}"
/>
```

STEP: 11 — API Reference

DESCRIPTION: Use the official API reference for details on properties, events, methods, and allowed formatOptions: sap.fe.macros.Field API documentation.

LANGUAGE: URL/Reference

CODE:
```text
https://ui5.sap.com/#/api/sap.fe.macros.Field
```

fiori-elements-framework Field sap.fe.macros manifest.json formatOptions XML JavaScript JSON controlConfiguration valueHelp


**TITLE**: FilterBar Building Block — Usage and APIs

**INTRODUCTION**: Practical, code-focused reference for embedding and controlling the sap.fe.macros.FilterBar building block in Fiori Elements apps. Includes XML usage snippets, programmatic control (triggerSearch, SelectionVariant APIs), and personalization behavior controls.

**TAGS**: FilterBar, Fiori Elements, SAPUI5, macros, SelectionVariant, personalization, triggerSearch

STEP: 1 — Embed FilterBar in XML view

DESCRIPTION: Add a FilterBar building block to an XML fragment or view. Use metaPath to reference selection fields, wire up event handlers (search, filtersChanged), and set an ID for programmatic access.

LANGUAGE: XML

CODE:
```xml
<macros:FilterBar
    metaPath="@com.sap.vocabularies.UI.v1.SelectionFields#SF1"
    id="FilterBar"
    search=".handlers.onSearch"
    filtersChanged=".handlers.onFiltersChanged"
/>
```

STEP: 2 — Trigger filter search programmatically

DESCRIPTION: Call triggerSearch() on the FilterBar control to validate mandatory fields and run the filter bar "Go" action. Behavior: validates mandatory fields; only triggers search if all mandatory fields have valid values; if not filled, focus is set to the first mandatory field that isn't filled (no highlight or error messages are shown).

LANGUAGE: JavaScript

CODE:
```javascript
// Get the FilterBar control by ID and trigger search
const filterBar = this.byId("FilterBar"); // from controller context
if (filterBar && typeof filterBar.triggerSearch === "function") {
  // triggerSearch() returns a Promise in the control API
  filterBar.triggerSearch().then(() => {
    // search triggered successfully
  }).catch((err) => {
    // triggered validation prevented search (mandatory fields missing)
    // or handle unexpected errors
    console.error(err);
  });
}
```

STEP: 3 — Use SelectionVariant APIs (get/set)

DESCRIPTION: Use getSelectionVariant and setSelectionVariant to read and write filter state in SelectionVariant format. Note: custom filters are NOT included in these APIs.

LANGUAGE: JavaScript

CODE:
```javascript
// Example: read SelectionVariant from FilterBar
const filterBar = this.byId("FilterBar");
if (filterBar && typeof filterBar.getSelectionVariant === "function") {
  // async/await style
  (async () => {
    const selectionVariant = await filterBar.getSelectionVariant();
    // selectionVariant: SelectionVariant object representing standard filter fields
    console.log(selectionVariant);
  })();
}

// Example: set SelectionVariant on FilterBar
if (filterBar && typeof filterBar.setSelectionVariant === "function") {
  const selectionVariant = {
    // Construct SelectionVariant object per OData V4 format expected by the control
    // Example placeholder; construct actual SelectionVariant per your app
    Parameters: [],
    SelectOptions: []
  };
  (async () => {
    await filterBar.setSelectionVariant(selectionVariant);
    // FilterBar updated with provided SelectionVariant (custom filters not included)
  })();
}
```

STEP: 4 — Ignore personalization changes (transient filter state)

DESCRIPTION: Prevent persistence of personalization (filter positions, field values, variants) by setting ignorePersonalizationChanges="true". Use a new unique ID for the control when enabling this experimental feature. When enabled, variants and iAppState-stored application states are NOT applied to the filter bar. Recommended for transient contexts (dialogs, value help).

LANGUAGE: XML

CODE:
```xml
<macros:FilterBar
    metaPath="@com.sap.vocabularies.UI.v1.SelectionFields"
    ignorePersonalizationChanges="true"
    id="FilterBarTransient"
/>
```

STEP: 5 — Important notes, restrictions and references

DESCRIPTION: Consolidated restrictions, usage notes, and links for further reference.

LANGUAGE: text

CODE:
```text
Notes and Restrictions:
- When the FilterBar is used inside a custom section or custom subsection that deals with a navigation entity,
  ensure all controls to be filtered are part of the same UI fragment as the FilterBar building block.
- The FilterBar building block does not provide a visual filter bar toggle (no built-in provision to bring up
  the visual filter bar).
- Custom filters are NOT part of getSelectionVariant / setSelectionVariant APIs.
- ignorePersonalizationChanges is experimental:
  - Do NOT use it on a FilterBar with an existing ID. Create a NEW ID when using this attribute.
  - When personalization changes are not persisted, variants and iAppState application states are NOT applied.

Links:
- FilterBar live examples and defaults:
  https://ui5.sap.com/test-resources/sap/fe/core/fpmExplorer/index.html#/buildingBlocks/filterBar/filterBarDefault
  https://ui5.sap.com/test-resources/sap/fe/core/fpmExplorer/index.html#/buildingBlocks/filterBar/filterBarDefaultValue
- FilterBar public APIs (SelectionVariant, triggerSearch):
  https://ui5.sap.com/test-resources/sap/fe/core/fpmExplorer/index.html#/buildingBlocks/filterBar/filterBarPublicAPIs
- FilterBar API Reference:
  https://ui5.sap.com/#/api/sap.fe.macros.FilterBar
- Add custom filter fields:
  the-filterfield-building-block-2df7837.md
- Personalization / compatibility:
  ../02_Read-Me-First/compatibility-rules-91f0873.md
  ../09_Developing_Controls/how-to-enable-personalization-for-sapui5-controls-5f215c1.md
- Variants and iAppState:
  managing-variants-8ce658e.md
  store-restore-the-application-state-46bf248.md
```

FilterBar
Fiori Elements
SAPUI5
macros
SelectionVariant
personalization
triggerSearch


**TITLE**: FilterField Building Block — Add Custom XML Fragments to a FilterBar

**INTRODUCTION**: Use the FilterField building block to insert custom XML fragments as filter controls inside a macros:FilterBar. This guide shows how to declare FilterField items in XML, how to reference fragment files, and links to examples and API documentation.

**TAGS**: SAP Fiori, UI5, fiori-elements-framework, FilterBar, FilterField, XML fragment, macros

**STEP**: 1 — Add FilterField entries to a FilterBar

**DESCRIPTION**: Declare macros:FilterField elements inside macros:filterFields of a macros:FilterBar. Set key and label (and optional attributes such as required). Use a core:Fragment element to reference an external XML fragment that contains the UI control(s) for the filter field.

**LANGUAGE**: XML

**CODE**:
```xml
<macros:FilterBar
    metaPath="@com.sap.vocabularies.UI.v1.SelectionFields#SF1"
    id="FilterBar"
    showMessages="true"
    search=".handlers.onSearch"
    filterChanged=".handlers.onFiltersChanged"
>
    <macros:filterFields>
        <macros:FilterField key="NameProperty" label="Name">
            <core:Fragment fragmentName="<ApplicationId.FolderName.NameFilterXMLFileName>" type="XML" />
        </macros:FilterField>
        <macros:FilterField key="StreetProperty" label="Street" required="true">
            <core:Fragment fragmentName="<ApplicationId.FolderName.StreetFilterXMLFileName>" type="XML" />
        </macros:FilterField>
    </macros:filterFields>
</macros:FilterBar>
```

**STEP**: 2 — Create the XML fragment file referenced by core:Fragment

**DESCRIPTION**: Implement the UI for each custom filter as an XML fragment file. The fragment file should be stored in your project under the folder path that matches the module path used in fragmentName. Use sap.ui.core.FragmentDefinition as the root, or any valid UI5 XML fragment root element for the control(s) you need.

- fragmentName mapping: use the module path / namespace with dots, e.g. ApplicationId.FolderName.NameFilterXMLFileName (omit the .xml extension when referenced in fragmentName).
- File to create: NameFilterXMLFileName.xml (placed in the folder structure matching the module path).

**LANGUAGE**: XML

**CODE**:
```xml
<!-- Example: webapp/<folder-path>/NameFilterXMLFileName.xml -->
<core:FragmentDefinition
    xmlns="sap.m"
    xmlns:core="sap.ui.core">
    <!-- Replace with the control(s) you need for the filter -->
    <Input id="NameInput" placeholder="Enter name"/>
</core:FragmentDefinition>
```

**STEP**: 3 — Map fragmentName to file path and naming rules

**DESCRIPTION**: Ensure the fragmentName value corresponds to the fragment file location and module name:
- Use the application namespace and folder path separated by dots, matching the resource location in your project.
- Do not include the .xml extension in the fragmentName attribute.
- Example: core:Fragment fragmentName="com.mycompany.app.fragments.NameFilterXMLFileName" type="XML" corresponds to file path webapp/fragments/NameFilterXMLFileName.xml (depending on your project structure and namespace mapping).

**LANGUAGE**: Text

**CODE**:
```
fragmentName format example:
<ApplicationNamespace>.<FolderName>.<FragmentFileNameWithoutExtension>

Example:
core:Fragment fragmentName="com.mycompany.app.fragments.NameFilterXMLFileName" type="XML"
maps to file: webapp/fragments/NameFilterXMLFileName.xml
```

**STEP**: 4 — Explore live examples and API reference

**DESCRIPTION**: Use the official live examples and API documentation for reference and implementation details.

**LANGUAGE**: Text

**CODE**:
```
Live examples (Building Blocks - Filter Bar - Extensions - Custom Filter):
https://ui5.sap.com/test-resources/sap/fe/core/fpmExplorer/index.html#/buildingBlocks/filterBar/filterBarCustom

FilterField API Reference:
https://ui5.sap.com/#/api/sap.fe.macros.filterBar.FilterField

Guidance on creating custom filter XML templates:
Adding Custom Fields to the Filter Bar (see project documentation)
```

SAP Fiori
UI5
fiori-elements-framework
FilterBar
FilterField
XML fragment
macros


**TITLE**: FlexibleColumnLayoutActions Building Block

**INTRODUCTION**: Use the FlexibleColumnLayoutActions building block to insert the standard top-right controls for Flexible Column Layout (FCL) apps: Close, Enter Full Screen, and Exit Full Screen. Add the building block into an XML fragment that supports building-block usage to produce the correct control tree automatically.

**TAGS**: fiori-elements-framework, building-block, FlexibleColumnLayout, FCL, sap.fe.macros, UI5, fragment, XML

**STEP**: 1 — Basic instantiation

**DESCRIPTION**: Reference the building block namespace and insert the FlexibleColumnLayoutActions macro inside a fragment configured for building-block usage. This simple invocation instantiates the actual control tree for the Close, Enter Full Screen, and Exit Full Screen buttons.

**LANGUAGE**: XML

**CODE**:
```xml
<macros:FlexibleColumnLayoutActions/>
```

**STEP**: 2 — Minimal fragment example with namespace mapping

**DESCRIPTION**: Ensure your fragment declares the macros namespace (sap.fe.macros). The following minimal fragment shows how to include the building block in an XML fragment. Place this fragment where your FCL header/action area is rendered.

**LANGUAGE**: XML

**CODE**:
```xml
<!-- Sample fragment: FragmentName.fragment.xml -->
<core:FragmentDefinition
    xmlns="sap.m"
    xmlns:core="sap.ui.core"
    xmlns:macros="sap.fe.macros">

    <!-- Insert the FlexibleColumnLayoutActions building block -->
    <macros:FlexibleColumnLayoutActions/>
</core:FragmentDefinition>
```

**STEP**: 3 — What the building block provides

**DESCRIPTION**: The macro creates the standard set of action controls for FCL applications. Use this building block when you want consistent behavior and look/feel without implementing the controls manually.

**LANGUAGE**: text

**CODE**:
```
Provides three standard actions rendered in the top-right corner of FCL apps:
- Close
- Enter Full Screen
- Exit Full Screen
```

**STEP**: 4 — API reference

**DESCRIPTION**: Consult the official API documentation for detailed properties, events, and usage notes.

**LANGUAGE**: URL

**CODE**:
```
https://ui5.sap.com/#/api/sap.fe.macros.FlexibleColumnLayoutActions
```

fiori-elements-framework building-block FlexibleColumnLayout FCL sap.fe.macros UI5 fragment XML


**TITLE**: Form Building Block (sap.fe.macros.Form)

**INTRODUCTION**: Use the Form building block to instantiate a UI5 form from annotation metadata. Point the Form to a FieldGroup annotation or to a CollectionFacet that contains multiple FieldGroups. You can also add inline form elements (macros:FormElement) inside the Form to extend or override annotation-driven fields.

**TAGS**: sapui5, fiori-elements, form, FieldGroup, CollectionFacet, macros, UI5, annotations

**STEP**: 1 — Instantiate a Form from a FieldGroup annotation

**DESCRIPTION**: Create a Form macro and point the metaPath attribute to a FieldGroup annotation. Provide an id and an optional title. The metaPath value must reference the UI.v1.FieldGroup annotation (example format shown). This XML is used inside an XML view or fragment.

**LANGUAGE**: XML

**CODE**:
```xml
<macros:Form
     id="myForm"
     metaPath="@com.sap.vocabularies.UI.v1.FieldGroup#General"
     title="My Title"
></macros:Form>
```

**STEP**: 2 — Add inline FormElement(s) to a Form

**DESCRIPTION**: Place macros:FormElement elements as children of the macros:Form to add inline elements that are not driven by the referenced annotation. Use metaPath to reference the property, set id and label, and control placement and anchor to position the element relative to an annotation-driven element.

- metaPath: property name (annotation path for the element)
- placement: e.g., "After" or "Before"
- anchor: the element ID or annotation-based anchor to position relative to

**LANGUAGE**: XML

**CODE**:
```xml
<macros:Form
     id="myForm"
     metaPath="@com.sap.vocabularies.UI.v1.FieldGroup#General"
     title="My Title"
>
     <macros:FormElement
          metaPath="ID"
          id="formElementMacroID"
          label="ID Property After Number"
          placement="After"
          anchor="DataField::NumberProperty"
     />
</macros:Form>
```

**STEP**: 3 — Notes on metaPath targets (FieldGroup vs CollectionFacet)

**DESCRIPTION**: The metaPath can target:
- a single FieldGroup annotation (format shown in Step 1)
- a CollectionFacet that contains multiple FieldGroups (use the CollectionFacet annotation path in metaPath)

When using a CollectionFacet, the Form will render the FieldGroups contained in that facet. Adjust id/title and add inline FormElement children as needed.

**LANGUAGE**: Text

**CODE**:
```text
// Example metaPath formats (use in metaPath attribute):
// FieldGroup:
// @com.sap.vocabularies.UI.v1.FieldGroup#<FieldGroupID>
//
// CollectionFacet:
// @com.sap.vocabularies.UI.v1.CollectionFacet#<CollectionFacetID>
```

**STEP**: 4 — API Reference

**DESCRIPTION**: For the complete Form API and available properties/events, consult the official UI5 API reference.

**LANGUAGE**: Text

**CODE**:
```text
API Reference: https://ui5.sap.com/#/api/sap.fe.macros.Form
```

sapui5 fiori-elements form FieldGroup CollectionFacet macros UI5 annotations


**TITLE**: FormElement building block — usage and examples

**INTRODUCTION**: The FormElement building block (sap.fe.macros.FormElement) adds a label and visibility control for a field inside a Form. It can take its label from annotations or via explicit settings. Use it inside a Form's formElements aggregation; a Field is auto-created from the same metaPath, or you can configure a Field explicitly via the fields aggregation.

**TAGS**: fiori-elements-framework, sapui5, ui5, fragments, form, building-blocks, FormElement, macros, metaPath

**STEP**: Prerequisites and placement

**DESCRIPTION**: Place FormElement only inside the formElements aggregation of a FormContainer which is itself inside a Form. Also ensure the building block namespace (sap.fe.macros) is referenced within the fragment where you use building blocks.

**LANGUAGE**: XML

**CODE**:
```xml
<f:Form>
  <f:formContainers>
    <f:FormContainer>
      <f:formElements>
        <!-- Place FormElement here -->
      </f:formElements>
    </f:FormContainer>
  </f:formContainers>
</f:Form>
```

**STEP**: Basic instantiation (auto-created Field)

**DESCRIPTION**: Instantiate FormElement by referencing the building block namespace within a fragment enabled for building block usage. If you provide a metaPath on the FormElement, a Field building block is automatically created using the same metaPath.

**LANGUAGE**: XML

**CODE**:
```xml
<f:Form>
  <f:layout>
    <f:ColumnLayout columnsM="2" columnsL="3" columnsXL="4" labelCellsLarge="12" />
  </f:layout>
  <f:formContainers>
    <f:FormContainer>
      <f:formElements>
        <macros:FormElement xmlns:macro="sap.fe.macros" metaPath="MyProperty" id="myID" />
      </f:formElements>
    </f:FormContainer>
  </f:formContainers>
</f:Form>
```

**STEP**: Explicit Field configuration via fields aggregation

**DESCRIPTION**: To customize the Field that belongs to the FormElement (for example to set custom controls or attributes), define a macros:fields aggregation inside the FormElement and add a macros:Field with the desired metaPath and settings.

**LANGUAGE**: XML

**CODE**:
```xml
<f:Form xmlns:f="sap.ui.layout.form" >
  <f:layout>
    <f:ColumnLayout columnsM="2" columnsL="3" columnsXL="4" labelCellsLarge="12" />
  </f:layout>
  <f:formContainers>
    <f:FormContainer>
      <f:formElements>
        <macros:FormElement xmlns:macro="sap.fe.macros" metaPath="MyProperty" id="myID">
          <macros:fields>
            <macros:Field metaPath="MyProperty"/>
          </macros:fields>
        </macros:FormElement>
      </f:formElements>
    </f:FormContainer>
  </f:formContainers>
</f:Form>
```

**STEP**: Allowed usage contexts

**DESCRIPTION**: Use FormElement inside:
- custom header facets
- custom sections
- custom pages
- custom table columns

(Ensure the surrounding Form -> FormContainer -> formElements structure is respected.)

**LANGUAGE**: text

**CODE**:
```
Allowed contexts: custom header facets, custom sections, custom pages, custom table columns
```

**STEP**: API reference

**DESCRIPTION**: Full API details, properties, aggregations, and events for sap.fe.macros.FormElement.

**LANGUAGE**: text

**CODE**:
```
https://ui5.sap.com/#/api/sap.fe.macros.FormElement
```

fiori-elements-framework sapui5 ui5 fragments form building-blocks FormElement macros metaPath


**TITLE**: KPITag Building Block (sap.fe.macros.KPITag)

**INTRODUCTION**: Use the KPITag building block to display a compact KPI (key performance indicator) with a numeric value, unit, and visual status in Fiori elements/App UI5 XML views. This document shows how to add the control, bind OData/model fields, and find the API reference and live examples.

**TAGS**: fiori-elements-framework, KPITag, sap.fe.macros, UI5, SAP Fiori, macros

**STEP**: 1 — Add KPITag to an XML view

**DESCRIPTION**: Add the KPITag control into your XML view. Ensure the macros namespace is declared (xmlns:macros="sap.fe.macros"). The snippet below contains the exact example usage from the documentation.

**LANGUAGE**: XML

**CODE**:
```xml
<macros:KPITag
  id="mySuccessKPI"
  number="{TotalPrice}"
  unit="{CurrencyCode_code}"
  status="Success"
/>
```

**STEP**: 2 — Minimal complete XML view example with namespace

**DESCRIPTION**: Place KPITag inside a view with the proper namespace declarations. This example shows a minimal, usable XML view wrapper that ensures the macros prefix is available.

**LANGUAGE**: XML

**CODE**:
```xml
<mvc:View
  xmlns:mvc="sap.ui.core.mvc"
  xmlns:macros="sap.fe.macros"
  controllerName="your.controller.Name">
  <macros:KPITag
    id="mySuccessKPI"
    number="{TotalPrice}"
    unit="{CurrencyCode_code}"
    status="Success" />
</mvc:View>
```

**STEP**: 3 — Data binding guidance

**DESCRIPTION**: Bind number and unit to OData or JSON model fields. Use any valid binding path for number and unit. Status can be a literal string (e.g., "Success") or bound to a model property. Example: bind status to a field named KPIStatus.

**LANGUAGE**: XML

**CODE**:
```xml
<macros:KPITag
  id="kpiBound"
  number="{/TotalPrice}"               <!-- absolute JSON path example -->
  unit="{CurrencyCode_code}"           <!-- relative binding from current context -->
  status="{KPIStatus}" />              <!-- bind status to model property -->
```

**STEP**: 4 — API Reference and live examples

**DESCRIPTION**: Use the links below to review the full API, available properties, events, and live building-block examples in the SAP Fiori development portal.

**LANGUAGE**: text

**CODE**:
```
Live examples (Building Blocks - KPI Tag - Overview):
https://ui5.sap.com/test-resources/sap/fe/core/fpmExplorer/index.html#/buildingBlocks/kpiTag/kpiTagDefault

API Reference (sap.fe.macros.KPITag):
https://ui5.sap.com/#/api/sap.fe.macros.KPITag
```

fiori-elements-framework
KPITag
sap.fe.macros
UI5
SAP Fiori
macros


**TITLE**: MessageButton Building Block — Embed and Extend in Fiori Elements

**INTRODUCTION**: The MessageButton building block collects and displays bound messages (non-technical) using the sap.fe.macros.MessageButton control. Use it to show aggregated message counts and criticality, and extend its behavior via controller hooks to control rendering, grouping, link behavior, and visibility of the parent container (for example the footer toolbar). This document provides concise, code-focused guidance and skeletons for embedding the control and implementing controller extension hooks and message lifecycle management.

**TAGS**: fiori-elements-framework, MessageButton, sap.fe.macros, message model, message handling, UI5, controller extension, visibilityChange, beforeShowMessageButton

STEP: 1 — Embed MessageButton in XML view

DESCRIPTION: Add the MessageButton macro to your XML view. Optionally bind the visibilityChange property to a controller method to be invoked before the control is displayed (allowing control of the parent container visibility such as a footer toolbar).

LANGUAGE: XML

CODE:
```xml
<macros:MessageButton visibilityChange=".handleMessageButtonVisibility" />
```

STEP: 2 — Implement visibilityChange handler (controller)

DESCRIPTION: Implement the handler referenced by visibilityChange to update the parent container (for example, show/hide footer toolbar) before the MessageButton is rendered. The framework invokes this handler before the control is displayed. Implementations should accept a boolean indicating the upcoming visibility state and apply it to the containing UI element.

LANGUAGE: JavaScript

CODE:
```javascript
// Controller extension snippet (UI5 controller)
handleMessageButtonVisibility: function (bVisible) {
  // bVisible: boolean indicating whether the MessageButton container will be visible
  // Example: show or hide footer toolbar that contains the MessageButton
  var oFooter = this.byId("footerToolbar");
  if (oFooter) {
    oFooter.setVisible(bVisible);
  }
  // Additional actions: adjust layout, reserve space, toggle other UI controls, etc.
}
```

STEP: 3 — Implement beforeShowMessageButton hook (controller extension)

DESCRIPTION: The framework calls the controller extension hook before showing the MessageButton when bound, non-technical messages exist. Implement this hook to:
- Decide whether the MessageButton should render messages (or render them elsewhere).
- Filter or group messages (default group is "General").
- Customize link behavior (override default focus-to-field action).
- Detect page edit mode and change behavior (for example display a dialog outside edit mode).

Do not rely on internal shape assumptions — inspect the framework hook parameters in your project if needed. Use the hook to mutate the provided messages/context or to trigger custom UI artifact rendering.

LANGUAGE: JavaScript

CODE:
```javascript
// Controller extension skeleton for beforeShowMessageButton
beforeShowMessageButton: function (oContext) {
  // oContext: framework-provided object describing messages and options.
  // Typical actions you can perform (implement based on your project hook signature):
  //
  // 1) Filter messages that you want to handle differently:
  //    const messages = (oContext && oContext.messages) || [];
  //    const nonTechnical = messages.filter(m => !m.technical);
  //
  // 2) Prevent default rendering by the MessageButton and render elsewhere:
  //    // e.g. set a flag on context or call framework method if provided:
  //    // oContext.renderByMessageButton = false;
  //    // this.showCustomMessageStrip(nonTechnical);
  //
  // 3) Group messages for custom UI:
  //    // create groups, e.g. by target section or severity
  //
  // 4) Override link click behavior:
  //    // intercept message.link click and implement navigation/focus logic
  //
  // 5) Check page edit mode and handle messages differently:
  //    if (!this.isPageInEditMode || !this.isPageInEditMode()) {
  //      // show dialog instead of message popover, and prevent popover usage
  //      // this.showMessageDialog(nonTechnical);
  //      // ensure messages do not appear in popover while not in edit mode
  //    }
  //
  // NOTE: The exact shape of oContext and the mechanism to stop default rendering is
  // provided by the framework in your version — inspect the hook signature in your
  // project or the framework docs. Use the hook to mutate messages or set flags
  // that the framework reads.
}
```

STEP: 4 — Manage message lifecycle (clear or update messages)

DESCRIPTION: Manage message lifetime in the global message model. Clear messages that are no longer relevant (for example after Save or navigation), and ensure state messages are only added at appropriate times. Use UI5 MessageManager APIs to remove or filter messages.

LANGUAGE: JavaScript

CODE:
```javascript
// Example: remove all messages (UI5 MessageManager)
var oMessageManager = sap.ui.getCore().getMessageManager();
oMessageManager.removeAllMessages();

// Example: selectively remove non-persistent messages (pseudo-pattern)
// Inspect your message objects and remove only those you want to clear.
var aMessages = oMessageManager.getMessageModel().getData() || [];
var aToRemove = aMessages.filter(function (m) {
  // decide removal criteria, e.g. !m.persistent or !m.technical
  return !m.persistent;
});
if (aToRemove.length) {
  oMessageManager.removeMessages(aToRemove);
}
```

STEP: 5 — Notes for correct behavior and API reference

DESCRIPTION: Implementation notes and references:
- Bound, non-technical messages are filtered by the macro; use the beforeShowMessageButton hook to further filter or control rendering.
- In edit mode, bound messages must appear only in the message popover. If the page is not in edit mode, use the hook to display messages in a dialog or other UI to prevent popover appearance.
- If a visibilityChange handler is bound, it is invoked before the control is displayed so you can toggle the parent container visibility (e.g., footer toolbar).
- Always ensure message lifecycle is managed (clear stale messages after actions like Save).
- API Reference: https://ui5.sap.com/#/api/sap.fe.macros.MessageButton

LANGUAGE: N/A

CODE:
```text
API Reference: https://ui5.sap.com/#/api/sap.fe.macros.MessageButton
```

fiori-elements-framework
MessageButton
sap.fe.macros
message model
message handling
UI5
controller extension
visibilityChange
beforeShowMessageButton


**TITLE**: MicroChart Building Block (fiori-elements)

**INTRODUCTION**: Use the macros:MicroChart building block as a standalone micro chart in XML views. Provide a metadata path (metaPath) and optionally a binding context (contextPath). Control appearance with size and hide labels with showOnlyChart. Use when you need compact visual summaries driven by OData metadata annotations.

**TAGS**: fiori-elements-framework, microchart, ui5, sap-fe, macros, xml

**STEP**: 1 — Basic usage (original sample)
**DESCRIPTION**: Place the MicroChart macro in any XML container. Provide id, metaPath (annotation selector), optional contextPath, and optional batchGroupId.
**LANGUAGE**: XML
**CODE**:
```xml
<macros:MicroChart
    id="bar"
    metaPath="@com.sap.vocabularies.UI.v1.Chart#BarStackedPath"
    contextPath="/RootEntity/_Item"
    batchGroupId="$auto.abc"
/>
```

**STEP**: 2 — contextPath behavior (absolute vs relative metaPath)
**DESCRIPTION**: If metaPath is an absolute annotation path, you may omit contextPath. If metaPath is relative and no contextPath is provided, the parent binding path is used as contextPath. Use an absolute metaPath when you want the macro to resolve without a separate contextPath.
**LANGUAGE**: XML
**CODE**:
```xml
<!-- Example: absolute metaPath (no contextPath required) -->
<macros:MicroChart
    id="barAbs"
    metaPath="/RootEntity/@com.sap.vocabularies.UI.v1.Chart#BarStackedPath"
/>
```

**STEP**: 3 — Control size and hide labels
**DESCRIPTION**: Configure visual size via the size attribute (e.g., "S", "M", "L") and hide labels by setting showOnlyChart="true". Provide contextPath when metaPath is relative to ensure correct binding.
**LANGUAGE**: XML
**CODE**:
```xml
<macros:MicroChart
    id="barSmall"
    metaPath="@com.sap.vocabularies.UI.v1.Chart#BarStackedPath"
    contextPath="/RootEntity/_Item"
    size="S"
    showOnlyChart="true"
/>
```

**STEP**: 4 — References and API
**DESCRIPTION**: Use the SAP Fiori development portal for live examples and the UI5 API reference for full property/method details.
**LANGUAGE**: text
**CODE**:
```
Examples / Overview:
https://ui5.sap.com/test-resources/sap/fe/core/fpmExplorer/index.html#/buildingBlocks/microchart/microChartDefault

API Reference:
https://ui5.sap.com/#/api/sap.fe.macros.MicroChart
```

fiori-elements-framework microchart ui5 sap-fe macros xml


**TITLE**: Page Building Block (sap.fe.macros.Page)

**INTRODUCTION**: Use the Page building block to create a custom page with a predefined layout and correct margins/padding in SAP Fiori elements apps. This document shows how to declare a Page in an XML view, configure its main attributes, and add child Panels containing Text controls. It also links to live examples and the API reference.

**TAGS**: fiori-elements-framework, UI5, sap.fe.macros, Page, building-block, XML, UI5-macros

**STEP**: 1 — Add a Page to an XML view

**DESCRIPTION**: Declare the Page building block in your XML view. Set common properties (title, description, avatarSrc) on the Page and add child Panel controls. The following sample shows two Panels each containing a Text element. Use this snippet inside an XML view file (for example: view.xml).

**LANGUAGE**: XML

**CODE**:
```xml
<macros:Page title="Page title" description="Page description" avatarSrc="sap-icon://page">
    <Panel headerText="First content" id="firstContent">
        <Text text="This is the first content of the page" />
    </Panel>
    <Panel headerText="Second content" id="secondContent">
        <Text text="This is the second content, it is properly padded" />
    </Panel>
</macros:Page>
```

**STEP**: 2 — Configure Page properties

**DESCRIPTION**: Use these primary attributes to control page metadata and appearance:
- title: main page title (string)
- description: subtitle or short description (string)
- avatarSrc: icon URI, e.g., "sap-icon://page" (string)

Set these attributes directly on the <macros:Page> element as shown in the sample. Additional layout, margins and padding are applied by the building block automatically.

**LANGUAGE**: XML

**CODE**:
```xml
<!-- Example of setting title, description and avatar -->
<macros:Page title="My App Page" description="Overview" avatarSrc="sap-icon://account">
    <!-- child content -->
</macros:Page>
```

**STEP**: 3 — Add Panels and child controls

**DESCRIPTION**: Place Panel controls inside the Page to create content sections. Panels commonly use:
- headerText: visible header title for the panel (string)
- id: control id for referencing in code (string)

Use standard UI5 controls (Text, List, Table, Form, etc.) as children of Panel.

**LANGUAGE**: XML

**CODE**:
```xml
<Panel headerText="Details" id="detailsPanel">
    <Text text="Detailed information goes here" />
</Panel>
```

**STEP**: 4 — Links: live examples and API reference

**DESCRIPTION**: Use the live examples and API docs for more properties, methods and detailed examples.

**LANGUAGE**: JSON

**CODE**:
```json
{
  "LiveExamples": "https://ui5.sap.com/test-resources/sap/fe/core/fpmExplorer/index.html#/buildingBlocks/page/pageDefault",
  "APIReference": "https://ui5.sap.com/#/api/sap.fe.macros.Page"
}
```


**TITLE**: Paginator Building Block (sap.fe.macros.Paginator) — Fiori Elements Framework

**INTRODUCTION**: Use the Paginator building block to add paginator buttons for end users to traverse large lists in SAP Fiori elements applications. Place the macro in your XML view and initialize it in the controller so it is connected to the list binding and initial context.

**TAGS**: fiori-elements-framework, paginator, sap.fe.macros, building-blocks, UI5, XML, controller, pagination

**STEP**: 1 — Add the Paginator macro to your XML view

**DESCRIPTION**: Insert the Paginator building block macro into the XML view. Keep the control id to reference it from the controller for initialization.

**LANGUAGE**: XML

**CODE**:
```xml
<macros:Paginator id="paginator" />
```

**STEP**: 2 — Prepare the list control and binding to paginate

**DESCRIPTION**: Identify the list/table control in your view whose binding you want to paginate. Get its binding in the controller (items, rows, or the aggregation used by your list control). This binding is what the Paginator must be initialized with.

**LANGUAGE**: JavaScript

**CODE**:
```javascript
// Example: get the list/table control and its binding in the controller
var oList = this.byId("myList"); // replace "myList" with your list control id
var oListBinding = oList.getBinding("items"); // or "rows" / aggregation used by your control
```

**STEP**: 3 — Initialize the Paginator in the controller (connect binding and context)

**DESCRIPTION**: In your controller, get the Paginator control by id and initialize it with the list binding and any initial context required (for example the starting page or skip/top parameters). Consult the Paginator API for exact initialization methods and parameters—use the control reference obtained above to pass the binding/context into the Paginator.

**LANGUAGE**: JavaScript

**CODE**:
```javascript
// Example initialization skeleton in the controller
var oPaginator = this.byId("paginator");

// oListBinding: the binding obtained from your list/table (see previous step)
// oInitialContext: any initial context/options you need (page index, page size, etc.)

// Use the Paginator API to initialize/attach the list binding and context.
// Replace the following line with the actual API call(s) from the Paginator reference.
oPaginator.initialize?.(oListBinding, oInitialContext); // placeholder — see API Reference
```

**STEP**: 4 — Reference documentation and live examples

**DESCRIPTION**: Use the official resources to implement the correct initialization API calls and view live examples.

**LANGUAGE**: JSON (links)

**CODE**:
```json
{
  "examples": "https://ui5.sap.com/test-resources/sap/fe/core/fpmExplorer/index.html#/buildingBlocks/features/paginatorDefault",
  "apiReference": "https://ui5.sap.com/#/api/sap.fe.macros.Paginator"
}
```

fiori-elements-framework paginator sap.fe.macros building-blocks UI5 XML controller pagination


**TITLE**: RichTextEditor Building Block (SAP Fiori Elements)

**INTRODUCTION**: Use the RichTextEditor building block to display formatted text in display mode and enable inline editing in edit mode. The display mode renders content using sap.m.FormattedText (some formatting like images may not be supported). Configure the editor by declaring button groups and plugins the same way as in SAPUI5.

**TAGS**: fiori-elements-framework, SAPUI5, RichTextEditor, macros, XML, FormattedText, rich-text, building-blocks

**STEP**: 1 — Purpose & display-mode limitation

**DESCRIPTION**: Understand when to use the RichTextEditor and the display-mode considerations. Display mode uses sap.m.FormattedText which does not support all formatting (for example, images). Validate formatting support against the FormattedText API when designing UI that shows formatted content.

**LANGUAGE**: Text

**CODE**:
```Text
Note: The RichTextEditor building block uses sap.m.FormattedText in display mode.
Some formatting (for example, images) is not supported in display mode.
See: https://ui5.sap.com/#/api/sap.m.FormattedText%23controlProperties
```

**STEP**: 2 — Example: Add RichTextEditor to a view/fragment

**DESCRIPTION**: Copy this XML fragment into your SAPUI5 view or XML fragment. Configure value binding, id, required state, buttonGroups, and plugins. Button groups define toolbar sections; plugins enable editor features.

**LANGUAGE**: XML

**CODE**:
```XML
<macros:RichTextEditor value="{custom>/myFormattedValue}" id="myRichTextEditor" required="true">
	<macros:buttonGroups>
		<richtexteditor:ButtonGroup
			name="font-style"
			visible="true"
			priority="10"
			customToolbarPriority="10"
			buttons="bold,italic"
		/>
		<richtexteditor:ButtonGroup
			name="styleselect"
			visible="true"
			priority="10"
			customToolbarPriority="10"
			buttons="styleselect"
		/>
		<richtexteditor:ButtonGroup name="table" visible="true" priority="10" customToolbarPriority="10" buttons="table" />
	</macros:buttonGroups>
	<macros:plugins>
		<richtexteditor:Plugin name="autoresize" />
	</macros:plugins>
</macros:RichTextEditor>
```

**STEP**: 3 — ButtonGroup and Plugin configuration pattern

**DESCRIPTION**: Use these attributes when declaring button groups and plugins. - ButtonGroup attributes: name, visible (true/false), priority (number), customToolbarPriority (number), buttons (comma-separated list). - Plugin declaration: one element per plugin with name attribute.

**LANGUAGE**: XML

**CODE**:
```XML
<!-- Button group pattern -->
<richtexteditor:ButtonGroup
  name="group-name"
  visible="true"
  priority="10"
  customToolbarPriority="10"
  buttons="bold,italic,underline" />

<!-- Plugin pattern -->
<richtexteditor:Plugin name="pluginName" />
```

**STEP**: 4 — References & live examples

**DESCRIPTION**: Use the API Reference and Fiori development portal for full property/event/method details and live building-block examples.

**LANGUAGE**: Text

**CODE**:
```Text
RichTextEditor API (macros): https://ui5.sap.com/#/api/sap.fe.macros.RichTextEditor
sap.m.FormattedText API: https://ui5.sap.com/#/api/sap.m.FormattedText%23controlProperties
Live examples: https://ui5.sap.com/test-resources/sap/fe/core/fpmExplorer/index.html#/buildingBlocks/rte/rteDefault
```

fiori-elements-framework SAPUI5 RichTextEditor macros XML FormattedText rich-text building-blocks


**TITLE**: The `Share` Building Block

**INTRODUCTION**: Use the SAP Fiori `Share` building block in freestyle SAPUI5 applications to provide end users with sharing actions (Send Email, Share to Microsoft Teams, Save as Tile, Share in SAP Jam). Configure visibility of the individual share actions via the shareOptions element. Defaults: showSendEmail = false, showCollaborationManager = false.

**TAGS**: fiori-elements-framework, SAPUI5, Share, building-block, macros, shareOptions, controller-extensions

**STEP**: 1 — Add the Share building block to a view

**DESCRIPTION**: Insert the Share building block into your XML view using the macros:Share control. Configure shareOptions to control which share actions are visible to end users. Example below demonstrates how to set showSendEmail and showCollaborationManager attributes (note: defaults are false).

**LANGUAGE**: XML

**CODE**:
```xml
<macros:Share id="shareWithStaticProperties">
      <macros:shareOptions showSendEmail="false" showCollaborationManager="true" />"
</macros:Share>
```

**STEP**: 2 — Behavior and defaults

**DESCRIPTION**: The shareOptions properties control visibility:
- showSendEmail: false by default. Set to true to display "Send Email".
- showCollaborationManager: false by default. Set to true to display "Share: Collaboration Manager" (e.g., SAP Jam integration).
Adjust attribute values directly in the XML (or via data binding/programmatic configuration in controllers) to enable or disable these UI options.

**LANGUAGE**: JSON

**CODE**:
```json
{
  "shareOptions": {
    "showSendEmail": false,
    "showCollaborationManager": true
  }
}
```

**STEP**: 3 — Reference documentation and live examples

**DESCRIPTION**: Use the official SAP Fiori development portal for live examples and API references:
- Building Blocks - Share - Overview: https://ui5.sap.com/test-resources/sap/fe/core/fpmExplorer/index.html#/buildingBlocks/share
- Building Blocks - Share - Share Extensions: https://ui5.sap.com/test-resources/sap/fe/core/fpmExplorer/index.html#/controllerExtensions/shareExtensibility
- Share API Reference (macros.Share): https://ui5.sap.com/#/api/sap.fe.macros.Share
- Share Controller Extensions API Reference: https://ui5.sap.com/#/api/sap.fe.core.controllerextensions.Share

**LANGUAGE**: Text

**CODE**:
```text
See the links above for live examples and the full API:
- Overview: https://ui5.sap.com/test-resources/sap/fe/core/fpmExplorer/index.html#/buildingBlocks/share
- Share Extensions: https://ui5.sap.com/test-resources/sap/fe/core/fpmExplorer/index.html#/controllerExtensions/shareExtensibility
- API (macros.Share): https://ui5.sap.com/#/api/sap.fe.macros.Share
- API (controller extensions): https://ui5.sap.com/#/api/sap.fe.core.controllerextensions.Share
```

The `Share` Building Block

fiori-elements-framework SAPUI5 Share building-block macros shareOptions controller-extensions


**TITLE**: Share Functionality — Configuration and Extension for SAP Fiori Elements

**INTRODUCTION**: Practical, code-focused guidance for configuring and extending the Share menu in SAP Fiori elements apps (OData V2 and V4). Covers enabling share options (Print, Export to Spreadsheet/CSV/PDF), configuring press handlers at application and page level, modifying Send Email subject via controller extension, hiding share menu options, and enabling semantic bookmarking (annotations). Use these steps to update manifest.json and controller extension files so the Share menu behaves as required.

**TAGS**: fiori-elements-framework, share, manifest.json, controllerextensions, semantic-bookmarking, sap.fe, OData V4, OData V2, tiles, export, print

STEP: Share options overview and behavior differences (OData V2 vs OData V4)
DESCRIPTION: Summary of option availability and key behavior differences you must account for when implementing Share functionality:
- Share is available for List Report, Object Page, and Subobject Page. In flexible column layout, it appears at the highest view level.
- Not visible for newly created objects in draft mode.
- OData V2: For draft objects with an existing active instance, Share directly shares the URL of the active instance.
- OData V4: For draft objects with an existing active instance, Share uses semantic bookmarking (if semantic keys exist); otherwise it shares the active instance URL.
- OData V2 additional note: Share is hidden for creation pages of non-draft objects. You can change tile type from dynamic to static via extension (see corresponding extension docs).
LANGUAGE: text
CODE:
```text
No code required. Refer to steps below for manifest and controller extension samples.
```

STEP: Enable Print (application-level) — OData V4 sample (define press handler)
DESCRIPTION: To display the Print option globally, define a press handler at the application level inside sap.fe.app.share.print.press. Provide a reference to your custom handler function (namespace + function) in manifest.json.
LANGUAGE: JSON
CODE:
```json
"sap.fe": {
    "app": {
        "share": {
            "print": {
                "press": SalesOrder.ext.CustomHandler.print
            }
        },
        ...
    }
}
```

STEP: Enable Export to Spreadsheet (page-level) — show option only on specific page
DESCRIPTION: To display Export to Spreadsheet only on the List Report page, define the share.exportToSpreadsheet.press setting in the page target options.settings.share section of the routing target in manifest.json. Use a function reference or controller method string for the press handler.
LANGUAGE: JSON
CODE:
```json
"sap.ui5": {
    "routing": {
        "targets": {
            "SalesOrderManageList": {
                "type": "Component",
                "id": "SalesOrderManageList",
                "name": "sap.fe.templates.ListReport",
                "options": {
                    "settings": {
                        "share": {
                            "exportToSpreadsheet": {
                                "press": "SalesOrder.ext.CustomHandler.export"
                            }
                            …
                        }
                    }
                },
                …
            },
    }
}
```

STEP: Configure Send Email subject via controller extension (manifest + controller)
DESCRIPTION: To change email subject or otherwise adapt email metadata, register a controller extension in manifest.json and implement the share.adaptShareMetadata controller extension method in your controller extension JS file. The override.share.adaptShareMetadata method receives oShareMetadata — modify oShareMetadata.email.title and return the object.
LANGUAGE: JSON
CODE:
```json
"sap.ui5": {
    "extends": {
        "extensions": {
            "sap.ui.controllerExtensions": {
                "sap.fe.templates.ObjectPage.ObjectPageController": {
                    "controllerName": "SalesOrder.ext.OPExtend"
                }
            }
        }
    },
}
```

LANGUAGE: JavaScript
CODE:
```javascript
sap.ui.define(["sap/ui/core/mvc/ControllerExtension"],
    function(ControllerExtension) {
        "use strict";
        return ControllerExtension.extend("SalesOrder.ext.OPExtend", {
            // this section allows to extend lifecycle hooks or override public methods of the base controller
            override: {
                onInit: function() {},
                share: {
                    adaptShareMetadata: function(oShareMetadata) {
                        oShareMetadata.email.title = "test email subject"; // customize or change email subject
                        return oShareMetadata;
                    }
                }
            }
        });
    }
);
```

STEP: Display additional export/print options (OData V4 properties)
DESCRIPTION: Option names and their manifest property keys — set press handlers to show these options (either at app or page level). If press is not defined, these options are not shown.
- Print => print
- Export to Spreadsheet => exportToSpreadsheet
- Export to CSV => exportToCSV
- Export to PDF => exportToPDF
LANGUAGE: text
CODE:
```text
Share Options and Properties:
Print                  => "print"
Export to Spreadsheet  => "exportToSpreadsheet"
Export to CSV          => "exportToCSV"
Export to PDF          => "exportToPDF"

To display an option: define "press" for the option under "sap.fe". For page-only, define under routing targets -> options -> settings -> "share".
```

STEP: Hide/Show specific Share menu options (application-level)
DESCRIPTION: Control visibility of Send Email, Microsoft Teams, and Collaboration Manager globally by setting properties under sap.fe.app.share. Application-level false overrides page-level. Use expression binding where needed.
- Properties:
  - Send E-Mail => showSendEmail
  - Microsoft Teams => showMsTeamsOptions (under teams)
  - Collaboration Manager => showCollaborationManager
LANGUAGE: JSON
CODE:
```json
"sap.fe": {
    "app": {
        "share": {
            "showSendEmail": "{= !${isVerified} }",
            "teams": {
                "showMsTeamsOptions": false
            }
        },
        ...
    }
}
```

STEP: Hide/Show specific Share menu options (page-level)
DESCRIPTION: Override or configure visibility per page/target. If app-level setting is true or undefined, the page-level binding applies. If app-level is false, page-level is ignored.
LANGUAGE: JSON
CODE:
```json
"sap.ui5": {
    "routing": {
        "targets": {
            "SalesOrderManageList": {
                "type": "Component",
                "id": "SalesOrderManageList",
                "name": "sap.fe.templates.ListReport",
                "options": {
                    "settings": {
                        "share": {
                            "showSendEmail": false,
                            "teams": {
                                "showMsTeamsOptions": "{= ${Delivered} }"
                            },
                            …
                        }
                    }
                },
                …
            },
            "SalesOrderManageObjectPage": {
                "type": "Component",
                "id": "SalesOrderManageObjectPage",
                "name": "sap.fe.templates.ObjectPage",
                "options": {
                    "settings": {
                        "share": {
                            "teams": {
                                "showMsTeamsOptions": true
                            },
                        },
                        …
                    }
                },
                …
            },
            …
        }
    }
}
```

STEP: Microsoft Teams visibility note
DESCRIPTION: showMsTeamsOptions applies only when the app runs on SAP Fiori launchpad and Teams integration is available (requires ushell and Fiori launchpad configuration). Ensure platform support before enabling.

LANGUAGE: text
CODE:
```text
Note: showMsTeamsOptions works only on SAP Fiori launchpad where Share: Microsoft Teams integration exists (requires ushell + launchpad configuration).
```

STEP: Semantic bookmarking — define semantic keys (XML, ABAP CDS, CAP CDS)
DESCRIPTION: To enable semantic bookmarking (allow sharing object pages even when an object is in draft), define semantic keys in metadata for the entity set. If semantic keys exist, the URL contains semantic keys instead of technical keys, allowing recipients to open the shared URL regardless of whether the sharer is in edit (draft) or display (active) mode. If semantic keys are missing, URLs contain technical keys and drafts cannot be accessed by other users.
LANGUAGE: XML
CODE:
```xml
<Annotation Term="Common.SemanticKey">
   <Collection>
      <PropertyPath>SalesOrder</PropertyPath>
   </Collection>
</Annotation>
```

LANGUAGE: ABAP CDS
CODE:
```

@ObjectModel: {
  semanticKey: [ 'SalesOrder' ]
}

define view SALESORDERMANAGE {

}
```

LANGUAGE: CDS
CODE:
```

Common.SemanticKey : [
    SalesOrder
],
```

STEP: Semantic bookmarking limitations and behavior
DESCRIPTION: Key limitations you must handle in code/metadata:
- Semantic bookmarking is not supported for subobject pages.
- If not all semantic keys defined for the entity set are part of the available context, semantic keys fall back to technical keys when switching to edit mode. In that case, if a user shares the URL in edit mode, another user cannot open the draft link.
LANGUAGE: text
CODE:
```text
Limitations:
- Not supported for subobject pages.
- If required semantic key values are missing from context, the URL will include technical keys when switching to edit mode -> sharing will not allow other users to open the draft.
```

STEP: OData V2 note — tile creation and static tile extension
DESCRIPTION: In OData V2:
- Share is hidden for creation pages of non-draft objects.
- During tile creation you can change tile type from dynamic to static by implementing an extension referenced in docs ("Extending the Bookmark Function to Save Static Tiles to the SAP Fiori Launchpad"). Use this extension if you need static tiles instead of dynamic tiles.
LANGUAGE: text
CODE:
```text
Note: For OData V2 list report, dynamic tiles with record count are created (filters are respected). To create static tiles instead, implement the extension described in the "Extending the Bookmark Function to Save Static Tiles to the SAP Fiori Launchpad" documentation.
```

fiori-elements-framework
share
manifest.json
controllerextensions
semantic-bookmarking
sap.fe
OData V4
OData V2
tiles
export
print