:toc:
toc::[]

= Ionic client generation

We are going to show you **how to** generate a CRUD Ionic application from an **ETO**
using CobiGen. 

NOTE: This is a short introduction to the Ionic generation. For a deeper tutorial including the generation of the backend, we strongly recommend you to follow link:files/HOW-TO-devonfw-ide-CobiGen-PoC-E2E_v3.2.pdf[this document].

== Prerequisites

Before starting, make sure you have the following things already installed on your machine:

- link:https://ionicframework.com/docs/installation/cli[Ionic]: follow the steps described on the Ionic page.
It includes the installation of:
** link:https://nodejs.org/en/[NodeJS]: We have to use the `npm` package manager for downloading packages.
** Ionic CLI.

- link:https://capacitor.ionicframework.com/docs/getting-started/[Capacitor]: Necessary to access to native device features.

If _CobiGen_Templates_ are not already downloaded, follow the next steps:

- Right click on any file in your Eclipse workspace. Select _CobiGen -> Update Templates..._ from the context menu and now you are able to start the generation. 

- If you want to adapt the templates, select _CobiGen -> Adapt Templates..._ from the menu and you should have the _CobiGen_Templates_ as a new project in your Eclipse's workspace.

After following those steps correctly, you should have the latest version of the templates ready to use.

== Generation

We are going to generate the CRUD functions into a **sample application**.
First, clone or download the link:https://github.com/devonfw/devon4ng-ionic-application-template[devon4ng Ionic template] in your workspace.

After that, please create a link:https://github.com/devonfw/devon4ng/wiki/tutorial-newapp[devon4j project] and then start implementing the ETO: you can find an example link:https://github.com/devonfw/devon4j/blob/develop/samples/core/src/main/java/io/devonfw/gastronomy/restaurant/tablemanagement/logic/api/to/TableEto.java[here].

As you can see, `TableEto` contains 3 attributes: 2 of them are `Long` and the third one `TableState` is an enum that you will find 
link:https://github.com/devonfw/devon4j/blob/develop/samples/core/src/main/java/io/devonfw/gastronomy/restaurant/tablemanagement/common/api/datatype/TableState.java[here]. 
The Ionic generation works fine for any Java primitive attribute (string, float, char, boolean...) and enums. However, if you want to use your own objects, you should 
override the `toString()` method, as explained link:https://stackoverflow.com/questions/35361482/typescript-override-tostring[here]. 

The attributes explained above will be used for generating a page that shows a list. Each item of that list 
will show the values of those attributes. 

For generating the files:

* Right click your ETO file and click on _CobiGen > Generate_ as shown on the figure below.

image::images/howtos/ionic-gen/rightClick.png[Eclipse CobiGen generation,width="500"link="images/howtos/ionic-gen/rightClick.png"]

* Select the Ionic increments for generating as shown below. _Increments group a set of templates for generating
different projects_.
..  **`Ionic List`** used for generating the page containing the list.
..  **`Ionic devon4ng environments`**  is for stating the server path.
..  **`Ionic i18n`** used for generating the different language translations for the _`translationService`_ (currently English and Spanish).
..  **`Ionic routing`** adds an app-routing.module.ts file to allow navigation similar to the one available in Angular.
..  **`Ionic theme`** generates the `variables.scss` file which contains variables to style the application.

image::images/howtos/ionic-gen/wizardCobiGen.png[CobiGen Ionic Wizard,width="500"link="images/howtos/ionic-gen/wizardCobiGen.png"]

NOTE: By default, the generated files will be placed inside "devon4ng-ionic-application-template", next to the root of your project's folder.
See the image below to know where they are generated. For **changing the generation path** and the name of the application go to `_CobiGen_Templates/crud_ionic_client_app/cobigen.properties_`.

image::images/howtos/ionic-gen/pathOfGeneration.png[Generation path,width="500"link="images/howtos/ionic-gen/pathOfGeneration.png"]

Now that we have generated the files, lets start testing them:

* First change the **SERVER_URL** of your application. For doing that, modify `_src/environments/environments.ts_`, also modify `_src/environments/environments.android.ts_` (android) and `_src/environments/environments.prod.ts_` (production) if you want to test in different environments.

* Check that there are no duplicated imports. Sometimes there are duplicated imports in `_src/app/app.module.ts_`.
This happens because the merger of CobiGen prefers to duplicate rather than to delete.

* Run ``npm install`` to install all the required dependencies.

* Run ```ionic serve`` on your console.

After following all these steps your application should start. However, remember that you will need your **server** to be running for access to the list page.

== Running it on Android

To run the application in an android emulated device, it is necessary to have Android Studio and Android SDK. After its installation, the following commands have to be run on your console:

* ``npx cap init "name-for-the-app (between quotes)" "id-for-the-app (between quotes)"``

* ``ionic build --configuration=android``. To use this command, you must add an android build configuration at angular.json
[source]
----
    "build": {
      ...
      "configurations": {
        ...
        "android": {
          "fileReplacements": [
            {
              "replace": "src/environments/environment.ts",
              "with": "src/environments/environment.android.ts"
            }
          ]
        },
      }
    }
----

* ``npx cap add android``

* ``npx cap copy``

* ``npx cap open android``

The last steps are done in Android studio: make the project, make the app, build and APK and run in a device.

image::images/howtos/ionic-gen/and-vsc-make.png[Click on make project,width="500" link="images/howtos/ionic-gen/and-vsc-make.png"]

image::images/howtos/ionic-gen/and-vsc-make-app.png[click on make app,width="500" link="images/howtos/ionic-gen/and-vsc-make-app.png"]

image::images/howtos/ionic-gen/and-vsc-build-apk.png[click on build APK,width="500" link="images/howtos/ionic-gen/and-vsc-build-apk.png"]

image::images/howtos/ionic-gen/and-vsc-build-run.png[click on running device,width="500" link="images/howtos/ionic-gen/and-vsc-build-run.png"]

