CDS Annotations Part 3: Fiori UI Annotations — Line Items, Facets and Selection Fields

📌 KEY POINTS
✅ @UI.lineItem = list columns; @UI.selectionField = filter bar; @UI.headerInfo = object title.
✅ Object page = @UI.facet (sections) pointing to @UI.identification or @UI.fieldGroup.
✅ Actions become buttons via @UI.lineItem / @UI.identification with type #FOR_ACTION.
💡 Value helps: @Consumption.valueHelpDefinition on the field.

━━━━━━━━━━━━━━━━━━━━
▶ WHERE WE ARE
Part 2 made the data meaningful. Now you describe the screen. Fiori Elements generates list reports and object pages entirely from these annotations — no UI5 code.

━━━━━━━━━━━━━━━━━━━━
▶ 1. THE LIST REPORT

• @UI.headerInfo (entity level) — typeName ('Purchase Request'), typeNamePlural, title (the field shown as object title), description.
• @UI.lineItem: [{ position: 10, importance: #HIGH }] — a column in the table. position orders columns; importance decides what stays visible on small screens.
• @UI.selectionField: [{ position: 10 }] — a field in the filter bar.
• @UI.hidden: true — technical fields (UUIDs) never shown.

━━━━━━━━━━━━━━━━━━━━
▶ 2. THE OBJECT PAGE
The object page is built from facets:

• @UI.facet on one element (usually the key) lists the sections: { id: 'General', purpose: #STANDARD, type: #IDENTIFICATION_REFERENCE, label: 'General', position: 10 }.
• #IDENTIFICATION_REFERENCE shows all fields with @UI.identification.
• #FIELDGROUP_REFERENCE with targetQualifier shows fields with @UI.fieldGroup: [{ qualifier: 'Amounts', position: 10 }].
• #LINEITEM_REFERENCE with targetElement: '_Item' shows a table of child entities (their own @UI.lineItem).
• #HEADER purpose puts data points or field groups into the header.

━━━━━━━━━━━━━━━━━━━━
▶ 3. ACTIONS AS BUTTONS
Add to an element's lineItem or identification:
{ type: #FOR_ACTION, dataAction: 'approve', label: 'Approve' }
The action must exist in the BDEF and projection; feature control enables or disables the button automatically.

━━━━━━━━━━━━━━━━━━━━
▶ 4. VALUE HELPS
@Consumption.valueHelpDefinition: [{ entity: { name: 'I_Currency', element: 'Currency' } }]
The value-help entity must be accessible (released view or your own) and, in RAP services, exposed or reachable through the service (Service Definitions Part 6).

━━━━━━━━━━━━━━━━━━━━
▶ 5. TEXT AND DISPLAY

• @UI.textArrangement: #TEXT_FIRST — show "Completed (C)".
• @UI.dataPoint for KPIs in the header, @UI.lineItem with criticality for colored status.
• @EndUserText.label gives the column and field labels.

━━━━━━━━━━━━━━━━━━━━
▶ 6. WHERE TO PUT THEM
Put UI annotations into a metadata extension of the projection view (Part 4), not into the base BO view — the same BO can serve several apps with different layouts.

━━━━━━━━━━━━━━━━━━━━
▶ STEP BY STEP

1. Use the metadata extension in the code example for ZC_PurchReq.
2. Add @Metadata.allowExtensions: true to ZC_PurchReq.
3. Activate and open the service binding preview.
4. Check: filter bar, columns, object page sections, items table, Approve button.

✅ CHECKPOINT: you can build a complete Fiori Elements UI from annotations.

A team planned three weeks of UI5 development for a purchase-request app with list, filters, object page, item table and an approve button. A senior developer showed that Fiori Elements could generate all of it from annotations.
They built the metadata extension in two days, including value helps and a status column with criticality colors. Feature control from the BDEF automatically disabled the Approve button for non-submitted requests. The only custom UI5 work left was a small extension for a chart, and the app went to test two weeks early.

• UI annotations in the base BO view instead of a metadata extension on the projection.
• Forgetting @Metadata.allowExtensions: true on the projection.
• Facets pointing to a qualifier or element that does not exist.
• Action buttons for actions not exposed in the projection BDEF.
• Showing UUIDs instead of hiding them.
• Value helps on entities the service cannot reach.

• Design the screen first: columns, filters, sections, actions — then annotate.
• Use positions in steps of 10 to allow later insertions.
• Use importance for responsive tables.
• Hide technical keys; show readable IDs and texts.
• Keep one metadata extension per projection and consumer.

Questions: "Which annotations build a Fiori Elements list report and object page?", "How do you add an action button?", "How do you add a value help?"
Strong answer: headerInfo, lineItem, selectionField for the list; facets with identification, fieldGroup and lineItem references for the object page; #FOR_ACTION entries for buttons (action must be in BDEF and projection, feature control handles enablement); @Consumption.valueHelpDefinition for value helps; all in a metadata extension of the projection.