Tree view

advanced/fiori.md

@@ -745,9 +745,9 @@ Cache Control feature is currently supported on the Java runtime only.
 
 ## Hierarchical Tree Views
 
-Recursive hierarchies are parent-child hierarchies, where each entity references its parent and through that defines the hierarchical structure. A common example is a company organization structure or HR reporting, where each employee entity references another employee as a direct report or manager.
+Recursive hierarchies are parent-child hierarchies: each entity references its parent and through that defines the hierarchical structure. A common example is a company organization structure or HR reporting, where each employee entity references another employee as a direct report or manager.
 
-A generic hierarchy implementation for hierarchies is available on all relational datases supported by the CAP runtimes.
+A generic hierarchy implementation for hierarchies is available on all relational databases supported by the CAP runtimes.
 
 ::: warning
 On H2, only small hierarchies should be used for performance reasons.
@@ -761,6 +761,7 @@ Let's assume we have the following domain model and its projection in a service:
 namespace my.bookshop;
 
 entity Genres { //...
+  ID : UUID;
   parent : Association to Genres;
 }
 ```
@@ -774,19 +775,67 @@ service AdminService {
 ```
 :::
 
+In this example, there is a managed to-one association `parent` that defines the parent-child hierarchy
+based on a single key element. In such a situation you can define the Tree View via the annotation `@hierarchy`:
 
