CUBA CLI Quick Start
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.
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.
gradlew startDb to start the local HyperSQL server.
gradlew createDb to create the database instance.
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
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
String type. 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. 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
gradlew updateDb to create the table for the
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.
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
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
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:
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
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
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
Additionally, for the database integrity, you can define database constraints, but this part is out of our scope now.
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
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.
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
Let’s create the standard screens for the
Order entity contains two reference attributes -
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
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
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.