- SAP Managed Tags:
Those who develop applications with the SAP Cloud Application Programming model (aka CAP) sometimes get stuck when it comes to maintaining annotations for SAP Fiori apps. Which annotations do I use? What do they look like in CAP CDS (core data services) syntax? How can I make sure I defined them correctly with no typographical errors that will break my UI (user interface)? And, if I do have a typo, how can I quickly find and fix it? In short, when will I have language server protocol (LSP) support for annotations in my CDS projects?
Ever since we released the XML annotation LSP as part of SAP Fiori tools, we often receive questions from the CAP and SAP Fiori development communities on whether similar functionality will be provided for CAP core data services (aka CDS).
The good news is that SAP CDS language support plugin is now enhanced with a new module that helps you add and edit OData annotations applied to CDS models more efficiently.
It provides the basic LSP features for OData annotations such as code completion, diagnostics, navigation to the referenced annotations, preview of vocabulary information and basic i18n support.
Let’s look deeper into the enhancements provided by this module to see how you can speed up the definition of annotations used in Fiori UIs while working in CAP CDS projects.
From the functional perspective, it is very similar to XML annotation LSP extension provided as part of SAP Fiori tools. The main difference is that it works with the OData annotations in .cds files rather than in xml annotation files.
Code Completion
When you need to define annotations serving Fiori UIs in your .cds files, you can use the code completion for adding and editing annotations applied to service entities and elements. Just use CTRL + Space on Windows or CMD + Space on Mac in your annotate directive or next to your entity definition and choose from the list of applicable annotations to add. You can also choose to add just a vocabulary alias and then add several annotations from that vocabulary to the same annotate directive in the next steps.
Due to the built-in micro-snippets, the annotations are added along with the basic structure, so you do not need to remember and add it manually. Then, you can use the code completion again to define a qualifier and move with the Tab along the tab stops within the annotation body. Code completion can be used at each tab stop to add annotation records and properties, You can also select values for these properties, be they entity elements, Boolean or enumeration values, or even references to other annotations provided in the same file or underlying ones.
You can check the vocabulary definition of the annotations and their elements while hovering over the annotation in the file or in the code completion lists.
Diagnostics
Every time you open or modify the .cds files, all OData annotations it contains are validated against the OData vocabularies and service metadata. If the annotation structure or any of its elements does not match the definition in the OData vocabulary, the respective part is highlighted and accompanied with a warning or error message. The same is true for the values you use in annotation properties, e.g. if you reference a path to a non-existing entity element or not yet defined annotation.
Internationalization (i18n) Support
Additional diagnostics are triggered when you define the labels for language-dependent texts. If it is a hard-coded string value, it gets highlighted with a warning. You can then use a recommended Quick Fix action to replace the hard-coded text with a reference to the auto-generated text key/value pair in the i18n file. Yes, all this in just one click!
Viewing /Modifying Referenced Annotations
With the built in Go to Definition and Pick Definition support, you can view the source of the referenced annotations and, if desired, update its definition.
If you are as excited to try the OData annotation support as our beta customers and partners are, you can download the SAP CDS language support plugin version 3.0 from the Visual Studio Code marketplace. It will then automatically get the CDS OData Language Server module for annotations from npmjs.com.
If you use SAP Business Application Studio, you can find it in the SAP Cloud Business Application dev space since November 08, 2020. Nothing to download or configure; everything is pre-installed.
More information on OData annotation support in CAP CDS
Ever since we released the XML annotation LSP as part of SAP Fiori tools, we often receive questions from the CAP and SAP Fiori development communities on whether similar functionality will be provided for CAP core data services (aka CDS).
The good news is that SAP CDS language support plugin is now enhanced with a new module that helps you add and edit OData annotations applied to CDS models more efficiently.
It provides the basic LSP features for OData annotations such as code completion, diagnostics, navigation to the referenced annotations, preview of vocabulary information and basic i18n support.
Annotation LSP for CAP CDS
Let’s look deeper into the enhancements provided by this module to see how you can speed up the definition of annotations used in Fiori UIs while working in CAP CDS projects.
From the functional perspective, it is very similar to XML annotation LSP extension provided as part of SAP Fiori tools. The main difference is that it works with the OData annotations in .cds files rather than in xml annotation files.
Code Completion
When you need to define annotations serving Fiori UIs in your .cds files, you can use the code completion for adding and editing annotations applied to service entities and elements. Just use CTRL + Space on Windows or CMD + Space on Mac in your annotate directive or next to your entity definition and choose from the list of applicable annotations to add. You can also choose to add just a vocabulary alias and then add several annotations from that vocabulary to the same annotate directive in the next steps.
Code completion for OData annotations in SAP CAP CDS
Due to the built-in micro-snippets, the annotations are added along with the basic structure, so you do not need to remember and add it manually. Then, you can use the code completion again to define a qualifier and move with the Tab along the tab stops within the annotation body. Code completion can be used at each tab stop to add annotation records and properties, You can also select values for these properties, be they entity elements, Boolean or enumeration values, or even references to other annotations provided in the same file or underlying ones.
Referencing annotations with code completion in .cds files
You can check the vocabulary definition of the annotations and their elements while hovering over the annotation in the file or in the code completion lists.
Viewing annotation definitions on hover
Diagnostics
Every time you open or modify the .cds files, all OData annotations it contains are validated against the OData vocabularies and service metadata. If the annotation structure or any of its elements does not match the definition in the OData vocabulary, the respective part is highlighted and accompanied with a warning or error message. The same is true for the values you use in annotation properties, e.g. if you reference a path to a non-existing entity element or not yet defined annotation.
Validating OData annotations in .cds files
Internationalization (i18n) Support
Additional diagnostics are triggered when you define the labels for language-dependent texts. If it is a hard-coded string value, it gets highlighted with a warning. You can then use a recommended Quick Fix action to replace the hard-coded text with a reference to the auto-generated text key/value pair in the i18n file. Yes, all this in just one click!
Quick fixes for language dependent texts
Viewing /Modifying Referenced Annotations
With the built in Go to Definition and Pick Definition support, you can view the source of the referenced annotations and, if desired, update its definition.
Viewing referenced annotations
If you are as excited to try the OData annotation support as our beta customers and partners are, you can download the SAP CDS language support plugin version 3.0 from the Visual Studio Code marketplace. It will then automatically get the CDS OData Language Server module for annotations from npmjs.com.
If you use SAP Business Application Studio, you can find it in the SAP Cloud Business Application dev space since November 08, 2020. Nothing to download or configure; everything is pre-installed.
More information on OData annotation support in CAP CDS
- SAP CAP documentation https://cap.cloud.sap/docs/advanced/fiori
- SAP CAP release notes https://cap.cloud.sap/docs/releases/sep20#editing-odata-annotations
- My next blog post with "How-to" example: https://blogs.sap.com/2020/11/06/annotating-annotations-in-sap-cloud-application-programming-cap-wit...
21 Comments
