refactor: simpler annotations, cloud sdk, structure

Author: SirSimon04

.cdsprettier.json

@@ -0,0 +1,8 @@
+{
+  "maxDocCommentLine": 80,
+  "formatDocComments": true,
+  "tabSize": 2,
+  "alignPostAnnotations": false,
+  "alignColonsInAnnotations": false,
+  "alignValuesInAnnotations": false
+}

.prettierrc.js

@@ -0,0 +1,6 @@
+module.exports = {
+  tabWidth: 2,
+  semi: true,
+  printWidth: 100,
+  trailingComma: "all",
+};

CHANGELOG.md

@@ -36,29 +36,26 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - Fixed handling of unmanaged composition of many
 - Proper casing of the operation enum type
 
-
 ### Changed
 
 - Added warning and mitigation for multi-tenant deployments with MTX
 - Added a disclaimer of upcoming new version having a minimum requirement of CDS 8.6 for multitenancy fix
 - Changed the default limit on non-HANA databases from 255 to 5000 characters for all String values
 - Updated peer dependency from CDS7 to CDS8
 
-
 ## Version 1.0.7 - 20.08.24
 
 ### Added
 
- - A global switch to preserve change logs for deleted data
- - For hierarchical entities, a method to determine their structure and a flag to indicate whether it is a root entity was introduced. For child entities, information about the parent is recorded.
-
+- A global switch to preserve change logs for deleted data
+- For hierarchical entities, a method to determine their structure and a flag to indicate whether it is a root entity was introduced. For child entities, information about the parent is recorded.
 
 ### Fixed
 
 - CDS 8 does not support queries for draft-enabled entities on the application service anymore. This was causing: SqliteError: NOT NULL constraint failed: (...).DraftAdministrativeData_DraftUUID
 - CDS 8 deprecated cds.transaction, causing change logs of nested documents to be wrong, replaced with req.event
 - CDS 8 rejects all direct CRUD requests for auto-exposed Compositions in non-draft cases. This was affecting test cases, since the ChangeView falls into this category
-- req._params and req.context are not official APIs and stopped working with CDS 8, replaced with official APIs
+- req.\_params and req.context are not official APIs and stopped working with CDS 8, replaced with official APIs
 - When running test cases in CDS 8, some requests failed with a status code of 404
 - ServiceEntity is not captured in the ChangeLog table in some cases
 - When modeling an inline entity, a non-existent association and parent ID was recorded
@@ -70,22 +67,21 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - Data marked as personal data using data privacy annotations won't get change-tracked anymore to satisfy product standards
 - Restructured Documentation
 
-
 ## Version 1.0.6 - 29.04.24
 
 ### Fixed
 
- -  Storage of wrong ObjectID in some special scenarios
- -  Missing localization of managed fields
- -  Views without keys won't get the association and UI facet pushed anymore
+- Storage of wrong ObjectID in some special scenarios
+- Missing localization of managed fields
+- Views without keys won't get the association and UI facet pushed anymore
 
 ### Added
 
- - A method to disable automatic generation of the UI Facet
+- A method to disable automatic generation of the UI Facet
 
 ### Changed
 
- - Improved documentation of the @changelog Annotation
+- Improved documentation of the @changelog Annotation
 
 ## Version 1.0.5 - 15.01.24
 
@@ -112,7 +108,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
 ### Added
 
-- Added note about using `SAPUI5 v1.120.0` or later for proper lazy loading of the *Change History* table.
+- Added note about using `SAPUI5 v1.120.0` or later for proper lazy loading of the _Change History_ table.
 - In README, add warning about tracking personal data.
 
 ### Changed
@@ -141,4 +137,3 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 ### Added
 
 - Initial release
-

CONTRIBUTING.md

@@ -10,11 +10,11 @@ Instances of abusive, harassing, or otherwise unacceptable behavior may be repor
 
 We use GitHub to manage reviews of pull requests.
 
