Major Release June 2024

.github/workflows/PR-SAP.yml

@@ -28,7 +28,7 @@ jobs:
           GH_TOKEN:        ${{ secrets.GITHUB_TOKEN }}
           GH_TOKEN_PARENT: ${{ secrets.GH_TOKEN_PARENT }}
       - name: Use Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: 18.x
           cache: 'npm'

.github/workflows/PR.yml

@@ -12,9 +12,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Use Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: 18.x
           cache: 'npm'

.github/workflows/lint.yml

@@ -29,7 +29,7 @@ jobs:
         GH_TOKEN:        ${{ secrets.GITHUB_TOKEN }}
         GH_TOKEN_PARENT: ${{ secrets.GH_TOKEN_PARENT }}
     - name: Use Node.js
-      uses: actions/setup-node@v3
+      uses: actions/setup-node@v4
       with:
         node-version: 18.x
         cache: 'npm'

.github/workflows/main.yml

@@ -25,11 +25,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Setup Pages
-        uses: actions/configure-pages@v3
+        uses: actions/configure-pages@v5
       - name: Use Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: 18.x
           cache: 'npm'

.vitepress/config.ts

@@ -11,7 +11,8 @@ import * as MdAttrsPropagate from './lib/md-attrs-propagate'
 export type CapireThemeConfig = DefaultTheme.Config & {
   capire: {
     versions: { [key: string]: string },
-    gotoLinks: { href:string, key:string, name?:string, hidden?:boolean }[]
+    gotoLinks: { href:string, key:string, name?:string, hidden?:boolean }[],
+    maven_host_base: string
   }
 }
 
