416 lines
10 KiB
Markdown
416 lines
10 KiB
Markdown
# 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`
|