CUBA CLI Quick Start


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 CUBA Platform without any additional proprietary 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:

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. Choose HSQLDB

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

Close CLI or open 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.

CUBA plugin for IntelliJ IDEA

In order to develop business logic, CUBA provides the integration plugin for Java IDE. Open IntelliJ IDEA and install the CUBA Framework integration plugin. This plugin provides navigation between screen descriptor, controller and data model components, advanced injections, including screen components, actions, services, data sources, CUBA infrastructure beans and services, CUBA-specific code generation and refactoring, hot deploy of individual source code file, and simple localized messages creation and selection in components.

To import the project into IDE, run gradlew idea and then open the .ipr file.

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. The Order entity should have a many-to-one relationship to Customer.

Let’s start with creating a Customer class. Enter 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 your IDE. Add the name and email fields, both of String type. CUBA platform supports localization in the same way as other Java applications: by using files. Let's add messages for the new attributes. Create getters and setters for them. Once all the attributes are created, we will set the name pattern to get a meaningful Customer instance representation in UI. CUBA CLI generates DB scripts stubs for the created entities, but the custom fields should be added manually. Add NAME and EMAIL both to DB initialization and update scripts.

Run gradlew updateDb to create the table for the Customer entity.

Creating the UI

Now let’s create the user interface for the application. CUBA CLI can generate the standard CRUD screens using the two predefined screen templates: browser screen and editor screen. 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 screen browse and accept the defaults to create the Browse screen for the Customer entity. Enter screen edit and repeat the steps to create the Edit screen for the Customer entity.

The screens have been created in the web module package. Let's customize them a little, adding name and email fields to the browse table and editor fieldGroup.

Enhancing the data model

Let’s create the Order entity. 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.

At this stage, we can already define, how exactly we want to choose a customer in the UI when creating an order. Let it be a dropdown list with a lookup action and the ability to open the selected customers in a new window. Don't forget to define the messages and add the new attributes to DB scripts.

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. Both attributes are mandatory.

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.

And 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.

Additionally, for the database integrity, you can define database constraints, but this part is out of our scope now.

Run gradlew updateDb to create tables for the new entities.

Enhancing the UI

Time to create the UI! At first, create the standard screens for the Product.

After that, create the UI for OrderLine. The list of order lines should be displayed in the Order editor only, 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 necessary fields to Order screens

We will also make the Customer editor display the list of orders. Open the customer-edit.xml file and create a new datasource for loading the linked Order instances. Use CUBA plugin autocomplete function.

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 linesDs datasource into the controller class. Now add a listener to the datasource in the init() method using a lambda expression as the implementation.

The lambda expression will call the new calculateAmount() method.

Having finished here, we can perform hot deploy, and 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, and all that we used is CUBA command line interface and Java IDE. Thank you for your attention.