Product Information
Maintaining annotations in CAP CDS projects becomes easier with new LSP features
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.
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-with-code-completion/
Please note that updating SAP Business Application Studio with OData annotation support is planned for 08.11.2020.
Edit: updated the planned date, sorry for inconvenience
OData annotation support will be available in the SAP Cloud Business Application dev spaces of SAP Business Application Studio on November 8, 2020
Edit: updated the planned date, sorry for the inconvenience
Hi Mariana,
Is the support available on the SAP Business Application Studio on the trial landscape?
Ctrl+Space does not seems to trigger the code completion in .cds files.
I'm looking forward to use it.
Thanks and great work!!!
David
Hi David LAPOINTE
Are you on Mac OS?
No. Windows.
Thanks for the info.
Could you please check the version of vscode-cds installed in your dev space?
View->Plugins, then use the browser search for cds and manually scroll down the list. The min. version containing this feature is 3.0.0
Thanks for the quick reply.
It looks like it's version 2.1.4
I'm guessing that it can be upgraded but sorry, I'm fairly new to npm. Can I do it manually or it has to be done on the platform?
Thanks again,
David
David LAPOINTE
Thanks for checking, I’m afraid there is nothing you can do to update it right now in App Studio.
I already informed the colleagues responsible for App Studio updates, need to check whether the trial has a different update schedule.
I will get back to you on this soon.
In the time being you can try this feature in Visual Studio Code with SAP Cloud Platform core data services plug-in for Visual Studio Code V 3.0 is available there already
Great. No problem if it's not present right now. Will check later when it's updated as this look like a great new feature.
Thank you very much for you time. Business Application Studio looks like a great tool.
David LAPOINTE
I've checked with the colleagues - the update is scheduled for November 8th, 2020 sorry for inconvenience. I will update my comment with this updated info
Thanks for your understanding,
Hi David LAPOINTE
The LSP support for OData annotations is now finally available on SAP Business Application Studio (also on Trial). So you can try it out in your SAP Cloud Business Application dev space.
Looking forward to your feedback.
Mariana
Hi Mariana,
I confirm that everything works now. What a great new feature. Keep on the good work.
David
yes yeS yES YES ?
finally, CDS OData annotations via LSP. aiding us devs in CAP apps, reducing the amount of trial'n'error of "where in the code to use what annotation“
i wish you could see the virtual tear of joy rolling down my cheeks ?
now still keeping on hoping for that annotations playground similar to UI5 cards ?
This will be real help. Looking forward to use it in BAS.
Hi Sumit Kumar Kundu
The LSP support for OData annotations is now finally available at SAP Business Application Studio. So you can try it out in your SAP Cloud Business Application dev space.
Looking forward to your feedback.
Mariana
Thanks for the update!
Best regards,
Sumit
Code completion and inline documentation (hovering on the annotation) are working like a charm.. saving me from switching between documentation and editor 🙂
Thanks for your feedback!
I'm glad you like it. Please let me know if you have the improvement proposals
Please note that SAP Cloud Platform core data services plug-in for Visual Studio Code is now renamed to SAP CDS Language Support but it still provides the annotation LSP features described in this post
how to add annotations for value help, I didn't find any example till now, Can you suggest, please.
Hello Ahmed Ali Khan
if you need it for the application based on the Fiori elements List Report/Object Page (OData v 4), the easiest way would be to use the Application Modeler extension of SAP Fiori Tools. It is available for both SAP Business Application Studio and Visual studio code.
Just open a Page Map for your project and choose to edit the page you want to add it to. Then click on the node representing the field you want to update with the value help.
As an example, I here chose the List Report page, expanded the Filter Fields and chose Agency ID.
In the Properties Pane. find the Display Type property and choose the Value Help option. In the pop-up, choose the Value Source Entity (entity containing acceptable values for the field, in my case TravelAgency) and Value Source Property (an element of that entity to be used for input, usually a code or id, in my case Agency ID). This would be a minimum required configuration.
Additionally, you can choose the descriptive text and how this text should be arranged with the code.
Finally, you decide if you want to display it as a drop-down or a Value Help dialog.
When you click Apply, annotations for the value help will be auto-generated. You can always see the generated code by clicking on the Go to code button next to the Value help in the properties pane (it appears on hover.
Hope you find it helpful.
If you want to define it manually you can use my code code snippet below and adjust it based on your service and needs. Using annotation LSP (Ctrl/CMD+Space) will help you to choose the values based on your service
Please let me know if you need further help.
Best Regards,
Mariana