CUBA CLI Quick Start

Download

CLI installation guide

In this video, we'll get an overview of CUBA command line interface. In a nutshell, CUBA CLI is a command line utility that allows you to easily create projects based on CUBA Platform. Also, it provides the lightweight scaffolding of the main project artifacts: entities, screens, services, and so on. With this tool, you can use the framework without any additional tools.

I will show you how to create a simple application for customers and orders management using only a command line and a Java IDE.

Creating a project

Open a terminal and run the cuba-cli command to start CUBA CLI.

To create a new application, input the command create-app. You can use TAB auto-completion. CLI will ask you about the project. If a question implies the default answer, you can press ENTER to accept it. You will be asked the following questions:

  • Repository to be used in the project. The list of repositories already contains binary artifacts repository URL and authentication parameters. Feel free to choose any of them.

  • Project name – for sample projects, CLI generates random names that can be selected by default.

  • Project namespace – the namespace which will be used as a prefix for entity names and database tables. The namespace can consist of Latin letters only and should be as short as possible.

  • Root package – the root package of Java classes.

  • Platform version – the platform artifacts of the selected version will be automatically downloaded from the repository on project build.

  • Database – the SQL database to use. For the sample application, choose HSQLDB.

An empty project will be created in a new folder in the current directory.

Close CLI or open a new terminal window and navigate to the project folder.

Run gradlew assemble. At this stage, all the required libraries will be downloaded, and CLI will build project artifacts in the build subfolders of the project folder.

Run gradlew startDb to start the local HyperSQL server.

Run gradlew createDb to create the database instance.

Run gradlew setupTomcat deploy start. The Tomcat server with the application will be deployed in the deploy subfolder of the project.

Open the web browser and proceed to the default application URL (http://localhost:8080/app). The username and password are admin - admin, they are filled in by default.

The running out-of-the-box application contains two main menu items: Administration and Help, as well as the functionality for security and administration.

To stop the application, run gradlew stop.

CUBA plugin for IntelliJ IDEA

In order to develop business logic, you can use any Java IDE. To make it easier, I will use the free version of dedicated CUBA Studio IDE. It is based on the open-source IntelliJ IDEA Platform and extends its functionality with some CUBA-specific features: database scripts generation, navigation between screen descriptor, controller and data model components, advanced injections, CUBA-specific code generation and refactoring, and so on. Some part of these tasks can also be done in CLI.

Import the project into IDE as described in the documentation and wait for Gradle synchronization and project indexing process to complete. The CUBA project tree should appear in the Project tool window.

Creating the data model

Let's create a data model and a graphic interface for our simple CUBA-based application for customers and orders management. In our data model, the Order entity should have a many-to-one relationship to Customer.

Let’s start with creating a Customer class. Enter create-entity in a terminal. You will be asked to enter the entity class name - Customer - and select the entity class package name. Accept default.

An entity may be Persistent, Persistent Embedded or Not Persistent. Choose Persistent to make the entity able to be saved in the database.

Let's add some fields. Open the created class in Studio. It has appeared in the Data Model section of the project tree. Add the name and email fields, both of String type, and create getters and setters for them. CUBA platform supports localization in the same way as other Java applications: by using message.properties files. Let's add messages for the new attributes. We will also set the name pattern to get a meaningful Customer instance representation in UI. CUBA CLI generates DB scripts stubs for the created entities. To add the custom fields, I will use the Generate Database Scripts command in the main menu. If the new script conflicts with or overlays the older one, the older one will be marked to be deleted. Of course, you can manage the database script files and add fields manually without Studio.

You can run the gradlew updateDb task either from Studio or command line interface.

Creating the UI

Now let’s create the user interface for the application. CUBA CLI can generate the standard CRUD screens using the predefined screen templates. For example, the browser is a screen for viewing all records from a database, it includes data filter and supports paging by default. The editor is a screen for viewing or editing an individual record.

Enter create-screen, select new browse screen_,_ select the Customerentity and accept the defaults. Create the Edit screen for the Customer entity in the same way.

The screens have been created in the web module package. They are now available in the Generic UI section of the project tree. Let's customize them a little, adding name and email fields to the browse table and editor form. Use the Studio popups and intentions to speed up the process.

Enhancing the data model

Let’s create the Order entity. Feel free to use TAB auto-completion in CLI. Add the following attributes: date - the order date, amount - the order amount of BigDecimal type, and customer - the many-to-one reference to the Customer entity. Don't forget to create getters and setters and define the messages.

Now let's add two more entities: OrderLine and Product, so the Order will contain a set of order lines which refer to some product. Furthermore, we will implement the order amount calculation based on the quantity and price of the selected products.

So, we create the Product entity and define its attributes: name which is a String and price which is a BigDecimal. Select name as the Product's name pattern.

Now let's create the OrderLine entity. Add the following attributes: order which is a many-to-one reference to Order; product which is a many-to-one reference to Product; finally, the quantity attribute of BigDecimal type which sets the product quantity for a given order line.

Add the collection of lines for the order: create the lines attribute which is a Composition reference to the OrderLine entity. That means that the order lines are created and edited alongside the original order. The corresponding attribute on the reverse side of the relationship is defined with the mappedBy attribute.

The constraints for the database integrity will be created on the next scripts generation.

Enhancing the UI

Now. let's scaffold the user interface for the new entities. At first, create the standard screens for Product.

After that, create the UI for OrderLine. The list of order lines should be displayed only in the Order editor, so we don't need an OrderLine browser.

Since the OrderLine entity includes the reference attribute product, we have to create an entity view that includes this attribute. A view, in CUBA terms, is a declarative way to specify which data (attributes and nested instances/collections) should be extracted from a database.

Now we can display products in the OrderLine editor.

Let’s create the standard screens for the Order. The Order entity contains two reference attributes - customer and lines. Suppose we would like to display customers in the browse screen, and the complete graph of entities in the Order editor. In this case, we need two separate views.

Now we can add all the necessary fields to Order screens. To display the list of customers in the lookup field, create a new data container that will load the collection of customers from the database. Let's also add the table for displaying the order lines.

We will also make the Customer editor display the list of orders. Open the customer-edit.xml file and create a new data container for loading the linked Order instances. Pass the edited Customer instance as a parameter for the container's loader.

All the screens are done now. Start the application server and make sure they are functional.

Development beyond CRUD

We still have to implement the order amount calculations based on the product price and quantity. Switch to the Java controller of the Order editor. To begin with, let’s inject the link to the linesDc data container into the controller class. Now subscribe to the CollectionChangeEvent that will call the new calculateAmount() method every time the lines collection is changed.

The changes in the existing screens will be hot deployed, and we will see the changes simply by switching to the web browser and reopening the order editor, without stopping the application server.

As we can see, the order amount corresponds to the order lines, and if you modify them, the amount is recalculated.

Our application is done, at a first approximation. Feel free to develop it using any tools you like. Thank you for your attention.