@@ -22,8 +23,8 @@ if (!siteURL.pathname.endsWith('/'))  siteURL.pathname += '/'
 const redirectLinks: Record<string, string> = {}
 
 const latestVersions = {
-  java_services: '2.10.0',
-  java_cds4j: '2.10.0'
+  java_services: '3.0.0',
+  java_cds4j: '3.0.0'
 }
 
 const localSearchOptions = {
@@ -74,7 +75,7 @@ const localSearchOptions = {
 } as { provider: 'local'; options?: DefaultTheme.LocalSearchOptions }
 
 const menu = sidebar()
-const nav = nav4(menu) as DefaultTheme.NavItem[]
+const nav = nav4(menu) as DefaultTheme.NavItemWithLink[]
 const loadSyntax = async (file:string, name:string, alias:string=name):Promise<LanguageInput> => {
   const src = await fs.readFile(join(__dirname, file))
   const grammar:RawGrammar = JSON.parse(src.toString())
@@ -83,6 +84,7 @@ const loadSyntax = async (file:string, name:string, alias:string=name):Promise<L
 
 const config:UserConfig<CapireThemeConfig> = {
   title: 'cap≽ire',
+  titleTemplate: ':title | capire', // for the window title
   description: 'Documentation for SAP Cloud Application Programming Model',
   base,
   srcExclude: ['**/.github/**', '**/README.md', '**/LICENSE.md', '**/CONTRIBUTING.md', '**/CODE_OF_CONDUCT.md', '**/menu.md', '**/-*.md'],
@@ -112,7 +114,11 @@ const config:UserConfig<CapireThemeConfig> = {
       {icon: 'github', link: 'https://github.com/cap-js/docs'}
     ],
     outline: [2,3],
-    capire: { versions: latestVersions, gotoLinks: [] }
+    capire: {
+      versions: latestVersions,
+      gotoLinks: [],
+      maven_host_base: 'https://repo1.maven.org/maven2'
+    }
   },
   head: [
     ['meta', { name: 'theme-color', content: '#db8b0b' }],

.vitepress/lib/cds-maven-site.ts

@@ -4,7 +4,7 @@ import AdmZip from 'adm-zip'
 export async function copySiteAssets(outDir:string, site:SiteData) {
   const { themeConfig: { capire }} = site
   const version = capire.versions.java_services
-  const url = `https://repo1.maven.org/maven2/com/sap/cds/cds-maven-plugin/${version}/cds-maven-plugin-${version}-site.jar`
+  const url = capire.maven_host_base + `/com/sap/cds/cds-maven-plugin/${version}/cds-maven-plugin-${version}-site.jar`
 
   const resp = await fetch(url)
   const jar = await resp.arrayBuffer()

.vitepress/theme/components/Since.vue

@@ -1,5 +1,5 @@
 <template>
-  <Badge type="info" :text="`requires ${of} ${version}`" :title="`This feature is only available as of ${of} version ${version} or higher.`" />
+  <Badge type="info" :text="`since ${of} ${version}`" :title="`This feature is only available as of ${of} version ${version} or higher.`" />
 </template>
 
 <script setup lang="ts">

.vitepress/theme/custom.scss

@@ -113,6 +113,7 @@ main {
     pre.log {
       font-size: var(--vp-code-font-size);
       line-height: var(--vp-code-line-height);
+      background: var(--vp-code-block-bg);
       padding: 12px 22px !important;
       overflow-x: auto;
       margin: 16px -24px; // same negative margin technique is used in Vitepress
@@ -151,13 +152,14 @@ main {
       i {
         color: grey;
       }
-
-      background: var(--vp-code-block-bg);
     }
 
     .line-numbers-wrapper {
       padding-top: 13px; // align with code line height
     }
+
+    // code blocks without background, e.g. as sole values in table cells
+    :not(pre) code.no-bg { background-color: initial; }
   }
 
   // Table of Contents
@@ -185,12 +187,12 @@ main {
     border-width: 0 0 0 7px;
     border-radius: 14px;
     &.tip {
-      &, & code, & a { color: #041 };
       background-color: #dfe;
       border-color: #096;
+      &, & code, & a { color: #041 };
       .dark & {
-        &, & code, & a { color: #ced; }
         background-color: #021;
+        &, & code, & a { color: #ced; }
       }
     }
     &.info {
@@ -199,21 +201,21 @@ main {
       }
     }
     &.warning {
-      &, & code, & a { color: #960; }
       background-color: #fff7f0;
       border-color: #ea0;
+      &, & code, & a { color: #960; }
       .dark & {
-        &, & code, & a { color: #ea0; }
         background-color: #210;
+        &, & code, & a { color: #ea0; }
       }
     }
     &.danger {
-      &, & code, & a { color: #600; }
       background-color: #fee;
       border-color: #900;
+      &, & code, & a { color: #600; }
       .dark & {
-        &, & code, & a { color: #fcc; }
         background-color: #300;
+        &, & code, & a { color: #fcc; }
       }
     }
     a {
@@ -252,6 +254,8 @@ main {
   .event::before { content: 'Event: '; color: #999 }
   .class::before { content: 'Class: '; color: #999 }
   .async-method::before { content: 'Method: async '; color: #999 }
+  .deprecated::after { content: ' – deprecated'; color: #999 }
+
   h3.event, h3.method, h3.async-method {
     margin-top: 5em;
     // font-size: 22px;
@@ -338,11 +342,11 @@ kbd {
 }
 
 .learn-more {
-  &, & a { color: #999 !important; .dark & { color: #777 !important }};
   font-style: italic;
   margin-top: -5px;
   margin-bottom: 5px;
   display: block;
+  &, & a { color: #999 !important; .dark & { color: #777 !important }};
 
   &::before {
     content: url('/images/learn-more.svg');
@@ -402,8 +406,7 @@ html.node .java {
 
 // make sidebar content scroll nicely underneath the logo
 @media (min-width: 960px) {
-  header .title {
+  .VPNavBar .has-sidebar > .title {
     background-color: var(--vp-sidebar-bg-color);
   }
 }
-

about/features.md

@@ -223,7 +223,7 @@ Following is an index of the features currently covered by CAP, with status and
 | [Draft Support](../advanced/fiori#draft-support)                                                 | <X/> |  <X/>   | <X/> |
 | [Draft for Localized Data](../advanced/fiori#draft-for-localized-data)                           | <X/> |  <X/>   | <X/> |
 | [Support for Fiori Analytics](../advanced/analytics)                                             | <X/> |  <D/>   | <X/> |
-| [Support for other UI technologies, e.g. Vue.js](../get-started/in-a-nutshell#vue)  <sup>1</sup> | <X/> |  <X/>   | <X/> |
+| [Support for other UI technologies, for example Vue.js](../get-started/in-a-nutshell#vue)  <sup>1</sup> | <X/> |  <X/>   | <X/> |
 
 >  <sup>1</sup> through standard REST/AJAX
 
@@ -259,5 +259,4 @@ Following is an index of the features currently covered by CAP, with status and
 | Declarative Constraints                                                                  | <O/> |
 | Execute Sandboxed Code                                                                   | <O/> |
 | Runtime API for In-App Extensibility                                                     | <D/> |
-| [Key-User Extensibility (incl. UI)](../guides/extensibility/ui-flex)                     | <D/> |
 | Propagating Extensions across (µ) Services                                               | <O/> |

about/index.md

@@ -36,7 +36,7 @@ CAP-based projects benefit from a **[primary focus on domain](#domain-modeling)*
 
 The CAP framework features a mix of proven and broadly adopted open-source and SAP technologies, as highlighted in the figure below.
 
-<img src="../assets/overview.drawio.svg" style="width:480px; margin: auto" alt="The graphic is explained in the accompanying text.">
+![The graphic is explained in the accompanying text.](../assets/overview.drawio.svg){style="width:480px; margin: auto"}
 
 <div id="logos" style="text-align:center;">
   <img src="../assets/logos/nodejs.svg" style="height:40px" alt="Node.js logo" />
@@ -310,7 +310,7 @@ All behavioral aspects in CAP are based on ubiquitous notions of [Services](#ser
 Services in CAP are **stateless** and with a **minimal footprint**, which allows you to modularize solutions into single-purposed (nano) services or functions-as-a-service.
 
 <figure>
-  <img src="../assets/agnostic-services.drawio.svg" width="333px">
+   <img src="../assets/agnostic-services.drawio.svg" width="333px">
   <figcaption><a href="#hexagonal-architecture">Hexagonal Architecture à la CAP</a></figcaption>
 </figure>
 
@@ -396,7 +396,7 @@ cds.service.impl (function(){
 
 
 // Emitting Events
-// e.g. in this.on ('cancelOrder', ...)
+// in this.on ('cancelOrder', ...)
 let { ID } = req.data
 this.emit ('orderCancelled', {ID})
 

advanced/analytics.md

@@ -64,7 +64,7 @@ You can use the following aggregations: `#SUM`, `#MAX`, `#MIN`, `#AVG`, `#COUNT_
 ### Introduction
 
 An application can implement the Cloud Data Integration (CDI) protocol for exposing its data,
-e.g. to act as a data provider for Data Plane Services (DPS).
+for example, to act as a data provider for Data Plane Services (DPS).
 Basically, this means that the app has to provide a set of OData V4 services as described
 in the [CDI specification](https://github.tools.sap/DataPlane/cloud-data-integration-specification).
 This is easy to achieve for a CAP application, as CAP provides generic OData exposure based on CDS models.

advanced/fiori.md

@@ -68,13 +68,11 @@ It is active by default, but disabled automatically in case the [production prof
 To also enable it in cloud deployments, for test or demo purposes maybe, add the following configuration:
 
 ::: code-group
-
-```yaml [application.yaml]
+```yaml [srv/src/main/resources/application.yaml]
 cds:
   index-page:
     enabled: true
 ```
-
 :::
 
 </div>
@@ -485,6 +483,50 @@ SELECT.from(Books.drafts) //returns all drafts of the Books entity
 
 [Learn how to query drafts in Java.](../java/fiori-drafts#draftservices){.learn-more}
 
+## Use Roles to Toggle Visibility of UI elements
+
+In addition to adding [restrictions on services, entities, and actions/functions](/guides/security/authorization#restrictions), there are use cases where you only want to hide certain parts of the UI for specific users. This is possible by using the respective UI annotations like `@UI.Hidden` or `@UI.CreateHidden` in conjunction with `$edmJson` pointing to a singleton.
+
+First, you define the [singleton](../advanced/odata#singletons) in your service and annotate it with [`@cds.persistency.skip`](../guides/databases#cds-persistence-skip) so that no database artefact is created:
+
+```cds
+@odata.singleton @cds.persistency.skip
+entity Configuration {
+    key ID: String;
+    isAdmin : Boolean;
+}
+```
+> A key is technically not required, but without it some consumers might run into problems.
+
+Then define an `on` handler for serving the request:
+
+```js
+srv.on('READ', 'Configuration', async req => {
+    req.reply({
+        isAdmin: req.user.is('admin') //admin is the role, which for example is also used in @requires annotation
+    });
+});
+```
+
+Finally, refer to the singleton in the annotation by using a [dynamic expression](../advanced/odata#dynamic-expressions):
+
+```cds
+annotate service.Books with @(
+    UI.CreateHidden : { $edmJson: {$Not: { $Path: '/CatalogService.EntityContainer/Configuration/isAdmin'} } },
+    UI.UpdateHidden : { $edmJson: {$Not: { $Path: '/CatalogService.EntityContainer/Configuration/isAdmin'} } },
+);
+```
+
+The Entity Container is OData specific and refers to the `$metadata` of the OData service in which all accessible entities are located within the Entity Container. 
+
+:::details SAP Fiori elements also allows to not include it in the path
+```cds
+annotate service.Books with @(
+    UI.CreateHidden : { $edmJson: {$Not: { $Path: '/Configuration/isAdmin'} } },
+    UI.UpdateHidden : { $edmJson: {$Not: { $Path: '/Configuration/isAdmin'} } },
+);
+```
+:::
 
 ## Value Helps
 

advanced/hybrid-testing.md

@@ -283,7 +283,7 @@ Example output:
 
 With `cds bind` you avoid storing credentials on your hard disk. If you need to start other local applications with cloud service bindings, you can use the `exec` option.
 
-For example, you can run the approuter from an `approuter` child directory:
+For example, you can run the App Router from an `approuter` child directory:
 
 ::: code-group
 ```sh [Mac/Linux]
@@ -465,7 +465,7 @@ cds bind --exec [--] <command> <args ...>
 
 Use the double-dash (`--`) if your command has args starting with a dash (`-`) character. Otherwise the `cds` command line will try to parse them as their own options.
 
-On PowerShell you need to quote the double dash (`--`) when an option with double dash follows, e.g.
+On PowerShell you need to quote the double dash (`--`) when an option with double dash follows:
 
 ```powershell
 cds bind --exec '--' somecmd --someflag --some-double-dash-parameter 42

advanced/odata.md

@@ -24,6 +24,8 @@ status: released
 
 # Serving OData APIs
 
+[[toc]]
+
 ## Feature Overview { #overview}
 
 OData is an OASIS standard, which essentially enhances plain REST with standardized system query options like `$select`, `$expand`, `$filter`, etc. Find a rough overview of the feature coverage in the following table:
@@ -1201,12 +1203,14 @@ The cds build for OData v4 will render the entity type `Book` in `edmx` with the
 </EntityType>
 ```
 
-The entity `Book` is open, allowing the client to enrich the entity with additional properties, e.g.:
+The entity `Book` is open, allowing the client to enrich the entity with additional properties. 
+
+Example 1:
 
 ```json
 {"id": 1, "title": "Tow Sawyer"}
 ```
-or
+Example 2:
 
 ```json
 {"title": "Tow Sawyer",
@@ -1226,7 +1230,7 @@ service CatalogService {
   type Book {} // [!code focus]
 }
 ```
-Following payload for `Order` is allowed:
+The following payload for `Order` is allowed:
 
 `{"guid": 1, "book": {"id": 2, "title": "Tow Sawyer"}}`
 
@@ -1236,11 +1240,6 @@ Note that type `Order` itself is not open thus doesn't allow dynamic properties,
 Dynamic properties are not persisted in the underlying data source automatically and must be handled completely by custom code.
 :::
 
-::: warning
-The full support of Open Types (`@open`) in OData is currently available for the Java Runtime only.
-The Node.js runtime currently only supports the feature for actions via REST. Full support will be available in the new OData adapter in `@sap/cds^8`.
-:::
-
 ### Java Type Mapping
 
 #### Simple Types

advanced/publishing-apis/asyncapi.md

@@ -22,6 +22,7 @@ status: released
 
 You can convert events in CDS models to the [AsyncAPI specification](https://www.asyncapi.com), a widely adopted standard used to describe and document message-driven asynchronous APIs.
 
+[[toc]]
 
 ## Usage from CLI { #cli}