-* If you are a new contributor, see: [Steps to Contribute](#steps-to-contribute)
+- If you are a new contributor, see: [Steps to Contribute](#steps-to-contribute)
 
-* Before implementing your change, create an issue that describes the problem you would like to solve or the code that should be enhanced. Please note that you are willing to work on that issue.
+- Before implementing your change, create an issue that describes the problem you would like to solve or the code that should be enhanced. Please note that you are willing to work on that issue.
 
-* The team will review the issue and decide whether it should be implemented as a pull request. In that case, they will assign the issue to you. If the team decides against picking up the issue, the team will post a comment with an explanation.
+- The team will review the issue and decide whether it should be implemented as a pull request. In that case, they will assign the issue to you. If the team decides against picking up the issue, the team will post a comment with an explanation.
 
 ## Steps to Contribute
 
@@ -28,11 +28,11 @@ You are welcome to contribute code in order to fix a bug or to implement a new f
 
 The following rule governs code contributions:
 
-* Contributions must be licensed under the [Apache 2.0 License](./LICENSE)
-* Due to legal reasons, contributors will be asked to accept a Developer Certificate of Origin (DCO) when they create the first pull request to this project. This happens in an automated fashion during the submission process. SAP uses [the standard DCO text of the Linux Foundation](https://developercertificate.org/).
+- Contributions must be licensed under the [Apache 2.0 License](./LICENSE)
+- Due to legal reasons, contributors will be asked to accept a Developer Certificate of Origin (DCO) when they create the first pull request to this project. This happens in an automated fashion during the submission process. SAP uses [the standard DCO text of the Linux Foundation](https://developercertificate.org/).
 
 ## Issues and Planning
 
-* We use GitHub issues to track bugs and enhancement requests.
+- We use GitHub issues to track bugs and enhancement requests.
 
-* Please provide as much context as possible when you open an issue. The information you provide must be comprehensive enough to reproduce that issue for the assignee.
+- Please provide as much context as possible when you open an issue. The information you provide must be comprehensive enough to reproduce that issue for the assignee.

README.md

@@ -18,138 +18,92 @@ See [Getting Started](https://cap.cloud.sap/docs/get-started) on how to jumpstar
 
 Usage of this plugin requires a valid subscription of the [SAP Print Service](https://help.sap.com/docs/SCP_PRINT_SERVICE).
 
-To integrate the print functionality in your application, simply annotate any action with `@print`. This annotation automatically manages the process of sending documents to the print queues, requiring no additional setup for handling print jobs.
+## Usage
 
-### Required Fields
+To use this plugin to print documents there are two main steps:
 
-The following three fields should be annotated with the corresponding `@print` annotations:
+1. Add required annotations to your CDS model:
+   a. Entity
+   b. Action
+2. Configure print queues to select from available options. (Optional, but recommended)
 
-1. **`@print.queue`**: Specifies the queue to which the document should be sent for printing.
-2. **`@print.numberOfCopies`**: Defines the number of copies to be printed.
-3. **`@print.fileContent`**: Provides the file content to be printed. You can also specify the file name using the `fileNameField` property.
+### Annotations in CDS model
 
-#### Example
+#### Entity
+
+First of all, the entity needs to be annotated to define the content and the name of the document to be printed.
 
 ```cds
-@print.fileContent: {
-    fileNameField: '<Field Name>',
+entity Incidents : cuid {
+  @print.fileContent
+  file : LargeBinary @Core.MediaType: 'application/pdf';
+  @print.fileName
+  fileName : String;
 }
-```
-
-Multiple fields can be annotated with `@print.fileContent` to send several documents to the print queue in a single action.
-
-### Main Document
 
-To designate a specific document as the primary document for printing, annotate it with `@print.MainDocument`:
-
-```cds
-@print.MainDocument
-invoiceContent,
 ```
 
-This ensures the specified document is treated as the main document when multiple documents are involved.
-
-## Print Queue Configuration
-
-You can retrieve all available print queues from the Print Service Application for selection by defining a `Queues` entity with **skip persistency**. This setup will offer a value help for the print queues, allowing users to select from available options.
+- `@print.fileContent`: Annotates the field containing the document content to be printed.
+- `@print.fileName`: Annotates the field containing the name of the document
 
-### Define the `Queues` Entity
+#### Annotation of actions
 
-Define an entity like `Product` and associate it with the `Queues` entity as shown below:
+Sending a print request works via bound actions annotated with `@print`. The parameter of the action are used to define the print job details.
 
-#### Example
 ```cds
-entity Product {
-    qName : Association to one Queues;
-}
-
-@cds.skip.persistence
-entity Queues {
-    key ID          : String;
-        description : String;
-}
-```
+service IncidentService {
+    entity Incidents as projection on db.Incidents actions {
 
-#### Annotating with `@print.queue`
-
-Once the `Queues` entity is defined, specify it in the `@print.queue` annotation like so:
-
-```cds
-@print.queue: {
-    SourceEntity: 'Queues'
+    @print
+    action printIncidentFile(
+          @Common: {
+              ValueListWithFixedValues,
+              ValueList: {
+                  $Type: 'Common.ValueListType',
+                  CollectionPath: 'Queues',
+                  Parameters: [{
+                      $Type: 'Common.ValueListParameterInOut',
+                      LocalDataProperty: qnameID,
+                      ValueListProperty: 'ID'
+                  }]
+              },
+              Label: 'Print Queues',
+          }
+          @print.queue
+          qnameID: String,
+          @print.numberOfCopies
+          @UI.ParameterDefaultValue : 1
+          copies: Integer
+      );
+    };
 }
-qName
 ```
 
-### Parameterizing Print Queue in Actions
+- `@print`: Annotates the action that triggers the print job.
+- `@print.queue`: Annotates the parameter specifying the print queue. It is recommended to use a value help for this parameter to select from available print queues. See TOOD
+- `@print.numberOfCopies`: Annotates the parameter specifying the number of copies to print
 
-Alternatively, if the print queue is passed as a parameter in the action, you can annotate it directly within the action definition. This can be done as follows:
+### Queues
 
-#### In Database Definition:
+Every print request needs to specify a print queue it is send to. It is recommended to provide a value help for the print queue selection. To enbale this, define an entity as projection on the `Queues` entity provided by the print service. When this projection is in place, the plugin automatically provides the available print queues coming from the print service.
 
 ```cds
-entity Product {
-    qName : Association to one Queues;
-}
-
-@cds.skip.persistence
-entity Queues {
-    key ID          : String;
-        description : String;
-}
-```
-
-#### In Service Definition:
+using {sap.print as sp} from '@cap-js/print';
 
-```cds
-service MyService {
-    @print
-    action print(
-        @print.queue: {
-            SourceEntity: 'Queues'
-        }
-        @Common: {
-            ValueListWithFixedValues,
-            ValueList: {
-                $Type: 'Common.ValueListType',
-                CollectionPath: 'Queues',
-                Parameters: [{
-                    $Type: 'Common.ValueListParameterInOut',
-                    LocalDataProperty: qnameID,
-                    ValueListProperty: 'ID'
-                }]
-            },
-            Label: 'Print Queues',
-        }
-        qnameID: String
-    );
-
-    entity Queues as projection on db.Queues;
+service IncidentService {
+    entity Queues as projection on sp.Queues;
 }
 ```
 
-In this setup, the `qnameID` parameter will be used to dynamically select the print queue from the `Queues` entity. The `Common.ValueList` provides a drop-down selection for available queues during runtime.
+## Local Development
 
+When running the application locally, i.e. `cds watch`, the print service is mocked. This mock implementation prints the print job details to the console instead of sending it to the actual print service. It also provides a number of sample print queues for selection.
 
-## Note
+## Hybrid Testing
 
-If you are running the application in a production way locally(E.g. adding VCAP_SERVICES in `default-env.json`), add the environmental variable `SUBSCRIBER_SUBDOMAIN_FOR_LOCAL_TESTING=<Your subscriber subdomain name>` in the `package.json` as shown below.
+You can also run the application locally with a binding to the cloud print service with CAP profiles. For more information, see [Hybrid Testing](https://cap.cloud.sap/docs/advanced/hybrid-testing#hybrid-testing). You need an instance of the SAP Print Service.
 
-#### Example
-
-```json
-"scripts": {
-    "start": "SUBSCRIBER_SUBDOMAIN_FOR_LOCAL_TESTING=sub01 cds-serve"
-}
-```
-
-If you are running the application in offline mode which is without remote connection to the online environment, you can add the environmental variable `PRINT_CONSOLE_MODE=true cds watch` in the `package.json` as shown below.
-
-```json
-"scripts": {
-    "watch-offline": "PRINT_CONSOLE_MODE=true cds watch"
-}
-```
+TODO: More doc about setting up the print service
 
 ## Support, Feedback, Contributing