-Annotate/extend the entity in the service as follows:
+```cds
+annotate AdminService.Genres with @hierarchy : parent;
+```
+
+If the entity contains only one such association, you can even omit the value:
+
+```cds
+annotate AdminService.Genres with @hierarchy;
+```
+
+Configure the TreeTable in UI5's _manifest.json_ file:
+
+```jsonc
+  "sap.ui5": { ...
+    "routing": { ...
+      "targets": { ...
+        "GenresList": { ...
+          "options": {
+            "settings": { ...
+              "controlConfiguration": {
+                "@com.sap.vocabularies.UI.v1.LineItem": {
+                  "tableSettings": {
+                    "hierarchyQualifier": "GenresHierarchy", // [!code focus]
+                    "type": "TreeTable" // [!code focus]
+                  }
+                }
+              }
+            }
+          }
+        },
+      },
+    },
+```
+
+> Note: construct the `hierarchyQualifier` with the following pattern: <br>
+> `<entity name in service>Hierarchy`
+
+You can now start the server with `cds watch` and see the hierarchical tree view in action in the [_Browse Genres_](http://localhost:4004/fiori-apps.html#Genres-display) app.
+
+![Fiori UI with hierarchical tree view.](assets/hierarchical-tree-view.png) {style="filter: drop-shadow(0 2px 5px rgba(0,0,0,.40));"}
+
+The compiler automatically expands the shortcut annotation `@hierarchy` to the
+following annotate and extend statements. 
+
+### Manual Approach
+
+The following documents what happens behind the scenes, done by the compiler as described before. You can also use it, if you cannot use the `@hierarchy` annotation, for example, because you only have an unmanaged parent association.
 
 ```cds
 // declare a hierarchy with the qualifier "GenresHierarchy"
-annotate AdminService.Genres with @Aggregation.RecursiveHierarchy #GenresHierarchy : {
+annotate AdminService.Genres with @Aggregation.RecursiveHierarchy #GenresHierarchy: {
   NodeProperty             : ID,    // identifies a node, usually the key
   ParentNavigationProperty : parent // navigates to a node's parent
 };
 
 extend AdminService.Genres with @(
   // The computed properties expected by Fiori to be present in hierarchy entities
-  Hierarchy.RecursiveHierarchy #GenresHierarchy : {
+  Hierarchy.RecursiveHierarchy #GenresHierarchy: {
     LimitedDescendantCount : LimitedDescendantCount,
     DistanceFromRoot       : DistanceFromRoot,
     DrillState             : DrillState,
@@ -797,7 +846,7 @@ extend AdminService.Genres with @(
     'LimitedDescendantCount', 'DistanceFromRoot', 'DrillState', 'LimitedRank'
   ],
   // Disallow sorting on these properties from Fiori UIs
-  Capabilities.SortRestrictions.NonSortableProperties    : [
+  Capabilities.SortRestrictions.NonSortableProperties: [
     'LimitedDescendantCount', 'DistanceFromRoot', 'DrillState', 'LimitedRank'
   ],
 ) columns { // Ensure we can query these columns from the database
@@ -811,31 +860,5 @@ extend AdminService.Genres with @(
 > Note: When naming the hierarchy qualifier, use the following pattern: <br>
 > `<entity name in service>Hierarchy`
 
-Configure the TreeTable in UI5's _manifest.json_ file:
-
-```jsonc
-  "sap.ui5": { ...
-    "routing": { ...
-      "targets": { ...
-        "GenresList": { ...
-          "options": {
-            "settings": { ...
-              "controlConfiguration": {
-                "@com.sap.vocabularies.UI.v1.LineItem": {
-                  "tableSettings": {
-                    "hierarchyQualifier": "GenresHierarchy", // [!code focus]
-                    "type": "TreeTable" // [!code focus]
-                  }
-                }
-              }
-            }
-          }
-        },
-      },
-    },
-```
-
-> Note: use the `hierarchyQualifier` declared earlier
-
 <div id="reserved-words" />
 

tools/cds-cli.md

@@ -468,6 +468,72 @@ To customize the diagram layout, use these settings in the _Cds > Preview_ categ
 - [Diagram: Namespaces](vscode://settings/cds.preview.diagram.namespaces)
 - [Diagram: Queries](vscode://settings/cds.preview.diagram.queries)
 
+
+## cds export
+
+With `cds export` you create an API client package to be used
+for data exchange via CAP-level Service integration ("Calesi").
+
+First define a data provider service in your CDS model that serves as an
+interface to your data. Put each such data provider service in a separate file.
+
+For the [xflights](https://github.com/capire/xflights) sample app,
+an API that provides information about flights, airports, and airlines
+could look like this:
+
+::: code-group
+
+```cds [srv/data-service.cds]
+using { sap.capire.flights as my } from '../db/schema';
+
+@data.product @hcql @rest @odata 
+service sap.capire.flights.data {
+  @readonly entity Flights as projection on my.Flights;
+  @readonly entity Airlines as projection on my.Airlines;
+  @readonly entity Airports as projection on my.Airports;
+}
+```
+
+:::
+
+Then create an API client package for this service:
+
+```sh
+cds export srv/data-service.cds
+```
+
+The API client package is generated into a new folder _apis/data-service_.
+
+![The screenshot is described in the accompanying text.](assets/cds-export.png) {style="filter: drop-shadow(0 2px 5px rgba(0,0,0,.40));"}
+
+The `service.csn` contains only the interface defined in the service,
+stripping away the query part of the entities and all the model underneath it.
+In addition, there are i18n bundles with the localized metadata relevant
+for the interface, and a _data_ folder with test data
+that exactly matches the structure of the entities in the API.
+
+`cds export` also adds a _package.json_. The package name is the
+application name (from the main _package.json_) prefixed with the
+file name of the data service, in our example `@capire/xflights-data-service`.
+You can change this name as appropriate.
+
+The generated package can then be published, e.g. via `npm publish`.
+
+For consuming the API in another CAP application
+* import the API package with `npm add`
+* define consumption views on the imported entities
+* use them in your model as if they were local entities
+* add custom code to access the data in the provider app via any of the offered protocols
+
+Have a look at the [xtravels](https://github.com/capire/xtravels) sample app for an
+example of using an API client package.
+
+With the possibility to export and import API packages via `cds export` and `npm add`,
+you no longer have to use EDMX (or OpenAPI) as intermediate format for exchanging API information
+between CAP applications, with the known problem of loosing information.
+
+
+
 ## cds watch
 
 Use `cds watch` to watch for changed files, restarting your Node.js server.