4.5.3. Example of Application Component

In this section, we’ll consider a complete example of creating an application component and using it in a project. The component will provide a "Customer Management" functionality and include the Customer entity and corresponding UI screens. The application will use the Customer entity from the component as a reference in its Order entity.

app components sample
Creating the Customer Management component

  1. Create a new project in Studio and specify the following properties on the New project screen:

    • Project name – customers

    • Project namespace – cust

    • Root package – com.company.customers

  2. Open the Project Properties window and set the Module prefix to cust.

  3. Create the Customer entity with at least the name attribute.

    If your component contains @MappedSuperclass persistent classes, make sure they have descendants which are entities (i.e., annotated with @Entity) in the same project. Otherwise, such base classes will not be properly enhanced and you will not be able to use them in applications.

  4. Generate DB scripts and create standard screens for the Customer entity: cust_Customer.browse and cust_Customer.edit.

  5. Go to the menu designer and rename the application-cust menu item to customerManagement. Then, open the messages.properties file in the Main Message Pack section and specify the new caption for the customerManagement menu item.

  6. Generate app-component.xml descriptor by clicking the CUBA > Advanced > App Component Descriptor item in the main menu.

  7. Test the Customer Management functionality:

    • Select CUBA > Create Database in the main menu.

    • Run the application: click the debug button next to the selected CUBA Application configuration in the main toolbar.

    • Open http://localhost:8080/cust in your web browser.

  8. Install the application component into the local Maven repository by selecting the CUBA > Advanced > Install App Component menu item.

Creating the Sales application

  1. Create a new project in Studio and specify the following properties on the New project screen:

    • Project name – sales

    • Project namespace – sales

    • Root package – com.company.sales

  2. Open the Project Properties window and select Use local Maven repository checkbox.

  3. Include application component in the project as described in the Installing add-on by coordinates section of the Studio User Guide. Use Maven coordinates of the Customer Management component, e.g. com.company.customers:cust-global:0.1-SNAPSHOT.

  4. Create the Order entity and add the date and amount attributes. Then add the customer attribute as a many-to-one association with the Customer entity – it should be available in the Type drop-down list.

  5. Generate DB scripts and create standard screens for the Order entity. When creating standard screens, create an order-with-customer view that includes the customer attribute and use it for the screens.

  6. Test the application functionality:

    • Select CUBA > Create Database in the main menu.

    • Run the application: click the debug button next to the selected CUBA Application configuration in the main toolbar.

    • Open http://localhost:8080/app in your web browser. The application will contain two top-level menu items: Customer Management and Application with the corresponding functionality.

Modifying the Customer Management component

Suppose we have to change the component functionality (add an attribute to Customer) and then reassemble the application to incorporate the changes.

  1. Open the customers project in Studio.

  2. Edit the Customer entity and add the address attribute. Include this attribute to both browser and editor screens.

  3. Generate DB scripts – a script for altering table will be created. Save the scripts.

  4. Test the changes in the component:

    • Select CUBA > Update Database in the main menu.

    • Run the application: click the debug button next to the selected CUBA Application configuration in the main toolbar.

    • Open http://localhost:8080/cust in your web browser.

  5. Re-install the application component into the local Maven repository by selecting the CUBA > Advanced > Install App Component menu item.

  6. Switch to the sales project in Studio.

  7. Select CUBA > Build Tasks > Clean.

  8. Select CUBA > Update Database in the main menu – the update script from the Customer Management component will be executed.

  9. Run the application: click the debug button next to the selected CUBA Application configuration in the main toolbar.

  10. Open http://localhost:8080/app in your web browser – the application will contain the Customer entity and screens with the new address attribute.