zhongwei/gh-secondsky-sap-skills-skills-sap-fiori-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:55:20 +08:00
commit fee63d563a
11 changed files with 3748 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,12 @@
{
"name": "sap-fiori-tools",
"description": "Develops SAP Fiori applications using SAP Fiori tools extensions for VS Code and BAS. Covers Fiori Elements, Page Editor, and Freestyle SAPUI5 generation.",
"version": "1.0.0",
"author": {
"name": "Zhongwei Li",
"email": "zhongweili@tubi.tv"
},
"skills": [
"./"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# sap-fiori-tools
Develops SAP Fiori applications using SAP Fiori tools extensions for VS Code and BAS. Covers Fiori Elements, Page Editor, and Freestyle SAPUI5 generation.

419
SKILL.md Normal file
View File

@@ -0,0 +1,419 @@
---
name: sap-fiori-tools
description: |
Develops SAP Fiori applications using SAP Fiori tools extensions for VS Code and SAP Business Application Studio.
Use when: generating Fiori Elements or Freestyle SAPUI5 applications, configuring Page Editor for List Report
or Object Page, working with annotations and Service Modeler, setting up deployment to ABAP or Cloud Foundry,
creating adaptation projects, using Guided Development, previewing with mock data or live data, configuring
SAP Fiori launchpad, or using AI-powered generation with Project Accelerator/Joule.
Technologies: SAP Fiori Elements, SAPUI5, OData V2/V4, CAP, SAP BTP, ABAP, Cloud Foundry.
license: GPL-3.0
metadata:
version: "1.0.0"
last_verified: "2025-11-25"
---
# SAP Fiori Tools Development Skill
## Related Skills
- **sapui5**: Use for underlying UI5 framework details, custom control development, and advanced UI patterns
- **sap-cap-capire**: Use for CAP service integration, OData consumption, and backend service configuration
- **sap-abap-cds**: Use when consuming ABAP CDS views as OData services or working with ABAP backends
- **sap-btp-cloud-platform**: Use for deployment targets, BTP destination configuration, and Cloud Foundry deployment
- **sap-api-style**: Use when documenting OData APIs or following API documentation standards for Fiori apps
Comprehensive guidance for developing SAP Fiori applications using SAP Fiori tools extensions.
## Overview
SAP Fiori tools is a collection of extensions that simplifies SAP Fiori elements and SAPUI5 application development. It includes six main components:
| Component | Purpose |
|-----------|---------|
| **Application Wizard** | Generate Fiori Elements and Freestyle SAPUI5 templates |
| **Application Modeler** | Visual Page Map and Page Editor for configuration |
| **Guided Development** | Step-by-step feature implementation guides |
| **Service Modeler** | Visualize OData service metadata and annotations |
| **Annotations Language Server** | Code completion, diagnostics, i18n for annotations |
| **Environment Check** | Validate setup and destination configurations |
**Minimum SAPUI5 Version**: 1.65+
**Support Component**: CA-UX-IDE
## Sample Projects
Official SAP sample repository with Fiori Elements applications built using SAP Fiori tools:
**Repository**: [SAP-samples/fiori-tools-samples](https://github.com/SAP-samples/fiori-tools-samples)
| Folder | Content |
|--------|---------|
| `V2/` | OData V2 Fiori Elements samples |
| `V4/` | OData V4 Fiori Elements samples |
| `cap/` | CAP project integration samples |
| `app-with-tutorials/` | Tutorial companion projects |
**Quick Start**:
```bash
git clone [https://github.com/SAP-samples/fiori-tools-samples](https://github.com/SAP-samples/fiori-tools-samples)
cd fiori-tools-samples/V4/apps/salesorder
npm install
npm start
```
---
## Quick Start Commands
Access features via Command Palette (`Cmd/Ctrl + Shift + P`):
```
Fiori: Open Application Generator # Create new application
Fiori: Open Application Info # View project commands
Fiori: Open Page Map # Visual navigation editor
Fiori: Open Guided Development # Feature implementation guides
Fiori: Open Service Modeler # Explore OData service
Fiori: Add Deployment Configuration # Setup ABAP or CF deployment
Fiori: Add Fiori Launchpad Configuration # Configure FLP tile
Fiori: Validate Project # Run project validation
Fiori: Open Environment Check # Troubleshoot destinations
```
## Application Generation
### Fiori Elements Floorplans
| Floorplan | OData V2 | OData V4 | Use Case |
|-----------|----------|----------|----------|
| List Report Page | Yes | Yes | Browse large datasets, navigate to details |
| Worklist Page | Yes | 1.99+ | Process work items, task completion |
| Analytical List Page | Yes | 1.90+ | Data analysis, KPI visualization |
| Overview Page | Yes | Yes | Role-based dashboards, multi-card views |
| Form Entry Object Page | Yes | Yes | Structured data entry |
| Custom Page | No | Yes | Extensible custom UI with building blocks |
### Data Source Options
1. **SAP System** - Connect to ABAP on-premise or BTP systems
2. **CAP Project** - Use local Node.js or Java CAP project
3. **EDMX File** - Upload metadata for mock-only development
4. **SAP Business Accelerator Hub** - Development/testing only (deprecated)
### Generated Project Structure
```
webapp/
├── manifest.json # App descriptor
├── Component.js # UI5 component
├── localService/ # Mock data and metadata
│ ├── metadata.xml
│ └── mockdata/
└── annotations/ # Local annotation files
package.json
ui5.yaml # UI5 tooling config
ui5-local.yaml # Local development config
```
## Page Editor Configuration
The Page Editor provides visual configuration for Fiori Elements pages.
### List Report Page Elements
- **Filter Fields** - Configure filter bar with value helps
- **Table** - Configure columns, actions, row selection
- **Multiple Views** - Create tabbed table views
- **Analytical Chart** - Add data visualizations
### Object Page Elements
- **Header** - Configure header facets and actions
- **Sections** - Form, Table, Identification, Chart, Group sections
- **Footer** - Configure footer actions
### Extension-Based Elements (OData V4)
| Element | Location | Description |
|---------|----------|-------------|
| Custom Column | Table | Add custom columns with fragments |
| Custom Section | Object Page | Add custom sections with views |
| Custom Action | Header/Table | Add action buttons with handlers |
| Custom View | List Report | Add custom tab views |
| Controller Extension | Page | Override lifecycle methods |
For detailed configuration, see `references/page-editor.md`.
## Annotations Development
### Language Server Features
- **Code Completion** (`Ctrl/Cmd + Space`) - Context-aware suggestions
- **Micro-Snippets** - Insert complete annotation blocks
- **Diagnostics** - Validation against vocabularies
- **i18n Support** - Externalize translatable strings
- **Peek/Go to Definition** - Navigate to annotation sources
### Supported Vocabularies
OASIS OData v4: Core, Capabilities, Aggregation, Authorization, JSON, Measures, Repeatability, Temporal, Validation
SAP Vocabularies: Analytics, CodeList, Common, Communication, DataIntegration, DirectEdit, Graph, Hierarchy, HTML5, ODM, PDF, PersonalData, Preview, Session, UI
### Annotation Files Location
- **CDS files**: CAP project `.cds` files
- **XML files**: `webapp/annotations/*.xml`
For annotation patterns, see `references/annotations.md`.
## Preview Options
### NPM Scripts
```bash
npm start # Live data from backend
npm run start-mock # Mock data via MockServer
npm run start-local # Mock data + local SAPUI5 resources
npm run start-noflp # Without Fiori launchpad sandbox
```
### Run Control
Configure via `launch.json` in `.vscode/` folder. Supports:
- Multiple run configurations per workspace
- VS Code and BAS integration
- App-to-app navigation preview
### Mock Data
- **Data Editor** - Visual mock data management
- **AI Generation** - Generate contextual mock data (requires SAP Build Code)
- **MockServer** - Automatic mock server setup
For preview details, see `references/preview.md`.
## Deployment
### ABAP Deployment
**Prerequisites**:
- SAP_UI 7.53+
- SAPUI5 ABAP Repository service enabled
- S_DEVELOP authorization
**Configuration**:
```bash
npx fiori add deploy-config # Generate ui5-deploy.yaml
npm run deploy # Execute deployment
```
**Generated Files**: `ui5-deploy.yaml`, updated `package.json`
### Cloud Foundry Deployment
**Prerequisites**:
- MTA tool: `npm i -g mta`
- CF CLI with multiapps plugin
- HTML5 Repository service instance
**Configuration**:
```bash
npx fiori add deploy-config # Select Cloud Foundry
npm run build # Generate mta.yaml
npm run deploy # Deploy to CF
```
**Generated Files**: `mta.yaml`, `xs-app.json`, `xs-security.json`
For deployment details, see `references/deployment.md`.
## Fiori Launchpad Configuration
Add FLP tile configuration via:
```
Fiori: Add Fiori Launchpad Configuration
```
**Required Parameters**:
- Semantic Object (unique identifier)
- Action (e.g., "display")
- Title
- Subtitle (optional)
Configuration updates `manifest.json` with inbound navigation.
## Adaptation Projects
Extend existing Fiori applications without modifying source code.
### Prerequisites
**On-Premise (VS Code)**:
- SAP_UI 7.54+, SAPUI5 1.72+
- Base app must have manifest.json
- Cannot use ABAP Cloud packages
**S/4HANA Cloud & BTP ABAP**:
- Application must be "released for extensibility"
- 3-system landscape with developer tenant
- Required business catalogs assigned
### Adaptation Workflow
1. Create adaptation project via Template Wizard
2. Make UI adaptations in Adaptation Editor
3. Preview adaptation
4. Deploy to ABAP repository
### Adaptation Capabilities
| Adaptation | Description |
|------------|-------------|
| Control Variants | Create page variants/views |
| Fragments | Add UI fragments to extension points |
| Controller Extensions | Override/extend controller methods |
| App Descriptor Changes | Modify manifest.json settings |
| OData Service | Add/replace OData services |
| Component Usages | Add SAPUI5 component references |
For adaptation details, see `references/adaptation-projects.md`.
## AI-Powered Generation
### Project Accelerator / Joule
Generate complete CAP projects with Fiori UI from business requirements.
**Input Formats**: Text, Images, or Combined
**Generated Output**:
- Entity definitions and associations
- Code lists and value helps
- List Report applications
- Object Page configurations
- Sample data
**Limitations**:
- No charts or specialized headers
- Do not include personal/sensitive data in requirements
### AI Mock Data Generation
Generate contextual mock data using entity property names (requires SAP Build Code subscription).
## Project Functions
| Function | Command |
|----------|---------|
| Application Info | `Fiori: Open Application Info` |
| Project Validation | `Fiori: Validate Project` |
| Environment Check | `Fiori: Open Environment Check` |
| Data Editor | Via Application Info page |
| Service Metadata | `Fiori: Open Service Modeler` |
| System Connections | Manage SAP Systems in VS Code |
### Project Validation Checks
1. **Project** - Verify package.json, manifest.json, ui5.yaml
2. **Annotation** - Validate annotation files
3. **Specification** - Check manifest and changes folder
4. **ESLint** - Run ESLint if configured
## Building Blocks (OData V4)
Reusable UI components for custom pages and sections:
| Block | Use Case |
|-------|----------|
| Chart | Data visualization |
| Filter Bar | Query filtering |
| Table | Tabular data display |
| Page | Custom page container |
| Rich Text Editor | Content editing in custom sections |
## Troubleshooting
### Common Issues
**Port 8080 in use**: System auto-selects next available port
**HTTPS/SSL errors**: Configure browser to trust localhost certificates
**Deployment 400 errors**: Check `/IWFND/ERROR_LOG`, configure virus scan in `/IWFND/VIRUS_SCAN`
**Debug deployment**:
```bash
# macOS/Linux
DEBUG=ux-odata-client npm run deploy
# Windows
set DEBUG=ux-odata-client & npm run deploy
```
### CLI Help
```bash
npx fiori help # List available commands
npx fiori deploy help # Deployment command help
```
## Migration from SAP Web IDE
Migrate existing projects using:
```
Fiori: Migrate Project for use in Fiori tools
```
**Supported Types**: Fiori Elements (V2/V4), Freestyle SAPUI5, Adaptation Projects, Extensibility Projects
**Post-Migration**: Run `npm run deploy-config` to update deployment configuration.
For migration details, see `references/getting-started.md`.
## Guided Development (76+ Guides)
Access step-by-step implementation guides:
```
Fiori: Open Guided Development
```
**Guide Categories**:
- Building Blocks (Chart, Filter Bar, Table)
- Page Elements (Cards, Header Facets, Sections)
- Table Enhancements (Column types, Actions)
- Filtering & Navigation
- Configuration (Variant management, Side effects)
- Extensions (Custom actions, sections, columns)
## Reference Documentation
For detailed information on specific topics:
- `references/getting-started.md` - Installation, migration, ADT integration, commands
- `references/configuration.md` - MTA, middlewares, SAPUI5 versions, project functions
- `references/page-editor.md` - Page Editor configuration details
- `references/annotations.md` - Annotation patterns and examples
- `references/deployment.md` - Deployment configuration details
- `references/adaptation-projects.md` - Adaptation project workflows
- `references/preview.md` - Preview and testing options
## Documentation Sources
**Primary Source**: [https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs](https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs)
**Last Updated**: 2025-11-22
| Section | Documentation Link |
|---------|-------------------|
| Getting Started | `Getting-Started-with-SAP-Fiori-Tools/` |
| Generating Apps | `Generating-an-Application/` |
| Developing | `Developing-an-Application/` |
| Previewing | `Previewing-an-Application/` |
| Deploying | `Deploying-an-Application/` |
| Project Functions | `Project-Functions/` |
| Adaptation Projects | Root docs folder |
**SAP Resources**:
- Fiori Design Guidelines: [https://experience.sap.com/fiori-design-web/](https://experience.sap.com/fiori-design-web/)
- SAP Help Portal: [https://help.sap.com/docs/SAP_FIORI_tools](https://help.sap.com/docs/SAP_FIORI_tools)

73
plugin.lock.json Normal file
View File

@@ -0,0 +1,73 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:secondsky/sap-skills:skills/sap-fiori-tools",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "33ad98de2cfae8c3e4cb1df0c80510b95a9ae875",
"treeHash": "85a796a8d15c23d6d0f2f1fe66893194e2397094edb1702279a235f6ca462fbd",
"generatedAt": "2025-11-28T10:28:13.844021Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "sap-fiori-tools",
"description": "Develops SAP Fiori applications using SAP Fiori tools extensions for VS Code and BAS. Covers Fiori Elements, Page Editor, and Freestyle SAPUI5 generation.",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "7681fbfc151af583a026bd241902cd6937ef20fe599d65e2fba51da45b531230"
},
{
"path": "SKILL.md",
"sha256": "e00c79ec49ed0a81ce8e0f0e1120750d011ea8f9ba7b98a7e3e4036516e27b21"
},
{
"path": "references/page-editor.md",
"sha256": "5e234decae5c075772a86152e5014464721570aede50ee7ee08167fb40fe2f47"
},
{
"path": "references/annotations.md",
"sha256": "ffa5d85a99c5c7dd5ad5df857c42f6730d2e5f2a9b63859f86c6e2e6c4be0e7a"
},
{
"path": "references/getting-started.md",
"sha256": "439c78ad1444e5812d0dea4437b7e312879f4b65ab136068c086dd332f52ddea"
},
{
"path": "references/adaptation-projects.md",
"sha256": "9c7e384fec4622ad2b76646600265803cf2b1f40eb1d3ed75be05f76c1f5615b"
},
{
"path": "references/deployment.md",
"sha256": "58fedd8e9dca69b02aea4e328fb3f51934bf82ca081a6bc726d13ddfec5e6dc3"
},
{
"path": "references/configuration.md",
"sha256": "eae2ae9d55f2ee09327d947840e3a0a7bd1695674e20e4a8f365c9ce75ee8d77"
},
{
"path": "references/preview.md",
"sha256": "611d07ad65f2b2da9b2d7d0dd3ea5cf26b733757500099bfbacb905e6227ecff"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "6796392db809275d28bd8ba90073c6171767e692ca582acfb421237a2ae3d2f8"
}
],
"dirSha256": "85a796a8d15c23d6d0f2f1fe66893194e2397094edb1702279a235f6ca462fbd"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

479
references/adaptation-projects.md Normal file
View File

@@ -0,0 +1,479 @@
# Adaptation Projects Reference
Comprehensive reference for creating and managing SAP Fiori adaptation projects.
## Table of Contents
1. [Overview](#overview)
2. [On-Premise Systems](#on-premise-systems)
3. [S/4HANA Cloud and BTP ABAP](#s4hana-cloud-and-btp-abap)
4. [Creating Adaptation Projects](#creating-adaptation-projects)
5. [Adaptation Capabilities](#adaptation-capabilities)
6. [Controller Extensions](#controller-extensions)
7. [Fragments and Extension Points](#fragments-and-extension-points)
8. [Preview and Testing](#preview-and-testing)
9. [Deployment](#deployment)
10. [Upgrade-Safe Rules](#upgrade-safe-rules)
---
## Overview
Adaptation projects allow extending existing SAP Fiori applications without modifying source code. They create **application variants** that maintain separation from the original application.
### Benefits
- Non-invasive extensions
- Independent lifecycle from base application
- Upgrade-safe modifications
- Version control support
### Supported Environments
| Environment | IDE Support | Deployment Target |
|-------------|-------------|-------------------|
| On-Premise ABAP | VS Code | ABAP Repository |
| SAP S/4HANA Cloud | BAS | BTP ABAP Environment |
| SAP BTP ABAP | BAS, VS Code | BTP ABAP Environment |
---
## On-Premise Systems
### Prerequisites
| Requirement | Version/Details |
|-------------|-----------------|
| SAP_UI Component | 7.54 or higher |
| System SAPUI5 Version | 1.72 or higher |
| Base App SAPUI5 Version | 1.30 or higher |
| Base App | Must have manifest.json |
### Limitations
- Cannot use ABAP Cloud Development packages
- Apps with mandatory startup parameters unsupported
- Previously deployed application variants cannot serve as bases
- Apps using `sap.ca.scfld.md` scaffolding unsupported
### Required Services
Enable and activate:
- `/sap/bc/adt` - ABAP Development Tools
- `/sap/bc/ui2/app_index/` - Application Index
Grant access to:
- `/sap/bc/adt/discovery`
### Workflow
1. Create adaptation project
2. (Optional) Initialize Git repository
3. Make adaptations
4. Preview adaptation project
5. Deploy to ABAP repository
---
## S/4HANA Cloud and BTP ABAP
### Prerequisites
**SAP S/4HANA Cloud**:
- Verify extensibility support in SAP Fiori Apps Reference Library
- 3-system landscape with developer tenant required
- Submit enhancement requests via Influence Opportunity Homepage if needed
**Both Environments**:
- Source application must be "released for extensibility"
- Destination to development tenant configured
- Required business catalogs assigned
### Required Business Catalogs
| Catalog | Purpose |
|---------|---------|
| SAP_A4C_BC_DEV_UID_PC | Development - UI Deployment |
| SAP_A4C_BC_DEV_OBJ_DIS_PC | Retrieve extensible applications |
### Destination Configuration
Create destination in BTP Cockpit pointing to development tenant with appropriate authentication.
---
## Creating Adaptation Projects
### Via Template Wizard
1. Open Command Palette: `Cmd/Ctrl + Shift + P`
2. Execute: `Fiori: Open Template Wizard`
3. Select "Adaptation Project" tile
4. Configure project settings
### Configuration Fields
| Field | Description |
|-------|-------------|
| Project Name | Unique project identifier |
| Application Title | Display title |
| Namespace | Prefixed with `customer.` |
| SAPUI5 Version | Target UI5 version |
| Target System | SAP system connection |
| Application | Base application to extend |
### Via Generator Command
```
Fiori: Open Adaptation Project Generator
```
### Add Deployment Configuration
Optional during creation or added later via:
```
Fiori: Add Deployment Configuration
```
---
## Adaptation Capabilities
### UI Adaptations
| Adaptation | Description |
|------------|-------------|
| Control Variants | Create page variants/views |
| Hide/Show Controls | Toggle control visibility |
| Move Controls | Reposition UI elements |
| Rename Labels | Change display texts |
| Change Properties | Modify control properties |
### Structural Changes
| Change | Description |
|--------|-------------|
| Add Fragments | Insert UI fragments at extension points |
| Controller Extensions | Override/extend controller methods |
| Component Usages | Add SAPUI5 component references |
### Configuration Changes
| Change | Description |
|--------|-------------|
| App Descriptor | Modify manifest.json settings |
| OData Service | Add/replace OData services |
| Local Annotations | Add annotation files |
| Inbound Navigation | Modify navigation configuration |
### Adaptation Editor UI Operations
Access: Right-click `manifest.appdescr_variant` > "Open Adaptation Editor"
| Operation | Method |
|-----------|--------|
| Modify properties | Select element, adjust in Properties pane |
| Add fields | Right-click group > "Add Field" > select fields |
| Create groups | Right-click > "Add Group" |
| Add sections | Right-click sections > "Add Section" |
| Rename elements | Double-click or right-click > rename |
| Reorder elements | Drag and drop |
| Move elements | Cut, highlight target, paste |
| Combine fields | Ctrl+click multiple (max 3) > "Combine" |
| Split fields | Right-click combined > "Split" |
| Remove elements | Right-click > remove or Delete key |
**Note**: Removed fields remain available for re-adding. Mandatory fields require confirmation.
### Quick Actions Availability Matrix
Quick actions vary by SAPUI5 version. Key milestones:
| Action | Min Version | OData |
|--------|-------------|-------|
| Add Controller to Page | 1.71 | V2, V4 |
| Add Header Field | 1.71 | V2, V4 |
| Add Custom Section | 1.71 | V2, V4 |
| Enable/Disable Clear Button | 1.71 | V2, V4 |
| Add Custom Table Action | 1.96 | V2, V4 |
| Add Custom Table Column | 1.96 | V2, V4 |
| Change Table Columns | 1.96 | V2, V4 |
| Enable Variant Management | 1.96 | V2, V4 |
| Add Custom Page Action | 1.120 | V2, V4 |
| Add Local Annotation File | 1.133 | V2, V4 |
| Add Subpage (V4) | 1.135 | V4 only |
---
## Controller Extensions
### Purpose
Enhance existing controller functionality with:
- New methods
- Override methods
- Lifecycle hooks
### File Structure
```
webapp/
├── changes/
│ ├── coding/
│ │ └── MyExtension.js
│ └── MyExtension.controllerExtension.change
```
### Extension Template
```javascript
sap.ui.define([
"sap/ui/core/mvc/ControllerExtension"
], function(ControllerExtension) {
"use strict";
return ControllerExtension.extend("customer.project.extension.MyExtension", {
// Override member for lifecycle and base methods
override: {
// Lifecycle methods
onInit: function() {
// Called after base controller onInit
},
onBeforeRendering: function() {
// Called before view rendering
},
onAfterRendering: function() {
// Called after view rendering
},
onExit: function() {
// Called on controller destruction
}
},
// Custom methods (outside override)
myCustomMethod: function(oEvent) {
// Custom business logic
}
});
});
```
### Event Handler Binding
For methods in XML fragments, use prefix:
```
.extension.<controller extension namespace>
```
Example:
```xml
<Button press=".extension.customer.project.extension.MyExtension.myCustomMethod"/>
```
### Provided Methods by Template
| Application Type | Provided Methods |
|-----------------|------------------|
| List Report | Lifecycle + template overrides |
| Object Page | Lifecycle + template overrides |
| Overview Page | Lifecycle + template overrides |
| Analytical List Page | Lifecycle only |
### Important Rules
- Keep custom code in `changes/coding/` folder
- Do not create additional folders at higher levels
- Namespace extensions with `.extension` to avoid conflicts
---
## Fragments and Extension Points
### Adding Fragments to Aggregations
1. Open Adaptation Editor
2. Click Edit mode
3. Select target control (smart filter bar, toolbar, etc.)
4. Choose "Add Fragment" from context menu
5. Configure fragment settings
**Quick Actions**:
- Add Custom Page Action
- Add Custom Table Action
- Add Custom Table Column
- Add Header Field
- Add Custom Section
### Fragment Configuration
| Field | Description |
|-------|-------------|
| Target Aggregation | Container for fragment |
| Index | Position within aggregation |
| Fragment | Select existing or create new |
### Fragment Template
```xml
<core:FragmentDefinition
xmlns:core="sap.ui.core"
xmlns:uxap="sap.uxap"
xmlns="sap.m">
<uxap:ObjectPageSection id="customer.project.customSection" title="Custom Section">
<uxap:subSections>
<uxap:ObjectPageSubSection>
<Text text="Custom content"/>
</uxap:ObjectPageSubSection>
</uxap:subSections>
</uxap:ObjectPageSection>
</core:FragmentDefinition>
```
### Requirements
- Define namespace for all controls used
- Use stable and unique IDs
- IDs should follow pattern: `customer.<project>.<elementId>`
### Adding Fragments to Extension Points
For freestyle SAPUI5 applications with predefined extension points:
1. Expand outline tree to find extension points
2. Right-click parent element
3. Select "Add fragment at extension point"
4. Configure fragment
### Generated Files
- Fragment: `webapp/changes/fragments/<name>.fragment.xml`
- Change: `webapp/changes/addXML.change`
### Cleanup
Delete associated change files when removing fragments to avoid blocking future additions.
---
## Preview and Testing
### Launch Preview
```
Fiori: Preview Adaptation Project
```
Or via Application Info page.
### Preview Characteristics
- Runs in sandbox-like environment
- Outside SAP Fiori launchpad context
- Some FLP-dependent features may not work
- Features work correctly after deployment
### Testing Adaptations
1. Make changes in Adaptation Editor
2. Preview immediately reflects changes
3. Test functionality in preview
4. Deploy only when satisfied
---
## Deployment
### On-Premise Deployment
Deploy to ABAP repository using standard deployment:
```bash
npm run deploy
```
### S/4HANA Cloud Deployment
Use Adaptation Project Deployment Wizard:
```
Fiori: Deploy Adaptation Project
```
### Post-Deployment
- Application variant appears in Fiori launchpad
- Independent tile/navigation configuration possible
- Base application updates do not affect deployed variant
---
## Upgrade-Safe Rules
### Core Principles
SAPUI5 Flexibility uses modification-free extensibility:
- Extension code separated from base application lifecycle
- Base application can upgrade independently
- Extensions remain functional across upgrades
### Controller Extension Rules
1. **Follow SAPUI5 best practices**
2. **Access only controls with stable IDs**
- Never rely on control order in aggregations
- Never rely on parent-child relationships
3. **Verify control existence before access**
- Check if control exists
- Verify control type
4. **Avoid private/protected methods**
- Do not call or override private methods
- Do not use deprecated artifacts
5. **No hardcoded property values**
- OData metadata values change during upgrades
- Do not use value help entity sets in code
6. **Handle reuse component changes**
- Implement robust error handling
- Components may change during upgrades
### Fragment Rules
- Use stable IDs with proper namespacing
- Do not reference controls by position
- Handle missing extension points gracefully
---
## Checking Compatibility
### Base App Upgrade Check
```
Fiori: Check Base App Upgrades
```
Verifies if adaptation project is current with base application updates.
### Release State Consistency
```
Fiori: Check Consistency of Release State
```
Validates that adaptations align with released application state.
---
## Documentation Source
**GitHub**: [https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs](https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs)
Key files:
- `extending-an-existing-application-6e25aca.md`
- `extending-an-sap-fiori-application-for-an-on-premise-system-802f01c.md`
- `extending-an-sap-fiori-application-for-sap-s-4hana-cloud-public-edition-and-sap-btp-abap-f4881a9.md`
- `creating-an-adaptation-project-072f566.md`
- `controller-extensions-ad7b4ae.md`
- `add-fragments-to-an-aggregation-or-extension-point-6033d56.md`
- `upgrade-safe-compatibility-rules-53706e2.md`
- `making-adaptations-2a076dd.md`
- `previewing-an-adaptation-project-64cc15b.md`
- `deploying-an-adaptation-project-to-the-abap-repository-febf0d9.md`

415
references/annotations.md Normal file
View File

@@ -0,0 +1,415 @@
# Annotations Reference
Comprehensive reference for working with annotations in SAP Fiori tools.
## Table of Contents
1. [Language Server Features](#language-server-features)
2. [Supported File Types](#supported-file-types)
3. [Supported Vocabularies](#supported-vocabularies)
4. [Code Completion](#code-completion)
5. [Micro-Snippets](#micro-snippets)
6. [Diagnostics](#diagnostics)
7. [Internationalization](#internationalization)
8. [Service Modeler](#service-modeler)
9. [Common Annotation Patterns](#common-annotation-patterns)
---
## Language Server Features
SAP Fiori tools provides two annotation language servers:
| Server | File Type | Scope |
|--------|-----------|-------|
| CDS OData Language Server | `.cds` files | CAP projects |
| XML Annotation Language Server | `annotation.xml` files | All projects |
### Capabilities
- Code completion for annotation targets, terms, attributes, values
- Validation against OData vocabularies and project metadata
- Navigation to referenced annotations
- Quick vocabulary information views
- Internationalization (i18n) support
---
## Supported File Types
### CDS Annotation Files
Location: CAP project `.cds` files
```cds
annotate CatalogService.Products with @(
UI: {
HeaderInfo: {
TypeName: 'Product',
TypeNamePlural: 'Products',
Title: { Value: name }
},
LineItem: [
{ Value: ID },
{ Value: name },
{ Value: price }
]
}
);
```
### XML Annotation Files
Location: `webapp/annotations/*.xml`
**Prerequisites**:
1. OData Service with local metadata copy
2. Path specified in `manifest.json` as local `Uri`
3. Metadata contains `<edm:Schema>` definitions
4. Single `EntityContainer` in metadata
5. Valid XML file with `</edmx:DataServices/Schema>` nodes
**Manifest Configuration**:
```json
{
"sap.app": {
"dataSources": {
"mainService": {
"uri": "/sap/opu/odata/sap/SERVICE/",
"type": "OData",
"settings": {
"localUri": "localService/metadata.xml",
"annotations": ["annotation"]
}
},
"annotation": {
"type": "ODataAnnotation",
"uri": "annotations/annotation.xml"
}
}
}
}
```
---
## Supported Vocabularies
### OASIS OData v4 Vocabularies
| Vocabulary | Namespace | Description |
|------------|-----------|-------------|
| Core | Org.OData.Core.V1 | Core vocabulary terms |
| Capabilities | Org.OData.Capabilities.V1 | Service capabilities |
| Aggregation | Org.OData.Aggregation.V1 | Aggregation support |
| Authorization | Org.OData.Authorization.V1 | Authorization schemes |
| JSON | Org.OData.JSON.V1 | JSON-related terms |
| Measures | Org.OData.Measures.V1 | Units of measure |
| Repeatability | Org.OData.Repeatability.V1 | Request repeatability |
| Temporal | Org.OData.Temporal.V1 | Temporal data |
| Validation | Org.OData.Validation.V1 | Data validation |
### SAP OData Vocabularies
| Vocabulary | Namespace | Description |
|------------|-----------|-------------|
| Analytics | com.sap.vocabularies.Analytics.v1 | Analytical annotations |
| CodeList | com.sap.vocabularies.CodeList.v1 | Code list definitions |
| Common | com.sap.vocabularies.Common.v1 | Common terms |
| Communication | com.sap.vocabularies.Communication.v1 | Contact information |
| DataIntegration | com.sap.vocabularies.DataIntegration.v1 | Data integration |
| DirectEdit | com.sap.vocabularies.DirectEdit.v1 | Direct editing |
| Graph | com.sap.vocabularies.Graph.v1 | Graph structures |
| Hierarchy | com.sap.vocabularies.Hierarchy.v1 | Hierarchical data |
| HTML5 | com.sap.vocabularies.HTML5.v1 | HTML5 rendering |
| ODM | com.sap.vocabularies.ODM.v1 | One Domain Model |
| PDF | com.sap.vocabularies.PDF.v1 | PDF generation |
| PersonalData | com.sap.vocabularies.PersonalData.v1 | Personal data marking |
| Preview | com.sap.vocabularies.Preview.v1 | Preview features |
| Session | com.sap.vocabularies.Session.v1 | Session handling |
| UI | com.sap.vocabularies.UI.v1 | UI annotations |
---
## Code Completion
### Activation
- **Windows**: `Ctrl + Space`
- **macOS**: `Cmd + Space`
### Context-Aware Suggestions
Code completion provides suggestions based on:
- Project metadata (entities, properties, associations)
- OData vocabulary definitions
- Current cursor context
### Path Navigation
Use `/` character to:
1. Accept current segment selection
2. Trigger completion for next segment
3. Navigate multi-segment annotation paths
### Supported Contexts
- Annotation targets
- Terms and term values
- Attributes and attribute values
- Record properties
- Path expressions
---
## Micro-Snippets
Pre-defined code blocks for rapid annotation development.
### Available Snippets
| Snippet Type | Description |
|--------------|-------------|
| Annotation Target | `<Annotations Target=""></Annotations>` |
| Terms | Complete term structures |
| Records | Record with properties |
| Property Values | Property value templates |
### Record Snippet Types
1. **Minimal Version**: Only mandatory properties (nullable=false)
2. **Complete Version**: All available properties
### Usage Example
Within `<Schema>` tags:
1. Trigger code completion
2. Select annotation target snippet
3. Cursor positions inside quotes for immediate target selection
---
## Diagnostics
### Validation Scope
The language server validates:
- Annotation syntax
- Vocabulary compliance
- Metadata references
- Property types and values
### Message Types
| Type | Severity | Description |
|------|----------|-------------|
| Error | High | Must fix before deployment |
| Warning | Medium | Potential issues |
| Info | Low | Informational messages |
### Accessing Diagnostics
1. **Hover**: Mouse over highlighted sections
2. **Problems Panel**: View > Problems (all issues)
### Quick Fixes
Light bulb icon provides automatic fixes:
- Missing required properties
- Type mismatches
- Value corrections
### Limitations
**Not Supported**:
- Annotations embedded in metadata
- Dynamic expressions
- Backend annotation file modifications (local copies only)
---
## Internationalization
### Configuration
**Non-CAP Projects**:
```json
// webapp/manifest.json
{
"sap.ui5": {
"models": {
"i18n": {
"type": "sap.ui.model.resource.ResourceModel",
"settings": {
"bundleName": "project.i18n.i18n"
}
}
}
}
}
```
**CAP Projects**:
```json
// .cdsrc.json or package.json
{
"i18n": {
"folders": ["_i18n", "i18n", "assets/i18n"]
}
}
```
### Key Naming Conventions
| Project Type | Format | Example |
|--------------|--------|---------|
| Non-CAP | camelCase | `productTitle` |
| CAP | PascalCase | `ProductTitle` |
### i18n Scenarios
1. **Non-internationalized labels**: Convert to i18n key references
2. **Missing i18n keys**: Auto-generate with matching values
3. **Duplicate text**: Link to existing i18n entries
### Mass i18n Generation
Bulk externalization of multiple UI texts:
1. Access via Page Editor or annotation file
2. Select multiple translatable strings
3. Generate keys in batch operation
### Best Practice
Handle i18n near project completion to minimize unused entries and reduce localization costs.
---
## Service Modeler
### Purpose
Visualize OData service metadata and annotations for exploration and overriding.
### Launching
- Command Palette: `Fiori: Open Service Modeler`
- Context Menu: Right-click folder > "Override Annotations"
- Editor: Click icon when metadata.xml is open
### Features
**Annotation Display**:
- View backend and local annotation files
- Local annotations override backend annotations
- Search annotations by term or target
**Source Navigation**:
- "Show in Source" icon opens original file
- Highlighting for context
### Editing Annotations
Backend annotations cannot be modified directly. Local annotations:
- Location: `/webapp/annotations/<filename>.xml`
- Edit via XML Code Editor
- Delete using Service Modeler delete icon
### Override Priority
Local annotations win over backend annotations when:
- Same annotation term
- Same qualifier
- Same target
---
## Common Annotation Patterns
### List Report Line Item
```xml
<Annotations Target="Namespace.EntityType">
<Annotation Term="UI.LineItem">
<Collection>
<Record Type="UI.DataField">
<PropertyValue Property="Value" Path="PropertyName"/>
<PropertyValue Property="Label" String="Column Label"/>
</Record>
</Collection>
</Annotation>
</Annotations>
```
### Selection Fields (Filter Bar)
```xml
<Annotation Term="UI.SelectionFields">
<Collection>
<PropertyPath>Property1</PropertyPath>
<PropertyPath>Property2</PropertyPath>
</Collection>
</Annotation>
```
### Header Info
```xml
<Annotation Term="UI.HeaderInfo">
<Record Type="UI.HeaderInfoType">
<PropertyValue Property="TypeName" String="Entity"/>
<PropertyValue Property="TypeNamePlural" String="Entities"/>
<PropertyValue Property="Title">
<Record Type="UI.DataField">
<PropertyValue Property="Value" Path="Name"/>
</Record>
</PropertyValue>
</Record>
</Annotation>
```
### Object Page Facets
```xml
<Annotation Term="UI.Facets">
<Collection>
<Record Type="UI.ReferenceFacet">
<PropertyValue Property="Label" String="General"/>
<PropertyValue Property="ID" String="GeneralFacet"/>
<PropertyValue Property="Target" AnnotationPath="@UI.FieldGroup#General"/>
</Record>
</Collection>
</Annotation>
```
### Field Group
```xml
<Annotation Term="UI.FieldGroup" Qualifier="General">
<Record Type="UI.FieldGroupType">
<PropertyValue Property="Data">
<Collection>
<Record Type="UI.DataField">
<PropertyValue Property="Value" Path="Property1"/>
</Record>
</Collection>
</PropertyValue>
</Record>
</Annotation>
```
---
## Documentation Source
**GitHub**: [https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs/Developing-an-Application](https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs/Developing-an-Application)
Key files:
- `maintaining-annotations-with-language-server-6fc93f8.md`
- `code-completion-dd4fc3b.md`
- `micro-snippets-addf811.md`
- `diagnostics-1fd8f54.md`
- `internationalization-i18n-eb427f2.md`
- `visualizing-annotations-with-service-modeler-58784b5.md`
- `working-with-annotations-55bfb91.md`
- `overriding-annotations-2f1bb9c.md`

549
references/configuration.md Normal file
View File

@@ -0,0 +1,549 @@
# Configuration Reference
Comprehensive reference for configuring SAP Fiori tools projects.
## Table of Contents
1. [MTA Configuration](#mta-configuration)
2. [JavaScript Code Assist](#javascript-code-assist)
3. [Security Certificates](#security-certificates)
4. [Custom Middlewares](#custom-middlewares)
5. [SAPUI5 Version Management](#sapui5-version-management)
6. [Project Functions](#project-functions)
7. [Reuse Libraries](#reuse-libraries)
8. [UI Service Generation](#ui-service-generation)
---
## MTA Configuration
### Generate MTA Deployment File
**Command**:
```
Fiori: Open CF Application Router Generator
```
### Generated Structure
```
project/
├── router/ # App router configuration
├── mta.yaml # MTA configuration
├── package.json
├── package-lock.json
└── .gitignore
```
### Router Type Options
| Type | Description |
|------|-------------|
| Managed | SAP-managed router |
| Application Frontend service | Frontend routing service |
| Standalone | Self-managed router |
### Adding Applications to MTA
**Existing MTA File**:
When MTA file exists, Application Generator:
- Automatically enables deployment configuration
- Updates MTA file with settings
**New MTA File**:
Select "Cloud Foundry" as target landscape during generation.
**Best Practice**:
1. Create MTA file first
2. Generate Fiori application in subfolder
3. Better supports multi-application deployments
### CAP Projects
Options for MTA in CAP:
- Generate new instance-based destination
- Use existing destinations from MTA file
---
## JavaScript Code Assist
### Prerequisites
SAPUI5 version 1.76 or newer
### Setup Steps
**1. Add Dependencies**
In `package.json`:
```json
{
"devDependencies": {
"eslint": "5.16.x",
"@sap/eslint-plugin-ui5-jsdocs": "2.0.x",
"@sapui5/ts-types": "1.92.x"
}
}
```
**2. Create tsconfig.json**
```json
{
"compilerOptions": {
"module": "none",
"noEmit": true,
"checkJs": true,
"allowJs": true,
"types": ["@sapui5/ts-types"]
}
}
```
**3. Create .eslintrc**
```json
{
"plugins": ["@sap/ui5-jsdocs"],
"extends": [
"eslint:recommended",
"plugin:@sap/ui5-jsdocs/recommended"
]
}
```
**4. Install Dependencies**
```bash
rm -rf node_modules
npm install
```
### Features
- Code completion for SAPUI5
- Type-aware suggestions
- Documentation hints
---
## Security Certificates
### When Certificates Needed
When local certificate authority is unknown to operating system (certificate valid but not trusted).
### Setup Steps
**Step 1: Obtain Certificate**
Export certificate from web browser or obtain from CA.
**Step 2: Install to Trust Store**
**Windows**:
1. Right-click CA certificate
2. Select "Install Certificate"
3. Add to trust store (current user or all users)
**macOS**:
1. Right-click CA certificate
2. Open With > Keychain Access
3. Import into System keychain
**Step 3: Configure Environment**
Set `NODE_EXTRA_CA_CERTS` environment variable:
**Windows**:
1. System Properties > Advanced > Environment Variables
2. Create new variable with certificate path
**macOS**:
```bash
export NODE_EXTRA_CA_CERTS=path/to/certificate/file
```
### Troubleshooting Invalid Certificates
For truly invalid certificates (not recommended):
```bash
NODE_TLS_REJECT_UNAUTHORIZED=0
```
**Warning**: Resolve underlying certificate issues instead.
---
## Custom Middlewares
### Overview
Plug custom middleware into SAPUI5 Server module's express server.
### Application Reload Middleware
Auto-refresh browser on file changes.
**Configuration** (`ui5.yaml`):
```yaml
server:
customMiddleware:
- name: fiori-tools-appreload
afterMiddleware: compression
configuration:
path: webapp # Directory to monitor
ext: html,js,json,xml,properties,change
port: 35729 # Communication port
debug: false # Enable logging
```
### Proxy Middleware
Connect to backend systems and manage SAPUI5 versions.
**Basic Backend Connection**:
```yaml
server:
customMiddleware:
- name: fiori-tools-proxy
afterMiddleware: compression
configuration:
backend:
- path: /sap
url: [https://my.backend.com:1234](https://my.backend.com:1234)
```
**Multiple Backends**:
```yaml
configuration:
backend:
- path: /sap/opu/odata/sap/SERVICE1
url: [https://system1.com](https://system1.com)
- path: /sap/opu/odata/sap/SERVICE2
url: [https://system2.com](https://system2.com)
```
**Special Options**:
| Option | Value | Description |
|--------|-------|-------------|
| scp | true | SAP BTP ABAP Environment |
| apiHub | true | SAP Business Accelerator Hub |
| ws | true | WebSocket support |
| pathPrefix | string | Remap request paths |
**SAPUI5 Version Management**:
```yaml
configuration:
ui5:
path:
- /resources
- /test-resources
url: [https://sapui5.hana.ondemand.com](https://sapui5.hana.ondemand.com)
version: 1.78.0
```
### Serve Static Middleware
Deliver static resources locally.
**SAPUI5 Local Serving**:
```yaml
server:
customMiddleware:
- name: fiori-tools-servestatic
afterMiddleware: compression
configuration:
paths:
- path: /resources
src: "Path/To/SAPUI5-SDK"
```
### Execution
```bash
npx fiori run
```
Requires properly configured `ui5.yaml`.
---
## SAPUI5 Version Management
### Minimum Version
**Location**: `manifest.json`
```json
{
"sap.ui5": {
"dependencies": {
"minUI5Version": "1.120.0"
}
}
}
```
**Change Command**:
```
Fiori: Change Minimum SAPUI5 Version
```
Updates:
- `manifest.json` minUI5Version
- `@sap/ux-specification` module
**Deployment Warning**: If target system lacks required version, warning displays.
### Preview Version
**Default**: Uses minimum SAPUI5 version
**Custom Configuration**: Create custom run configuration
**Source**: `[https://ui5.sap.com`](https://ui5.sap.com`) (default)
**Fallback**: Next higher version if requested unavailable
### Deployed Version
**ABAP Environment**:
- FLP apps: Backend's installed SAPUI5 version
- Standalone: Relative paths (backend) or absolute URLs (specific version)
**Cloud Foundry**:
- Work Zone: iFrame with backend version
- Standalone: Configured destination, defaults to latest from ui5.sap.com
---
## Project Functions
### Application Information
**Command**: `Fiori: Open Application Info`
**Sections**:
| Section | Content |
|---------|---------|
| Project Detail | Type, SAPUI5 version, backend, pages |
| Status | Dependency summary with fix links |
| What you can do | Relevant command shortcuts |
| What you can learn | Help topics and support links |
### Project Validation
**Command**: `Fiori: Validate Project`
**Validation Steps**:
| Step | Validates |
|------|-----------|
| Project | package.json, manifest.json, ui5.yaml |
| Annotation | Annotation files (same as Language Server) |
| Specification | manifest.json, changes folder |
| ESLint | If eslint installed, runs project checks |
**Output**: Markdown report + Problems tab
### Project Cleanup
Removes unused elements:
- Orphaned `UI.FieldGroup` and `UI.LineItem` annotations
- Unused annotation terms: `UI.MultiLineText`, `Common.ValueListWithFixedValues`, `Common.Text`, `Common.ValueList`, `Common.FieldControl`
### Environment Check
**Command**: `Fiori: Open Environment Check`
**Report Sections**:
| Section | Content |
|---------|---------|
| Environment | Dev Space type, Node version |
| Destination Details | Parameters and specifics |
| All Destination Details | Complete destination list |
| Messages | Raw logs for support |
**Output Options**: View in interface or export as `.zip`
### Data Editor
**Command**: Via Application Info > Start Data Editor
**Capabilities**:
- Edit cells (double-click, excludes keys)
- Add rows (cascades to related entities)
- Delete rows (cascades deletions)
- Search functionality
- Show/hide columns
**Live Updates** (`ui5-mock.yaml`):
```yaml
server:
customMiddleware:
- name: "@sap-ux/ui5-middleware-fe-mockserver"
configuration:
watch: true
```
---
## Reuse Libraries
### Create Reusable Library
**Command**: `Fiori: Open Reusable Library Generator`
**Required Fields**:
- Module name
- Namespace
- Minimum SAPUI5 version
- OData service (optional)
### Add Library Reference
**Prerequisites**:
- Reuse library in workspace
- Existing SAP Fiori project
**Command**: `Fiori: Add Reference to SAP Fiori Reusable Libraries`
**Steps**:
1. Select target SAP Fiori project
2. Choose workspace as source
3. Select libraries/components
4. Click Finish
**Updated Files**:
- `ui5.yaml`
- `ui5-local.yaml`
- `manifest.json`
### Deploy Reuse Library
1. Add library project to workspace
2. Accept migration prompt
3. Dependencies install automatically
4. Generate deployment configuration
5. Deploy to ABAP
---
## UI Service Generation
### Purpose
Generate UI services from business objects or data models.
**Command**: `Fiori: Generate UI Service`
### Service Sources
| Source | Description |
|--------|-------------|
| Business Object Interface | Business object service |
| ABAP Core Data Service | CDS-based service |
### Options
- Draft enablement (if supported)
- Automatic Fiori application creation
### Procedure
1. Execute command
2. Select SAP system (VS Code) or destination (BAS)
3. Choose business object or data service
4. Specify package and transport
5. Enable drafts (optional)
6. Enable auto app creation (optional)
### Result
- UI service generated
- If auto-create enabled, SAP Fiori Generator launches
---
## Filter Fields Configuration
### Types
| Type | Description |
|------|-------------|
| Compact Filter | Field with value help |
| Visual Filter | Chart with selectable elements |
### Adding Filter Fields
1. Open Page Map for List Report
2. Select Configure Page
3. Click Add icon next to Filter Bar > Filter Fields
4. Select properties for filtering
**Generated Annotation**: `UI.SelectionFields`
### Restrictions
Cannot select properties marked with:
- `UI.Hidden`
- `UI.HiddenFilter`
- `NonFilterableProperties`
### Visual Filters
For analytically-enabled services:
**Configuration**:
- Select analytically-enabled entity
- Choose groupable property (dimension)
- Select/create measure
**Generated Annotations**:
- `UI.Chart`
- `UI.PresentationVariant`
- `Common.ValueList`
- `UI.SelectionFields`
### Editable Properties
**Compact Filters**: Label, External ID, Text, Text Arrangement, Display Type
**Visual Filters (Additional)**: Measure/Dimension Labels, Scale Factor, Fractional Digits, Sort Order, Fixed Values
---
## Table Configuration
### Sorting
**Presentation Variant Property**: `UI.SelectionPresentationVariant` or `UI.PresentationVariant`
**Add Sort Property**:
1. Configure presentation variant
2. Add sort properties
3. Specify direction
4. Reorder as needed
### Default Filtering
**Selection Variant**: `UI.SelectionPresentationVariant` or `UI.SelectionVariant`
**Add Default Filter**:
1. Configure selection variant
2. Add filter properties
3. Supports multiple filters per property
---
## Documentation Source
**GitHub**: [https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs](https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs)
Key files:
- `Generating-an-Application/Additional-Configuration/`
- `Project-Functions/`
- `Developing-an-Application/filter-fields-0b84286.md`
- `Developing-an-Application/table-aaff7b1.md`

430
references/deployment.md Normal file
View File

@@ -0,0 +1,430 @@
# Deployment Reference
Comprehensive reference for deploying SAP Fiori applications to ABAP and Cloud Foundry.
## Table of Contents
1. [Deployment Overview](#deployment-overview)
2. [ABAP Deployment](#abap-deployment)
3. [Cloud Foundry Deployment](#cloud-foundry-deployment)
4. [Fiori Launchpad Configuration](#fiori-launchpad-configuration)
5. [Undeployment](#undeployment)
6. [Troubleshooting](#troubleshooting)
---
## Deployment Overview
SAP Fiori tools supports deployment to two primary environments:
| Target | Repository | Runtime |
|--------|------------|---------|
| ABAP | SAPUI5 ABAP Repository | ABAP system provides hosting, routing, authentication |
| Cloud Foundry | HTML5 Repository | BTP provides hosting via HTML5 App Runtime |
### Deployment Workflow
1. Generate deployment configuration
2. Configure Fiori Launchpad (optional)
3. Execute deployment
4. Verify in target system
---
## ABAP Deployment
### Prerequisites
| Requirement | Details |
|-------------|---------|
| SAP_UI Component | Version 7.53 or higher |
| SAPUI5 ABAP Repository Service | `/sap/opu/odata/UI5/ABAP_REPOSITORY_SRV` enabled |
| Authorization | S_DEVELOP with required activities |
| Transport | Existing transport if package requires one |
### Authentication Methods
| Method | On-Premise | BTP ABAP |
|--------|------------|----------|
| Basic Authentication | Yes | No |
| OAuth 2.0 | No | Deprecated |
| Reentrance Ticket | No | Yes |
### Generate Configuration
**Command Palette**:
```
Fiori: Add Deployment Configuration
```
**CLI**:
```bash
npx fiori add deploy-config
```
### Configuration Prompts
| Field | Description | Required |
|-------|-------------|----------|
| Target | Select "ABAP" | Yes |
| Target System | Saved system or URL | Yes |
| Client | SAP client number (3 digits) | Yes |
| SAPUI5 ABAP Repository | Application name for deployment | Yes |
| Deployment Description | Optional descriptive text | No |
| Package | Valid ABAP package name | Yes |
| Transport Request | See options below | Yes |
### Transport Request Options
1. **Enter manually** - Provide transport request ID directly
2. **Choose from existing** - Select from system-provided list
3. **Create new** - Auto-generate during configuration
4. **Create during deployment** - Auto-generate on first deployment
### Generated Files
**ui5-deploy.yaml**:
```yaml
specVersion: "2.4"
metadata:
name: project-name
type: application
builder:
resources:
excludes:
- /test/**
- /localService/**
deploy:
target:
url: [https://system.url](https://system.url)
client: "100"
scp: false
params:
sap-language: EN
app:
name: ZAPP_NAME
package: ZPACKAGE
description: Application description
transport: DEVK900123
```
**package.json update**:
```json
{
"scripts": {
"deploy": "fiori deploy --config ui5-deploy.yaml"
}
}
```
### Execute Deployment
```bash
npm run deploy
```
The command:
1. Builds the application
2. Creates ZIP of `dist` folder
3. Uploads to SAPUI5 ABAP Repository
4. Registers with transport (if applicable)
---
## Cloud Foundry Deployment
### Prerequisites
| Requirement | Installation |
|-------------|-------------|
| MTA Build Tool | `npm install -g mta` (version 1.0+) |
| GNU Make | Required on Windows (version 4.2.1) |
| Cloud Foundry CLI | Download from official site |
| MultiApps Plugin | `cf install-plugin -r CF-Community "multiapps"` |
| Backend Destination | Configured in BTP cockpit |
### Generate Configuration
**Command Palette**:
```
Fiori: Add Deployment Configuration
```
Select "Cloud Foundry" as target.
### Configuration Prompts
| Field | Description |
|-------|-------------|
| Destination Name | BTP destination for backend |
| Add Application Router | Yes for standalone deployment |
| Override HTML5 App Name | Custom name in repository |
### Generated Project Structure
```
project/
├── webapp/
│ └── manifest.json
├── mta.yaml # MTA descriptor
├── xs-app.json # App router configuration
├── xs-security.json # Security descriptor
├── package.json # Updated with scripts
├── ui5.yaml
└── ui5-deploy.yaml
```
### MTA Descriptor (mta.yaml)
```yaml
_schema-version: "3.2"
ID: project-name
version: 0.0.1
modules:
- name: project-name-destination-content
type: com.sap.application.content
requires:
- name: project-name-destination-service
parameters:
content-target: true
- name: project-name-repo-host
parameters:
service-key:
name: project-name-repo-host-key
- name: project-name-uaa
parameters:
service-key:
name: project-name-uaa-key
parameters:
content:
instance:
destinations:
- Name: project-name-repo-host
ServiceInstanceName: project-name-html5-srv
ServiceKeyName: project-name-repo-host-key
sap.cloud.service: project-name
- Authentication: OAuth2UserTokenExchange
Name: project-name-uaa
ServiceInstanceName: project-name-xsuaa
ServiceKeyName: project-name-uaa-key
sap.cloud.service: project-name
existing_destinations_policy: update
- name: project-name
type: html5
path: .
build-parameters:
build-result: dist
builder: custom
commands:
- npm install
- npm run build:cf
resources:
- name: project-name-repo-host
type: org.cloudfoundry.managed-service
parameters:
service: html5-apps-repo
service-plan: app-host
- name: project-name-destination-service
type: org.cloudfoundry.managed-service
parameters:
service: destination
service-plan: lite
- name: project-name-uaa
type: org.cloudfoundry.managed-service
parameters:
service: xsuaa
service-plan: application
config:
xsappname: project-name
tenant-mode: dedicated
```
### xs-app.json (App Router Configuration)
```json
{
"welcomeFile": "/index.html",
"authenticationMethod": "route",
"routes": [
{
"source": "^/sap/opu/odata/(.*)$",
"target": "/sap/opu/odata/$1",
"destination": "backend-destination",
"authenticationType": "xsuaa"
},
{
"source": "^(.*)$",
"target": "$1",
"service": "html5-apps-repo-rt",
"authenticationType": "xsuaa"
}
]
}
```
### Build and Deploy
```bash
# Build MTA archive
npm run build
# Deploy to Cloud Foundry
npm run deploy
```
Or using CF CLI directly:
```bash
# Build
mbt build
# Deploy
cf deploy mta_archives/project-name_0.0.1.mtar
```
### SAP Business Application Studio Alternative
1. Create Basic Multitarget Application template
2. Add Approuter Configuration module
3. Configure destination-content module
---
## Fiori Launchpad Configuration
### Generate Configuration
**Command Palette**:
```
Fiori: Add Fiori Launchpad Configuration
```
**CLI**:
```bash
npx @sap-ux/create
```
### Configuration Parameters
| Parameter | Description | Example |
|-----------|-------------|---------|
| Semantic Object | Unique identifier | `Product` |
| Action | Navigation action | `display`, `manage`, `create` |
| Title | Tile title | `Manage Products` |
| Subtitle | Tile subtitle (optional) | `Product Management` |
### Manifest Updates
```json
{
"sap.app": {
"crossNavigation": {
"inbounds": {
"intent1": {
"semanticObject": "Product",
"action": "display",
"title": "{{appTitle}}",
"subTitle": "{{appSubTitle}}",
"signature": {
"parameters": {},
"additionalParameters": "allowed"
}
}
}
}
}
}
```
---
## Undeployment
### ABAP Undeployment
Via Application Info page or CLI:
```bash
npx fiori undeploy --config ui5-deploy.yaml
```
### Cloud Foundry Undeployment
```bash
cf undeploy project-name --delete-services
```
---
## Troubleshooting
### Common ABAP Issues
| Issue | Cause | Solution |
|-------|-------|----------|
| Service activation error | SAP_UI component outdated | Verify SAP_UI 7.53+ |
| 400 status error | Backend processing error | Check `/IWFND/ERROR_LOG` |
| Virus scan failure | Scan profile misconfigured | Configure `/IWFND/VIRUS_SCAN` |
| Authorization error | Missing S_DEVELOP | Grant required authorizations |
### Debug Deployment
**macOS/Linux**:
```bash
DEBUG=ux-odata-client npm run deploy
```
**Windows**:
```bash
set DEBUG=ux-odata-client & npm run deploy
```
### CLI Help
```bash
npx fiori help # All commands
npx fiori deploy help # Deploy command options
npx fiori add deploy-config help # Configuration options
```
### Required OData Services
Ensure these services are enabled and accessible:
| Service | Path |
|---------|------|
| SAPUI5 Repository | `/sap/opu/odata/UI5/ABAP_REPOSITORY_SRV` |
| OData V2 Catalog | `/sap/opu/odata/IWFND/CATALOGSERVICE;v=2` |
| OData V4 Catalog (dev) | `/sap/opu/odata4/iwfnd/config/default/iwfnd/catalog/0001` |
| OData V4 Catalog (prod) | `/sap/opu/odata4/iwfnd/config/default/iwfnd/catalog/0002` |
| ATO Settings | `/sap/bc/adt/ato/settings` |
---
## Central Application Router
For exposing applications through central managed router:
1. Configure destination to HTML5 Repository
2. Set up managed application router service
3. Reference application in launchpad configuration
See `expose-application-to-central-application-router-85ad10d.md` for details.
---
## Documentation Source
**GitHub**: [https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs/Deploying-an-Application](https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs/Deploying-an-Application)
Key files:
- `deploying-an-application-1b7a3be.md`
- `deployment-configuration-1c85927.md`
- `generate-deployment-configuration-abap-c06b9cb.md`
- `generate-deployment-configuration-cloud-foundry-41e63bd.md`
- `sap-fiori-launchpad-configuration-bc3cb89.md`
- `deployment-of-application-607014e.md`
- `undeploy-an-application-70872c4.md`
- `security-8a147c6.md`

375
references/getting-started.md Normal file
View File

@@ -0,0 +1,375 @@
# Getting Started Reference
Comprehensive reference for setting up and migrating SAP Fiori tools projects.
## Table of Contents
1. [Installation](#installation)
2. [Migration from SAP Web IDE](#migration-from-sap-web-ide)
3. [Importing Applications](#importing-applications)
4. [ADT Integration](#adt-integration)
5. [Command Palette Reference](#command-palette-reference)
6. [Telemetry](#telemetry)
7. [Security Best Practices](#security-best-practices)
---
## Installation
### Visual Studio Code
**Prerequisites**:
| Requirement | Details |
|-------------|---------|
| Node.js | LTS version required |
| npm | Compatible version with Node.js |
| MTA Tool | `npm install -g mta` (version 1.0+) |
| CF CLI | Latest Cloud Foundry CLI |
**Windows Node.js Setup**:
1. Download Windows installer from nodejs.org (requires admin rights) or standalone binary
2. Extract binary to `C:\Users\<your_user>\AppData\Local\Programs`
3. Set `NODE_PATH` environment variable pointing to Node folder
4. Add `%NODE_PATH%` to System variables Path
5. Restart computer after changes
**macOS Node.js Setup**:
Use package manager: Homebrew or Node Version Manager (nvm)
**npm Configuration Check**:
```bash
npm config get @sap:registry
```
Expected values: `[https://registry.npmjs.org`](https://registry.npmjs.org`) or `undefined`
If set incorrectly to `@sap`, remove entry from `.npmrc` file in home directory.
**Required Extensions**:
Install **SAP Fiori tools - Extension Pack** which includes:
- Application Wizard
- Application Modeler
- Guided Development
- Service Modeler
- XML Annotation Language Server
- XML Toolkit
**Optional Extensions**:
- SAP CDS Language Support (for CAP applications)
- UI5 Language Assistant Support (control ID checks)
### SAP Business Application Studio
**Dev Space Types with SAP Fiori Tools**:
1. **SAP Fiori Dev Space** - Dedicated for Fiori development
2. **Full Stack Cloud Application Dev Space** - For CAP applications
**Setup Steps**:
1. Complete SAP Business Application Studio onboarding
2. Create dev space with appropriate type
3. Start dev space and begin development
**Note**: UI5 Language Assistant is installed automatically in SAP Fiori tools Dev Spaces.
### Authentication Methods
| Type | On Premise | ABAP Environment | Cloud Foundry | S/4HANA Cloud |
|------|-----------|------------------|---------------|---------------|
| OAuth 2.0 | No | Deprecated | No | No |
| Basic Auth | Yes | No | Yes | No |
| Reentrance Ticket | No | Yes | Yes | Yes |
### Required OData Services (SAML Disabled)
| Service | Path |
|---------|------|
| OData V2 Catalog | `/sap/opu/odata/IWFND/CATALOGSERVICE;v=2` |
| OData V4 Catalog (dev) | `/sap/opu/odata4/iwfnd/config/default/iwfnd/catalog/0001` |
| OData V4 Catalog (prod) | `/sap/opu/odata4/iwfnd/config/default/iwfnd/catalog/0002` |
| ATO Catalog | `/sap/bc/adt/ato/settings` |
| SAPUI5 Repository | `/sap/opu/odata/UI5/ABAP_REPOSITORY_SRV` |
---
## Migration from SAP Web IDE
### Overview
SAP Fiori tools enables migrating projects from SAP Web IDE to VS Code or SAP Business Application Studio.
**Note**: SAP Web IDE requires productive SAP BTP global account (not available on free tier).
### Supported Project Types
- SAP Fiori elements (V2 and V4)
- Freestyle SAPUI5
- SAPUI5 Adaptation Projects
- SAPUI5 Extensibility projects
### Prerequisites
- Latest SAP Fiori tools extensions installed
- Project functioning properly in SAP Web IDE
- **BAS**: Destination defined for target system
- **VS Code**: Knowledge of target system hostname and client
### Migration Steps
1. **Import/Clone Project**
- Clone from Git repository, OR
- Export from SAP Web IDE and drag into workspace
2. **Launch Migration**
- Click "Start Migration" prompt, OR
- Command Palette: `Fiori: Migrate Project for use in Fiori tools`
3. **Select Projects**
- Check desired projects in list
- Manually add via filesystem if not detected
4. **Configure Settings**
| Field | Description |
|-------|-------------|
| Application Identifier | Unique app ID |
| Project Path | Target location |
| SAP System | Target ABAP system |
| Destination (BAS) | Destination name |
| Hostname (VS Code) | System URL |
| Client | SAP client number |
| SAPUI5 Version | Target UI5 version |
5. **Execute Migration**
- Click "Start Migration"
- Packages install automatically
### Files Modified During Migration
Approximately 13 files updated including:
- `package.json`
- `ui5.yaml`
- `manifest.json`
- `index.html`
- `changes_loader.js` (created)
- `locate-reuse-libs.js` (created)
### Post-Migration Steps
**CRITICAL**: Migration doesn't update deployment configuration!
```bash
npm run deploy-config
```
**Verification**:
- Review source control changes
- Test SAP Fiori tools features (Page Map, Application Generator)
- Sync OData services if `metadata.xml` is missing
---
## Importing Applications
### From SAPUI5 ABAP Repository
**Prerequisites**:
Create two folders in workspace:
- `restore-from-exported` - stores restored application
- `restore-from-exported/webapp` - contains extracted files
### Import Procedure
1. Access SAPUI5 ABAP backend system
2. Open transaction `SE80`
3. Execute report `/UI5/UI5_REPOSITORY_LOAD`
4. Enter SAPUI5 application name
5. Select Download and choose empty folder
6. Download as `.zip` archive
7. Extract to `restore-from-exported/webapp`
- Ensure `manifest.json` at exact path
8. Create `package.json` in `restore-from-exported`:
```json
{
"name": "your-app-name",
"version": "1.0.0"
}
```
9. Run: `Fiori: Migrate Project for use in Fiori tools`
10. Complete migration process
### Important Notes
- Downloaded code typically minified
- `-dbg.js` files contain unminified source
- Before UI5 CLI build, remove:
- `-dbg.js` files
- `-preload.js` files
- `.js.map` files
---
## ADT Integration
### Overview
Launch SAP Fiori Generator directly from ABAP Development Tools in Eclipse.
### One-Time Configuration
1. Select target system in ADT
2. Access system properties
3. Navigate to ABAP Development settings
4. Enable IDE configuration option
5. Specify preferred IDE (BAS or VS Code)
### Features
**Streamlined Project Creation**:
- "Create Fiori Project" button appears near service details
- Data source selection step skipped (already selected in ADT)
- Main entity pre-selected
**Application Download**:
- Quick Fiori Application generator option
- Downloads deployed application to workspace
- Updates for SAP Fiori tools compatibility
**Direct Command**:
```
Fiori: Download ADT Deployed App from SAPUI5 ABAP Repository
```
**Important**: VS Code saved ABAP system URL must match ADT URL.
---
## Command Palette Reference
Access via `Cmd/Ctrl + Shift + P`, then type "Fiori:"
### Project Management
| Command | Description |
|---------|-------------|
| Add SAP System | Create/save ABAP On-Premises or ABAP Environment connection |
| Import SAP System | Import ABAP On-Premise systems |
| Show SAP System Details | View saved system configuration |
| Archive Project | Preserve project state |
| Validate Project | Check project integrity |
| Migrate Project | Transition from SAP Web IDE |
### Application Development
| Command | Description |
|---------|-------------|
| Open Application Generator | Create SAP Fiori application |
| Open Reusable Library Generator | Create shareable components |
| Delete Application from CAP Project | Remove apps from multi-app setups |
| Open Application Info | Display application metadata |
### Configuration & Deployment
| Command | Description |
|---------|-------------|
| Add Deployment Configuration | Setup deployment parameters |
| Deploy Application | Execute deployment |
| Add SAP Fiori Launchpad Configuration | Prepare for launchpad |
| Add SAP Fiori Launchpad Embedded Configuration | Enable external preview |
| Change Minimum SAPUI5 Version | Update version requirements |
| Add Configuration for Variants Creation | Enable variant management |
### Development Tools
| Command | Description |
|---------|-------------|
| Open Guided Development | Generate code snippets for features |
| Open Service Modeler | Visualize OData models |
| Open Annotation File Manager | Manage annotation files |
| Open Data Editor | Launch data editing interface |
| Show Page Editor | Outline view of configurable elements |
| Show Page Map | Application pages and navigation paths |
| Open Run Configurations | Configure preview settings |
### Navigation & Preview
| Command | Description |
|---------|-------------|
| Preview Application | Execute start script |
| Enable App-to-App Navigation Preview | Test navigation between apps |
| Open CF Application Router Generator | Create MTA deployment config |
### System & Utilities
| Command | Description |
|---------|-------------|
| Open Environment Check | Check/create environment reports |
| Change Telemetry Settings | Control data collection |
| Show Release Notes | Display version information |
| Show Output Channel | Open diagnostics view |
| Restart XML Annotation Language Server | Recover failed services |
| Run UI5 Linter | Validate SAPUI5 best practices |
| Refresh Application Modeler View | Update UI state |
### AI Assistance
| Command | Description |
|---------|-------------|
| Show Fiori Tools Joule | Activate AI assistant (requires SAP Build Code) |
---
## Telemetry
### Overview
SAP Fiori tools collects non-personally identifiable usage information to improve the product.
### Configuration
```
Fiori: Change Telemetry Settings
```
Toggle telemetry collection on/off according to preference.
---
## Security Best Practices
### Development Security
- Follow organization's software development security policies
- **Avoid using production OData services for development**
- Use separate credentials for development vs production
- Use trusted NPM registry
- Apply security guidelines for all required tools
- Implement source control with regular commits
### Path Variable Security
Verify PATH variable content:
- `node` command points to trusted origin
- `cds` command points to trusted origin
### Reporting Issues
1. Check SAP Fiori tools FAQs
2. Search SAP Community
3. Create incident in SAP Support Portal
- Component: `CA-UX-IDE`
---
## Documentation Source
**GitHub**: [https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs/Getting-Started-with-SAP-Fiori-Tools](https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs/Getting-Started-with-SAP-Fiori-Tools)
Key files:
- `getting-started-with-sap-fiori-tools-2d8b1cb.md`
- `installation-e870fcf.md`
- `visual-studio-code-17efa21.md`
- `sap-business-application-studio-b011040.md`
- `migration-70d41f3.md`
- `importing-an-application-ab4657c.md`
- `abap-development-tools-integration-20da2fd.md`
- `command-palette-4896dcc.md`
- `telemetry-837c231.md`
- `report-issues-and-security-7c755a5.md`

482
references/page-editor.md Normal file
View File

@@ -0,0 +1,482 @@
# Page Editor Reference
Detailed configuration reference for the SAP Fiori tools Page Editor.
## Table of Contents
1. [List Report Page](#list-report-page)
2. [Object Page](#object-page)
3. [Extension-Based Elements](#extension-based-elements)
4. [Building Blocks](#building-blocks)
5. [Quick Actions](#quick-actions)
---
## List Report Page
### Filter Fields
Configure filter bar elements for data discovery.
**Types**:
- **Compact Filters**: Fields with value help
- **Visual Filters**: Charts with selectable elements (analytics-enabled services)
**Adding**: Page Map > Configure Page > Add icon next to Filter Bar > Filter Fields
Generates `UI.SelectionFields` annotation.
**Excluded Properties**: `UI.Hidden`, `UI.HiddenFilter`, `NonFilterableProperties`
**Editable Properties (Compact)**: Label, External ID, Text, Text Arrangement, Display Type
**Visual Filter Properties**: Measure/Dimension Labels, Scale Factor, Fractional Digits, Sort Order, Fixed Values
### Table Configuration
**Supported Table Types**: Responsive, Grid, Analytical, Tree (hierarchical data)
**Column Types (7)**:
| Column Type | Description |
|-------------|-------------|
| Basic Column | Standard value display (String, Decimal) |
| Chart Column | Inline chart visualization |
| Contact Column | Contact information display |
| Progress Column | Progress indicator |
| Rating Column | Star rating display |
| Table Actions | Actionable elements |
| External Navigation | External navigation links |
**Column Properties**:
- **Label**: From `Common.Label` or `@title`, customizable
- **Importance**: Controls small-screen visibility (None = hidden)
- **Hidden**: Conditional hiding via boolean property
### Table Actions
**Action Types**:
| Type | Annotation | Description |
|------|------------|-------------|
| Internal | `UI.DataFieldForAction` | Operations within app using bound actions |
| External | `UI.DataFieldForIntentBasedNavigation` | Navigate to other FLP apps |
**Placement**: Toolbar or Inline (column)
**Properties**:
- Label (from `Common.Label` or `@title`)
- Importance (column actions only)
- Criticality (Positive/Negative for inline only)
- Hidden (conditional)
- Semantic Object Mapping (external navigation)
- Requires Context (toolbar external navigation)
### Multiple Views
Display additional tables/charts in separate tabs via icon tab bar.
**Requirements**:
- `@Aggregation.ApplySupported` at service level
- Custom aggregations: `@Aggregation.CustomAggregate`
- Transformation aggregations: SAPUI5 1.106+
- Cannot coexist with Analytical Charts
**Adding Views**:
1. Click Add icon on Views node
2. Select table or chart view type
3. Choose Entity from OData Service
4. For charts: specify type, dimension, measure
Generates `UI.LineItem` or `UI.Chart` with qualifiers, updates `manifest.json`.
**Management**: Drag-and-drop reordering, delete icon (cannot remove last main entity table view)
### Analytical Chart
Add aggregated data visualization to List Report.
**Prerequisites**:
- No Multiple Views in List Report
- Main entity has aggregable/groupable properties
- Transformation aggregations: SAPUI5 1.106+
**Adding**:
1. Click "Add Chart" in Page Editor header
2. Select chart type
3. Choose dimension (groupable property)
4. Choose measure (aggregable property or create new)
**Configuration Properties**:
| Property | Description |
|----------|-------------|
| Chart Type | Visualization style |
| Title | Display text (supports i18n) |
| Measures | Aggregated values (min 1 default, cannot add same twice) |
| Dimensions | Groupable categories (min 1 default) |
| Presentation Variant | Controls sorting (New, From Table, None) |
**Note**: Sort order applies to both chart and table.
---
## Object Page
### Header Configuration
Based on `@UI.HeaderInfo` annotation.
**Header Properties**:
| Property | Description |
|----------|-------------|
| Type Name/Plural | String describing main object |
| Title | Displayed in header area |
| Description | Additional context |
| Image | Reference via `ImageUrl` |
| Initials | Path to string properties |
| Icon URL | SAP icon format (e.g., `sap-icon://accept`) |
**Header Actions**:
- **Standard Actions**: Edit, Delete (can be hidden conditionally)
- **Annotation-Based**: `UI.DataFieldForAction`, `UI.DataFieldForIntentBasedNavigation`, `UI.DataFieldForActionGroups`
- **Custom Actions**: Based on application extensions
**Header Sections (7 Types)**:
| Section | Description |
|---------|-------------|
| Form Section | Groups multiple fields |
| Data Point | Single key metrics with semantic coloring |
| Progress | Progress toward targets |
| Rating | Star ratings (default 5-star) |
| Bullet Micro Chart | Values on scales with targets |
| Area/Column/Line Micro Chart | Trend visualization |
| Radial/Comparison/Harvey/Stacked Bar | Additional chart types |
Reorder sections via drag-and-drop (updates `UI.HeaderFacets`).
### Section Types
#### Form Section
Based on `UI.FieldGroup` annotation.
**Adding**:
1. Open Page Editor for Object/Form Entry Page
2. Navigate to section node > Add icon
3. Choose "Add Form Section"
4. Enter label
**Properties**:
- Label: Section title
- Display on Demand: Hide content under "Show More"
- Hidden: Visibility control
#### Table Section
**Adding**:
1. Open Page Editor
2. Section node > Add icon > "Add Table Section"
3. Enter label and Value Source Entity
Generates `UI.LineItem` annotation with reference facet.
**Properties**: Label, Hidden
#### Identification Section
Display key identifying information prominently.
#### Chart Section
Embed charts within Object Page for data visualization.
#### Group Section
Group related content logically with collapsible containers.
### Footer Configuration
Actions from `UI.DataFieldForAction` records where `Determining = true`.
**Limitations**:
- External navigation actions NOT allowed in footer
- Importance and Requires Context properties don't apply
**Criticality**: Affects action ordering (Positive/Negative reorganizes nodes)
### Basic Fields
**Adding Fields**:
1. Expand section > click add button
2. Search/select fields from dropdown
3. Multiple fields can be added simultaneously
**Excluded Properties**:
- `Edm.Guid` type properties
- Draft properties: `IsActiveEntity`, `HasActiveEntity`, `HasDraftEntity`
- Draft navigation: `SiblingEntity`, `DraftAdministrativeData`
- Already referenced properties
- Duplicates within same section
**Moving Fields**:
- Drag-and-drop (highlights green when valid)
- Arrow buttons (up/down)
- Multi-select: Ctrl+Click
- Cross-section only when same entity `FieldGroup`/`Identification`
**Field Properties**:
| Property | Description |
|----------|-------------|
| Label | Display text |
| Criticality | Semantic coloring |
| Display as Image | Image rendering |
| External ID | External identifier |
| Hidden / Hide by Property | Visibility control |
| Restrictions | Input control |
| Semantic Object Name/Mapping | Navigation |
| Text / Text Arrangement | Display format |
| Display Type | Rendering type |
**Restrictions (Input Control)**:
| Option | Behavior |
|--------|----------|
| None | No annotations, defaults to optional |
| Optional | Field may remain empty |
| Mandatory | Value required |
| ReadOnly | Non-editable display-only |
**Note**: Read-only objects disable Display Type and Restrictions properties.
---
## Extension-Based Elements
### Custom Columns (OData V4)
Add custom columns with XML fragments:
**Configuration Steps**:
1. Select Table in Page Editor
2. Add > Custom Column
3. Provide: Header text, Fragment name, Anchor column, Placement
4. Optional: Generate event handler
**Generated Files**:
- Fragment: `webapp/ext/fragments/<name>.fragment.xml`
- Controller (optional): `webapp/ext/<name>.controller.js`
**Fragment Template**:
```xml
<core:FragmentDefinition xmlns:core="sap.ui.core" xmlns="sap.m">
<Text text="{PropertyPath}" id="customColumn"/>
</core:FragmentDefinition>
```
### Custom Sections (OData V4)
Add custom sections to Object Page:
**Configuration**:
- Section title
- View type: Fragment (V4) or View (V2)
- Fragment/View name
- Anchor section and placement
- Generate event handler option
**Fragment Location**: `webapp/ext/fragments/`
### Custom Actions (OData V4 1.96+)
Add action buttons with custom handlers:
**Configuration**:
- Action ID (unique identifier)
- Button Text
- Anchor and Placement
- Action Handler File
- Handler Method name
- Requires Selection toggle (for table actions)
**Handler Template**:
```javascript
sap.ui.define([], function() {
"use strict";
return {
onCustomAction: function(oEvent) {
// Custom action logic
}
};
});
```
### Custom Views (OData V4 1.96.29+)
Add custom tab views to List Report:
**Configuration**:
- View Key (unique)
- Label text
- Fragment selection
- Event handler generation
### Controller Extensions
Extend page controller lifecycle and methods:
**Lifecycle Methods**:
- `onInit` - Component initialization
- `onBeforeRendering` - Before UI rendering
- `onAfterRendering` - After UI rendering
- `onExit` - Component destruction
**Override Pattern**:
```javascript
sap.ui.define(["sap/ui/core/mvc/ControllerExtension"], function(ControllerExtension) {
return ControllerExtension.extend("customer.extension.MyExtension", {
override: {
onInit: function() {
// Extension logic
}
},
// Custom methods outside override
myCustomMethod: function() {
// Custom logic
}
});
});
```
**File Locations**:
- Extension: `webapp/changes/coding/<name>.js`
- Change descriptor: `webapp/changes/<name>.controllerExtension.change`
---
## Building Blocks
Reusable UI components for OData V4 custom pages and sections.
### Chart Building Block
Embed charts in custom UI:
```xml
<macros:Chart
id="chartBlock"
metaPath="@com.sap.vocabularies.UI.v1.Chart"
contextPath="/EntitySet"/>
```
### Filter Bar Building Block
Add filter capabilities:
```xml
<macros:FilterBar
id="filterBar"
metaPath="@com.sap.vocabularies.UI.v1.SelectionFields"
liveMode="true"/>
```
### Table Building Block
Display tabular data:
```xml
<macros:Table
id="tableBlock"
metaPath="@com.sap.vocabularies.UI.v1.LineItem"
readOnly="true"/>
```
### Page Building Block
Container for custom pages:
```xml
<macros:Page id="customPage">
<!-- Page content -->
</macros:Page>
```
### Rich Text Editor Building Block
Content editing in custom sections:
```xml
<macros:RichTextEditor
id="richTextEditor"
value="{Description}"/>
```
---
## Quick Actions
Page Editor provides quick action shortcuts for common operations:
| Quick Action | Description | Availability |
|--------------|-------------|--------------|
| Add Custom Page Action | Add action to page header | Object Page |
| Add Custom Table Action | Add action to table toolbar | List Report, Object Page |
| Add Custom Table Column | Add custom column | List Report, Object Page |
| Add Header Field | Add field to header | Object Page |
| Add Custom Section | Add custom section | Object Page |
### Accessing Quick Actions
1. Right-click element in Page Editor outline
2. Select from context menu
3. Configure in dialog
---
## Configuration Files
### Manifest.json Updates
Page Editor modifications update `manifest.json`:
```json
{
"sap.ui5": {
"routing": {
"targets": {
"ListReport": {
"options": {
"settings": {
"content": {
"header": {},
"body": {}
}
}
}
}
}
}
}
}
```
### UI Flexibility Changes
Custom extensions generate flexibility changes in `webapp/changes/`:
- `addXML.change` - Fragment additions
- `controllerExtension.change` - Controller extensions
- `propertyChange.change` - Property modifications
---
## Documentation Source
**GitHub**: [https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs/Developing-an-Application](https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs/Developing-an-Application)
Key files:
- `list-report-page-493f2aa.md`
- `form-and-object-page-1eb11a6.md`
- `maintaining-extension-based-elements-02172d2.md`
- `maintaining-building-blocks-6d3ad83.md`
- `supported-elements-in-page-editor-47f0424.md`

511
references/preview.md Normal file
View File

@@ -0,0 +1,511 @@
# Preview Reference
Comprehensive reference for previewing SAP Fiori applications during development.
## Table of Contents
1. [Preview Overview](#preview-overview)
2. [NPM Scripts](#npm-scripts)
3. [Run Control](#run-control)
4. [Mock Data](#mock-data)
5. [Live Data](#live-data)
6. [App-to-App Navigation](#app-to-app-navigation)
7. [External FLP Preview](#external-flp-preview)
8. [Developer Variants](#developer-variants)
9. [SAP Horizon Theme](#sap-horizon-theme)
10. [Virtual Endpoints](#virtual-endpoints)
11. [CAP Project Preview](#cap-project-preview)
---
## Preview Overview
SAP Fiori tools provides multiple preview options:
| Method | Use Case |
|--------|----------|
| NPM Scripts | Quick terminal-based preview |
| Run Control | IDE-integrated launch configurations |
| Context Menu | Right-click folder quick commands |
### Default Preview Port
Applications run on `localhost:8080` by default. If port is in use, system selects next available port.
### HTTPS/SSL Considerations
- `localhost` serves as HTTP proxy to backend services
- Domain security policies may require HTTPS
- Configure browser to trust local certificates if needed
---
## NPM Scripts
### Available Scripts
| Script | Command | Description |
|--------|---------|-------------|
| start | `npm start` | Live data from backend OData service |
| start-mock | `npm run start-mock` | Mock data via MockServer |
| start-local | `npm run start-local` | Mock data + local SAPUI5 resources |
| start-noflp | `npm run start-noflp` | Without Fiori launchpad sandbox |
### Running Scripts
**VS Code**:
1. Open terminal: `Ctrl + `` `
2. Navigate to project root
3. Run script: `npm run start-mock`
**SAP Business Application Studio**:
1. Open terminal: Terminal > New Terminal
2. Navigate to project root
3. Run script: `npm run start-mock`
**Context Menu**:
Right-click project folder and select from available scripts.
---
## Run Control
### Configuration Location
```
<workspace_root>/.vscode/launch.json
```
**Important**: Run Control only searches root-level `.vscode/` folder, not subfolders.
### Sample launch.json
```json
{
"version": "0.2.0",
"configurations": [
{
"name": "Start app-name",
"type": "node",
"request": "launch",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "start"],
"cwd": "${workspaceFolder}",
"console": "integratedTerminal"
},
{
"name": "Start app-name (mock)",
"type": "node",
"request": "launch",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "start-mock"],
"cwd": "${workspaceFolder}",
"console": "integratedTerminal"
}
]
}
```
### Multi-Root Workspace
Multiple configurations can be merged:
1. Add folders as workspace roots
2. Each root's `launch.json` configurations become available
3. Access via Run and Debug view
### Creating Run Configurations
**VS Code**:
```
Fiori: Create Run Configuration (VS Code)
```
**SAP Business Application Studio**:
```
Fiori: Create Run Configuration (BAS)
```
---
## Mock Data
### MockServer Setup
Install MockServer:
```
Fiori: Install MockServer
```
Or manually:
```bash
npm install @sap-ux/ui5-middleware-fe-mockserver --save-dev
```
### Mock Data Location
```
webapp/localService/mockdata/
├── EntitySet.json
├── AssociatedEntitySet.json
└── ...
```
### Mock Data Format
```json
[
{
"ID": "1",
"Name": "Product 1",
"Price": 100.00,
"Currency": "USD"
},
{
"ID": "2",
"Name": "Product 2",
"Price": 200.00,
"Currency": "EUR"
}
]
```
### Data Editor
Visual mock data management tool.
**Launch**:
Via Application Info page > Start Data Editor
**Features**:
- Edit cells by double-clicking (primary/foreign keys excluded)
- Add rows with automatic cascading to related entities
- Delete rows with cascading deletions
- Search functionality
- Show/hide columns
**Configuration for Live Updates**:
Add to `ui5-mock.yaml`:
```yaml
server:
customMiddleware:
- name: "@sap-ux/ui5-middleware-fe-mockserver"
configuration:
watch: true
```
### AI Mock Data Generation
Generate contextual mock data using entity property names.
**Requirements**:
- SAP Build Code subscription or Test Drive access
- EDMX project with `metadata.xml` file
**Launch**:
Via Page Editor > Generate Mock Data action
---
## Live Data
### Configuration
Live data preview connects to actual backend OData services.
**Requirements**:
- Backend system accessible
- Authentication configured
- Destination set up (BAS) or system connection (VS Code)
### Start Command
```bash
npm start
```
### ui5.yaml Configuration
```yaml
server:
customMiddleware:
- name: fiori-tools-proxy
afterMiddleware: compression
configuration:
backend:
- path: /sap
url: [https://backend.system.com](https://backend.system.com)
destination: BACKEND_DESTINATION
```
---
## App-to-App Navigation
### Enable Navigation Preview
```
Fiori: Enable App-to-App Navigation Preview
```
### Configuration Steps
1. Execute command via Command Palette
2. Select source application
3. Select destination application(s)
4. Launch source app preview
5. Execute navigation
### Generated Files
**Source Application**:
- `appconfig/fioriSandboxConfig.json` - FLP sandbox configuration
- Updated `ui5.yaml` - Middleware configuration
### fioriSandboxConfig.json Structure
```json
{
"applications": {
"destination-app-semantic-object-action": {
"additionalInformation": "SAPUI5.Component=namespace.destination",
"applicationType": "URL",
"url": "../destination-app/",
"title": "Destination App"
}
}
}
```
### Requirements
- Both applications in same workspace
- Configured external navigation in source app
- Matching semantic objects and actions
---
## External FLP Preview
### Purpose
Preview application within actual SAP Fiori launchpad environment.
### Configuration
```
Fiori: Preview on External Fiori Launchpad
```
### Parameters
| Parameter | Description |
|-----------|-------------|
| FLP URL | URL of target Fiori launchpad |
| Semantic Object | Application semantic object |
| Action | Navigation action |
### Use Cases
- Test FLP-dependent features
- Verify tile configuration
- Test cross-application navigation
---
## Developer Variants
### Purpose
Create and test page variants during development.
### Creating Variants
```
Fiori: Create Developer Variant
```
### Variant Types
- Filter variants
- Table variants
- Page variants
### Storage
Developer variants stored locally, not deployed to backend.
---
## SAP Horizon Theme
### Preview with Horizon Theme
```
Fiori: Preview with SAP Horizon Theme
```
### About SAP Horizon
SAP Horizon is SAP's evolved design language with:
- Modern visual design
- Improved accessibility
- Enhanced user experience
### Theme Variants
| Theme | Description |
|-------|-------------|
| sap_horizon | Light theme |
| sap_horizon_dark | Dark theme |
| sap_horizon_hcb | High contrast black |
| sap_horizon_hcw | High contrast white |
---
## Virtual Endpoints
### Purpose
Convert project to use virtual endpoints for simplified proxy configuration.
### Convert Command
```
Fiori: Convert to Virtual Endpoints
```
### Benefits
- Simplified destination configuration
- Consistent endpoint naming
- Easier multi-system setup
### Configuration Update
Updates `ui5.yaml` with virtual endpoint mappings.
---
## CAP Project Preview
### Prerequisites
- CAP project with `cds` dependencies
- Node.js or Java runtime
- Database configured (SQLite for development)
### Starting Preview
**Node.js CAP**:
```bash
cds watch
```
**Java CAP**:
```bash
mvn spring-boot:run
```
### Fiori Preview in CAP
From CAP project root:
```bash
npm run start
```
Or use Run Control with CAP-specific configuration.
### Supported Templates for CAP
- List Report Object Page (OData V4)
- Analytical List Page (OData V4)
### CAP-Specific ui5.yaml
```yaml
specVersion: "2.4"
metadata:
name: cap-app
type: application
server:
customMiddleware:
- name: fiori-tools-proxy
afterMiddleware: compression
configuration:
backend:
- path: /odata/v4
url: [http://localhost:4004](http://localhost:4004)
```
---
## Custom Middlewares
### Adding Custom Middleware
Create custom server middleware for specialized preview needs.
### Configuration
In `ui5.yaml`:
```yaml
server:
customMiddleware:
- name: my-custom-middleware
afterMiddleware: compression
configuration:
option1: value1
```
### Use Cases
- Custom authentication handling
- Request/response modification
- Logging and debugging
- Feature flags
---
## Troubleshooting
### Port Already in Use
System automatically selects next available port. Check terminal output for actual port.
### SSL Certificate Errors
Configure browser to trust localhost certificates or use HTTP for development.
### Backend Connection Failed
1. Verify destination/system configuration
2. Check authentication credentials
3. Confirm backend service is accessible
4. Review proxy configuration in ui5.yaml
### Mock Data Not Loading
1. Verify MockServer is installed
2. Check mock data file names match entity sets
3. Validate JSON syntax in mock data files
4. Ensure metadata.xml is present
---
## Documentation Source
**GitHub**: [https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs/Previewing-an-Application](https://github.com/SAP-docs/btp-fiori-tools/tree/main/docs/Previewing-an-Application)
Key files:
- `previewing-an-application-b962685.md`
- `use-mock-data-bda83a4.md`
- `use-live-data-497aee2.md`
- `generating-mock-data-with-ai-815c310.md`
- `run-control-overview-d7f20f3.md`
- `app-to-app-navigation-preview-543675f.md`
- `preview-an-application-on-external-sap-fiori-launchpad-c789692.md`
- `developer-variant-creation-ceb845a.md`
- `preview-an-application-with-the-sap-horizon-theme-2a42256.md`
- `use-custom-middlewares-dce5315.md`
- `previewing-an-sap-fiori-elements-cap-project-1dc179a.md`