OneCX UI App Generator

The OneCX UI App Generator is a powerful tool that simplifies the development of UI applications within the OneCX framework. It automates the creation of key UI components, ensuring consistency and adherence to best practices.

In addition to generation, significant parts still need to be created or modified manually by the user.
To clearly explain how the generator works and the necessary adjustments, the following example is used in this documentation: an application to manage Books. The Bookstore application allows users to search for books, view details about them, and manage their properties.

Prerequisites

Environment Setup

Make sure your development environment is set up correctly before using the OneCX UI App Generator.
The following tools must be installed and versions verified:

npm version should be >= 10.2.4
node version should be 20.11.0
nx - Local: v19.6.4
nx - Global: v20.0.6

Check versions

node --version
npm --version
nx --version

Install the Nx CLI globally

npm install -g nx@latest

In case of issues during Nx installation, try the following steps:

Nx CLI installation issue resolution

rm -rf node_modules
npm cache verify
npm install -g @nrwl/cli
npm install

Knowledge of Angular and Nx

The OneCX UI App Generator is built on top of Angular and Nx, so a basic understanding of these technologies is essential to effectively use the generator and customize the generated code.

Familiarity with Angular concepts such as components, modules, services, and state management (e.g., NgRx) will help you understand the structure of the generated code and how to extend it.

Knowledge of App Integration

The easiest way to integrate the generated App into local running OneCX is to follow the OneCX Local Environment guidelines in Extend OneCX. This ensures that the components are correctly registered and accessible within the application.

Knowledge of OpenAPI Specification

The generator relies on the OpenAPI specification to define the API endpoints and data models. Understanding how to read and modify OpenAPI YAML files is crucial for customizing the API interactions of the generated components.
Use the Swagger Editor to validate the syntax and structure of the OpenAPI file (openapi-bff.yaml) against the OpenAPI Specification.

Use of Swagger Editor with example OpenAPI file

Generation by Example

Let’s explore the capabilities of the OneCX App Generator through a practical example. We will create a simple application to manage books, which includes features such as searching for books, viewing details, and managing their properties.
We also provide a simple mock solution to simulate the backend services for the generated components, allowing you to see the generator’s output in action without needing a fully functional backend.

The generator offers a range of commands to gradually create various UI components such as applications, function modules, and pages. During the generation of some parts, you will be prompted to specify parameters that determine the structure and naming of the generated components. Occasionally, code adjustments will be necessary to implement business requirements.

Make the adjustments carefully and in accordance with the specifications and naming conventions of your project to ensure consistency and maintainability of the codebase.

Start Generation

Here is an overview of the application parts that can be generated using the OneCX App Generator. Start from top to bottom, i.e. first generate the application, then the feature module, and then the pages. The generator will guide you through the necessary steps and parameters for each part.

OneCX UI App ⇐ start here
- Feature Module
  - Entity Schema and OpenAPI
  - Search Component
  - Details Page
  - Create/Update Dialog
  - Delete Dialog
  - Simple NgRx Page

Build the UI App

After generating the UI App and its components, you can build the application.
Use the following command to build the application:

Build the application

npm run build

Figure 1. Excerpt of the build output (exemplary for bookstore application)

Lint the UI App

The generator creates code that adheres to standard linting rules, but it’s always a good practice to run the linter after generation to catch any potential issues or inconsistencies.
Use the following command to lint the application:

Static code analyzing of the application

npm run lint

Figure 2. Excerpt of the lint output (exemplary for bookstore application)

Test the UI App

After generating the application and its components, it’s crucial to run the tests to ensure that everything is working as expected. The generator creates basic test cases for the generated components, but you may need to add more tests or adjust the existing ones based on your specific requirements and business logic.
Use the following command to run the tests:

Test the application

npm run test

Figure 3. Excerpt of the test output (exemplary for bookstore application)

Development: Get the Generator

The following is only required if you want to contribute to the development of the generator or want to use the generator locally without installing it globally from npm. If you just want to use the generator, you can install it globally from npm and skip the following steps.

Clone the onecx-nx-plugins repository into a folder on the local machine/inside WSL2
```
git clone https://github.com/onecx/onecx-nx-plugins.git
```
Navigate into the cloned repository and install the dependencies
```
cd onecx-nx-plugins
npm install
```
Build the OneCX App Generator
```
npm run build
```