diff --git a/documentation/howto-devonfw-ide-CobiGen-PoC-E2E.asciidoc b/documentation/howto-devonfw-ide-CobiGen-PoC-E2E.asciidoc index 92fde7aa50..0ad3b57d0b 100644 --- a/documentation/howto-devonfw-ide-CobiGen-PoC-E2E.asciidoc +++ b/documentation/howto-devonfw-ide-CobiGen-PoC-E2E.asciidoc @@ -5,50 +5,40 @@ toc::[] This article helps to create a sample application using CobiGen. == Prerequisites -Download and install devonfw IDE https://devonfw.com/website/pages/docs/devonfw-ide-introduction.asciidoc.html#setup.asciidoc[here], +Download and install devonfw IDE by this https://devonfw.com/website/pages/docs/devonfw-guide_ide.wiki_setup.asciidoc.html[tutorial]. == Steps to create a Sample Project using CobiGen The `HOW_TO` is divided in 2 parts: + [arabic] -. `BE`-Backend generator (`DB` + `DAO` + services) – CONTRACT FIRST APPROACH -. `FE`-Frontend generator (Web App Angular + Ionic App) – CONTRACT FIRST APPROACH +. `BE`-Backend generator (`DB` + `DAO` + services) +. `FE`-Frontend generator (Web App Angular + Ionic App) image:images/howtos/e2e_gen/image63.png[CobiGen code-first generation] -So, ready to go! We’re going to start from the `BE` part … +So, ready to go! We’re going to start with the `BE` part. === Backend -Under your path installation of devonfw, you can find the _eclipse-main.bat_ script and you can run it: + -run _installation_path_\eclipse-main.bat - -It will open eclipse +1.Under your path installation of devonfw, you can find the _eclipse-main.bat_ script. To run it, execute _installation_path_\eclipse-main.bat.This will open eclipse. [arabic] -Create a project using a command from the command prompt. + -To made it, it's necessary to open a CMD and open the folder where it's installed devonfw and launch this command under the path `_workspaces/main_`. + +2.Create a project: Navigate in the folder containing the devonfw installation and then to `*workspaces/main*`. Right-click and choose "_Open devonfw CMD shell here_". Next, launch this command in the shell: -NOTE: To facilitate this step, you can go from your "_File Explorer_" under `*workspaces/main*` folder and with the right button of the mouse, choose "_Open devonfw CMD shell here_" -image:images/howtos/e2e_gen/image85.png[eclipse devon] - -Then launch this command from CMD: [source, java] ---- devon java create com.example.domain.myapp ---- -Import the project to eclipse as maven project -image:images/howtos/e2e_gen/image14.png[eclipse devon] +3.In eclipse, import the project as a maven project as specified in the image below: -Click *FINISH* +image:images/howtos/e2e_gen/image14.png[eclipse devon] -Now We have the following 4 projects. +4.Click *FINISH*. Now you should have the following 4 projects: image:images/howtos/e2e_gen/image15.png[eclipse package explorer] -*BEFORE to start to create an Entity class, remember to create the tables, for this POC it's used an H2 Database!* - [arabic] -Create a new *SQL* *file* (`i.e: V0002__CreateTables_myapp.sql`) inside _`myapp-core`_ , under the folder path _`/myapp-core/src/main/resources/db/migration/1.0`_ and insert the following script: +5.Create a new *SQL* *file* `V0002__CreateTables_myapp.sql` inside _`myapp-core`_ , under the folder path _`/myapp-core/src/main/resources/db/migration/1.0`_ and insert the following script: [source] ---- @@ -62,17 +52,13 @@ PRIMARY KEY (employeeid) ); ---- -*_WARNING 1_*: please note that there in that folder is present only one file, 0001, and you have to add the other files in progressive number order (i.e. 0002)! + -*_WARNING 2_*: please note that there are 2 underscore in the name! +*_WARNING 1_*: In this folder there is only one file (0001). You have to add the other files in progressive number order (i.e. 0002)! + +*_WARNING 2_*: There are 2 underscores in the name! image:images/howtos/e2e_gen/image64.png[SQL file] [arabic] -Now create another SQL file (`i.e: V0003__PopulateTables-myapp.sql`) and add following script about the INSERT in order to populate the table created before. -The script must be inserted at the same path used before: _`/myapp-core/src/main/resources/db/migration/1.0`_ - -*_WARNING 1_*: please note that there in that folder is present only one file, 0001, and you have to add the other files in progressive number order (i.e. 0003)! + -*_WARNING 2_*: please note that there are 2 underscore in the name! +6.Create another SQL file analogously named `V0003__PopulateTables-myapp.sql` in the same folder and add following script about the INSERT to populate the table created before. Please note the warnings from the previous step here, as well. [source] ---- @@ -83,17 +69,15 @@ INSERT INTO EMPLOYEE (id, modificationCounter, employeeid, name, surname,email) image:images/howtos/e2e_gen/image65.png[SQL insert] -*Let's create the Entity Class for the code generation* - [arabic] -Create a package ```*employeemanagement.dataaccess.api*``` under the folder _`myapp-core`_. + -Note: It is important to follow this naming convention for CobiGen to work properly. + +7.We will now create the Entity Class for the code generation. For this, create a package named ``*com.example.domain.myapp.employeemanagement.dataaccess.api*`` in the folder _`myapp-core/src/main/java`_. + +*_WARNING_*: It's important to follow this naming convention to ensure CobiGen is working properly. image:images/howtos/e2e_gen/image66.png[package] -Now create a `JPA` Entity class in this package +Now create a new class named `EmployeeEntity` in this package and paste the code below to turn it into a `JPA` Entity. -[source, java] ---- package com.example.domain.myapp.employeemanagement.dataaccess.api; @@ -116,52 +100,34 @@ public class EmployeeEntity { } ---- -then generate `getters` and `setters` for all attribute, as you can see in the image below: +8.Generate `getters` and `setters` for all attributes, as you can see in the image below: image:images/howtos/e2e_gen/image67.png[`getter & setter`] image:images/howtos/e2e_gen/image68.png[`getter & setter`] [arabic] -Use CobiGen to generate code. Right click on `EmployeeEntity`. CobiGen -> Generate - -If it will ask you to download the templates, click on _update_: - -image:images/howtos/e2e_gen/image19.png[CobiGen generate] - -It will automatically download the latest version of _CobiGen_Templates_. - -*Attention:* If you want to adapt the CobiGen_Templates, (normally this is not necessary), you will find at the end of this document (in a separate chapter) a tutorial on how to import them and adapt them! - -[arabic] -Click on all the option selected as below: +9.Now we can use CobiGen to generate code! First, right-click in the package explorer on `EmployeeEntity.java` -> `CobiGen` and select `Update Template`. Next, right-click on `EmployeeEntity.java` -> CobiGen -> Generate and tick the boxes as can be seen in the picture: image:images/howtos/e2e_gen/image20.png[CobiGen option selection] [arabic] -Click on finish. Below Screen would be seen. Click on continue - -image:images/howtos/e2e_gen/image21.png[CobiGen finish] - -*The entire [.underline]#`BE` layer# structure having `CRUD` operation methods will be auto generated.* - -Some classes will be generated on the API part (_`myapp-api`)_, normally it will be interfaces, as shown below: +10.Click on *Finish* to complete the process. *The entire [.underline]#`BE` layer# structure including `CRUD` operation methods was auto generated.* + +Some classes are generated in the API part (_`myapp-api`)_, e.g. interfaces, as shown below: image:images/howtos/e2e_gen/image22.png[be layer] -Some other classes will be generated on the core part (_`myapp-core`)_, normally it will be implementations as shown below: +Other classes are generated in the core part (_`myapp-core`)_, like implementations, as shown below: image:images/howtos/e2e_gen/image23.png[core folder] [arabic] -The last step is to add the Cross Domain process, because when you are developing JavaScript client and server application separately, you have to deal with cross domain issues. - -So, we need to prepare server side to accept request from other domains. We need to cover the following points: +11.The last step is to add the cross-domain process, as we are developing the JavaScript client and the server application separately. For this, we need to prepare the server side to accept requests from other domains, covering the following points: * Accept request from other domains. * Accept devonfw used headers like `X-CSRF-TOKEN` or `correlationId`. * Be prepared to receive secured request (cookies). -To do this it's necessary to add two kind of dependencies in the pom.xml of the _`myapp-core`_ folder, at the end of the list of dependencies: +Add these two kind of dependencies in the pom.xml of the _`myapp-core`_ folder, at the end of the list of dependencies: [source, xml] ---- @@ -177,7 +143,7 @@ To do this it's necessary to add two kind of dependencies in the pom.xml of the image:images/howtos/e2e_gen/image70.png[pom xml] -Next step is to add some properties under your _application.properties_ file, in the `myapp-core` folder in the _resources/config_: +12.Add these properties in your _application.properties_ file, in the `myapp-core` folder in the _resources/config_: [source, properties] ---- @@ -190,82 +156,47 @@ security.cors.pathPattern=/** image:images/howtos/e2e_gen/image71.png[application properties] -*BEFORE to generate the `FE`*, please start the Tomcat server to check that `BE` Layer has been generated properly. - -To start a server you just have to right click on _`SpringBootApp.java`_ -> _run as -> Java Application_ - -image:images/howtos/e2e_gen/image24.png[Eclipse run as] +13.To check if the `BE` layer has been generated properly, start the server by right-clicking on _`SpringBootApp.java`_ -> _run as -> Java Application_. If it looks like the image below, the `BE` part is done! image:images/howtos/e2e_gen/image69.png[Spring boot run] image:images/howtos/e2e_gen/image26.png[Spring boot run] -*`BE` DONE* - -Last but not least: We make a quick REST services test ! - -See in the _application.properties_ the TCP Port and the `PATH` - -image:images/howtos/e2e_gen/image27.png[application properties] - -Now compose the Rest service URL: +Optional step: + +14.To test if the `Backend` works properly, we perform a REST service test! For this, we use Postman. You can download it https://www.postman.com/downloads/[here]. + -*service class /* - -* refers to server with port no. (i.e: `localhost:8081`) -* is in the _application.properties_ (empty in our case, see above) -* refers to `EmployeemanagementRestService`: (i.e: `/employeemanagement/v1`) -* /employee/\{id} (i.e: for `getEmployee` method) - -image:images/howtos/e2e_gen/image28.png[URL mapping] - -URL of `getEmployee` for this example is: - -For all employees (`POST`) -[source, URL] ----- -http://localhost:8081/services/rest/employeemanagement/v1/employee/search ----- - -For the specific employee (`GET`) -[source, URL] +First send a POST request for the body with the URL [source, URL]. ---- http://localhost:8081/services/rest/employeemanagement/v1/employee/1 ---- -Now download https://www.getpostman.com/apps[Postman] to test the rest services. - -Once done, you have to create a `POST` Request for the LOGIN and insert in the body the JSON containing the username and password _admin_ +Under `Body`, insert the JSON containing -image:images/howtos/e2e_gen/image72.png[postman] -*_WARNING_*: please note that the body of the request must be JSON type! - -Once done with success (*Status: 200 OK*) - _you can see the status of the response in the top right corner of Postman_ - we can create a NEW `GET` Request in order to get one employee. - -To do this you have to create a new request in Postman, `GET` type, and insert the URL specified before: +---- +{ + "j_username":"admin", + "j_password":"admin" +} +---- +Click on send. "Status:200 OK" means it worked. + +Next, we create a new request, this time `GET` type with the URL [source, URL] ---- http://localhost:8081/services/rest/employeemanagement/v1/employee/1 ---- - -Then click on *"SEND"* button... - -Now you have to check that response has got *Status: 200 OK* and to see the below Employee +Click on send. If you get "Status:200 OK" again and see employee "John Doe" as you can see in the image below, the Backend works fine! image:images/howtos/e2e_gen/image73.png[postman] -Now that We have successfully tested the `BE` is time to go to create the `FE` ! - === Frontend -Let’s start now with angular Web and then Ionic app. +Let's start with the Frontend! We want to create an *Angular Web App*: -==== Angular Web App [arabic] -To generate angular structure, download or clone *devon4ng-application-template* from +1.To generate angular structure, download or clone *devon4ng-application-template* from [source, URL] https://github.com/devonfw/devon4ng-application-template @@ -273,38 +204,29 @@ https://github.com/devonfw/devon4ng-application-template image:images/howtos/e2e_gen/image74.png[devon dist folder] [arabic] -IMPORTANT when you download the zip of the source code of your `FE` application, the name of the app MUST BE *devon4ng-application-template* and you can extract it in your devonfw folder, under `_workspaces/main_` +*IMPORTANT* if you download the zip of the source code, the name of the app MUST BE *devon4ng-application-template*. Extract it into your devonfw folder, under `_workspaces/main_`. -Once downloaded the `APP`, you can open the application with your favorite IDE (IntelliJ, Visual Studio Code, ...) + -Instead, if you want to open this project with Eclipse, you have to follow these steps: + -[arabic] -. Right click on the left part of Eclipse, and click on "Import": +2.After downloading the `APP`, open the application in Eclipse. For this, right click on the left part of Eclipse and click "Import" + image:images/howtos/e2e_gen/image83.png[import] -. Click on "Projects from Folder or Archive" +Then choose "Projects from Folder or Archive": + image:images/howtos/e2e_gen/image82.png[import] -. Select your folder where you have saved the Angular `FE` Application, under `_workspaces/main_`. Wait that all the dependencies are charged and then click on "Finish" +Select the folder containing the Angular `FE` Application, under `_workspaces/main_`.Click on *Finish* after all dependencies have been loaded. image:images/howtos/e2e_gen/image84.png[import] -. At the end, you will have a structure like this: +Now, you should have a structure like this: image:images/howtos/e2e_gen/image86.png[import] [arabic] -Once done, right click on `EmployeeEto`.java file present under the `package _com.devonfw.poc.employeemanagement.logic.api.to_`, in the Backend part (_`myapp-core_ module`). -Click on the selected options as seen in the screenshot: +3.Right click on `EmployeeEto`.java file in the package `_com.example.domain.myapp.employeemanagement.logic.api.to_`, in the `BE` part (_`myapp-api_ module`). Choose `Cobigen -> Generate` and select the options as seen in the screenshot and click on *Finish*: image:images/howtos/e2e_gen/image37.png[eclipse generate] [arabic] -Click on Finish - -image:images/howtos/e2e_gen/image38.png[eclipse] - -[arabic] -The entire `ANGULAR` structure has been auto generated. The generated code will be merged to the existing. +4.The entire `ANGULAR` structure has been auto generated and the generated code was merged into already existing code. image:images/howtos/e2e_gen/image39.png[angular `ee` layer] [arabic] -IMPORTANT now you have to check in the *_app-routing.module.ts_* file, if the content corresponding to the code below: +The *_app-routing.module.ts_* file (in src/app) should correspond to the code below, so copy the code and replace the existing content in your file with this: [source, ts] ---- @@ -361,7 +283,7 @@ export class AppRoutingModule { } ---- -After that, if you want to make visible the Employee Grid in you `FE` application, you have to modify the `nav-bar.component.html`, to add the Employee grid in the section: +5.To make the Employee Grid in you `FE` application visible, you have to replace the code in `nav-bar.component.html` with the code below: [source, HTML] ---- @@ -410,20 +332,19 @@ After that, if you want to make visible the Employee Grid in you `FE` applicatio ---- [arabic] -Open the command prompt and execute _devon npm install_ from your application folder (`_workspaces/main/devon4ng-application-template_`), which would download all the required libraries. +6.Open the devon CMD shell and execute `devon npm install` in `_workspaces/main/devon4ng-application-template_`, which will download all the required libraries. [arabic] -Check the file *environment.ts* if the server path is correct. (for production you will have to change also the environment.prod.ts file) +7.Check in the file *environment.ts* (in src/app/environments) if the server path is correct. image:images/howtos/e2e_gen/image42.png[environment] -In order to do that, it’s important to look at the application.properties to see the values as `PATH`, TCP port etc... +The values `PATH`, TCP port etc. in application.properties should match the image below. Set the security field to *CSRF* , if it is not configured this way already image:images/howtos/e2e_gen/image43.png[configure] -For example in this case the URL should be since the context path is empty the server `URLS` should be like: - [source, ts] + ---- export const environment = { production: false, @@ -433,15 +354,15 @@ export const environment = { }; ---- -*Warning*: REMEMBER to set security filed to *CSRF* , if it is not configured already. + [arabic] -Now run the `*devon ng serve -o*` command to run the Angular Application, from your application folder (`_workspaces/main/devon4ng-application-template_`), as done before. +8.For the last steps, the `BE` server should be running. Then run `*devon ng*` and then `*devon ng serve -o*` to start the Angular Application, in a CMD shell in your application folder (`_workspaces/main/devon4ng-application-template_`). image:images/howtos/e2e_gen/image75.png[ng serve command] [arabic] -If the command execution is *successful*, the below screen will *appear* and it would be automatically redirected to the URL: +9.If the command execution is *successful*, the screen shown below will appear and you would be automatically redirected to the URL: [source, URL] ---- @@ -450,126 +371,8 @@ http://localhost:4200/login image:images/howtos/e2e_gen/image77.png[angular web app] -You can login in the Web Application, with *_admin_* user and password. + -Obviously, the `BackEnd` part must be up & running during this test! - -*`ANGULAR WebApp DONE`* - - -==== Ionic Mobile App - -[arabic] -To generate Ionic structure, download or clone _*devon4ng-application-template*_ from -[source, URL] ----- -https://github.com/devonfw/devon4ng-ionic-application-template ----- - -[arabic] -IMPORTANT when you download the zip of the source code of your `FE` application, the name of the app MUST BE *devon4ng-ionic-application-template* and you can extract it in your devonfw folder, under `_workspaces/main_` - -Once downloaded the `APP`, you can open the application with your favorite IDE (IntelliJ, Visual Studio Code, ...) + -Instead, if you want to open this project with Eclipse, you have to follow these steps: + -[arabic] -. Right click on the left part of Eclipse, and click on "Import": -image:images/howtos/e2e_gen/image83.png[import] -. Click on "Projects from Folder or Archive" -image:images/howtos/e2e_gen/image82.png[import] -. Select your folder where you have saved the Angular `FE` Application, under `_workspaces/main_`. Wait that all the dependencies are charged and then click on "Finish" -image:images/howtos/e2e_gen/image84.png[import] -. At the end, you will have a structure like this: -image:images/howtos/e2e_gen/image86.png[import] - -Once done, Right click on the *`EmployeeEto`* as you already did before in order to use CobiGen. -Click on the selected options as seen in the screenshot: - -image:images/howtos/e2e_gen/image46.png[CobiGen ionic] - -[arabic] -Click on Finish + -The entire ionic structure will be auto generated. - -image:images/howtos/e2e_gen/image47.png[] - -[arabic] -Change (if necessary) the server URL (with correct serve URL) in _environment.ts_, _environment.prod.ts_ and _environment.android.ts_ files (i.e: `itapoc\devon4ng-ionic-application-template\src\environments\`). - -The `_angular.json_` file inside the project has already a build configuration for android. - -image:images/howtos/e2e_gen/image48.png[] - -The only *TWO* thing that you have to modify, in this IONIC app is in `_employee-list.page.html_` and _business-operator.service.ts_.y + - -*1:* + -You have to change this line: -[source,HTML] - - -with this line: -[source,HTML] - - - -*2:* + -You have to change this line: -[source,ts] ----- -return this.restPath + '/security/v1/csrftoken'; ----- - -with this line: -[source,ts] ----- -return this.restPath + 'csrf/v1/token/'; ----- - -[arabic] -Once checked if all the files are correct, open a CMD devon CLI on the folder of the ionic template application (`_workspaces/main/devon4ng-ionic-application-template_`), under your `devonFW` workspace. + -In this folder: + -Run the command _*devon npm install*_ in the root folder to download the dependencies. + -Once finished, run the command _*devon ionic serve*_ - -image:images/howtos/e2e_gen/image49.png[] - -Once the execution is successful, you can make the LOGIN with *admin/admin* and... - -image:images/howtos/e2e_gen/image50.png[] - -*IONIC Mobile App DONE* - -So: *Well Done!!!* - -`*Starting from an Entity class you have successfully generated the Backend layer (REST, SOAP, `DTO`, Spring services, `Hibernate DAO`), the Angular Web App and the Ionic mobile App!*` - -image:images/howtos/e2e_gen/image51.png[] - - -===== Build `APK` - -Since We’re going to create apk remember the following preconditions: - -* https://gradle.org/install/[Gradle] -* https://developer.android.com/studio[Android Studio] -* https://developer.android.com/studio/#command-tools[Android SDK] -* https://capacitor.ionicframework.com/docs/getting-started/[Capacitor] - - -[arabic] -Now, open CMD and type the path where your _devon4ng-ionic-application-template_ project is present. + -Run the following commands: - -. npx cap init -. ionic build --configuration=android -. npx cap add android -. npx cap copy -. npx cap open android +To log into the web application, you can use the credentials *admin* for user and for password. + -Build the `APK` using Android studio. -image:images/howtos/e2e_gen/image52.png[] -image:images/howtos/e2e_gen/image53.png[] -image:images/howtos/e2e_gen/image54.png[] -image:images/howtos/e2e_gen/image55.png[] +Now the *`ANGULAR WebApp`* is done! -You can find your apk file in: -_/devon4ng-ionic-application-template/android/app/build/outputs/apk/debug_ diff --git a/documentation/images/howtos/e2e_gen/image14.png b/documentation/images/howtos/e2e_gen/image14.png index 39c8403da6..e3dd14b086 100644 Binary files a/documentation/images/howtos/e2e_gen/image14.png and b/documentation/images/howtos/e2e_gen/image14.png differ diff --git a/documentation/images/howtos/e2e_gen/image20.png b/documentation/images/howtos/e2e_gen/image20.png index 632c481d5c..887ad4a698 100644 Binary files a/documentation/images/howtos/e2e_gen/image20.png and b/documentation/images/howtos/e2e_gen/image20.png differ diff --git a/documentation/images/howtos/e2e_gen/image22.png b/documentation/images/howtos/e2e_gen/image22.png index 1245e4d802..a47eae6541 100644 Binary files a/documentation/images/howtos/e2e_gen/image22.png and b/documentation/images/howtos/e2e_gen/image22.png differ diff --git a/documentation/images/howtos/e2e_gen/image23.png b/documentation/images/howtos/e2e_gen/image23.png index 26568da005..dc334d9f81 100644 Binary files a/documentation/images/howtos/e2e_gen/image23.png and b/documentation/images/howtos/e2e_gen/image23.png differ diff --git a/documentation/images/howtos/e2e_gen/image37.png b/documentation/images/howtos/e2e_gen/image37.png index 835fd3e8ff..ef9c217cd4 100644 Binary files a/documentation/images/howtos/e2e_gen/image37.png and b/documentation/images/howtos/e2e_gen/image37.png differ diff --git a/documentation/images/howtos/e2e_gen/image39.png b/documentation/images/howtos/e2e_gen/image39.png index 61720c65fc..b46e15e946 100644 Binary files a/documentation/images/howtos/e2e_gen/image39.png and b/documentation/images/howtos/e2e_gen/image39.png differ